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,233 @@
1
+ """
2
+ The errors the stack commands end with, each carrying the status it exits with.
3
+ """
4
+
5
+ from __future__ import annotations
6
+
7
+ from abc import ABC
8
+ from dataclasses import dataclass
9
+ from pathlib import Path
10
+ from typing import TYPE_CHECKING
11
+
12
+ from basstler.class_property import classproperty
13
+ from basstler.exceptions import DataclassException
14
+ from basstler.exit_codes import CommandFailure, StackExitCode
15
+ from basstler.github.repository import Repository
16
+ from basstler.github.stack_configuration import StackSetting
17
+
18
+ if TYPE_CHECKING:
19
+ from basstler.stack.settings import Remote
20
+
21
+ # %% base
22
+
23
+
24
+ @dataclass
25
+ class StackError(CommandFailure, DataclassException, ABC):
26
+ """
27
+ Base for every refusal the stack commands report, each carrying its own exit status.
28
+ """
29
+
30
+
31
+ # %% remotes
32
+
33
+
34
+ @dataclass
35
+ class ForkRemoteNotFoundError(StackError, LookupError):
36
+ """
37
+ Raised when no remote points at a repository other than the upstream.
38
+ """
39
+
40
+ @classproperty
41
+ def exit_code(cls) -> StackExitCode:
42
+ """:return: The status this kind of error ends a command with."""
43
+ return StackExitCode.REMOTES_UNRESOLVED
44
+
45
+ upstream_repository: Repository
46
+ """The upstream every candidate turned out to be."""
47
+
48
+ def error_message(self) -> str:
49
+ return f"no remote points at a fork: every remote is {self.upstream_repository}"
50
+
51
+ def suggest_correction(self) -> str:
52
+ return (
53
+ f"Add a remote for your fork, or set {StackSetting.FORK_REPOSITORY} in "
54
+ f"stack.toml."
55
+ )
56
+
57
+
58
+ @dataclass
59
+ class OwnRemoteNotFoundError(StackError, LookupError):
60
+ """
61
+ Raised when a project naming no upstream has no remote of the name its base is
62
+ followed on.
63
+ """
64
+
65
+ @classproperty
66
+ def exit_code(cls) -> StackExitCode:
67
+ """:return: The status this kind of error ends a command with."""
68
+ return StackExitCode.REMOTES_UNRESOLVED
69
+
70
+ remote_name: str
71
+ """
72
+ The remote the settings name as the clone's own.
73
+ """
74
+
75
+ def error_message(self) -> str:
76
+ return (
77
+ f"no upstream is named and the clone has no remote '{self.remote_name}' "
78
+ f"to follow instead"
79
+ )
80
+
81
+ def suggest_correction(self) -> str:
82
+ return (
83
+ f"Add the remote '{self.remote_name}', set {StackSetting.FORK_REMOTE} in "
84
+ f"stack.toml to the clone's own remote, or name the upstream with "
85
+ f"{StackSetting.UPSTREAM_REPOSITORY}."
86
+ )
87
+
88
+
89
+ @dataclass
90
+ class AmbiguousForkRemoteError(StackError, LookupError):
91
+ """
92
+ Raised when several remotes could each be the fork.
93
+ """
94
+
95
+ @classproperty
96
+ def exit_code(cls) -> StackExitCode:
97
+ """:return: The status this kind of error ends a command with."""
98
+ return StackExitCode.REMOTES_UNRESOLVED
99
+
100
+ candidates: tuple[Remote, ...]
101
+ """The remotes that are not the upstream, in the order git reported them."""
102
+
103
+ def error_message(self) -> str:
104
+ listed = ", ".join(
105
+ f"{remote.name} -> {remote.repository}" for remote in self.candidates
106
+ )
107
+ return f"several remotes could be the fork ({listed})"
108
+
109
+ def suggest_correction(self) -> str:
110
+ return f"Set {StackSetting.FORK_REPOSITORY} in stack.toml to say which."
111
+
112
+
113
+ # %% the board
114
+
115
+
116
+ @dataclass
117
+ class BoardUnavailable(StackError, RuntimeError):
118
+ """
119
+ Raised when ``board.json`` is missing.
120
+ """
121
+
122
+ @classproperty
123
+ def exit_code(cls) -> StackExitCode:
124
+ """:return: The status this kind of error ends a command with."""
125
+ return StackExitCode.BOARD_UNAVAILABLE
126
+
127
+ board: Path
128
+ """
129
+ Where the board export was looked for.
130
+ """
131
+
132
+ def error_message(self) -> str:
133
+ return f"{self.board.name} not found"
134
+
135
+ def suggest_correction(self) -> str:
136
+ return 'Export it with `"${BASSTLER_PYTHON}" -m basstler.maintenance board --write`.'
137
+
138
+
139
+ # %% label writes
140
+
141
+
142
+ @dataclass
143
+ class ContradictoryLabelWriteError(StackError, ValueError):
144
+ """
145
+ Raised when one write is asked both to carry a label and to drop it.
146
+ """
147
+
148
+ @classproperty
149
+ def exit_code(cls) -> StackExitCode:
150
+ """:return: The status this kind of error ends a command with."""
151
+ return StackExitCode.USAGE
152
+
153
+ labels: tuple[str, ...]
154
+ """
155
+ The labels asked for in both directions.
156
+ """
157
+
158
+ def error_message(self) -> str:
159
+ return (
160
+ f"cannot both add and remove {', '.join(self.labels)}: "
161
+ f"either outcome would be a guess at what was meant"
162
+ )
163
+
164
+ def suggest_correction(self) -> str:
165
+ return "Ask for each label to be either added or removed, not both."
166
+
167
+
168
+ # %% promotion links
169
+
170
+
171
+ @dataclass
172
+ class PromotionLinkTooLongError(StackError, ValueError):
173
+ """
174
+ Raised when a link cannot fit even with its whole description dropped.
175
+ """
176
+
177
+ @classproperty
178
+ def exit_code(cls) -> StackExitCode:
179
+ """:return: The status this kind of error ends a command with."""
180
+ return StackExitCode.USAGE
181
+
182
+ branch: str
183
+ """
184
+ The branch whose link was being built.
185
+ """
186
+ length_without_a_description: int
187
+ """
188
+ How long the URL already is before any description is added.
189
+ """
190
+ url_character_limit: int
191
+ """
192
+ The longest URL the link may be.
193
+ """
194
+
195
+ def error_message(self) -> str:
196
+ return (
197
+ f"the compare link for {self.branch} is {self.length_without_a_description} "
198
+ f"characters before its description, over the "
199
+ f"{self.url_character_limit}-character limit"
200
+ )
201
+
202
+ def suggest_correction(self) -> str:
203
+ return "Shorten the title."
204
+
205
+
206
+ # %% scoping
207
+
208
+
209
+ @dataclass
210
+ class BaseBranchScopeError(StackError, ValueError):
211
+ """
212
+ Raised when a stack is scoped to the upstream base, which every branch is stacked
213
+ on.
214
+ """
215
+
216
+ @classproperty
217
+ def exit_code(cls) -> StackExitCode:
218
+ """:return: The status this kind of error ends a command with."""
219
+ return StackExitCode.USAGE
220
+
221
+ upstream_base: str
222
+ """
223
+ The upstream base the scope named.
224
+ """
225
+
226
+ def error_message(self) -> str:
227
+ return f"'{self.upstream_base}' is the upstream base: every branch is stacked on it"
228
+
229
+ def suggest_correction(self) -> str:
230
+ return (
231
+ "Name a branch of the stack, or leave --stacked-on out to pass over every "
232
+ "branch."
233
+ )
@@ -0,0 +1,68 @@
1
+ """
2
+ The complete label set a pull request has to be written back with.
3
+ """
4
+
5
+ from __future__ import annotations
6
+
7
+ from collections.abc import Iterable
8
+ from dataclasses import dataclass
9
+
10
+ from basstler.stack.exceptions import ContradictoryLabelWriteError
11
+ from basstler.standard_streams import StandardStreamHandler
12
+
13
+ logger = StandardStreamHandler.logger_for(__name__)
14
+ """
15
+ This module's logger, which is also what its command prints through.
16
+ """
17
+
18
+ # %% label writes
19
+
20
+
21
+ @dataclass(frozen=True)
22
+ class LabelWrite:
23
+ """
24
+ The complete label set a pull request has to be written back with.
25
+
26
+ GitHub's label write replaces the whole set rather than adding to it, so the labels
27
+ a change leaves untouched still have to be sent. Computing them from the intended
28
+ change alone is what silently strips the rest.
29
+ """
30
+
31
+ labels: tuple[str, ...]
32
+ """
33
+ Every label the pull request will carry once written, in the order it will carry
34
+ them.
35
+ """
36
+
37
+ @classmethod
38
+ def replacing(
39
+ cls,
40
+ current: Iterable[str],
41
+ added: Iterable[str] = (),
42
+ removed: Iterable[str] = (),
43
+ ) -> LabelWrite:
44
+ """
45
+ Work out the full set that adding and removing labels leaves behind.
46
+
47
+ :param current: The labels the pull request carries now.
48
+ :param added: Labels it must carry afterwards.
49
+ :param removed: Labels it must not carry afterwards.
50
+ :return: The complete set to write.
51
+ :raises ContradictoryLabelWriteError: If a label is both added and removed.
52
+ """
53
+ added, removed = tuple(added), tuple(removed)
54
+ contradictory = tuple(label for label in added if label in removed)
55
+ if contradictory:
56
+ raise ContradictoryLabelWriteError(contradictory)
57
+ kept = [label for label in current if label not in removed]
58
+ return cls(tuple(kept + [label for label in added if label not in kept]))
59
+
60
+ def print_labels(self) -> None:
61
+ """
62
+ Print the complete label set, one label per line.
63
+
64
+ One per line rather than a separator-joined list, because a label may contain
65
+ any character a separator could be.
66
+ """
67
+ for label in self.labels:
68
+ logger.info(label)
@@ -0,0 +1,195 @@
1
+ """
2
+ Whether one branch of a remote merges into another, decided by git from a fresh fetch.
3
+
4
+ The answer never depends on a hosted service's lazily computed mergeable state: the same
5
+ two commits always give the same verdict and the same conflicting paths.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import json
11
+ from dataclasses import asdict, dataclass
12
+ from enum import StrEnum
13
+ from pathlib import Path
14
+
15
+ from basstler.exit_codes import StackExitCode
16
+ from basstler.git.commands import GitCommandFailed, GitCommandRunner
17
+ from basstler.stack.checkout import GitArgument, MergeTreeStatus
18
+ from basstler.stack.report import MergeVerdict
19
+ from basstler.standard_streams import StandardStreamHandler
20
+
21
+ logger = StandardStreamHandler.logger_for(__name__)
22
+ """
23
+ This module's logger, which is also what its command prints through.
24
+ """
25
+
26
+ # %% where the probed branches are kept
27
+
28
+
29
+ class ProbedReference(StrEnum):
30
+ """
31
+ Where a probe keeps the two branches it fetched, so it never moves a remote-tracking
32
+ branch or ``FETCH_HEAD``.
33
+ """
34
+
35
+ BASE = "refs/basstler/merge-probe/base"
36
+ """
37
+ The branch merged into.
38
+ """
39
+
40
+ HEAD = "refs/basstler/merge-probe/head"
41
+ """
42
+ The branch merged.
43
+ """
44
+
45
+
46
+ class MergeTreeOption(StrEnum):
47
+ """
48
+ The ``git merge-tree`` flags a probe passes beside :attr:`GitArgument.WRITE_TREE`.
49
+ """
50
+
51
+ NAME_ONLY = "--name-only"
52
+ """
53
+ Lists each conflicting path once, without its stages.
54
+ """
55
+
56
+ NO_MESSAGES = "--no-messages"
57
+ """
58
+ Leaves out the informational messages after the paths.
59
+ """
60
+
61
+
62
+ # %% the verdict
63
+
64
+
65
+ @dataclass(frozen=True)
66
+ class MergeProbeResult:
67
+ """
68
+ What merging one fetched branch into another gives.
69
+ """
70
+
71
+ base_location: str
72
+ """
73
+ The remote name or URL the base branch was fetched from.
74
+ """
75
+
76
+ base_commit: str
77
+ """
78
+ The commit the base branch pointed at when it was fetched.
79
+ """
80
+
81
+ head_commit: str
82
+ """
83
+ The commit the head branch pointed at when it was fetched.
84
+ """
85
+
86
+ verdict: MergeVerdict
87
+ """
88
+ Whether the merge is clean.
89
+ """
90
+
91
+ conflicting_paths: tuple[str, ...]
92
+ """
93
+ Every path the merge conflicts in, sorted; empty when it is clean.
94
+ """
95
+
96
+ @property
97
+ def exit_code(self) -> StackExitCode:
98
+ """
99
+ :return: The status the command ends with for this verdict.
100
+ """
101
+ if self.verdict is MergeVerdict.CLEAN:
102
+ return StackExitCode.SUCCESS
103
+ return StackExitCode.MERGE_CONFLICTS
104
+
105
+ def print_report(self) -> None:
106
+ """
107
+ Print the result as one JSON object, and describe a conflict on stderr.
108
+ """
109
+ logger.info(json.dumps(asdict(self), sort_keys=True))
110
+ if self.verdict is MergeVerdict.CLEAN:
111
+ return
112
+ logger.error(
113
+ "%s: commit %s does not merge cleanly into %s's commit %s; it conflicts "
114
+ "in %s",
115
+ self.exit_code.name_for_a_caller,
116
+ self.head_commit,
117
+ self.base_location,
118
+ self.base_commit,
119
+ ", ".join(self.conflicting_paths),
120
+ )
121
+
122
+
123
+ # %% the probe
124
+
125
+
126
+ @dataclass(frozen=True)
127
+ class MergeProbe:
128
+ """
129
+ A merge of one branch of a remote into another, run without touching any branch or
130
+ the working tree.
131
+ """
132
+
133
+ head_location: str
134
+ """
135
+ The remote name or URL the head branch is fetched from.
136
+ """
137
+
138
+ base_location: str
139
+ """
140
+ The remote name or URL the base branch is fetched from.
141
+ """
142
+
143
+ base: str
144
+ """
145
+ The branch merged into, such as a pull request's base.
146
+ """
147
+
148
+ head: str
149
+ """
150
+ The branch merged, such as a pull request's head.
151
+ """
152
+
153
+ def run(self, working_directory: Path) -> MergeProbeResult:
154
+ """
155
+ Fetch both branches and merge them.
156
+
157
+ :param working_directory: The checkout to fetch into.
158
+ :return: The verdict on the commits just fetched.
159
+ :raises GitCommandFailed: If either branch cannot be fetched, or git cannot
160
+ merge them for a reason other than a conflict.
161
+ """
162
+ git = GitCommandRunner(working_directory)
163
+ for location, branch, reference in (
164
+ (self.base_location, self.base, ProbedReference.BASE),
165
+ (self.head_location, self.head, ProbedReference.HEAD),
166
+ ):
167
+ git.run(
168
+ GitArgument.FETCH,
169
+ GitArgument.QUIET,
170
+ GitArgument.NO_WRITE_FETCH_HEAD,
171
+ location,
172
+ f"+refs/heads/{branch}:{reference}",
173
+ )
174
+ merge = git.attempt(
175
+ GitArgument.MERGE_TREE,
176
+ GitArgument.WRITE_TREE,
177
+ MergeTreeOption.NAME_ONLY,
178
+ MergeTreeOption.NO_MESSAGES,
179
+ ProbedReference.BASE,
180
+ ProbedReference.HEAD,
181
+ )
182
+ if merge.exit_status not in set(MergeTreeStatus):
183
+ raise GitCommandFailed(
184
+ status=merge.exit_status,
185
+ detail=merge.error_output,
186
+ arguments=merge.arguments,
187
+ )
188
+ clean = merge.exit_status == MergeTreeStatus.CLEAN
189
+ return MergeProbeResult(
190
+ base_location=self.base_location,
191
+ base_commit=git.run(GitArgument.REVISION_PARSE, ProbedReference.BASE),
192
+ head_commit=git.run(GitArgument.REVISION_PARSE, ProbedReference.HEAD),
193
+ verdict=MergeVerdict.CLEAN if clean else MergeVerdict.CONFLICTS,
194
+ conflicting_paths=tuple(sorted(set(merge.output.splitlines()[1:]))),
195
+ )