basstler-stack 4.2.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (38) hide show
  1. basstler/maintenance/__init__.py +0 -0
  2. basstler/maintenance/__main__.py +128 -0
  3. basstler/maintenance/board.py +113 -0
  4. basstler/maintenance/check_overview.py +80 -0
  5. basstler/maintenance/commands.py +595 -0
  6. basstler/maintenance/default_branch_sync.py +444 -0
  7. basstler/maintenance/exceptions.py +36 -0
  8. basstler/maintenance/fast_forward.py +223 -0
  9. basstler/maintenance/finish_summary.py +515 -0
  10. basstler/maintenance/fork_pull_request_action.py +38 -0
  11. basstler/maintenance/landed_closing.py +85 -0
  12. basstler/maintenance/landed_closing_follow_up.py +85 -0
  13. basstler/maintenance/promotion.py +248 -0
  14. basstler/maintenance/promotion_context.py +221 -0
  15. basstler/maintenance/report.py +304 -0
  16. basstler/maintenance/restack_procedure.py +279 -0
  17. basstler/maintenance/restack_steps.py +769 -0
  18. basstler/maintenance/upstream_pull_request_synchronization.py +189 -0
  19. basstler/maintenance/upstream_read_route.py +37 -0
  20. basstler/stack/__init__.py +0 -0
  21. basstler/stack/__main__.py +377 -0
  22. basstler/stack/branch_status.py +54 -0
  23. basstler/stack/checkout.py +416 -0
  24. basstler/stack/commit_move.py +218 -0
  25. basstler/stack/exceptions.py +233 -0
  26. basstler/stack/label_write.py +68 -0
  27. basstler/stack/merge_probe.py +195 -0
  28. basstler/stack/model.py +696 -0
  29. basstler/stack/promotability.py +103 -0
  30. basstler/stack/promotion_link.py +138 -0
  31. basstler/stack/report.py +304 -0
  32. basstler/stack/settings.py +453 -0
  33. basstler/stack/stack.toml +31 -0
  34. basstler_stack-4.2.0.dist-info/METADATA +16 -0
  35. basstler_stack-4.2.0.dist-info/RECORD +38 -0
  36. basstler_stack-4.2.0.dist-info/WHEEL +4 -0
  37. basstler_stack-4.2.0.dist-info/licenses/LICENSE +202 -0
  38. basstler_stack-4.2.0.dist-info/licenses/NOTICE +13 -0
