1"""The pure decision: given the state, what does a workflow driver do?
3Every reserved-branch workflow shares one lifecycle: cut a
4``workflow/<name>`` branch, do the work, open a squash PR, arm, and
5merge (a release then publishes). The engine
6(livery.workshop._workflow_engine.run_workflow) gathers the inputs,
7asks ``workflow_decision``, and acts; each driver plugs in only
8its do-the-work and after-the-merge steps.
10The decision is a pure function so every branch is table-testable.
11Order is load-bearing and stated inline. Every STOP message teaches:
12it names what stopped the driver and lists the options with when
13each applies.
14"""
23 WORKFLOW_PREFIX,
24 WorkflowKind,
25 WorkflowState,
26 WorkflowStatus,
27)
29#: Live (non-terminal) states: a workflow here is still someone's.
31 {
32 WorkflowState.IN_PROGRESS,
33 WorkflowState.AWAITING_REVIEW,
34 WorkflowState.PREPARING,
35 }
36)
40 """What a driver does next; the same vocabulary for every kind."""
54 """The chosen action, a line to announce or teach, and a tidy target.
56 ``tidy_target`` names WHICH workflow a TIDY_THEN_START removes: a
57 finished other under coexistence, or None for the driver's own
58 leftover. Without it the engine could not tell somebody else's
59 leftover from its own live branch, and tidying the wrong one
60 closes a live PR.
61 """
69 "The working tree has uncommitted changes, and a workflow must not"
70 " guess whether they belong to it. Commit them (they ride along),"
71 " or discard them, then run this again."
72)
76 return "release" if kind is WorkflowKind.RELEASE else "update"
80 *,
81 kind: WorkflowKind,
82 name: str,
83 wf: WorkflowStatus,
84 members: tuple[str, ...],
85 branch: str,
86 dirty: bool,
87 behind_default: int,
88 default_branch: str,
89 current_user: str,
90 others: tuple[WorkflowStatus, ...] = (),
91) -> WorkflowDecision:
92 """Decide what the *name* driver does next. Pure, no I/O.
94 *wf* is this driver's own detected workflow (NONE when absent);
95 *others* are the coexisting workflows on different names;
96 *members* are a release driver's package directories, used for the
97 intersection refusal. Order matters: the wrong-branch refusal,
98 then the fail-safe and human stops, then coexistence, then the
99 automatic actions keyed on the detector's state.
100 """
101 own_branch = f"{WORKFLOW_PREFIX}{name}"
102 if branch and branch not in (default_branch, own_branch):
103 return WorkflowDecision(
104 WorkflowAction.STOP,
105 f"A {_noun(kind)} runs from {default_branch} or {own_branch}, and"
106 f" you are on {branch}. Switch to {default_branch} to run it"
107 f" (or to {own_branch} to resume this one), then run it again.",
108 )
110 if wf.state is WorkflowState.UNKNOWN:
111 return WorkflowDecision(
112 WorkflowAction.STOP,
113 f"The forge cannot be reached to read the {_noun(kind)} state, so"
114 " nothing here may act on a guess. Retry when the forge answers;"
115 f" `{footman.prog()} status --workflow` shows what is known meanwhile.",
116 )
118 if wf.author and current_user and wf.author != current_user and wf.state in ACTIVE:
119 return WorkflowDecision(
120 WorkflowAction.STOP,
121 f"A {_noun(kind)} on {name} is in flight, run by {wf.author}: it"
122 " is theirs to drive. Coordinate with them, watch it with"
123 f" `{footman.prog()} status --workflow`, or abort it deliberately with"
124 f" `{footman.prog()} workflow.abort {name} --force` if you both agree it is"
125 " dead.",
126 )
128 # A second release whose set intersects an in-flight release
129 # refuses immediately, from read-only state, nothing to undo. An
130 # UNKNOWN other still refuses: absence cannot be proven from a
131 # blip. Disjoint sets coexist.
132 if kind is WorkflowKind.RELEASE and members:
133 for other in others:
134 if other.kind is not WorkflowKind.RELEASE:134 ↛ 135line 134 didn't jump to line 135 because the condition on line 134 was never true
135 continue
136 live = other.state in ACTIVE or other.state is WorkflowState.UNKNOWN
137 overlap = sorted(set(members) & set(other.members))
138 if live and overlap:
139 who = other.author or "someone"
140 return WorkflowDecision(
141 WorkflowAction.STOP,
142 f"Release {other.name} ({who}) is in flight and shares"
143 f" {', '.join(overlap)} with this set. Options: wait for"
144 " it to land; release the disjoint remainder now"
145 " (drop the shared packages from your set); or, if it is"
146 f" yours and dead, `{footman.prog()} workflow.abort {other.name}`.",
147 )
149 # A finished other leftover is tidied so branches never
150 # accumulate; a live other coexists; an UNKNOWN other is left
151 # strictly alone (never tear down on a state we could not read).
152 for other in others:
153 if other.name == name or not other.name:153 ↛ 154line 153 didn't jump to line 154 because the condition on line 153 was never true
154 continue
155 if other.state in ACTIVE or other.state is WorkflowState.UNKNOWN:
156 continue
157 if dirty:157 ↛ 158line 157 didn't jump to line 158 because the condition on line 157 was never true
158 return WorkflowDecision(WorkflowAction.STOP, _DIRTY)
159 return WorkflowDecision(
160 WorkflowAction.TIDY_THEN_START,
161 f"A finished {other.name} is lying around; tidying it, then"
162 f" starting {name}.",
163 tidy_target=other,
164 )
166 if wf.state is not WorkflowState.NONE and wf.name and wf.name != name:166 ↛ 167line 166 didn't jump to line 167 because the condition on line 166 was never true
167 return WorkflowDecision(
168 WorkflowAction.STOP,
169 f"{wf.name} was passed as this driver's own workflow: a caller"
170 " bug, not a state a person can fix.",
171 )
173 # A dirty tree is ambiguous, except a PREPARING update resumed on
174 # its own branch: the renderer leaves conflict markers there, and
175 # re-running the verb is how a person resumes after resolving
176 # them. From any other branch the dirt is somebody's unrelated
177 # work, and preparing would carry it onto the workflow branch.
178 resumable = (
179 kind is WorkflowKind.UPDATE
180 and wf.state is WorkflowState.PREPARING
181 and branch == own_branch
182 )
183 if dirty and not resumable:
184 return WorkflowDecision(WorkflowAction.STOP, _DIRTY)
186 # A completed leftover is behind by construction (the squash), so
187 # tidy before the behind check, which would otherwise merge the
188 # base into a branch about to be deleted.
189 if wf.state is WorkflowState.SUCCEEDED:
190 return WorkflowDecision(
191 WorkflowAction.TIDY_THEN_START,
192 f"The last {_noun(kind)} completed; tidying the leftover and"
193 " starting the next one.",
194 )
196 # The base moved in the set's own paths: the stamped derivation is
197 # a claim about history that no longer holds, so re-prepare before
198 # anything arms. Routed before the behind check because the remedy
199 # differs: MERGE_DEFAULT integrates, REPREPARE re-derives.
200 if wf.blocker.name == "STALE_SET" and wf.state in ACTIVE:
201 return WorkflowDecision(
202 WorkflowAction.REPREPARE,
203 "The base moved in this set's own paths since prepare, so the"
204 " stamped versions and entries are stale. Re-deriving on the"
205 " moved base and re-submitting.",
206 )
208 if behind_default > 0 and not dirty:
209 return WorkflowDecision(
210 WorkflowAction.MERGE_DEFAULT,
211 f"{behind_default} commit(s) behind {default_branch}; merging it in.",
212 )
214 if wf.state is WorkflowState.AWAITING_REVIEW:
215 return WorkflowDecision(
216 WorkflowAction.ARM, f"Arming the ready {_noun(kind)} PR."
217 )
219 if wf.state is WorkflowState.FAILED:
220 if wf.reopenable:
221 return WorkflowDecision(
222 WorkflowAction.REOPEN,
223 f"Reopening the closed {_noun(kind)} PR and re-submitting.",
224 )
225 return WorkflowDecision(
226 WorkflowAction.RETRY, "Re-submitting after the previous failure."
227 )
229 if wf.state is WorkflowState.IN_PROGRESS:
230 return WorkflowDecision(
231 WorkflowAction.RETRY,
232 f"A {_noun(kind)} is already in progress; re-submitting is the"
233 " idempotent check on it.",
234 )
236 return WorkflowDecision(WorkflowAction.START)