Skip to content

livery.workshop._workflow_state

livery.workshop._workflow_state

Where each reserved-branch workflow sits in its lifecycle.

A workflow lives on a reserved branch whose name is its identity: workflow/release/<members> (the set's directory names, sorted, joined with +, or their count and a digest when that runs long) or workflow/update/<slug>. Different names coexist; this reader tells the truth per branch and never arbitrates between them, which is the decision extension's job (livery.workshop._workflow_decision.workflow_decision).

Classification is a pure function (classify) of gathered signals, so every mapping is testable with no I/O; the gathering (gather) isolates the network and answers None when the forge cannot be read. UNKNOWN is a first-class state, not an error: a blip must never read as "nothing running", so everything that mutates refuses on it.

Classes:

Name Description
WorkflowKind

Which reserved-branch workflow a branch names.

WorkflowState

Where a workflow sits in its lifecycle.

Blocker

Why a workflow will not land by itself, data beside the state.

WorkflowStatus

The detector's verdict for one workflow.

Signals

The gathered inputs classify maps to a state.

Functions:

Name Description
kind_of

The kind a workflow name declares by its first segment.

members_of

A release name's package directories; empty for an update.

classify

Map gathered sig to a lifecycle state. Pure, no I/O.

blocker

Why the workflow will not land by itself. Pure, no I/O.

base_moved_in_paths

Whether origin/<base> carries commits head lacks touching paths.

gather

Gather one workflow's signals, or None when the forge is unreadable.

status_of

One workflow's WorkflowStatus from its gathered signals.

active_workflow_names

The distinct workflow names in play, local and remote united.

workflow_states

Every active workflow, each classified on its own signals.

Attributes:

Name Type Description
WORKFLOW_PREFIX
TEARDOWN_SAFE

WORKFLOW_PREFIX module-attribute

WORKFLOW_PREFIX = 'workflow/'

TEARDOWN_SAFE module-attribute

WorkflowKind

Bases: Enum

Which reserved-branch workflow a branch names.

Attributes:

Name Type Description
RELEASE
UPDATE

RELEASE class-attribute instance-attribute

RELEASE = 'release'

UPDATE class-attribute instance-attribute

UPDATE = 'update'

WorkflowState

Bases: Enum

Where a workflow sits in its lifecycle.

UNKNOWN means the forge could not be read: callers that mutate treat it like a live state and refuse, never assuming "nothing running" from a blip.

Attributes:

Name Type Description
NONE
PREPARING
IN_PROGRESS
AWAITING_REVIEW
FAILED
SUCCEEDED
UNKNOWN

NONE class-attribute instance-attribute

NONE = 'none'

PREPARING class-attribute instance-attribute

PREPARING = 'preparing'

IN_PROGRESS class-attribute instance-attribute

IN_PROGRESS = 'in_progress'

AWAITING_REVIEW class-attribute instance-attribute

AWAITING_REVIEW = 'awaiting_review'

FAILED class-attribute instance-attribute

FAILED = 'failed'

SUCCEEDED class-attribute instance-attribute

SUCCEEDED = 'succeeded'

UNKNOWN class-attribute instance-attribute

UNKNOWN = 'unknown'

Blocker

Bases: Enum

Why a workflow will not land by itself, data beside the state.

Attributes:

Name Type Description
NONE
CONFLICTS
CI_FAILING
DISARMED
CLOSED
BEHIND_BASE
REVIEW_REQUIRED
STALE_SET

NONE class-attribute instance-attribute

NONE = 'none'

CONFLICTS class-attribute instance-attribute

CONFLICTS = 'conflicts'

CI_FAILING class-attribute instance-attribute

CI_FAILING = 'ci_failing'

DISARMED class-attribute instance-attribute

DISARMED = 'disarmed'

CLOSED class-attribute instance-attribute

CLOSED = 'closed'

BEHIND_BASE class-attribute instance-attribute

BEHIND_BASE = 'behind_base'

REVIEW_REQUIRED class-attribute instance-attribute

REVIEW_REQUIRED = 'review_required'

STALE_SET class-attribute instance-attribute

STALE_SET = 'stale_set'

WorkflowStatus dataclass

WorkflowStatus(kind: WorkflowKind | None, state: WorkflowState, name: str = '', branch: str = '', members: tuple[str, ...] = (), detail: str = '', reopenable: bool = False, author: str = '', armed: bool | None = False, blocker: Blocker = NONE, pr_number: int = 0, head_sha: str = '', ci_state: str = '', tagged: tuple[str, ...] = ())

The detector's verdict for one workflow.

Attributes:

Name Type Description
kind WorkflowKind | None

Release or update; None on the NONE placeholder.

state WorkflowState

The lifecycle state.

name str

The workflow name, the branch without its prefix (release/forge+workshop).

branch str

The reserved branch (workflow/<name>).

members tuple[str, ...]

A release's package directory names; empty for an update.

detail str

A short hint (the failing leg, an unreadable-arm note).

reopenable bool

FAILED from a closed-unmerged PR; reopening is an option.

author str

Who opened the PR, the forge's login namespace.

armed bool | None

True = a schedule is live; False = confirmed unarmed; None = unreadable, which watches like armed (a false "disarmed" is the proven wrong exit).

blocker Blocker

Why it will not land by itself.

pr_number int

The workflow's PR, when one exists.

head_sha str

The commit whose CI matters.

ci_state str

The combined CI verdict for that commit.

tagged tuple[str, ...]

A release's members whose receipt tag is already cut.

kind instance-attribute

kind: WorkflowKind | None

state instance-attribute

name class-attribute instance-attribute

name: str = ''

branch class-attribute instance-attribute

branch: str = ''

members class-attribute instance-attribute

members: tuple[str, ...] = ()

detail class-attribute instance-attribute

detail: str = ''

reopenable class-attribute instance-attribute

reopenable: bool = False

author class-attribute instance-attribute

author: str = ''

armed class-attribute instance-attribute

armed: bool | None = False

blocker class-attribute instance-attribute

blocker: Blocker = Blocker.NONE

pr_number class-attribute instance-attribute

pr_number: int = 0

head_sha class-attribute instance-attribute

head_sha: str = ''

ci_state class-attribute instance-attribute

ci_state: str = ''

tagged class-attribute instance-attribute

tagged: tuple[str, ...] = ()

Signals dataclass

Signals(kind: WorkflowKind, remote_branch: bool, pr_state: str, ci_state: str, tagged: tuple[str, ...] = (), members: tuple[str, ...] = (), armed: bool | None = False, mergeable: bool | None = None, detail: str = '', author: str = '', pr_number: int = 0, head_sha: str = '', stale_set: bool = False)

The gathered inputs classify maps to a state.

Attributes:

Name Type Description
kind WorkflowKind
remote_branch bool
pr_state str
ci_state str
tagged tuple[str, ...]
members tuple[str, ...]
armed bool | None
mergeable bool | None
detail str
author str
pr_number int
head_sha str
stale_set bool

kind instance-attribute

remote_branch instance-attribute

remote_branch: bool

pr_state instance-attribute

pr_state: str

ci_state instance-attribute

ci_state: str

tagged class-attribute instance-attribute

tagged: tuple[str, ...] = ()

members class-attribute instance-attribute

members: tuple[str, ...] = ()

armed class-attribute instance-attribute

armed: bool | None = False

mergeable class-attribute instance-attribute

mergeable: bool | None = None

detail class-attribute instance-attribute

detail: str = ''

author class-attribute instance-attribute

author: str = ''

pr_number class-attribute instance-attribute

pr_number: int = 0

head_sha class-attribute instance-attribute

head_sha: str = ''

stale_set class-attribute instance-attribute

stale_set: bool = False

kind_of

kind_of(name: str) -> WorkflowKind

The kind a workflow name declares by its first segment.

Source code in packages/workshop/src/livery/workshop/_workflow_state.py
def kind_of(name: str) -> WorkflowKind:
    """The kind a workflow *name* declares by its first segment."""
    return (
        WorkflowKind.RELEASE
        if name.split("/", 1)[0] == "release"
        else WorkflowKind.UPDATE
    )

members_of

members_of(name: str) -> tuple[str, ...]

A release name's package directories; empty for an update.

Source code in packages/workshop/src/livery/workshop/_workflow_state.py
def members_of(name: str) -> tuple[str, ...]:
    """A release name's package directories; empty for an update."""
    if kind_of(name) is not WorkflowKind.RELEASE:
        return ()
    _, _, joined = name.partition("/")
    return tuple(part for part in joined.split("+") if part)

classify

classify(sig: Signals) -> WorkflowState

Map gathered sig to a lifecycle state. Pure, no I/O.

Source code in packages/workshop/src/livery/workshop/_workflow_state.py
def classify(sig: Signals) -> WorkflowState:
    """Map gathered *sig* to a lifecycle state. Pure, no I/O."""
    if sig.pr_state == "none":
        return (
            WorkflowState.IN_PROGRESS if sig.remote_branch else WorkflowState.PREPARING
        )
    if sig.pr_state == "open":
        if sig.ci_state == "failure":
            return WorkflowState.FAILED
        # An unreadable arm (None) watches like armed: reporting a
        # live arm as absent is the proven wrong verdict.
        return (
            WorkflowState.AWAITING_REVIEW
            if sig.armed is False
            else WorkflowState.IN_PROGRESS
        )
    if sig.pr_state == "closed":
        return WorkflowState.FAILED
    # merged
    if sig.kind is WorkflowKind.UPDATE:
        return WorkflowState.SUCCEEDED
    # A release is done when every member's receipt tag is cut; the
    # tags are the ledger, so partial success reads IN_PROGRESS with
    # the cut members listed, and a red publish run reads FAILED.
    if sig.members and set(sig.tagged) >= set(sig.members):
        return WorkflowState.SUCCEEDED
    if sig.ci_state == "failure":
        return WorkflowState.FAILED
    return WorkflowState.IN_PROGRESS

blocker

blocker(sig: Signals) -> Blocker

Why the workflow will not land by itself. Pure, no I/O.

CONFLICTS first (fixing them re-triggers CI anyway), then CI red, then the stale set (re-preparing also re-runs CI, so it outranks the arm question), then unarmed.

Source code in packages/workshop/src/livery/workshop/_workflow_state.py
def blocker(sig: Signals) -> Blocker:
    """Why the workflow will not land by itself. Pure, no I/O.

    CONFLICTS first (fixing them re-triggers CI anyway), then CI red,
    then the stale set (re-preparing also re-runs CI, so it outranks
    the arm question), then unarmed.
    """
    if sig.pr_state == "closed":
        return Blocker.CLOSED
    if sig.pr_state != "open":
        return Blocker.NONE
    if sig.mergeable is False:
        return Blocker.CONFLICTS
    if sig.ci_state == "failure":
        return Blocker.CI_FAILING
    if sig.stale_set:
        return Blocker.STALE_SET
    if sig.armed is False:
        return Blocker.DISARMED
    return Blocker.NONE

base_moved_in_paths

base_moved_in_paths(root: Path, base: str, paths: tuple[str, ...], *, head: str = 'HEAD') -> bool

Whether origin/<base> carries commits head lacks touching paths.

The staleness probe for a release set: pure local git, empty paths is never stale. Movement outside the set's paths is harmless by construction and reads False. head is the release branch's tip; the checkout the act runs from is usually the base itself, so its own HEAD says nothing about the branch. A tip this clone does not hold reads False: the release pull request's own freshness check is the guard that never guesses.

Source code in packages/workshop/src/livery/workshop/_workflow_state.py
def base_moved_in_paths(
    root: Path, base: str, paths: tuple[str, ...], *, head: str = "HEAD"
) -> bool:
    """Whether ``origin/<base>`` carries commits *head* lacks touching *paths*.

    The staleness probe for a release set: pure local git, empty
    *paths* is never stale. Movement outside the set's paths is
    harmless by construction and reads False. *head* is the release
    branch's tip; the checkout the act runs from is usually the base
    itself, so its own HEAD says nothing about the branch. A tip this
    clone does not hold reads False: the release pull request's own
    freshness check is the guard that never guesses.
    """
    if not paths:
        return False
    try:
        out = git.log_paths(root, f"{head}..origin/{base}", paths)
    except git.GitError:
        return False
    return bool(out)

gather

gather(repo: Repository, root: Path, name: str, *, base: str = 'main') -> Signals | None

Gather one workflow's signals, or None when the forge is unreadable.

Source code in packages/workshop/src/livery/workshop/_workflow_state.py
def gather(
    repo: Repository,
    root: Path,
    name: str,
    *,
    base: str = "main",
) -> Signals | None:
    """Gather one workflow's signals, or None when the forge is unreadable."""
    branch = f"{WORKFLOW_PREFIX}{name}"
    kind = kind_of(name)
    members = members_of(name)
    try:
        pr = repo.pr.find_by_head(branch, state="all")
        if pr is None:
            head = git.any_head(root, branch)
            if head:
                pr = repo.pr.find_by_head_sha(head)
        remote_branch = repo.branch_exists(branch)
    except (ForgeError, Unsupported, OSError):
        return None

    if pr is None:
        return Signals(
            kind=kind,
            remote_branch=remote_branch,
            pr_state="none",
            ci_state="",
            members=members,
        )

    if pr.merged:
        pr_state = "merged"
    elif pr.state == "closed":
        pr_state = "closed"
    else:
        pr_state = "open"

    armed: bool | None = False
    mergeable: bool | None = None
    ci_state = ""
    detail = ""
    head_sha = pr.head_sha
    tagged: tuple[str, ...] = ()
    stale = False

    try:
        if pr_state == "open":
            try:
                armed = repo.pr.is_armed(pr.number)
            except (ForgeError, Unsupported):
                armed = None
                detail = "arming state unreadable"
            status = repo.checks.status(pr.head_sha)
            ci_state = status.state
            if kind is WorkflowKind.RELEASE:
                stale = base_moved_in_paths(
                    root,
                    base,
                    tuple(f"packages/{m}" for m in members),
                    head=pr.head_sha or "HEAD",
                )
        elif pr_state == "merged" and kind is WorkflowKind.RELEASE:
            tags = set(repo.tags(prefix="packages/"))
            # The receipt: each member's tag, whatever version it
            # carries, present on the repository after this merge.
            tagged = tuple(
                m for m in members if any(t.startswith(f"packages/{m}/v") for t in tags)
            )
            if set(tagged) < set(members):
                status = repo.checks.status(pr.head_sha)
                ci_state = status.state
    except (ForgeError, Unsupported, OSError):
        return None

    return Signals(
        kind=kind,
        remote_branch=remote_branch,
        pr_state=pr_state,
        ci_state=ci_state,
        tagged=tagged,
        members=members,
        armed=armed,
        mergeable=mergeable,
        detail=detail,
        author=pr.author,
        pr_number=pr.number,
        head_sha=head_sha,
        stale_set=stale,
    )

status_of

status_of(sig: Signals | None, name: str) -> WorkflowStatus

One workflow's WorkflowStatus from its gathered signals.

Source code in packages/workshop/src/livery/workshop/_workflow_state.py
def status_of(sig: Signals | None, name: str) -> WorkflowStatus:
    """One workflow's ``WorkflowStatus`` from its gathered signals."""
    kind = kind_of(name)
    branch = f"{WORKFLOW_PREFIX}{name}"
    if sig is None:
        return WorkflowStatus(
            kind=kind, state=WorkflowState.UNKNOWN, name=name, branch=branch
        )
    return WorkflowStatus(
        kind=kind,
        state=classify(sig),
        name=name,
        branch=branch,
        members=sig.members,
        detail=sig.detail,
        reopenable=(sig.pr_state == "closed"),
        author=sig.author,
        armed=sig.armed,
        blocker=blocker(sig),
        pr_number=sig.pr_number,
        head_sha=sig.head_sha,
        ci_state=sig.ci_state,
        tagged=sig.tagged,
    )

active_workflow_names

active_workflow_names(repo: Repository, root: Path) -> tuple[str, ...]

The distinct workflow names in play, local and remote united.

The union, never local-else-remote: a colleague's live release exists only on the remote, and a local leftover of your own would hide it. The remote probe degrades to the local list when the forge is unreachable.

Source code in packages/workshop/src/livery/workshop/_workflow_state.py
def active_workflow_names(repo: Repository, root: Path) -> tuple[str, ...]:
    """The distinct workflow names in play, local and remote united.

    The union, never local-else-remote: a colleague's live release
    exists only on the remote, and a local leftover of your own would
    hide it. The remote probe degrades to the local list when the
    forge is unreachable.
    """
    local = set(git.local_branches(root, WORKFLOW_PREFIX))
    try:
        remote = set(git.remote_branches(root, WORKFLOW_PREFIX))
    except Exception:
        remote = set()
    return tuple(sorted(b.removeprefix(WORKFLOW_PREFIX) for b in local | remote))

workflow_states

workflow_states(repo: Repository, root: Path, *, base: str = 'main') -> tuple[WorkflowStatus, ...]

Every active workflow, each classified on its own signals.

Coexistence is legitimate; multiple names are states to report, not a broken invariant. Releases sort first, then by name.

Source code in packages/workshop/src/livery/workshop/_workflow_state.py
def workflow_states(
    repo: Repository, root: Path, *, base: str = "main"
) -> tuple[WorkflowStatus, ...]:
    """Every active workflow, each classified on its own signals.

    Coexistence is legitimate; multiple names are states to report,
    not a broken invariant. Releases sort first, then by name.
    """
    states = [
        status_of(gather(repo, root, name, base=base), name)
        for name in active_workflow_names(repo, root)
    ]
    states.sort(key=lambda wf: (wf.kind is not WorkflowKind.RELEASE, wf.name))
    return tuple(states)