@@ -0,0 +1,189 @@
1
+ """
2
+ Keeping each fork pull request's record of its upstream review - the in-review label and
3
+ the link to the upstream pull request - in step with the upstream.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ from dataclasses import dataclass
9
+ from enum import StrEnum
10
+
11
+ from basstler.github.pull_request_description import (
12
+ PullRequestDescription,
13
+ UpstreamPullRequestLink,
14
+ )
15
+ from basstler.github.pull_request_record import (
16
+ PullRequestField,
17
+ )
18
+ from basstler.maintenance.fork_pull_request_action import ForkPullRequestAction
19
+ from basstler.github.branch_pull_request import BranchPullRequest
20
+ from basstler.stack.label_write import LabelWrite
21
+ from basstler.stack.model import BranchStatus, StackBranch
22
+
23
+
24
+ class UpstreamPullRequestSynchronizationAction(StrEnum):
25
+ """
26
+ What was written to a fork pull request to bring its record of the upstream review
27
+ in step.
28
+ """
29
+
30
+ LABEL_ADDED = "in-review label added"
31
+ """
32
+ The in-review label was added, because an upstream pull request opened from the
33
+ branch is open.
34
+ """
35
+
36
+ LABEL_REMOVED = "in-review label removed"
37
+ """
38
+ The in-review label was removed, because no upstream pull request opened from the
39
+ branch is open.
40
+ """
41
+
42
+ LINK_WRITTEN = "upstream link written"
43
+ """
44
+ The description now links the open upstream pull request opened from the branch.
45
+ """
46
+
47
+ LINK_REMOVED = "upstream link removed"
48
+ """
49
+ The description's link to an upstream pull request was removed, because none opened
50
+ from the branch is open.
51
+ """
52
+
53
+
54
+ @dataclass(frozen=True)
55
+ class UpstreamPullRequestSynchronizationChange(BranchPullRequest):
56
+ """
57
+ One write bringing a fork pull request's record of its upstream review in step.
58
+ """
59
+
60
+ action: UpstreamPullRequestSynchronizationAction
61
+ """
62
+ What was written.
63
+ """
64
+
65
+
66
+ @dataclass(frozen=True)
67
+ class UpstreamPullRequestSynchronization(ForkPullRequestAction):
68
+ """
69
+ The in-review label and the upstream pull request link on each fork pull request,
70
+ kept in step with the open upstream pull request opened from its branch.
71
+ """
72
+
73
+ def apply(self) -> list[UpstreamPullRequestSynchronizationChange]:
74
+ changes: list[UpstreamPullRequestSynchronizationChange] = []
75
+ for branch in self.stack.maintained_branches():
76
+ if branch.status is BranchStatus.MERGED:
77
+ continue
78
+ link = self.upstream_link_of(branch)
79
+ if self.label_in_step(branch.labels, link) and self.link_in_step(
80
+ branch.upstream_link, link
81
+ ):
82
+ continue
83
+ changes.extend(self.write(branch, link))
84
+ return changes
85
+
86
+ def upstream_link_of(self, branch: StackBranch) -> UpstreamPullRequestLink | None:
87
+ """
88
+ :param branch: A branch of the stack.
89
+ :return: The link to the open upstream pull request opened from it, ``None``
90
+ when none is open.
91
+ """
92
+ if branch.upstream_pull_request is None:
93
+ return None
94
+ return UpstreamPullRequestLink(
95
+ self.stack.configuration.upstream_repository, branch.upstream_pull_request
96
+ )
97
+
98
+ def label_in_step(
99
+ self, labels: list[str], link: UpstreamPullRequestLink | None
100
+ ) -> bool:
101
+ """
102
+ :param labels: The labels a pull request carries.
103
+ :param link: The upstream pull request it should link.
104
+ :return: Whether it carries the in-review label exactly when *link* exists.
105
+ """
106
+ return (self.stack.configuration.in_review_label in labels) == (
107
+ link is not None
108
+ )
109
+
110
+ @staticmethod
111
+ def link_in_step(
112
+ linked_url: str | None, link: UpstreamPullRequestLink | None
113
+ ) -> bool:
114
+ """
115
+ :param linked_url: The upstream pull request URL a description links.
116
+ :param link: The upstream pull request it should link.
117
+ :return: Whether the description links exactly *link*.
118
+ """
119
+ return linked_url == (None if link is None else link.url)
120
+
121
+ def write(
122
+ self, branch: StackBranch, link: UpstreamPullRequestLink | None
123
+ ) -> list[UpstreamPullRequestSynchronizationChange]:
124
+ """
125
+ Write the label and the link that disagree with what *branch*'s pull request
126
+ carries now.
127
+
128
+ :param branch: The branch whose pull request is written.
129
+ :param link: The upstream pull request it should link.
130
+ :return: The writes made.
131
+ """
132
+ number = branch.pull_request_number
133
+ current = self.fork.pull_request(number)
134
+ labels = PullRequestField.LABELS.read(current, number)
135
+ description = PullRequestDescription(
136
+ str(PullRequestField.BODY.read(current, number) or "")
137
+ )
138
+ actions = [
139
+ action
140
+ for action in (
141
+ self.write_label(number, labels, link),
142
+ self.write_link(number, description, link),
143
+ )
144
+ if action is not None
145
+ ]
146
+ return [
147
+ UpstreamPullRequestSynchronizationChange(branch.name, number, action)
148
+ for action in actions
149
+ ]
150
+
151
+ def write_label(
152
+ self, number: int, labels: list[str], link: UpstreamPullRequestLink | None
153
+ ) -> UpstreamPullRequestSynchronizationAction | None:
154
+ """
155
+ :param number: The fork pull request to write.
156
+ :param labels: The labels it carries now.
157
+ :param link: The upstream pull request it should link.
158
+ :return: What was written, ``None`` when its label was already in step.
159
+ """
160
+ if self.label_in_step(labels, link):
161
+ return None
162
+ label = self.stack.configuration.in_review_label
163
+ if link is None:
164
+ write = LabelWrite.replacing(labels, removed=[label])
165
+ action = UpstreamPullRequestSynchronizationAction.LABEL_REMOVED
166
+ else:
167
+ write = LabelWrite.replacing(labels, added=[label])
168
+ action = UpstreamPullRequestSynchronizationAction.LABEL_ADDED
169
+ self.fork.replace_labels(number, write.labels)
170
+ return action
171
+
172
+ def write_link(
173
+ self,
174
+ number: int,
175
+ description: PullRequestDescription,
176
+ link: UpstreamPullRequestLink | None,
177
+ ) -> UpstreamPullRequestSynchronizationAction | None:
178
+ """
179
+ :param number: The fork pull request to write.
180
+ :param description: The description it carries now.
181
+ :param link: The upstream pull request it should link.
182
+ :return: What was written, ``None`` when its link was already in step.
183
+ """
184
+ if self.link_in_step(description.upstream_link, link):
185
+ return None
186
+ self.fork.set_description(number, description.with_upstream_link(link))
187
+ if link is None:
188
+ return UpstreamPullRequestSynchronizationAction.LINK_REMOVED
189
+ return UpstreamPullRequestSynchronizationAction.LINK_WRITTEN
@@ -0,0 +1,37 @@
1
+ """
2
+ How a pass reads the upstream's open pull requests.
3
+ """
4
+
5
+ from __future__ import annotations
6
+
7
+ from enum import StrEnum
8
+
9
+ from basstler.locations import ClaudeCodeVariable
10
+
11
+ # %% the route
12
+
13
+
14
+ class UpstreamReadRoute(StrEnum):
15
+ """
16
+ How a pass reads the upstream's open pull requests.
17
+ """
18
+
19
+ DIRECT = "direct"
20
+ """
21
+ Through the GitHub API, with the session's own credential.
22
+ """
23
+
24
+ ACTION = "action"
25
+ """
26
+ Through the fork's Action, with the runner's credential.
27
+ """
28
+
29
+ @classmethod
30
+ def for_this_session(cls) -> UpstreamReadRoute:
31
+ """
32
+ :return: :attr:`ACTION` in a Claude Code cloud session, whose proxy refuses the
33
+ upstream's API until the upstream is attached; :attr:`DIRECT` elsewhere.
34
+ """
35
+ if ClaudeCodeVariable.REMOTE.is_true():
36
+ return cls.ACTION
37
+ return cls.DIRECT
File without changes
@@ -0,0 +1,377 @@
1
+ #!/usr/bin/env python3
2
+ """Stacked pull request helper for the fork-staging / upstream-review workflow.
3
+
4
+ GitHub is the single source of truth. The stack is **not** declared in a ledger: it is read from a
5
+ ``board.json`` export of the fork's pull requests, combined with plain ``git``:
6
+
7
+ * dependency tree = each fork pull request's **base branch** (base = parent);
8
+ * ``draft`` <-> ``ready`` = the fork pull request's draft flag;
9
+ * ``in-review`` = an upstream pull request opened from the branch is open, recorded on the board by the export;
10
+ * ``merged`` = the branch is an ancestor of ``<upstream_remote>/<upstream_base>``.
11
+
12
+ ``stack.toml`` carries the shipped defaults (label names, the base branch); the project's committed
13
+ ``.claude/basstler/stack.toml`` names its upstream, and a ``.claude/personal/stack.toml`` on the
14
+ personal-notes branch, if present, layers per-user overrides on top of both (see
15
+ :meth:`basstler.stack.settings.Configuration.load`).
16
+
17
+ Commands (run from the repo root; ``--help`` on any of them for its flags)::
18
+
19
+ python -m basstler.stack status # the whole stack: parent, state, drift
20
+ python -m basstler.stack check # would each branch merge cleanly onto its parent now?
21
+ python -m basstler.stack merge-probe # does one branch merge into another, and where not?
22
+ python -m basstler.stack next # which branches to submit upstream next
23
+ python -m basstler.stack next --porcelain # machine-readable: one 'name<TAB>pull request' line per branch
24
+ python -m basstler.stack restack-plan # bottom-up restack plan as JSON
25
+ python -m basstler.stack configuration # every resolved setting, including the remotes
26
+ python -m basstler.stack labels # the complete label set a write must send
27
+ python -m basstler.stack check-move # may these commits move onto that branch?
28
+ python -m basstler.stack promotion-link # the upstream compare-and-create URL for a branch
29
+ python -m basstler.stack reparents # children whose base has landed, and the base they need
30
+ python -m basstler.stack landed # open fork pull requests whose branch has landed
31
+
32
+ The last five exist so the steps most easily got wrong by hand are computed rather than recalled: a
33
+ label write replaces the whole set, a push whose two sides name different branches moves the wrong
34
+ commits, an unencoded compare URL loses its prefill, and a landed parent is decided by git ancestry
35
+ rather than by pull-request state. ``landed`` reports only. GitHub closes a pull request as merged
36
+ by itself only when its head reaches its own base: the upstream's merge does that for a pull
37
+ request based on the base branch, never for one stacked on another branch, which stays open
38
+ and is what ``landed`` lists.
39
+ """
40
+
41
+ from __future__ import annotations
42
+
43
+ from enum import StrEnum
44
+ from pathlib import Path
45
+ from typing import Annotated
46
+
47
+ from cyclopts import App, Parameter
48
+
49
+ from basstler.exit_codes import CommandFailure, ExitCode, StackExitCode
50
+ from basstler.git.commands import GitCommandRunner
51
+ from basstler.stack.commit_move import (
52
+ CommitMoveAction,
53
+ CommitMoveChecks,
54
+ ProposedCommitMove,
55
+ )
56
+ from basstler.github.repository_option import RepositoryOption
57
+ from basstler.locations import RepositoryStateLocation
58
+ from basstler.stack.label_write import LabelWrite
59
+ from basstler.stack.merge_probe import MergeProbe
60
+ from basstler.stack.model import Stack
61
+ from basstler.stack.promotion_link import PromotionLink
62
+ from basstler.stack.report import StackReport
63
+ from basstler.stack.settings import Configuration
64
+ from basstler.standard_streams import StandardStreamHandler
65
+
66
+ logger = StandardStreamHandler.logger_for(__name__)
67
+ """
68
+ This module's logger, which is also what its command prints through.
69
+ """
70
+
71
+ # %% commands
72
+
73
+
74
+ class Command(StrEnum):
75
+ """Every command this tool answers, named once so no caller spells one out."""
76
+
77
+ STATUS = "status"
78
+ """Render the derived stack, one line per branch."""
79
+
80
+ CHECK = "check"
81
+ """Report every structural problem the derived stack has."""
82
+
83
+ NEXT = "next"
84
+ """Name the branches ready to be promoted upstream."""
85
+
86
+ RESTACK_PLAN = "restack-plan"
87
+ """Emit the bottom-up plan of which branch integrates which parent, and how."""
88
+
89
+ REPARENTS = "reparents"
90
+ """Name the children whose base has landed and must be retargeted."""
91
+
92
+ LANDED = "landed"
93
+ """Name the branches whose own commits are already in the upstream base."""
94
+
95
+ CHECK_MOVE = "check-move"
96
+ """Answer whether a proposed commit move may be made, and refuse it if not."""
97
+
98
+ CONFIGURATION = "configuration"
99
+ """Print the resolved configuration, one ``field<TAB>value`` line per setting."""
100
+
101
+ LABELS = "labels"
102
+ """Compute the complete label set a write must send, from the labels carried now."""
103
+
104
+ PROMOTION_LINK = "promotion-link"
105
+ """Build the upstream compare-and-create link for one branch."""
106
+
107
+ MERGE_PROBE = "merge-probe"
108
+ """Answer whether one branch merges into another, naming every conflicting path."""
109
+
110
+
111
+ class CommandOption(StrEnum):
112
+ """Every option a command takes, named once so no caller spells one out."""
113
+
114
+ PORCELAIN = "--porcelain"
115
+ """Print only what a script reads, for :attr:`Command.NEXT`."""
116
+
117
+ FORK = "--fork"
118
+ """The fork, as ``owner/name``, when the caller already knows it."""
119
+
120
+ UPSTREAM = "--upstream"
121
+ """The upstream, as ``owner/name``, when the caller already knows it."""
122
+
123
+ CURRENT = "--current"
124
+ """A label the pull request carries now, repeated per label."""
125
+
126
+ ADD = "--add"
127
+ """A label to end up with."""
128
+
129
+ REMOVE = "--remove"
130
+ """A label to end up without."""
131
+
132
+ BRANCH = "--branch"
133
+ """The fork branch to build a promotion link for."""
134
+
135
+ TITLE = "--title"
136
+ """The title to prefill."""
137
+
138
+ BODY = "--body"
139
+ """The description to prefill."""
140
+
141
+ ACTION = "--action"
142
+ """What a commit move would do."""
143
+
144
+ SOURCE = "--source"
145
+ """The branch whose commits move."""
146
+
147
+ DESTINATION = "--destination"
148
+ """The branch they would land on."""
149
+
150
+ DESTINATION_REMOTE = "--destination-remote"
151
+ """The remote holding the destination."""
152
+
153
+ REMOTE = "--remote"
154
+ """The remote name or URL the probed branches are fetched from."""
155
+
156
+ BASE = "--base"
157
+ """The branch merged into."""
158
+
159
+ HEAD = "--head"
160
+ """The branch merged."""
161
+
162
+
163
+ # %% reading the inputs
164
+
165
+
166
+ def derived_stack() -> Stack:
167
+ """
168
+ :return: The stack derived from this checkout's ``board.json``.
169
+ :raises CommandFailure: If the board is missing or unreadable.
170
+ """
171
+ return Stack.load(
172
+ GitCommandRunner(Path.cwd()).repository_state_path(
173
+ RepositoryStateLocation.BOARD
174
+ )
175
+ )
176
+
177
+
178
+ # %% commands
179
+
180
+ stack_app = App(
181
+ name="basstler.stack",
182
+ help="Stacked pull request helper: read state, compute the writes.",
183
+ )
184
+ """
185
+ This module's command line: one command per :class:`Command`.
186
+ """
187
+
188
+
189
+ @stack_app.command(name=Command.STATUS)
190
+ def status() -> StackExitCode:
191
+ """
192
+ Print the whole stack: parent, state, drift.
193
+ """
194
+ StackReport(derived_stack()).print_status()
195
+ return StackExitCode.SUCCESS
196
+
197
+
198
+ @stack_app.command(name=Command.CHECK)
199
+ def check() -> StackExitCode:
200
+ """
201
+ Print whether each branch would merge cleanly onto its parent.
202
+ """
203
+ StackReport(derived_stack()).print_check()
204
+ return StackExitCode.SUCCESS
205
+
206
+
207
+ @stack_app.command(name=Command.NEXT)
208
+ def promotable(
209
+ *, porcelain: Annotated[bool, Parameter(name=CommandOption.PORCELAIN)] = False
210
+ ) -> StackExitCode:
211
+ """
212
+ Print which branches to submit upstream next.
213
+
214
+ :param porcelain: Print only a ``name<TAB>pull request`` line per branch.
215
+ """
216
+ report = StackReport(derived_stack())
217
+ if porcelain:
218
+ report.print_next_porcelain()
219
+ else:
220
+ report.print_next()
221
+ return StackExitCode.SUCCESS
222
+
223
+
224
+ @stack_app.command(name=Command.RESTACK_PLAN)
225
+ def restack_plan() -> StackExitCode:
226
+ """
227
+ Print the bottom-up restack plan as JSON.
228
+ """
229
+ StackReport(derived_stack()).print_restack_plan()
230
+ return StackExitCode.SUCCESS
231
+
232
+
233
+ @stack_app.command(name=Command.REPARENTS)
234
+ def reparents() -> StackExitCode:
235
+ """
236
+ Print the children whose base has landed, and the base they need.
237
+ """
238
+ StackReport(derived_stack()).print_reparents()
239
+ return StackExitCode.SUCCESS
240
+
241
+
242
+ @stack_app.command(name=Command.LANDED)
243
+ def landed() -> StackExitCode:
244
+ """
245
+ Print the open pull requests whose branch has landed.
246
+ """
247
+ StackReport(derived_stack()).print_landed()
248
+ return StackExitCode.SUCCESS
249
+
250
+
251
+ @stack_app.command(name=Command.CONFIGURATION)
252
+ def configuration(
253
+ *,
254
+ fork: Annotated[RepositoryOption, Parameter(name=CommandOption.FORK)] = None,
255
+ upstream: Annotated[
256
+ RepositoryOption, Parameter(name=CommandOption.UPSTREAM)
257
+ ] = None,
258
+ ) -> StackExitCode:
259
+ """
260
+ Print every resolved setting, including the remotes.
261
+
262
+ :param fork: The fork as ``owner/name``, when you already know it.
263
+ :param upstream: The upstream as ``owner/name``, when you already know it.
264
+ """
265
+ Configuration.load(
266
+ fork_repository=fork, upstream_repository=upstream
267
+ ).print_settings()
268
+ return StackExitCode.SUCCESS
269
+
270
+
271
+ @stack_app.command(name=Command.LABELS)
272
+ def labels(
273
+ *,
274
+ current: Annotated[tuple[str, ...], Parameter(name=CommandOption.CURRENT)] = (),
275
+ add: Annotated[tuple[str, ...], Parameter(name=CommandOption.ADD)] = (),
276
+ remove: Annotated[tuple[str, ...], Parameter(name=CommandOption.REMOVE)] = (),
277
+ ) -> StackExitCode:
278
+ """
279
+ Print the complete label set a label write must send.
280
+
281
+ :param current: A label the pull request carries now; repeat per label.
282
+ :param add: A label to end up with.
283
+ :param remove: A label to end up without.
284
+ """
285
+ LabelWrite.replacing(current, add, remove).print_labels()
286
+ return StackExitCode.SUCCESS
287
+
288
+
289
+ @stack_app.command(name=Command.PROMOTION_LINK)
290
+ def promotion_link(
291
+ *,
292
+ branch: Annotated[str, Parameter(name=CommandOption.BRANCH)],
293
+ title: Annotated[str, Parameter(name=CommandOption.TITLE)],
294
+ body: Annotated[str, Parameter(name=CommandOption.BODY)] = "",
295
+ ) -> StackExitCode:
296
+ """
297
+ Print the upstream compare-and-create URL for a branch.
298
+
299
+ :param branch: The fork branch to promote.
300
+ :param title: The title to prefill.
301
+ :param body: The description to prefill.
302
+ """
303
+ PromotionLink.build(Configuration.load(), branch, title, body).print_url()
304
+ return StackExitCode.SUCCESS
305
+
306
+
307
+ @stack_app.command(name=Command.MERGE_PROBE)
308
+ def merge_probe(
309
+ *,
310
+ remote: Annotated[str, Parameter(name=CommandOption.REMOTE)],
311
+ base: Annotated[str, Parameter(name=CommandOption.BASE)],
312
+ head: Annotated[str, Parameter(name=CommandOption.HEAD)],
313
+ ) -> StackExitCode:
314
+ """
315
+ Report whether one branch merges into another, and where it conflicts.
316
+
317
+ :param remote: The remote name or URL, except that the upstream base of a project
318
+ naming an upstream is read from the upstream.
319
+ :param base: The branch merged into.
320
+ :param head: The branch merged.
321
+ """
322
+ result = MergeProbe(
323
+ head_location=remote,
324
+ base_location=Configuration.location_of(base, remote),
325
+ base=base,
326
+ head=head,
327
+ ).run(Path.cwd())
328
+ result.print_report()
329
+ return result.exit_code
330
+
331
+
332
+ @stack_app.command(name=Command.CHECK_MOVE)
333
+ def check_move(
334
+ *,
335
+ action: Annotated[CommitMoveAction, Parameter(name=CommandOption.ACTION)],
336
+ source: Annotated[str, Parameter(name=CommandOption.SOURCE)],
337
+ destination: Annotated[str, Parameter(name=CommandOption.DESTINATION)],
338
+ destination_remote: Annotated[
339
+ str, Parameter(name=CommandOption.DESTINATION_REMOTE)
340
+ ],
341
+ ) -> StackExitCode:
342
+ """
343
+ Report whether these commits may move onto that branch.
344
+
345
+ :param action: What the move would do.
346
+ :param source: The branch whose commits move.
347
+ :param destination: The branch they would land on.
348
+ :param destination_remote: The remote holding the destination.
349
+ """
350
+ return CommitMoveChecks.of_checkout(derived_stack()).print_verdict(
351
+ ProposedCommitMove(
352
+ action=action,
353
+ source=source,
354
+ destination=destination,
355
+ destination_remote=destination_remote,
356
+ ),
357
+ )
358
+
359
+
360
+ # %% entry point
361
+
362
+
363
+ def main() -> ExitCode:
364
+ """
365
+ Run the invoked command, ending with the status a refusal carries.
366
+
367
+ :return: The process exit code.
368
+ """
369
+ try:
370
+ return stack_app(result_action="return_value")
371
+ except CommandFailure as error:
372
+ logger.error(f"{error}")
373
+ return error.exit_code
374
+
375
+
376
+ if __name__ == "__main__":
377
+ raise SystemExit(main())
@@ -0,0 +1,54 @@
1
+ """
2
+ A stack node's lifecycle position.
3
+ """
4
+
5
+ from __future__ import annotations
6
+
7
+ from enum import StrEnum
8
+
9
+ # %% lifecycle
10
+
11
+
12
+ class BranchStatus(StrEnum):
13
+ """
14
+ A stack node's lifecycle position.
15
+ """
16
+
17
+ DRAFT = "draft"
18
+ """
19
+ Its author has not yet reviewed it themselves, so it may not be promoted.
20
+ """
21
+
22
+ READY = "ready"
23
+ """Out of draft - reviewed by its author, and promotable once its parent has merged."""
24
+
25
+ IN_REVIEW = "in-review"
26
+ """
27
+ Promoted to the upstream, where it waits on that queue rather than on us.
28
+ """
29
+
30
+ MERGED = "merged"
31
+ """
32
+ Its own commits are already contained in the upstream base.
33
+ """
34
+
35
+ @classmethod
36
+ def derive(cls, draft: bool, merged: bool, in_review: bool) -> BranchStatus:
37
+ """
38
+ Map a pull request's raw facts to a lifecycle status.
39
+
40
+ Precedence: a merged branch is ``merged``; a branch under upstream review is
41
+ ``in-review``; an un-drafted branch is ``ready`` (self-approved for promotion);
42
+ otherwise ``draft``.
43
+
44
+ :param draft: Whether the pull request is still a draft.
45
+ :param merged: Whether the branch has landed upstream (git ancestry).
46
+ :param in_review: Whether an upstream pull request opened from the branch is
47
+ open.
48
+ :return: The derived status.
49
+ """
50
+ if merged:
51
+ return cls.MERGED
52
+ if in_review:
53
+ return cls.IN_REVIEW
54
+ return cls.DRAFT if draft else cls.READY