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,696 @@
1
+ """
2
+ The stack itself: the fork's pull requests, the branches they describe, and what the
3
+ stack derives from them.
4
+
5
+ The dependency tree is each fork pull request's base branch (base = parent). A branch is
6
+ ``draft`` or ``ready`` by its pull request's draft flag, ``in-review`` while an upstream
7
+ pull request opened from it is open, and ``merged`` once git finds it contained in
8
+ ``<upstream_remote>/<upstream_base>``.
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ import json
14
+ from collections.abc import Callable
15
+ from dataclasses import dataclass, field, replace
16
+ from enum import StrEnum
17
+ from pathlib import Path
18
+ from typing import Any
19
+
20
+ from basstler.git.branch import Branch
21
+ from basstler.git.commands import IntegrationStrategy
22
+ from basstler.github.repository import Repository
23
+ from basstler.github.states import CombinedCheckState
24
+ from basstler.github.tooling_labels import GitHubLabel
25
+ from basstler.github.branch_pull_request import BranchPullRequest
26
+ from basstler.stack.branch_status import BranchStatus
27
+ from basstler.stack.checkout import CurrentCheckout, ForkRefresh, LandedBranches
28
+ from basstler.stack.exceptions import BaseBranchScopeError, BoardUnavailable
29
+ from basstler.stack.promotability import PromotionReadiness
30
+ from basstler.stack.settings import Configuration
31
+ from basstler.text_file import TextFile
32
+
33
+ # %% domain model
34
+
35
+
36
+ class SkipReason(StrEnum):
37
+ """Why a pull request open on the fork is left out of the pass that maintains it."""
38
+
39
+ HEAD_ON_ANOTHER_FORK = "head-on-another-fork"
40
+ """Its head branch lives on another contributor's fork, which the pass cannot push
41
+ to."""
42
+
43
+ HEAD_REPOSITORY_DELETED = "head-repository-deleted"
44
+ """The repository its head branch lived in has been deleted, so there is no branch
45
+ left to maintain."""
46
+
47
+
48
+ class BoardKey(StrEnum):
49
+ """
50
+ The keys of ``board.json`` that are not a :class:`PullRequest` field.
51
+ """
52
+
53
+ PULL_REQUESTS = "pull_requests"
54
+ """
55
+ The exported pull requests, one object per :class:`PullRequest`.
56
+ """
57
+
58
+
59
+ @dataclass
60
+ class PullRequest:
61
+ """One fork pull request as exported into ``board.json``."""
62
+
63
+ number: int
64
+ """The pull request number on the fork."""
65
+
66
+ head: str
67
+ """The pull request's head branch - the branch this stack node names."""
68
+
69
+ base: str
70
+ """The pull request's base branch - its parent in the stack (``base = parent``)."""
71
+
72
+ draft: bool
73
+ """Whether the pull request is a draft (not yet approved for review)."""
74
+
75
+ head_repository: str | None
76
+ """The ``owner/name`` of the repository the head branch lives in, ``None`` once that
77
+ repository is deleted."""
78
+
79
+ labels: list[str] = field(default_factory=list)
80
+ """Labels currently on the pull request."""
81
+
82
+ check_state: CombinedCheckState = CombinedCheckState.NOT_REPORTED
83
+ """The verdict over every check and commit status reported on the pull request's
84
+ head."""
85
+
86
+ upstream_pull_request: int | None = None
87
+ """The number of the open upstream pull request opened from the head branch, ``None``
88
+ while none is open."""
89
+
90
+ session: str | None = None
91
+ """URL of the Claude session working this pull request, parsed from the pull request body (None if none)."""
92
+
93
+ title: str | None = None
94
+ """The pull request's title, ``None`` when the export did not carry one."""
95
+
96
+ description: str | None = None
97
+ """The pull request's description without the sections a pass writes,
98
+ ``None`` when the export did not carry one."""
99
+
100
+ upstream_link: str | None = None
101
+ """The URL of the upstream pull request a pass linked in the pull request body,
102
+ ``None`` while none is linked."""
103
+
104
+ def skip_reason(self, fork: Repository) -> SkipReason | None:
105
+ """:param fork: The fork the pass maintains.
106
+ :return: Why the pass has to leave this pull request out, ``None`` when its head
107
+ is a branch of *fork*."""
108
+ if self.head_repository is None:
109
+ return SkipReason.HEAD_REPOSITORY_DELETED
110
+ if self.head_repository != fork.full_name:
111
+ return SkipReason.HEAD_ON_ANOTHER_FORK
112
+ return None
113
+
114
+ @classmethod
115
+ def read_board(cls, path: Path) -> list[PullRequest]:
116
+ """Parse ``board.json`` into the list of fork pull requests.
117
+
118
+ :param path: The board export file.
119
+ :return: The exported pull requests.
120
+ :raises BoardUnavailable: If *path* does not exist.
121
+ """
122
+ if not path.exists():
123
+ raise BoardUnavailable(path)
124
+ board = json.loads(TextFile(path).read())
125
+ return [cls.from_board_entry(entry) for entry in board[BoardKey.PULL_REQUESTS]]
126
+
127
+ @classmethod
128
+ def from_board_entry(cls, entry: dict[str, Any]) -> PullRequest:
129
+ """:param entry: One pull request as ``board.json`` holds it.
130
+ :return: The pull request, its check state read back as its verdict."""
131
+ pull_request = cls(**entry)
132
+ return replace(
133
+ pull_request, check_state=CombinedCheckState(pull_request.check_state)
134
+ )
135
+
136
+
137
+ @dataclass(frozen=True)
138
+ class StackBranch(Branch[Repository]):
139
+ """A stack node derived from a fork pull request plus git state, named after the pull
140
+ request's head."""
141
+
142
+ parent: str
143
+ """The parent branch (the pull request base)."""
144
+
145
+ pull_request_number: int
146
+ """The fork pull request number."""
147
+
148
+ status: BranchStatus
149
+ """Lifecycle status."""
150
+
151
+ strategy: IntegrationStrategy
152
+ """Integration strategy onto the parent."""
153
+
154
+ labels: list[str]
155
+ """Labels carried by the pull request."""
156
+
157
+ skipped_pull_request: SkippedPullRequest | None
158
+ """The pull request in its role as one the pass leaves out, ``None`` when the branch
159
+ is on the fork."""
160
+
161
+ check_state: CombinedCheckState = CombinedCheckState.NOT_REPORTED
162
+ """The verdict over the checks reported on the pull request head."""
163
+
164
+ upstream_pull_request: int | None = None
165
+ """The open upstream pull request opened from this branch, if any."""
166
+
167
+ session: str | None = None
168
+ """URL of the Claude session working this pull request, if any."""
169
+
170
+ title: str | None = None
171
+ """The pull request's title, if known."""
172
+
173
+ description: str | None = None
174
+ """The pull request's description without the sections a pass writes, if known."""
175
+
176
+ @property
177
+ def owner_address(self) -> str:
178
+ """:return: The session link to address a comment to, or a note that the
179
+ description names none."""
180
+ if self.session:
181
+ return f"\n\n{self.session}"
182
+ return "\n\nThis pull request's description names no session to address."
183
+
184
+ upstream_link: str | None = None
185
+ """The URL of the upstream pull request linked on the pull request, if any."""
186
+
187
+ @property
188
+ def checks_failed(self) -> bool:
189
+ """:return: Whether the checks on the pull request head have failed."""
190
+ return self.check_state.failed
191
+
192
+ @classmethod
193
+ def from_pull_request(
194
+ cls,
195
+ pull_request: PullRequest,
196
+ configuration: Configuration,
197
+ is_merged: Callable[[str], bool],
198
+ ) -> StackBranch:
199
+ """:param pull_request: The exported pull request the node names.
200
+ :param configuration: The static configuration naming the labels.
201
+ :param is_merged: Maps a branch name to whether it has landed upstream.
202
+ :return: The stack node the pull request describes."""
203
+ skip_reason = pull_request.skip_reason(configuration.fork_repository)
204
+ return cls(
205
+ repository=configuration.fork_repository,
206
+ name=pull_request.head,
207
+ parent=pull_request.base,
208
+ pull_request_number=pull_request.number,
209
+ status=BranchStatus.derive(
210
+ pull_request.draft,
211
+ is_merged(pull_request.head),
212
+ pull_request.upstream_pull_request is not None,
213
+ ),
214
+ strategy=(
215
+ IntegrationStrategy.REBASE
216
+ if configuration.rebase_label in pull_request.labels
217
+ else IntegrationStrategy.MERGE
218
+ ),
219
+ labels=pull_request.labels,
220
+ skipped_pull_request=(
221
+ None
222
+ if skip_reason is None
223
+ else SkippedPullRequest(pull_request, skip_reason)
224
+ ),
225
+ check_state=pull_request.check_state,
226
+ upstream_pull_request=pull_request.upstream_pull_request,
227
+ session=pull_request.session,
228
+ title=pull_request.title,
229
+ description=pull_request.description,
230
+ upstream_link=pull_request.upstream_link,
231
+ )
232
+
233
+
234
+ @dataclass(frozen=True)
235
+ class RestackPlanEntry:
236
+ """One entry of :meth:`Stack.restack_plan`: a branch, and what and how it is brought up to date with."""
237
+
238
+ branch: str
239
+ """The branch to bring up to date."""
240
+
241
+ parent: str
242
+ """The branch it is brought up to date with."""
243
+
244
+ strategy: IntegrationStrategy
245
+ """How it is brought up to date."""
246
+
247
+
248
+ @dataclass(frozen=True)
249
+ class SkippedPullRequest:
250
+ """The role of a pull request open on the fork that the pass leaves alone.
251
+
252
+ It is neither restacked, promoted nor reported as landed, and nothing is written to
253
+ it; only its base can still be retargeted, through :meth:`Stack.reparents`.
254
+ """
255
+
256
+ pull_request: PullRequest
257
+ """The pull request taking the role."""
258
+
259
+ reason: SkipReason
260
+ """Why it is left alone."""
261
+
262
+
263
+ @dataclass(frozen=True)
264
+ class Reparent(BranchPullRequest):
265
+ """A pull request whose base has landed and must be retargeted at the upstream base.
266
+
267
+ A child left on a landed base cannot reach the upstream, and is closed outright the
268
+ moment that base branch is deleted.
269
+ """
270
+
271
+ current_base: str
272
+ """The landed branch it is still targeting."""
273
+
274
+ target_base: str
275
+ """The base it must be retargeted at."""
276
+
277
+
278
+ class ParentSituation(StrEnum):
279
+ """Where a parent branch's commits are, which decides what its child builds on."""
280
+
281
+ TRACKED = "tracked"
282
+ """It is the upstream base, or a branch an open pull request on the board describes."""
283
+
284
+ LANDED = "landed"
285
+ """Its commits are in the upstream base."""
286
+
287
+ IN_ANOTHER_BRANCH = "in-another-branch"
288
+ """Its commits are in another branch of the stack, having merged there rather than
289
+ upstream."""
290
+
291
+ GONE = "gone"
292
+ """Its commits are in nothing the stack can see, so no base follows from them."""
293
+
294
+
295
+ @dataclass(frozen=True)
296
+ class EffectiveParent:
297
+ """The branch a child has to build on now, and what became of the one it names."""
298
+
299
+ branch: str
300
+ """The branch to build on, which is the named parent itself when nothing carries it."""
301
+
302
+ situation: ParentSituation
303
+ """What became of the named parent."""
304
+
305
+
306
+ @dataclass
307
+ class Stack:
308
+ """The whole stack: configuration plus the branches derived from GitHub and git."""
309
+
310
+ configuration: Configuration
311
+ """The static configuration."""
312
+
313
+ branches: list[StackBranch]
314
+ """The derived stack nodes."""
315
+
316
+ is_merged: Callable[[str], bool]
317
+ """Maps any branch name - tracked by this stack or not - to whether it has landed
318
+ upstream."""
319
+
320
+ is_contained_by: Callable[[str, str], bool]
321
+ """Maps a pair of branch names to whether the first's commits are in the second."""
322
+
323
+ fork_refresh: ForkRefresh = ForkRefresh()
324
+ """What refreshing the fork's references left out."""
325
+
326
+ @classmethod
327
+ def build(
328
+ cls,
329
+ configuration: Configuration,
330
+ pull_requests: list[PullRequest],
331
+ is_merged: Callable[[str], bool],
332
+ is_contained_by: Callable[[str, str], bool],
333
+ fork_refresh: ForkRefresh | None = None,
334
+ ) -> Stack:
335
+ """Assemble the stack from the pull request export and the two git facts it needs.
336
+
337
+ :param configuration: The static configuration.
338
+ :param pull_requests: The exported pull requests.
339
+ :param is_merged: Maps a branch name to whether it has landed upstream; injected so
340
+ the pure assembly logic can be tested without git.
341
+ :param is_contained_by: Maps a pair of branch names to whether the first's commits
342
+ are in the second, injected for the same reason.
343
+ :param fork_refresh: What refreshing the fork's references left out, nothing when
344
+ omitted.
345
+ :return: The assembled stack.
346
+ """
347
+ return cls(
348
+ configuration=configuration,
349
+ branches=[
350
+ StackBranch.from_pull_request(pull_request, configuration, is_merged)
351
+ for pull_request in pull_requests
352
+ ],
353
+ is_merged=is_merged,
354
+ is_contained_by=is_contained_by,
355
+ fork_refresh=fork_refresh or ForkRefresh(),
356
+ )
357
+
358
+ @classmethod
359
+ def load(cls, board: Path) -> Stack:
360
+ """:param board: The exported board to derive the stack from.
361
+ :return: The full live stack: configuration + board export + git merged-detection.
362
+ :raises BoardUnavailable: If *board* does not exist.
363
+ """
364
+ return cls.from_pull_requests(PullRequest.read_board(board))
365
+
366
+ @classmethod
367
+ def from_pull_requests(cls, pull_requests: list[PullRequest]) -> Stack:
368
+ """:param pull_requests: The fork's open pull requests, as a board holds them.
369
+ :return: The full live stack: configuration + those pull requests + git
370
+ merged-detection.
371
+ """
372
+ configuration = Configuration.load()
373
+ heads_on_fork = {
374
+ pull_request.head
375
+ for pull_request in pull_requests
376
+ if pull_request.skip_reason(configuration.fork_repository) is None
377
+ }
378
+ bases = {pull_request.base for pull_request in pull_requests}
379
+ fork_refresh = CurrentCheckout.fetch(
380
+ configuration, sorted(heads_on_fork | bases)
381
+ )
382
+ return cls.build(
383
+ configuration,
384
+ pull_requests,
385
+ LandedBranches.from_checkout(configuration).contains,
386
+ CurrentCheckout.containment_predicate(configuration),
387
+ fork_refresh,
388
+ )
389
+
390
+ def maintained_branches(self) -> list[StackBranch]:
391
+ """The branches this pass can restack, promote and write to, parent before child.
392
+
393
+ :return: Every branch whose head is on the fork.
394
+ """
395
+ return [
396
+ branch for branch in self.ordered() if branch.skipped_pull_request is None
397
+ ]
398
+
399
+ def skipped_pull_requests(self) -> list[SkippedPullRequest]:
400
+ """:return: Every pull request the pass leaves alone, parent before child."""
401
+ return [
402
+ branch.skipped_pull_request
403
+ for branch in self.ordered()
404
+ if branch.skipped_pull_request is not None
405
+ ]
406
+
407
+ def needs_resolution(self, branch: StackBranch) -> bool:
408
+ """:param branch: The branch to check.
409
+ :return: Whether the branch is withheld from promotion pending conflict resolution.
410
+ """
411
+ return self.configuration.needs_resolution_label in branch.labels
412
+
413
+ def has_landed_upstream(self, branch_name: str) -> bool:
414
+ """Whether a branch's commits are already in the upstream base.
415
+
416
+ Answered from git ancestry, so it holds for any branch name - including one no open
417
+ pull request describes, which the board therefore never mentions.
418
+
419
+ :param branch_name: The branch to check.
420
+ :return: Whether its commits are in the upstream base.
421
+ """
422
+ return branch_name == self.configuration.upstream_base or self.is_merged(
423
+ branch_name
424
+ )
425
+
426
+ def tracks(self, branch_name: str) -> bool:
427
+ """:param branch_name: The branch to look for.
428
+ :return: Whether an open pull request on the board describes it."""
429
+ return any(branch.name == branch_name for branch in self.branches)
430
+
431
+ def effective_parent(self, branch: StackBranch) -> EffectiveParent:
432
+ """Where a branch's parent went, and what the branch therefore builds on.
433
+
434
+ :param branch: The branch whose parent to place.
435
+ :return: The branch to build on, and what became of the named parent.
436
+ """
437
+ parent = branch.parent
438
+ if parent == self.configuration.upstream_base:
439
+ return EffectiveParent(parent, ParentSituation.TRACKED)
440
+ if self.has_landed_upstream(parent):
441
+ return EffectiveParent(
442
+ self.configuration.upstream_base, ParentSituation.LANDED
443
+ )
444
+ if self.tracks(parent):
445
+ return EffectiveParent(parent, ParentSituation.TRACKED)
446
+ carrier = self.carrier_of(branch)
447
+ if carrier is None:
448
+ return EffectiveParent(parent, ParentSituation.GONE)
449
+ return EffectiveParent(carrier, ParentSituation.IN_ANOTHER_BRANCH)
450
+
451
+ def carrier_of(self, branch: StackBranch) -> str | None:
452
+ """The open branch that holds the commits of a branch's absent parent.
453
+
454
+ Branches stacked on *branch* are skipped, since they hold the parent too.
455
+
456
+ :param branch: The branch whose absent parent to find.
457
+ :return: The first such branch, parent before child, or ``None`` when there is none.
458
+ """
459
+ stacked_on_branch = {branch.name}
460
+ for candidate in self.ordered():
461
+ if (
462
+ candidate.name in stacked_on_branch
463
+ or candidate.parent in stacked_on_branch
464
+ ):
465
+ stacked_on_branch.add(candidate.name)
466
+ elif self.is_contained_by(branch.parent, candidate.name):
467
+ return candidate.name
468
+ return None
469
+
470
+ def ordered(self) -> list[StackBranch]:
471
+ """:return: The branches, topologically ordered so a parent always precedes its
472
+ children."""
473
+ by_name = {branch.name: branch for branch in self.branches}
474
+ ordered: list[StackBranch] = []
475
+ seen: set[str] = set()
476
+
477
+ def visit(branch: StackBranch) -> None:
478
+ if branch.name in seen:
479
+ return
480
+ seen.add(branch.name)
481
+ parent = by_name.get(branch.parent)
482
+ if parent is not None:
483
+ visit(parent)
484
+ ordered.append(branch)
485
+
486
+ for branch in self.branches:
487
+ visit(branch)
488
+ return ordered
489
+
490
+ def branches_stacked_on(self, branch_name: str) -> list[StackBranch]:
491
+ """Every not-yet-merged branch whose parent chain reaches *branch_name*.
492
+
493
+ A branch is stacked on another when its pull request's base is that branch,
494
+ directly or through the branches between them - the same parent relation
495
+ :meth:`restack_plan` works from. A merged branch is left out along with everything
496
+ only it carries, since its commits are already in the upstream base.
497
+
498
+ :param branch_name: The branch whose subtree is wanted; it is never in the result.
499
+ :return: The branches stacked on it, parent before child.
500
+ """
501
+ stacked: set[str] = set()
502
+ found = []
503
+ for branch in self.maintained_branches():
504
+ if branch.status == BranchStatus.MERGED:
505
+ continue
506
+ if branch.parent != branch_name and branch.parent not in stacked:
507
+ continue
508
+ stacked.add(branch.name)
509
+ found.append(branch)
510
+ return found
511
+
512
+ def scoped_to(self, branch_name: str | None) -> Stack:
513
+ """
514
+ The part of this stack one branch belongs to.
515
+
516
+ :param branch_name: The branch to scope to, or ``None`` for the whole stack.
517
+ :return: A stack of the branch, the branches it is stacked on and the branches
518
+ stacked on it; empty when no pull request names the branch or anything
519
+ stacked on it.
520
+ :raises BaseBranchScopeError: When *branch_name* is the upstream base.
521
+ """
522
+ if branch_name is None:
523
+ return self
524
+ if branch_name == self.configuration.upstream_base:
525
+ raise BaseBranchScopeError(upstream_base=branch_name)
526
+ by_name = {branch.name: branch for branch in self.branches}
527
+ kept = {branch.name for branch in self.branches_stacked_on(branch_name)}
528
+ beneath = by_name.get(branch_name)
529
+ while beneath is not None and beneath.name not in kept:
530
+ kept.add(beneath.name)
531
+ beneath = by_name.get(beneath.parent)
532
+ return replace(
533
+ self, branches=[branch for branch in self.branches if branch.name in kept]
534
+ )
535
+
536
+ def parent_landed(self, branch: StackBranch) -> bool:
537
+ """Whether a branch's parent has merged into its base, so it can promote.
538
+
539
+ A parent still in review does not count: the upstream pull request is compared
540
+ against the upstream base, so it would carry the parent's commits too.
541
+
542
+ A parent no open fork pull request describes is not on the board, so git ancestry
543
+ is the only evidence available for it - and absence from the board is not itself
544
+ evidence of a root branch.
545
+
546
+ :param branch: The branch to check.
547
+ :return: Whether the branch's parent has landed.
548
+ """
549
+ effective_parent = self.effective_parent(branch)
550
+ if effective_parent.situation is not ParentSituation.TRACKED:
551
+ return effective_parent.situation is ParentSituation.LANDED
552
+ parent = next(
553
+ (
554
+ candidate
555
+ for candidate in self.branches
556
+ if candidate.name == branch.parent
557
+ ),
558
+ None,
559
+ )
560
+ if parent is None:
561
+ return True
562
+ return parent.status is BranchStatus.MERGED
563
+
564
+ def integration_parent(self, branch: StackBranch) -> str:
565
+ """
566
+ :param branch: A branch of the stack.
567
+ :return: What it is brought up to date with: its parent, or the branch that now
568
+ carries the parent's commits - the upstream base once the parent landed.
569
+ """
570
+ return self.effective_parent(branch).branch
571
+
572
+ def readiness_of(self, branch: StackBranch) -> PromotionReadiness:
573
+ """
574
+ :param branch: A branch of the stack.
575
+ :return: The facts deciding whether it may be promoted, and what they say.
576
+ """
577
+ return PromotionReadiness(
578
+ status=branch.status,
579
+ parent_landed=self.parent_landed(branch),
580
+ withheld=self.needs_resolution(branch),
581
+ checks_failed=branch.checks_failed,
582
+ )
583
+
584
+ def promotion_order(self) -> list[StackBranch]:
585
+ """The branches to submit to the upstream next, in dependency order.
586
+
587
+ A branch is a candidate when it is approved (``ready``), its parent has landed, it
588
+ has not been withheld pending conflict resolution, and its checks have not failed.
589
+ Every such branch promotes together - there is no admission cap or per-stack slot
590
+ limit. A project with no upstream promotes nothing.
591
+
592
+ :return: The promotable branches, in dependency order.
593
+ """
594
+ if not self.configuration.has_upstream:
595
+ return []
596
+ return [
597
+ branch
598
+ for branch in self.maintained_branches()
599
+ if self.readiness_of(branch).is_promotable
600
+ ]
601
+
602
+ def withheld_by_failing_checks(self) -> list[StackBranch]:
603
+ """
604
+ :return: Every approved branch whose parent has landed but whose checks failed,
605
+ in dependency order; none for a project with no upstream to promote to.
606
+ """
607
+ if not self.configuration.has_upstream:
608
+ return []
609
+ return [
610
+ branch
611
+ for branch in self.maintained_branches()
612
+ if branch.status == BranchStatus.READY
613
+ and self.parent_landed(branch)
614
+ and branch.checks_failed
615
+ ]
616
+
617
+ def awaiting_promotion_link(self) -> list[StackBranch]:
618
+ """
619
+ :return: The branches of :meth:`promotion_order` whose upstream link no pass has
620
+ recorded yet, in dependency order.
621
+ """
622
+ return [
623
+ branch
624
+ for branch in self.promotion_order()
625
+ if GitHubLabel.PROMOTION_LINK_SENT not in branch.labels
626
+ ]
627
+
628
+ def restack_plan(self, stacked_on: str | None = None) -> list[RestackPlanEntry]:
629
+ """The bottom-up restack plan the ``restack`` workflow consumes as its arguments.
630
+
631
+ One entry per branch not yet ``merged``, in parent-before-child order. In-review
632
+ branches are included so they pick up a moved parent; their ``merge`` strategy never
633
+ rewrites their own commits, only replaces the merges earlier restacks left, so an
634
+ open review keeps its history.
635
+
636
+ When a branch's parent has **merged** into the upstream, its commits are already in
637
+ the base, so the child is reparented onto the upstream base: the restack rebases it
638
+ there and it stops depending on a landed (and about-to-be-closed) branch. The
639
+ maintenance skill mirrors this by retargeting the child pull request's base to the upstream base on
640
+ GitHub. This holds however the parent landed - including when its own pull request
641
+ was closed rather than merged, leaving the board with no entry for it at all.
642
+
643
+ Naming a branch in *stacked_on* limits the plan to that branch's own subtree.
644
+
645
+ :param stacked_on: The branch whose subtree to plan, or ``None`` for every branch.
646
+ :return: The restack plan, one entry per planned branch.
647
+ """
648
+ planned = (
649
+ self.maintained_branches()
650
+ if stacked_on is None
651
+ else self.branches_stacked_on(stacked_on)
652
+ )
653
+ return [
654
+ RestackPlanEntry(
655
+ branch=branch.name,
656
+ parent=self.integration_parent(branch),
657
+ strategy=branch.strategy,
658
+ )
659
+ for branch in planned
660
+ if branch.status != BranchStatus.MERGED
661
+ ]
662
+
663
+ def reparents(self) -> list[Reparent]:
664
+ """Every open pull request whose base left the board with its commits elsewhere.
665
+
666
+ A base whose commits reached nothing is not listed, since no target follows.
667
+
668
+ :return: The children to retarget, parent before child.
669
+ """
670
+ retargeting = {ParentSituation.LANDED, ParentSituation.IN_ANOTHER_BRANCH}
671
+ return [
672
+ Reparent(
673
+ branch=branch.name,
674
+ pull_request_number=branch.pull_request_number,
675
+ current_base=branch.parent,
676
+ target_base=self.effective_parent(branch).branch,
677
+ )
678
+ for branch in self.ordered()
679
+ if branch.status != BranchStatus.MERGED
680
+ and self.effective_parent(branch).situation in retargeting
681
+ ]
682
+
683
+ def landed_branches(self) -> list[StackBranch]:
684
+ """Every open fork pull request whose own branch is already in the upstream base.
685
+
686
+ These are the ones to label as landed and close; their children are named
687
+ separately by :meth:`reparents`, which must be acted on first so none is ever
688
+ orphaned.
689
+
690
+ :return: The landed branches, parent before child.
691
+ """
692
+ return [
693
+ branch
694
+ for branch in self.maintained_branches()
695
+ if branch.status == BranchStatus.MERGED
696
+ ]