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,103 @@
1
+ """
2
+ The one rule deciding whether a branch may be promoted to the upstream.
3
+ """
4
+
5
+ from __future__ import annotations
6
+
7
+ from dataclasses import dataclass
8
+ from enum import StrEnum
9
+
10
+ from basstler.stack.branch_status import BranchStatus
11
+
12
+ # %% why a branch is not promotable
13
+
14
+
15
+ class PromotionBlocker(StrEnum):
16
+ """
17
+ One reason a branch may not be promoted, worded for the reader it is shown to.
18
+ """
19
+
20
+ DRAFT = "its pull request is still a draft"
21
+ """
22
+ Its author has not yet reviewed it.
23
+ """
24
+
25
+ IN_REVIEW = "an upstream pull request is already open for it"
26
+ """
27
+ It was promoted already.
28
+ """
29
+
30
+ MERGED = "it has already landed upstream"
31
+ """
32
+ Its commits are in the upstream base.
33
+ """
34
+
35
+ PARENT_NOT_LANDED = "the branch it is stacked on has not landed upstream yet"
36
+ """
37
+ Promoting it now would carry its parent's commits too.
38
+ """
39
+
40
+ WITHHELD = "it is withheld until its conflicts are resolved"
41
+ """
42
+ It carries the label marking a pending conflict resolution.
43
+ """
44
+
45
+ CHECKS_FAILED = "the checks on its pull request have failed"
46
+ """
47
+ Its head reports a failing check.
48
+ """
49
+
50
+
51
+ @dataclass(frozen=True)
52
+ class PromotionReadiness:
53
+ """
54
+ The facts that decide whether one branch may be promoted, and what they say.
55
+ """
56
+
57
+ status: BranchStatus
58
+ """
59
+ The branch's lifecycle position.
60
+ """
61
+
62
+ parent_landed: bool
63
+ """
64
+ Whether the branch it is stacked on has landed upstream.
65
+ """
66
+
67
+ withheld: bool
68
+ """
69
+ Whether the branch is withheld pending conflict resolution.
70
+ """
71
+
72
+ checks_failed: bool
73
+ """
74
+ Whether the checks on its pull request head have failed.
75
+ """
76
+
77
+ @property
78
+ def blockers(self) -> list[PromotionBlocker]:
79
+ """
80
+ :return: Every reason the branch may not be promoted, empty when it may; an
81
+ open upstream pull request is the only one given, as it makes the rest moot.
82
+ """
83
+ if self.status is BranchStatus.IN_REVIEW:
84
+ return [PromotionBlocker.IN_REVIEW]
85
+ return [
86
+ blocker
87
+ for blocker, applies in (
88
+ (PromotionBlocker.DRAFT, self.status is BranchStatus.DRAFT),
89
+ (PromotionBlocker.IN_REVIEW, self.status is BranchStatus.IN_REVIEW),
90
+ (PromotionBlocker.MERGED, self.status is BranchStatus.MERGED),
91
+ (PromotionBlocker.PARENT_NOT_LANDED, not self.parent_landed),
92
+ (PromotionBlocker.WITHHELD, self.withheld),
93
+ (PromotionBlocker.CHECKS_FAILED, self.checks_failed),
94
+ )
95
+ if applies
96
+ ]
97
+
98
+ @property
99
+ def is_promotable(self) -> bool:
100
+ """
101
+ :return: Whether nothing holds the branch back.
102
+ """
103
+ return not self.blockers
@@ -0,0 +1,138 @@
1
+ """
2
+ The one-click link that opens a fork branch's pull request on the upstream.
3
+ """
4
+
5
+ from __future__ import annotations
6
+
7
+ from dataclasses import dataclass
8
+
9
+ from basstler.git.branch import Branch
10
+ from basstler.class_property import classproperty
11
+ from basstler.github.pull_request_form import (
12
+ PrefilledPullRequestLink,
13
+ PullRequestForm,
14
+ )
15
+ from basstler.github.repository import Repository
16
+ from basstler.github.stack_configuration import (
17
+ CommittedStackConfiguration,
18
+ MissingUpstreamRepositoryError,
19
+ )
20
+ from basstler.locations import ProjectLocation
21
+ from basstler.stack.exceptions import PromotionLinkTooLongError
22
+ from basstler.stack.settings import Configuration
23
+ from basstler.standard_streams import StandardStreamHandler
24
+
25
+ logger = StandardStreamHandler.logger_for(__name__)
26
+ """
27
+ This module's logger, which is also what its command prints through.
28
+ """
29
+
30
+ # %% promotion links
31
+
32
+
33
+ @dataclass(frozen=True)
34
+ class PromotionTarget:
35
+ """
36
+ Where a fork branch is promoted to: the upstream branch, and the fork the branch
37
+ lives in.
38
+ """
39
+
40
+ upstream_base: Branch[Repository]
41
+ """
42
+ The upstream branch the pull request merges into, on the repository it is opened on.
43
+ """
44
+
45
+ fork: Repository
46
+ """
47
+ The fork the promoted branch lives in.
48
+ """
49
+
50
+ @classmethod
51
+ def from_configuration(cls, configuration: Configuration) -> PromotionTarget:
52
+ """
53
+ :param configuration: The resolved configuration naming both repositories.
54
+ :return: The target it describes.
55
+ :raises MissingUpstreamRepositoryError: If the project names no upstream.
56
+ """
57
+ upstream_repository = configuration.upstream_repository
58
+ if upstream_repository is None:
59
+ raise MissingUpstreamRepositoryError(
60
+ CommittedStackConfiguration().project_file,
61
+ ProjectLocation.PERSONAL_STACK_CONFIGURATION.value,
62
+ )
63
+ return cls(
64
+ upstream_base=Branch(upstream_repository, configuration.upstream_base),
65
+ fork=configuration.fork_repository,
66
+ )
67
+
68
+
69
+ @dataclass(frozen=True)
70
+ class PromotionLink(PrefilledPullRequestLink):
71
+ """
72
+ A one-click compare-and-create link opening a fork branch's pull request upstream.
73
+ """
74
+
75
+ @classproperty
76
+ def url_character_limit(cls) -> int:
77
+ """
78
+ Longest URL to build, as :attr:`PullRequestForm.url_character_limit`.
79
+ """
80
+ return PullRequestForm.url_character_limit
81
+
82
+ @classproperty
83
+ def truncation_marker(cls) -> str:
84
+ """
85
+ Appended to a shortened body, as :attr:`PullRequestForm.truncation_marker`.
86
+ """
87
+ return PullRequestForm.truncation_marker
88
+
89
+ @classmethod
90
+ def build(
91
+ cls, configuration: Configuration, branch: str, title: str, body: str
92
+ ) -> PromotionLink:
93
+ """
94
+ Build the link promoting a fork branch to the upstream base.
95
+
96
+ :param configuration: The resolved configuration naming both repositories.
97
+ :param branch: The fork branch to promote.
98
+ :param title: Title to prefill.
99
+ :param body: Description to prefill, shortened if the URL would not otherwise
100
+ fit.
101
+ :return: The link, flagged if the body was shortened.
102
+ :raises MissingUpstreamRepositoryError: If the project names no upstream.
103
+ """
104
+ return cls.for_target(
105
+ PromotionTarget.from_configuration(configuration), branch, title, body
106
+ )
107
+
108
+ @classmethod
109
+ def for_target(
110
+ cls, target: PromotionTarget, branch: str, title: str, body: str
111
+ ) -> PromotionLink:
112
+ """
113
+ Build the link promoting a fork branch to a target.
114
+
115
+ :param target: Where the branch is promoted to.
116
+ :param branch: The fork branch to promote.
117
+ :param title: Title to prefill.
118
+ :param body: Description to prefill, shortened if the URL would not otherwise
119
+ fit.
120
+ :return: The link, flagged if the body was shortened.
121
+ """
122
+ form = PullRequestForm(
123
+ target.upstream_base, Branch(target.fork, branch), title, body
124
+ )
125
+ link = form.link
126
+ if link is None:
127
+ raise PromotionLinkTooLongError(
128
+ branch, len(form.url_without_description), cls.url_character_limit
129
+ )
130
+ return cls(link.url, link.body_was_truncated)
131
+
132
+ def print_url(self) -> None:
133
+ """
134
+ Print the compare-and-create URL, reporting on stderr if the body was shortened.
135
+ """
136
+ logger.info(self.url)
137
+ if self.body_was_truncated:
138
+ logger.error("the description was shortened to fit the URL length limit")
@@ -0,0 +1,304 @@
1
+ """
2
+ The read-only reports the stack commands print about one derived stack.
3
+ """
4
+
5
+ from __future__ import annotations
6
+
7
+ import json
8
+ from dataclasses import asdict, dataclass
9
+ from enum import StrEnum
10
+
11
+ from basstler.class_property import classproperty
12
+ from basstler.stack.checkout import CurrentCheckout, GitArgument, MergeTreeStatus
13
+ from basstler.stack.model import BranchStatus, Stack, StackBranch
14
+ from basstler.standard_streams import StandardStreamHandler
15
+
16
+ logger = StandardStreamHandler.logger_for(__name__)
17
+ """
18
+ This module's logger, which is also what its command prints through.
19
+ """
20
+
21
+ # %% the status table
22
+
23
+
24
+ class StatusColumn(StrEnum):
25
+ """
26
+ The columns of the status table, in the order they are printed, each with its width.
27
+ """
28
+
29
+ width: int
30
+ """
31
+ How many characters the column is padded to.
32
+ """
33
+
34
+ def __new__(cls, title: str, width: int) -> StatusColumn:
35
+ """
36
+ Make a member that is its own column title and carries the column's width.
37
+
38
+ :param title: The column's heading.
39
+ :param width: How many characters the column is padded to.
40
+ :return: The member.
41
+ """
42
+ member = str.__new__(cls, title)
43
+ member._value_ = title
44
+ member.width = width
45
+ return member
46
+
47
+ BRANCH = ("branch", 38)
48
+ """
49
+ The branch's name.
50
+ """
51
+
52
+ STATE = ("state", 10)
53
+ """
54
+ Its :class:`BranchStatus`.
55
+ """
56
+
57
+ CHECKS = ("checks", 9)
58
+ """
59
+ The verdict over the checks on its head, blank while nothing has reported.
60
+ """
61
+
62
+ PULL_REQUEST = ("pull request", 13)
63
+ """
64
+ Its fork pull request's number.
65
+ """
66
+
67
+ DRIFT = ("ahead/behind parent", 40)
68
+ """
69
+ How far it and its parent have diverged, and how it integrates the parent.
70
+ """
71
+
72
+ BEHIND_BASE = ("behind base", 11)
73
+ """
74
+ How many upstream base commits it does not have yet.
75
+ """
76
+
77
+ @classmethod
78
+ def line(cls, *cells: object) -> str:
79
+ """
80
+ :param cells: One value per column, in column order.
81
+ :return: The cells as one table line, each padded to its column's width.
82
+ """
83
+ return " ".join(
84
+ f"{cell!s:<{column.width}}" for column, cell in zip(cls, cells, strict=True)
85
+ ).rstrip()
86
+
87
+ @classproperty
88
+ def rule(cls) -> str:
89
+ """
90
+ The line separating the heading from the rows, as wide as the padded columns.
91
+ """
92
+ return "-" * sum(column.width + 1 for column in cls)
93
+
94
+
95
+ # %% the merge probe
96
+
97
+
98
+ class MergeVerdict(StrEnum):
99
+ """
100
+ Whether a branch would merge cleanly onto its parent right now.
101
+ """
102
+
103
+ CLEAN = "CLEAN"
104
+ """
105
+ It would merge without a conflict.
106
+ """
107
+
108
+ CONFLICTS = "CONFLICTS"
109
+ """
110
+ It would conflict with its parent.
111
+ """
112
+
113
+ UNKNOWN = "UNKNOWN"
114
+ """
115
+ One of the two references is missing, so the merge could not run.
116
+ """
117
+
118
+
119
+ # %% the reports
120
+
121
+
122
+ @dataclass(frozen=True)
123
+ class StackReport:
124
+ """
125
+ The read-only reports the commands print about one derived stack.
126
+ """
127
+
128
+ stack: Stack
129
+ """
130
+ The stack reported on.
131
+ """
132
+
133
+ def print_status(self) -> None:
134
+ """
135
+ Print the whole stack: parent, state, checks, and drift versus the upstream.
136
+ """
137
+ configuration = self.stack.configuration
138
+ upstream = f"{configuration.upstream_remote}/{configuration.upstream_base}"
139
+ logger.info(f"Stack ({len(self.stack.branches)} branches) vs {upstream}\n")
140
+ logger.info(StatusColumn.line(*StatusColumn))
141
+ logger.info(StatusColumn.rule)
142
+ for branch in self.stack.ordered():
143
+ reference = configuration.reference_on_fork(branch.name)
144
+ parent_reference = configuration.reference_on_fork(branch.parent)
145
+ ahead = CurrentCheckout.commit_count(f"{parent_reference}..{reference}")
146
+ behind_parent = CurrentCheckout.commit_count(
147
+ f"{reference}..{parent_reference}"
148
+ )
149
+ logger.info(
150
+ StatusColumn.line(
151
+ branch.name,
152
+ branch.status,
153
+ branch.check_state,
154
+ f"#{branch.pull_request_number}",
155
+ f"+{ahead}/-{behind_parent} "
156
+ f"({branch.strategy} onto {branch.parent})",
157
+ CurrentCheckout.commit_count(f"{reference}..{upstream}"),
158
+ )
159
+ )
160
+
161
+ def print_check(self) -> None:
162
+ """
163
+ Print whether each branch would merge cleanly onto its parent right now.
164
+ """
165
+ configuration = self.stack.configuration
166
+ logger.info(
167
+ "Integration probe - would each branch merge cleanly onto its parent "
168
+ "right now?\n"
169
+ )
170
+ for branch in self.stack.ordered():
171
+ reference = configuration.reference_on_fork(branch.name)
172
+ parent_reference = configuration.reference_on_fork(branch.parent)
173
+ status = CurrentCheckout.run(
174
+ GitArgument.MERGE_TREE,
175
+ GitArgument.WRITE_TREE,
176
+ parent_reference,
177
+ reference,
178
+ ).returncode
179
+ match status:
180
+ case MergeTreeStatus.CLEAN:
181
+ verdict = f"{MergeVerdict.CLEAN}"
182
+ case MergeTreeStatus.CONFLICTED:
183
+ verdict = f"{MergeVerdict.CONFLICTS} onto {branch.parent}"
184
+ case _:
185
+ verdict = (
186
+ f"{MergeVerdict.UNKNOWN} (reference missing: "
187
+ f"{parent_reference} / {reference})"
188
+ )
189
+ logger.info(f" {branch.name:<{StatusColumn.BRANCH.width + 2}} {verdict}")
190
+
191
+ def print_next(self) -> None:
192
+ """
193
+ Print which branches are ready to submit to the upstream next.
194
+ """
195
+ promotable = self.stack.promotion_order()
196
+ withheld = [
197
+ branch
198
+ for branch in self.stack.branches
199
+ if branch.status == BranchStatus.READY
200
+ and self.stack.parent_landed(branch)
201
+ and self.stack.needs_resolution(branch)
202
+ ]
203
+ if promotable:
204
+ self._print_promotable(promotable)
205
+ self._print_withheld(withheld)
206
+ self._print_withheld_by_checks()
207
+ return
208
+ waiting_on_a_parent = [
209
+ branch
210
+ for branch in self.stack.branches
211
+ if branch.status == BranchStatus.READY
212
+ and not self.stack.parent_landed(branch)
213
+ ]
214
+ drafts = [
215
+ branch
216
+ for branch in self.stack.ordered()
217
+ if branch.status == BranchStatus.DRAFT
218
+ ]
219
+ logger.info("Nothing to promote - no branch is both approved and unblocked.")
220
+ if waiting_on_a_parent:
221
+ logger.info(
222
+ " Approved but waiting on a parent to land: "
223
+ f"{', '.join(branch.name for branch in waiting_on_a_parent)}"
224
+ )
225
+ self._print_withheld(withheld)
226
+ self._print_withheld_by_checks()
227
+ if drafts:
228
+ logger.info(
229
+ " The gate: self-review a fork pull request, then un-draft it. "
230
+ f"Draft candidates: {drafts[0].name}"
231
+ )
232
+
233
+ def _print_promotable(self, promotable: list[StackBranch]) -> None:
234
+ """
235
+ :param promotable: The branches to submit upstream next, in dependency order.
236
+ """
237
+ plural = "es" if len(promotable) != 1 else ""
238
+ logger.info(
239
+ f"NEXT to submit to {self.stack.configuration.upstream_remote} "
240
+ f"({len(promotable)} branch{plural}):"
241
+ )
242
+ for branch in promotable:
243
+ logger.info(
244
+ f" {branch.name} (pull request #{branch.pull_request_number}) - "
245
+ f"approved, parent '{branch.parent}' landed"
246
+ )
247
+
248
+ def _print_withheld(self, withheld: list[StackBranch]) -> None:
249
+ """
250
+ :param withheld: The promotable branches withheld pending conflict resolution.
251
+ """
252
+ if not withheld:
253
+ return
254
+ logger.info(
255
+ f" Withheld ({self.stack.configuration.needs_resolution_label}): "
256
+ f"{', '.join(branch.name for branch in withheld)}"
257
+ )
258
+
259
+ def _print_withheld_by_checks(self) -> None:
260
+ """
261
+ Print the approved branches withheld for their failed checks, with the verdict.
262
+ """
263
+ withheld = self.stack.withheld_by_failing_checks()
264
+ if not withheld:
265
+ return
266
+ logger.info(
267
+ " Withheld for failing checks: "
268
+ + ", ".join(f"{branch.name} ({branch.check_state})" for branch in withheld)
269
+ )
270
+
271
+ def print_next_porcelain(self) -> None:
272
+ """
273
+ Print machine-readable :meth:`print_next`: one ``name<TAB>pull request`` line
274
+ per promotable branch.
275
+ """
276
+ for branch in self.stack.promotion_order():
277
+ logger.info(f"{branch.name}\t{branch.pull_request_number}")
278
+
279
+ def print_restack_plan(self) -> None:
280
+ """
281
+ Print the bottom-up restack plan as JSON, one object per not-yet-landed branch.
282
+ """
283
+ logger.info(
284
+ json.dumps([asdict(entry) for entry in self.stack.restack_plan()], indent=2)
285
+ )
286
+
287
+ def print_reparents(self) -> None:
288
+ """
289
+ Print one ``branch<TAB>pull request<TAB>current base<TAB>target base`` line per
290
+ orphaned child.
291
+ """
292
+ for reparent in self.stack.reparents():
293
+ logger.info(
294
+ f"{reparent.branch}\t{reparent.pull_request_number}\t"
295
+ f"{reparent.current_base}\t{reparent.target_base}"
296
+ )
297
+
298
+ def print_landed(self) -> None:
299
+ """
300
+ Print one ``branch<TAB>pull request`` line per open pull request whose branch
301
+ has landed.
302
+ """
303
+ for branch in self.stack.landed_branches():
304
+ logger.info(f"{branch.name}\t{branch.pull_request_number}")