platform-ci/platform_ci/event_selection.py

"""One event-selection rule for components and images, shared by `prepare` and the trusted publisher so both pick the same targets.

UNTESTED: written while test execution was suspended.

The repository's own `release.channels` are its event vocabulary. A channel matches an event when the event's BRANCH (a push's branch, or a
pull request's head branch) matches its `push_branches`, or the event's pushed TAG matches its `push_tags`; the literal `pull_request` matches
every pull request. A channel that declares `trigger.manual: true` ALSO matches a manual run (`workflow_dispatch`, which carries no branch or tag), so a
channel with no push trigger is selected by a manual run and by nothing else. A component or image restricted by `only_on_channels` runs only when one of
those names matches, and one restricted by `not_on_channels` is skipped when any of them matches. Nothing here names a repository, an owner or a run.
"""

from collections.abc import Sequence
from dataclasses import dataclass
from fnmatch import fnmatchcase
from typing import Final

from platform_ci.configuration import ReleaseChannel, branch_matches

PULL_REQUEST: Final = "pull_request"
"""A reserved selection name (not a channel): matches every pull request event."""
PUSH: Final = "push"
MANUAL: Final = "workflow_dispatch"
"""The event name of a manual run (`github.event_name` of a `workflow_dispatch`, also seen by a callable run started by one): the only event a `manual` channel adds."""


@dataclass(frozen=True)
class EventFacts:
   """The authoritative event facts selection and fixed script variables use: event name, branch (push branch or pull request head), tag, revision."""

   name: str
   branch: str = ""
   tag: str = ""
   source_revision: str = ""

   @property
   def ref_type(self) -> str:
      """`tag` for the push of a tag, otherwise `branch` (a push branch or a pull request's head branch), the same words as `github.ref_type`."""
      return "tag" if self.tag else "branch"

   @property
   def ref_name(self) -> str:
      """The short ref name a script may see: the pushed tag, else the push branch or pull request head branch."""
      return self.tag or self.branch


def push_facts(branch: str, source_revision: str) -> EventFacts:
   """Return the facts of a push to a branch (what the trusted publisher releases from)."""
   return EventFacts(PUSH, branch=branch, source_revision=source_revision)


def tag_facts(tag: str, source_revision: str) -> EventFacts:
   """Return the facts of a push of a tag (what the trusted publisher releases from for a tag-driven release kind)."""
   return EventFacts(PUSH, tag=tag, source_revision=source_revision)


def channel_matches(channel: ReleaseChannel, facts: EventFacts) -> bool:
   """Return whether the event is one the channel's triggers select: a manual run for a `manual` channel, or the event's branch or tag."""
   if channel.manual and facts.name == MANUAL:
      return True
   if facts.branch and branch_matches(channel.push_branches, facts.branch):
      return True
   return bool(facts.tag) and any(fnmatchcase(facts.tag, pattern) for pattern in channel.push_tags)


def matching_channel_names(channels: Sequence[ReleaseChannel], facts: EventFacts) -> set[str]:
   """Return the names of the channels the event matches, plus `pull_request` for a pull request."""
   names = {channel.name for channel in channels if channel_matches(channel, facts)}
   return names | {PULL_REQUEST} if facts.name == PULL_REQUEST else names


def selected(only_on: Sequence[str], not_on: Sequence[str], channels: Sequence[ReleaseChannel], facts: EventFacts) -> bool:
   """Return whether something restricted by `only_on` / `not_on` applies to this event; with neither it always does."""
   if not only_on and not not_on:
      return True
   matching = matching_channel_names(channels, facts)
   if only_on and not matching & set(only_on):
      return False
   return not matching & set(not_on)