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.
- basstler/maintenance/__init__.py +0 -0
- basstler/maintenance/__main__.py +128 -0
- basstler/maintenance/board.py +113 -0
- basstler/maintenance/check_overview.py +80 -0
- basstler/maintenance/commands.py +595 -0
- basstler/maintenance/default_branch_sync.py +444 -0
- basstler/maintenance/exceptions.py +36 -0
- basstler/maintenance/fast_forward.py +223 -0
- basstler/maintenance/finish_summary.py +515 -0
- basstler/maintenance/fork_pull_request_action.py +38 -0
- basstler/maintenance/landed_closing.py +85 -0
- basstler/maintenance/landed_closing_follow_up.py +85 -0
- basstler/maintenance/promotion.py +248 -0
- basstler/maintenance/promotion_context.py +221 -0
- basstler/maintenance/report.py +304 -0
- basstler/maintenance/restack_procedure.py +279 -0
- basstler/maintenance/restack_steps.py +769 -0
- basstler/maintenance/upstream_pull_request_synchronization.py +189 -0
- basstler/maintenance/upstream_read_route.py +37 -0
- basstler/stack/__init__.py +0 -0
- basstler/stack/__main__.py +377 -0
- basstler/stack/branch_status.py +54 -0
- basstler/stack/checkout.py +416 -0
- basstler/stack/commit_move.py +218 -0
- basstler/stack/exceptions.py +233 -0
- basstler/stack/label_write.py +68 -0
- basstler/stack/merge_probe.py +195 -0
- basstler/stack/model.py +696 -0
- basstler/stack/promotability.py +103 -0
- basstler/stack/promotion_link.py +138 -0
- basstler/stack/report.py +304 -0
- basstler/stack/settings.py +453 -0
- basstler/stack/stack.toml +31 -0
- basstler_stack-4.2.0.dist-info/METADATA +16 -0
- basstler_stack-4.2.0.dist-info/RECORD +38 -0
- basstler_stack-4.2.0.dist-info/WHEEL +4 -0
- basstler_stack-4.2.0.dist-info/licenses/LICENSE +202 -0
- basstler_stack-4.2.0.dist-info/licenses/NOTICE +13 -0
|
File without changes
|
|
@@ -0,0 +1,128 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""
|
|
3
|
+
Deterministic executor for the stacked-PR maintenance pass.
|
|
4
|
+
|
|
5
|
+
``basstler.stack`` derives what a pass should do and prints it; nothing in it moves a commit.
|
|
6
|
+
Every fetch, merge, rebase and push in the workflow was therefore performed by a session
|
|
7
|
+
following prose, and ``board.json`` was hand-assembled from whatever the caller happened
|
|
8
|
+
to fetch - the same class of hand-assembled input that let a dropped ``merged_at`` field
|
|
9
|
+
read as a legitimate value.
|
|
10
|
+
|
|
11
|
+
This module is the command line onto the modules that perform those steps::
|
|
12
|
+
|
|
13
|
+
python -m basstler.maintenance board --write # export the fork's open pull requests
|
|
14
|
+
python -m basstler.maintenance push # publish the checked-out branch, once the move checks clear it
|
|
15
|
+
python -m basstler.maintenance fast-forward # move the fork's base onto the upstream
|
|
16
|
+
python -m basstler.maintenance restack # integrate every moved parent, report every conflict
|
|
17
|
+
python -m basstler.maintenance restack --stacked-on <branch> # carry one branch into what is stacked on it
|
|
18
|
+
python -m basstler.maintenance promote # record the upstream link on every ready branch
|
|
19
|
+
python -m basstler.maintenance run-report # the whole pass, as its finish summary
|
|
20
|
+
python -m basstler.maintenance run-report --summaries <file> # with what each upstream pull request opens with
|
|
21
|
+
python -m basstler.maintenance run-report --json # the whole pass as one document
|
|
22
|
+
|
|
23
|
+
It executes an already-derived plan: structure still comes from ``basstler.stack`` and from
|
|
24
|
+
GitHub's own stack object. Retargeting a pull request's **base branch** is the one write
|
|
25
|
+
GitHub refuses to the credential this runs on - probed directly, alongside the label,
|
|
26
|
+
comment and description writes it does allow - so that step alone is reported for the
|
|
27
|
+
caller to perform through the GitHub MCP server.
|
|
28
|
+
|
|
29
|
+
The exit status is the result. ``run-report`` prints the finish summary
|
|
30
|
+
``/stacked-pr-maintenance`` relays; ``--json`` is the machine-readable form for tooling.
|
|
31
|
+
"""
|
|
32
|
+
|
|
33
|
+
from __future__ import annotations
|
|
34
|
+
|
|
35
|
+
import argparse
|
|
36
|
+
import sys
|
|
37
|
+
from pathlib import Path
|
|
38
|
+
|
|
39
|
+
from basstler.exit_codes import CommandFailure, ExitCode, StackExitCode
|
|
40
|
+
from basstler.git.commands import GitCommandRunner
|
|
41
|
+
from basstler.github.exceptions import GraphQLErrorsReturned, UpstreamReadError
|
|
42
|
+
from basstler.locations import RepositoryStateLocation
|
|
43
|
+
from basstler.maintenance.commands import MaintenanceCommand, MaintenancePass
|
|
44
|
+
from basstler.maintenance.landed_closing_follow_up import LandedClosingFollowUps
|
|
45
|
+
from basstler.maintenance.upstream_read_route import UpstreamReadRoute
|
|
46
|
+
from basstler.stack.settings import Configuration
|
|
47
|
+
from basstler.standard_streams import StandardStreamHandler
|
|
48
|
+
|
|
49
|
+
logger = StandardStreamHandler.logger_for(__name__)
|
|
50
|
+
"""
|
|
51
|
+
This module's logger, which is also what its command prints through.
|
|
52
|
+
"""
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
def _argument_parser() -> argparse.ArgumentParser:
|
|
56
|
+
""":return: The parser, built from the commands rather than from a list of them."""
|
|
57
|
+
parser = argparse.ArgumentParser(
|
|
58
|
+
prog="basstler.maintenance",
|
|
59
|
+
description="Stacked-PR maintenance: perform the pass, report what happened.",
|
|
60
|
+
)
|
|
61
|
+
parser.add_argument(
|
|
62
|
+
"--upstream-read",
|
|
63
|
+
choices=list(UpstreamReadRoute),
|
|
64
|
+
default=UpstreamReadRoute.for_this_session(),
|
|
65
|
+
help=(
|
|
66
|
+
"read the upstream's open pull requests with this session's own "
|
|
67
|
+
"credential, or through the fork's upstream-reviews Action - the default "
|
|
68
|
+
"in a Claude Code cloud session, whose proxy refuses the upstream's API"
|
|
69
|
+
),
|
|
70
|
+
)
|
|
71
|
+
subparsers = parser.add_subparsers(dest="command", required=True)
|
|
72
|
+
for command in MaintenanceCommand.every_command():
|
|
73
|
+
command.declare_arguments(
|
|
74
|
+
subparsers.add_parser(command.invoked_as, help=command.description)
|
|
75
|
+
)
|
|
76
|
+
return parser
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
def main() -> ExitCode:
|
|
80
|
+
"""
|
|
81
|
+
Run the command line and say, in words, what its status means.
|
|
82
|
+
|
|
83
|
+
The status itself can only be a number, so the name accompanies it on stderr for
|
|
84
|
+
anything other than a clean run - success stays silent, since announcing it would
|
|
85
|
+
make every run noisy.
|
|
86
|
+
|
|
87
|
+
:return: The process exit code.
|
|
88
|
+
"""
|
|
89
|
+
status = _dispatch()
|
|
90
|
+
if status is not StackExitCode.SUCCESS:
|
|
91
|
+
logger.error(
|
|
92
|
+
f"basstler.maintenance: {status.name_for_a_caller} ({int(status)})"
|
|
93
|
+
)
|
|
94
|
+
return status
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
def _dispatch() -> ExitCode:
|
|
98
|
+
"""
|
|
99
|
+
Run the requested command, mapping every refusal to its own status.
|
|
100
|
+
|
|
101
|
+
:return: The process exit code.
|
|
102
|
+
"""
|
|
103
|
+
arguments = _argument_parser().parse_args()
|
|
104
|
+
requested = next(
|
|
105
|
+
entry
|
|
106
|
+
for entry in MaintenanceCommand.every_command()
|
|
107
|
+
if entry.invoked_as == arguments.command
|
|
108
|
+
)
|
|
109
|
+
try:
|
|
110
|
+
git = GitCommandRunner(working_directory=Path.cwd())
|
|
111
|
+
maintenance = MaintenancePass(
|
|
112
|
+
configuration=Configuration.load(),
|
|
113
|
+
git=git,
|
|
114
|
+
board=git.repository_state_path(RepositoryStateLocation.BOARD),
|
|
115
|
+
upstream_read=UpstreamReadRoute(arguments.upstream_read),
|
|
116
|
+
closing_follow_ups=LandedClosingFollowUps.installed(),
|
|
117
|
+
)
|
|
118
|
+
return requested.run(maintenance, arguments)
|
|
119
|
+
except CommandFailure as error:
|
|
120
|
+
logger.error(f"{error}")
|
|
121
|
+
return error.exit_code
|
|
122
|
+
except (UpstreamReadError, GraphQLErrorsReturned) as error:
|
|
123
|
+
logger.error(f"{error}")
|
|
124
|
+
return StackExitCode.UPSTREAM_UNREADABLE
|
|
125
|
+
|
|
126
|
+
|
|
127
|
+
if __name__ == "__main__":
|
|
128
|
+
sys.exit(main())
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Reading fetched pull requests into the board the stack is derived from.
|
|
3
|
+
"""
|
|
4
|
+
|
|
5
|
+
from __future__ import annotations
|
|
6
|
+
|
|
7
|
+
import json
|
|
8
|
+
from collections.abc import Iterable
|
|
9
|
+
from dataclasses import asdict, dataclass
|
|
10
|
+
from pathlib import Path
|
|
11
|
+
|
|
12
|
+
from basstler.github.pull_request_description import PullRequestDescription
|
|
13
|
+
from basstler.github.pull_request_record import (
|
|
14
|
+
CommitChecks,
|
|
15
|
+
PullRequestField,
|
|
16
|
+
PullRequestHead,
|
|
17
|
+
PullRequestRecord,
|
|
18
|
+
)
|
|
19
|
+
from basstler.stack.model import BoardKey, PullRequest
|
|
20
|
+
from basstler.text_file import TextFile
|
|
21
|
+
from basstler.upstream_reviews.action.open_pull_requests import UpstreamPullRequests
|
|
22
|
+
|
|
23
|
+
# %% the export itself
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
@dataclass(frozen=True)
|
|
27
|
+
class BoardExport:
|
|
28
|
+
"""
|
|
29
|
+
The fork's open pull requests, in the shape the derived stack is read from.
|
|
30
|
+
"""
|
|
31
|
+
|
|
32
|
+
pull_requests: tuple[PullRequest, ...]
|
|
33
|
+
"""
|
|
34
|
+
The exported pull requests.
|
|
35
|
+
"""
|
|
36
|
+
|
|
37
|
+
@classmethod
|
|
38
|
+
def from_api_records(
|
|
39
|
+
cls,
|
|
40
|
+
records: Iterable[PullRequestRecord],
|
|
41
|
+
upstream_pull_requests: UpstreamPullRequests,
|
|
42
|
+
checks: CommitChecks,
|
|
43
|
+
) -> BoardExport:
|
|
44
|
+
"""
|
|
45
|
+
Build the export from what the REST API returned.
|
|
46
|
+
|
|
47
|
+
:param records: The fork's open pull requests.
|
|
48
|
+
:param upstream_pull_requests: The upstream pull requests open for the fork's
|
|
49
|
+
branches.
|
|
50
|
+
:param checks: Where the verdict over each head's checks is read from.
|
|
51
|
+
:return: The export.
|
|
52
|
+
:raises MissingPullRequestFieldError: If any record omits a required field.
|
|
53
|
+
"""
|
|
54
|
+
return cls(
|
|
55
|
+
tuple(
|
|
56
|
+
cls._pull_request(record, upstream_pull_requests, checks)
|
|
57
|
+
for record in records
|
|
58
|
+
)
|
|
59
|
+
)
|
|
60
|
+
|
|
61
|
+
@staticmethod
|
|
62
|
+
def _pull_request(
|
|
63
|
+
record: PullRequestRecord,
|
|
64
|
+
upstream_pull_requests: UpstreamPullRequests,
|
|
65
|
+
checks: CommitChecks,
|
|
66
|
+
) -> PullRequest:
|
|
67
|
+
"""
|
|
68
|
+
Read one fetched pull request into a board entry.
|
|
69
|
+
|
|
70
|
+
:param record: The fetched pull request.
|
|
71
|
+
:param upstream_pull_requests: The upstream pull requests open for the fork's
|
|
72
|
+
branches.
|
|
73
|
+
:param checks: Where the verdict over its head's checks is read from.
|
|
74
|
+
:return: The board entry.
|
|
75
|
+
:raises MissingPullRequestFieldError: If a required field is absent.
|
|
76
|
+
"""
|
|
77
|
+
number = int(PullRequestField.NUMBER.read(record))
|
|
78
|
+
head = PullRequestHead.from_record(record, number)
|
|
79
|
+
description = PullRequestDescription(
|
|
80
|
+
str(PullRequestField.BODY.read(record, number) or "")
|
|
81
|
+
)
|
|
82
|
+
return PullRequest(
|
|
83
|
+
number=number,
|
|
84
|
+
head=head.branch,
|
|
85
|
+
base=PullRequestField.BASE.read(record, number),
|
|
86
|
+
draft=bool(PullRequestField.DRAFT.read(record, number)),
|
|
87
|
+
head_repository=head.repository,
|
|
88
|
+
labels=PullRequestField.LABELS.read(record, number),
|
|
89
|
+
check_state=checks.check_state(head.commit),
|
|
90
|
+
upstream_pull_request=upstream_pull_requests.pull_request_for(head),
|
|
91
|
+
session=description.session_link,
|
|
92
|
+
title=PullRequestField.TITLE.read(record, number),
|
|
93
|
+
description=description.prose,
|
|
94
|
+
upstream_link=description.upstream_link,
|
|
95
|
+
)
|
|
96
|
+
|
|
97
|
+
def as_json(self) -> str:
|
|
98
|
+
""":return: The export, in the document :meth:`basstler.stack.model.PullRequest.read_board` parses."""
|
|
99
|
+
return json.dumps(
|
|
100
|
+
{BoardKey.PULL_REQUESTS: [asdict(entry) for entry in self.pull_requests]},
|
|
101
|
+
indent=2,
|
|
102
|
+
)
|
|
103
|
+
|
|
104
|
+
def write(self, path: Path) -> Path:
|
|
105
|
+
"""
|
|
106
|
+
Write the export where the derived stack is read from.
|
|
107
|
+
|
|
108
|
+
:param path: Where to write it.
|
|
109
|
+
:return: The path written to.
|
|
110
|
+
"""
|
|
111
|
+
path.parent.mkdir(parents=True, exist_ok=True)
|
|
112
|
+
TextFile(path).write(self.as_json() + "\n")
|
|
113
|
+
return path
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
"""
|
|
2
|
+
The verdict over every open branch's checks, as a few lines whatever the size of the
|
|
3
|
+
stack.
|
|
4
|
+
"""
|
|
5
|
+
|
|
6
|
+
from __future__ import annotations
|
|
7
|
+
|
|
8
|
+
from dataclasses import dataclass
|
|
9
|
+
|
|
10
|
+
from basstler.github.states import CombinedCheckState
|
|
11
|
+
from basstler.stack.model import BranchStatus, Stack, StackBranch
|
|
12
|
+
|
|
13
|
+
# %% the overview
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
@dataclass(frozen=True)
|
|
17
|
+
class CheckOverview:
|
|
18
|
+
"""
|
|
19
|
+
How many open branches' checks pass, run or fail, naming the ones that do not pass.
|
|
20
|
+
"""
|
|
21
|
+
|
|
22
|
+
stack: Stack
|
|
23
|
+
"""
|
|
24
|
+
The stack whose branches carry the verdict over their head's checks.
|
|
25
|
+
"""
|
|
26
|
+
|
|
27
|
+
entries_per_state: int = 5
|
|
28
|
+
"""
|
|
29
|
+
How many branches a line names before counting the rest.
|
|
30
|
+
"""
|
|
31
|
+
|
|
32
|
+
def open_branches(self) -> list[StackBranch]:
|
|
33
|
+
"""
|
|
34
|
+
:return: Every branch the pass maintains that has not landed, parent before
|
|
35
|
+
child.
|
|
36
|
+
"""
|
|
37
|
+
return [
|
|
38
|
+
branch
|
|
39
|
+
for branch in self.stack.maintained_branches()
|
|
40
|
+
if branch.status is not BranchStatus.MERGED
|
|
41
|
+
]
|
|
42
|
+
|
|
43
|
+
def branches_in(self, state: CombinedCheckState) -> list[StackBranch]:
|
|
44
|
+
"""
|
|
45
|
+
:param state: A verdict.
|
|
46
|
+
:return: The open branches whose checks have that verdict.
|
|
47
|
+
"""
|
|
48
|
+
return [
|
|
49
|
+
branch for branch in self.open_branches() if branch.check_state == state
|
|
50
|
+
]
|
|
51
|
+
|
|
52
|
+
def as_lines(self) -> list[str]:
|
|
53
|
+
"""
|
|
54
|
+
:return: One line counting every verdict, then one line per verdict other than
|
|
55
|
+
success naming its branches.
|
|
56
|
+
"""
|
|
57
|
+
counted = {state: len(self.branches_in(state)) for state in CombinedCheckState}
|
|
58
|
+
counts = ", ".join(
|
|
59
|
+
f"{count} {state}" for state, count in counted.items() if count
|
|
60
|
+
)
|
|
61
|
+
lines = [f"checks on {len(self.open_branches())} open branches: {counts}"]
|
|
62
|
+
for state in CombinedCheckState:
|
|
63
|
+
if state is CombinedCheckState.SUCCESS or not counted[state]:
|
|
64
|
+
continue
|
|
65
|
+
lines.append(f"{state}: {self.named(state)}")
|
|
66
|
+
return lines
|
|
67
|
+
|
|
68
|
+
def named(self, state: CombinedCheckState) -> str:
|
|
69
|
+
"""
|
|
70
|
+
:param state: A verdict.
|
|
71
|
+
:return: The first :attr:`entries_per_state` branches with it, by pull request
|
|
72
|
+
and name, and a count of the rest.
|
|
73
|
+
"""
|
|
74
|
+
branches = self.branches_in(state)
|
|
75
|
+
named = ", ".join(
|
|
76
|
+
f"#{branch.pull_request_number} `{branch.name}`"
|
|
77
|
+
for branch in branches[: self.entries_per_state]
|
|
78
|
+
)
|
|
79
|
+
hidden = len(branches) - self.entries_per_state
|
|
80
|
+
return named + (f" and {hidden} more" if hidden > 0 else "")
|