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
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 "")