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,85 @@
1
+ """
2
+ What other distributions do once a maintenance pass has closed fork pull requests whose
3
+ work landed upstream.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ from abc import ABC, abstractmethod
9
+ from collections.abc import Sequence
10
+ from dataclasses import dataclass
11
+ from enum import StrEnum
12
+ from importlib.metadata import entry_points
13
+
14
+ from basstler.maintenance.landed_closing import ClosedAsLanded
15
+
16
+ # %% registration
17
+
18
+
19
+ class EntryPointGroup(StrEnum):
20
+ """
21
+ The entry point groups an installed distribution registers maintenance work under.
22
+ """
23
+
24
+ LANDED_CLOSING_FOLLOW_UPS = "basstler.landed_closing_follow_ups"
25
+ """
26
+ Each entry names a :class:`LandedClosingFollowUp` subclass.
27
+ """
28
+
29
+
30
+ # %% follow-ups
31
+
32
+
33
+ class LandedClosingFollowUp(ABC):
34
+ """
35
+ Work a distribution above the stack does once a pass has closed pull requests whose
36
+ work landed; a registered subclass is constructed with no arguments.
37
+ """
38
+
39
+ @abstractmethod
40
+ def respond_to_closing(self, closed: Sequence[ClosedAsLanded]) -> str | None:
41
+ """
42
+ :param closed: The pull requests the pass closed, never empty.
43
+ :return: What became of the work, for the finish summary; ``None`` when there
44
+ was nothing to do.
45
+ """
46
+
47
+
48
+ @dataclass(frozen=True)
49
+ class LandedClosingFollowUps:
50
+ """
51
+ The follow-ups one pass runs after closing landed pull requests.
52
+ """
53
+
54
+ follow_ups: tuple[LandedClosingFollowUp, ...] = ()
55
+ """
56
+ Run in this order.
57
+ """
58
+
59
+ @classmethod
60
+ def installed(cls) -> LandedClosingFollowUps:
61
+ """
62
+ :return: One of each follow-up registered under
63
+ :attr:`EntryPointGroup.LANDED_CLOSING_FOLLOW_UPS`, in the order of their
64
+ entry point names.
65
+ """
66
+ registered = entry_points(group=EntryPointGroup.LANDED_CLOSING_FOLLOW_UPS)
67
+ return cls(
68
+ tuple(
69
+ entry.load()()
70
+ for entry in sorted(registered, key=lambda entry: entry.name)
71
+ )
72
+ )
73
+
74
+ def respond_to_closing(self, closed: Sequence[ClosedAsLanded]) -> tuple[str, ...]:
75
+ """
76
+ :param closed: The pull requests the pass closed.
77
+ :return: What became of each follow-up that had something to do; empty, with
78
+ none run, when nothing was closed.
79
+ """
80
+ if not closed:
81
+ return ()
82
+ outcomes = (
83
+ follow_up.respond_to_closing(closed) for follow_up in self.follow_ups
84
+ )
85
+ return tuple(outcome for outcome in outcomes if outcome is not None)
@@ -0,0 +1,248 @@
1
+ """
2
+ Recording the upstream link on every branch ready to be promoted.
3
+
4
+ The upstream pull request is not opened here - the credential has no write access there.
5
+ What is written is the link that opens it prefilled, into the fork pull request's own
6
+ description, plus the label that stops a later pass rebuilding it.
7
+
8
+ What the upstream reviewer reads is a reading of the diff, so it is written by the caller
9
+ as a :class:`PromotionSummary`; the title, the link back to the fork pull request and the
10
+ length budget stay here.
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ import json
16
+ from collections.abc import Mapping
17
+ from dataclasses import dataclass, field
18
+ from enum import StrEnum
19
+ from pathlib import Path
20
+ from typing import Any
21
+
22
+ from basstler.github.constants import MaintenanceText
23
+ from basstler.github.pull_request_description import PullRequestDescription
24
+ from basstler.github.pull_request_record import (
25
+ PullRequestField,
26
+ )
27
+ from basstler.github.repository_access import ForkPullRequests, PullRequestWriter
28
+ from basstler.github.tooling_labels import GitHubLabel
29
+ from basstler.github.branch_pull_request import BranchPullRequest
30
+ from basstler.stack.label_write import LabelWrite
31
+ from basstler.stack.model import BranchStatus, Stack
32
+ from basstler.stack.promotion_link import PromotionLink
33
+ from basstler.text_file import TextFile
34
+
35
+ # %% the summaries a caller writes
36
+
37
+
38
+ class PromotionSummaryField(StrEnum):
39
+ """
40
+ The keys one summary is written under in the summaries document.
41
+ """
42
+
43
+ POINTS = "points"
44
+ """
45
+ The points the upstream pull request's description opens with.
46
+ """
47
+
48
+ TITLE = "title"
49
+ """
50
+ The title to open the upstream pull request with instead of the fork pull request's
51
+ own.
52
+ """
53
+
54
+
55
+ @dataclass(frozen=True)
56
+ class PromotionSummary:
57
+ """
58
+ What one upstream pull request opens with, as far as anybody has written it.
59
+
60
+ Both halves are optional: with neither, the upstream pull request opens with the fork
61
+ pull request's title and the link back to it.
62
+ """
63
+
64
+ points: tuple[str, ...] = ()
65
+ """
66
+ The points for the upstream reviewer, one bullet each; empty when nobody wrote them.
67
+ """
68
+
69
+ title: str | None = None
70
+ """
71
+ The upstream title, or ``None`` to keep the fork pull request's own.
72
+ """
73
+
74
+ @classmethod
75
+ def from_json(cls, data: Mapping[str, Any]) -> PromotionSummary:
76
+ """
77
+ :param data: One entry of the summaries document.
78
+ :return: The summary it holds.
79
+ """
80
+ return cls(
81
+ points=tuple(data.get(PromotionSummaryField.POINTS, ())),
82
+ title=data.get(PromotionSummaryField.TITLE),
83
+ )
84
+
85
+ def upstream_description(self, fork_pull_request_url: str) -> str:
86
+ """
87
+ Build what the upstream pull request's description opens with.
88
+
89
+ :param fork_pull_request_url: The fork pull request this summary was written for.
90
+ :return: The points as a markdown bullet list where there are any, then the link
91
+ back to the fork pull request.
92
+ """
93
+ link_back = f"{MaintenanceText.FULL_DETAIL} {fork_pull_request_url}"
94
+ if not self.points:
95
+ return link_back
96
+ bullet_list = "\n".join(f"- {point}" for point in self.points)
97
+ return f"{bullet_list}\n\n{link_back}"
98
+
99
+
100
+ @dataclass(frozen=True)
101
+ class PromotionSummaries:
102
+ """
103
+ The summaries written for one pass, by the fork pull request each belongs to.
104
+ """
105
+
106
+ by_pull_request_number: Mapping[int, PromotionSummary] = field(default_factory=dict)
107
+ """
108
+ Each summary, keyed by its fork pull request's number.
109
+ """
110
+
111
+ @classmethod
112
+ def read_from(cls, path: Path | None) -> PromotionSummaries:
113
+ """
114
+ :param path: The summaries document, or ``None`` when the caller wrote none.
115
+ :return: The summaries it holds, none when there is no document.
116
+ """
117
+ if path is None:
118
+ return cls()
119
+ return cls.from_json(json.loads(TextFile(path).read()))
120
+
121
+ @classmethod
122
+ def from_json(cls, data: Mapping[str, Any]) -> PromotionSummaries:
123
+ """
124
+ :param data: The summaries document, keyed by fork pull request number.
125
+ :return: The summaries it holds.
126
+ """
127
+ return cls(
128
+ {
129
+ int(number): PromotionSummary.from_json(entry)
130
+ for number, entry in data.items()
131
+ }
132
+ )
133
+
134
+ def for_pull_request(self, number: int) -> PromotionSummary:
135
+ """
136
+ :param number: A fork pull request.
137
+ :return: Its summary, empty when nobody wrote one.
138
+ """
139
+ return self.by_pull_request_number.get(number, PromotionSummary())
140
+
141
+
142
+ # %% recording the link
143
+
144
+
145
+ @dataclass(frozen=True)
146
+ class Promotion(BranchPullRequest):
147
+ """
148
+ One branch's compare-and-create link, and where it was recorded.
149
+ """
150
+
151
+ url: str
152
+ """
153
+ The compare-and-create link opening the upstream pull request.
154
+ """
155
+
156
+ body_was_truncated: bool
157
+ """
158
+ Whether the prefilled description had to be shortened to fit the URL limit.
159
+ """
160
+
161
+
162
+ def promote(
163
+ stack: Stack, fork: ForkPullRequests, summaries: PromotionSummaries
164
+ ) -> list[Promotion]:
165
+ """
166
+ Build and record the upstream link for every branch ready to be promoted.
167
+
168
+ The upstream pull request is not opened here - the app has no write access there, so
169
+ that call fails every time. What is written is the link that opens it prefilled, into
170
+ the fork pull request's own description, plus the label stopping a later pass
171
+ rebuilding it. The upstream pull request does not exist until the developer clicks
172
+ Create.
173
+
174
+ Both the decision and the label write read the labels the branch carries *now*, not
175
+ the ones the board was exported with: the restack runs between those two moments and
176
+ withholds a branch by labelling it, so a snapshot is already out of date here.
177
+
178
+ :param stack: The derived stack.
179
+ :param fork: The fork to read descriptions from and write links back to.
180
+ :param summaries: What each upstream pull request opens with, where anybody wrote it.
181
+ :return: One entry per branch promoted, in dependency order.
182
+ """
183
+ promoted: list[Promotion] = []
184
+ withheld = stack.configuration.needs_resolution_label
185
+ for branch in stack.awaiting_promotion_link():
186
+ number = branch.pull_request_number
187
+ pull_request = fork.pull_request(number)
188
+ labels = PullRequestField.LABELS.read(pull_request, number)
189
+ if GitHubLabel.PROMOTION_LINK_SENT in labels or withheld in labels:
190
+ continue
191
+ description = PullRequestDescription(
192
+ str(PullRequestField.BODY.read(pull_request, number) or "")
193
+ )
194
+ summary = summaries.for_pull_request(number)
195
+ link = PromotionLink.build(
196
+ stack.configuration,
197
+ branch.name,
198
+ summary.title
199
+ or str(PullRequestField.TITLE.read(pull_request, number) or branch.name),
200
+ summary.upstream_description(
201
+ stack.configuration.fork_repository.pull_request_url(number)
202
+ ),
203
+ )
204
+ fork.set_description(
205
+ number,
206
+ description.with_promotion_link(link.url),
207
+ )
208
+ fork.replace_labels(
209
+ number,
210
+ LabelWrite.replacing(
211
+ labels, added=[GitHubLabel.PROMOTION_LINK_SENT]
212
+ ).labels,
213
+ )
214
+ promoted.append(
215
+ Promotion(
216
+ branch=branch.name,
217
+ pull_request_number=branch.pull_request_number,
218
+ url=link.url,
219
+ body_was_truncated=link.body_was_truncated,
220
+ )
221
+ )
222
+ return promoted
223
+
224
+
225
+ def clear_spent_promotion_labels(
226
+ stack: Stack, fork: PullRequestWriter
227
+ ) -> tuple[str, ...]:
228
+ """
229
+ Drop the link label from every branch whose link has already been acted on.
230
+
231
+ :param stack: The derived stack.
232
+ :param fork: The fork to write to.
233
+ :return: The branches whose label was cleared.
234
+ """
235
+ spent = [
236
+ branch
237
+ for branch in stack.maintained_branches()
238
+ if GitHubLabel.PROMOTION_LINK_SENT in branch.labels
239
+ and branch.status in {BranchStatus.IN_REVIEW, BranchStatus.MERGED}
240
+ ]
241
+ for branch in spent:
242
+ fork.replace_labels(
243
+ branch.pull_request_number,
244
+ LabelWrite.replacing(
245
+ branch.labels, removed=[GitHubLabel.PROMOTION_LINK_SENT]
246
+ ).labels,
247
+ )
248
+ return tuple(branch.name for branch in spent)
@@ -0,0 +1,221 @@
1
+ """
2
+ What a session writes each upstream summary from, read for it in one go.
3
+
4
+ A summary is a reading of the change, but not of every line of it: the fork pull
5
+ request's own title and description, its commit subjects and which files it changes by
6
+ how much are what an upstream reviewer's first paragraph is written from. Each is
7
+ capped, so the context for a branch stays the same size however large its change is.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ from collections.abc import Sequence
13
+ from dataclasses import dataclass
14
+
15
+ from basstler.class_property import classproperty
16
+ from basstler.git.commands import GitCommandRunner
17
+ from basstler.git.commit_range import CommitRange, FileChange
18
+ from basstler.github.pull_request_record import (
19
+ PullRequestField,
20
+ )
21
+ from basstler.github.repository_access import PullRequestReader
22
+ from basstler.stack.model import Stack, StackBranch
23
+
24
+ # %% how much a branch changes
25
+
26
+
27
+ @dataclass(frozen=True)
28
+ class ChangeSize:
29
+ """
30
+ How much a branch changes, with only its largest files named.
31
+ """
32
+
33
+ files_changed: int
34
+ """
35
+ How many files it changes.
36
+ """
37
+
38
+ insertions: int
39
+ """
40
+ Lines added across every file.
41
+ """
42
+
43
+ deletions: int
44
+ """
45
+ Lines removed across every file.
46
+ """
47
+
48
+ largest_files: tuple[FileChange, ...]
49
+ """
50
+ The files with the most changed lines, largest first.
51
+ """
52
+
53
+ @classmethod
54
+ def from_file_changes(
55
+ cls, changes: Sequence[FileChange], file_limit: int
56
+ ) -> ChangeSize:
57
+ """
58
+ :param changes: Every file the branch changes.
59
+ :param file_limit: How many of the largest to name.
60
+ :return: The size of the change.
61
+ """
62
+ largest = sorted(changes, key=lambda change: -change.changed_lines)
63
+ return cls(
64
+ files_changed=len(changes),
65
+ insertions=sum(change.insertions for change in changes),
66
+ deletions=sum(change.deletions for change in changes),
67
+ largest_files=tuple(largest[:file_limit]),
68
+ )
69
+
70
+
71
+ # %% one branch's context
72
+
73
+
74
+ @dataclass(frozen=True)
75
+ class PromotionContext:
76
+ """
77
+ Everything one upstream summary is written from.
78
+ """
79
+
80
+ pull_request_number: int
81
+ """
82
+ The fork pull request the summary is keyed by.
83
+ """
84
+
85
+ branch: str
86
+ """
87
+ The branch to be promoted.
88
+ """
89
+
90
+ compared_with: str
91
+ """
92
+ The reference its change is measured against: its parent on the fork, or the
93
+ upstream's base once that parent has landed.
94
+ """
95
+
96
+ title: str
97
+ """
98
+ The fork pull request's title.
99
+ """
100
+
101
+ description: str
102
+ """
103
+ The fork pull request's description, cut short at the reader's limit.
104
+ """
105
+
106
+ commit_subjects: tuple[str, ...]
107
+ """
108
+ The subjects of the branch's own commits, oldest first, merges left out.
109
+ """
110
+
111
+ commits_not_listed: int
112
+ """
113
+ How many more commits there are than :attr:`commit_subjects` lists.
114
+ """
115
+
116
+ change_size: ChangeSize
117
+ """
118
+ How much the branch changes.
119
+ """
120
+
121
+
122
+ @dataclass(frozen=True)
123
+ class PromotionContextReader:
124
+ """
125
+ Reads the :class:`PromotionContext` of every branch awaiting its upstream link.
126
+ """
127
+
128
+ stack: Stack
129
+ """
130
+ The derived stack the branches belong to.
131
+ """
132
+
133
+ git: GitCommandRunner
134
+ """
135
+ The checkout whose fork and upstream references the branches are compared in.
136
+ """
137
+
138
+ fork: PullRequestReader
139
+ """
140
+ The fork, read for each pull request's title and description.
141
+ """
142
+
143
+ file_limit: int = 8
144
+ """
145
+ How many of a branch's largest files to name.
146
+ """
147
+
148
+ commit_limit: int = 12
149
+ """
150
+ How many of a branch's commit subjects to list.
151
+ """
152
+
153
+ description_limit: int = 1200
154
+ """
155
+ How many characters of a pull request's description to keep.
156
+ """
157
+
158
+ @classproperty
159
+ def truncation_marker(cls) -> str:
160
+ """
161
+ What a shortened description ends with.
162
+ """
163
+ return " [...]"
164
+
165
+ def read(self) -> list[PromotionContext]:
166
+ """
167
+ :return: The context of every branch awaiting its upstream link, in dependency
168
+ order.
169
+ """
170
+ return [
171
+ self.context_of(branch) for branch in self.stack.awaiting_promotion_link()
172
+ ]
173
+
174
+ def compared_with(self, branch: StackBranch) -> str:
175
+ """
176
+ :param branch: A branch to be promoted.
177
+ :return: The reference its change is measured against.
178
+ """
179
+ configuration = self.stack.configuration
180
+ if self.stack.has_landed_upstream(branch.parent):
181
+ return configuration.upstream_base_reference
182
+ return configuration.reference_on_fork(branch.parent)
183
+
184
+ def context_of(self, branch: StackBranch) -> PromotionContext:
185
+ """
186
+ :param branch: A branch to be promoted.
187
+ :return: What its upstream summary is written from.
188
+ """
189
+ number = branch.pull_request_number
190
+ pull_request = self.fork.pull_request(number)
191
+ compared_with = self.compared_with(branch)
192
+ tip = self.stack.configuration.reference_on_fork(branch.name)
193
+ subjects = self.git.run(
194
+ "log", "--no-merges", "--reverse", "--format=%s", f"{compared_with}..{tip}"
195
+ ).splitlines()
196
+ commits = CommitRange(self.git, self.git.merge_base(compared_with, tip), tip)
197
+ return PromotionContext(
198
+ pull_request_number=number,
199
+ branch=branch.name,
200
+ compared_with=compared_with,
201
+ title=str(PullRequestField.TITLE.read(pull_request, number) or branch.name),
202
+ description=self.shortened(
203
+ str(PullRequestField.BODY.read(pull_request, number) or "")
204
+ ),
205
+ commit_subjects=tuple(subjects[: self.commit_limit]),
206
+ commits_not_listed=max(len(subjects) - self.commit_limit, 0),
207
+ change_size=ChangeSize.from_file_changes(
208
+ commits.file_changes(), self.file_limit
209
+ ),
210
+ )
211
+
212
+ def shortened(self, description: str) -> str:
213
+ """
214
+ :param description: A pull request's description.
215
+ :return: It, cut at the last whole word within :attr:`description_limit` and
216
+ marked as cut when it was.
217
+ """
218
+ if len(description) <= self.description_limit:
219
+ return description
220
+ kept = description[: self.description_limit].rsplit(maxsplit=1)[0]
221
+ return f"{kept}{self.truncation_marker}"