basstler-plan 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 (48) hide show
  1. basstler/plan/__init__.py +0 -0
  2. basstler/plan/check_dependency_readiness.py +86 -0
  3. basstler/plan/check_scope_overlap.py +445 -0
  4. basstler/plan/dependencies.py +539 -0
  5. basstler/plan/exceptions.py +843 -0
  6. basstler/plan/handover.py +591 -0
  7. basstler/plan/handover_command.py +280 -0
  8. basstler/plan/handover_continuation.py +274 -0
  9. basstler/plan/handover_options.py +89 -0
  10. basstler/plan/handover_originals.py +209 -0
  11. basstler/plan/handover_pull_request.py +405 -0
  12. basstler/plan/item_bootstrap/__init__.py +0 -0
  13. basstler/plan/item_bootstrap/__main__.py +53 -0
  14. basstler/plan/item_bootstrap/blockers.py +236 -0
  15. basstler/plan/item_bootstrap/check.py +184 -0
  16. basstler/plan/item_bootstrap/commands.py +294 -0
  17. basstler/plan/item_bootstrap/documents.py +379 -0
  18. basstler/plan/item_bootstrap/exceptions.py +299 -0
  19. basstler/plan/item_bootstrap/manifest_text.py +335 -0
  20. basstler/plan/item_bootstrap/opening.py +274 -0
  21. basstler/plan/item_bootstrap/record.py +153 -0
  22. basstler/plan/item_bootstrap/report.py +99 -0
  23. basstler/plan/item_bootstrap/update.py +119 -0
  24. basstler/plan/item_bootstrap/vocabulary.py +260 -0
  25. basstler/plan/item_brief.py +324 -0
  26. basstler/plan/item_mode.py +839 -0
  27. basstler/plan/manifest_tools.py +500 -0
  28. basstler/plan/merge.py +446 -0
  29. basstler/plan/merged_items/__init__.py +4 -0
  30. basstler/plan/merged_items/__main__.py +74 -0
  31. basstler/plan/merged_items/every_plan.py +185 -0
  32. basstler/plan/merged_items/plan_items.py +96 -0
  33. basstler/plan/model.py +1057 -0
  34. basstler/plan/model_alias.py +35 -0
  35. basstler/plan/plan-item-modes.toml +21 -0
  36. basstler/plan/repository_rules.py +130 -0
  37. basstler/plan/repository_rules_command.py +107 -0
  38. basstler/plan/repository_rules_store.py +86 -0
  39. basstler/plan/size_check.py +162 -0
  40. basstler/plan/size_limits.py +764 -0
  41. basstler/plan/structure.py +460 -0
  42. basstler/plan/updates_since_support.py +168 -0
  43. basstler/plan/validation.py +563 -0
  44. basstler_plan-4.2.0.dist-info/METADATA +19 -0
  45. basstler_plan-4.2.0.dist-info/RECORD +48 -0
  46. basstler_plan-4.2.0.dist-info/WHEEL +4 -0
  47. basstler_plan-4.2.0.dist-info/licenses/LICENSE +202 -0
  48. basstler_plan-4.2.0.dist-info/licenses/NOTICE +13 -0
File without changes
@@ -0,0 +1,86 @@
1
+ """
2
+ Classify one item's dependencies as ready or not-ready to build on, reusing the plan
3
+ site's own live-state classification and readiness rule.
4
+ """
5
+
6
+ from __future__ import annotations
7
+
8
+ from dataclasses import dataclass
9
+ from enum import StrEnum
10
+ from typing import Any
11
+
12
+ from basstler.github.pull_request_state import LivePullRequests
13
+ from basstler.plan.dependencies import Dependency, DependencyResolver, PlanDirectory
14
+ from basstler.plan.structure import Plan
15
+
16
+
17
+ class UnknownItemError(ValueError):
18
+ """
19
+ Raised when the requested item id doesn't exist in the plan.
20
+ """
21
+
22
+
23
+ class ReadinessField(StrEnum):
24
+ """
25
+ The keys one dependency's readiness carries once serialized.
26
+ """
27
+
28
+ IDENTIFIER = "identifier"
29
+ TITLE = "title"
30
+ LIVE_STATE = "live_state"
31
+ IS_READY = "is_ready"
32
+
33
+
34
+ @dataclass(frozen=True)
35
+ class DependencyReadiness:
36
+ """
37
+ One ``depends_on`` entry, and whether it is safe to build on.
38
+ """
39
+
40
+ dependency: Dependency
41
+ """
42
+ The dependency, with its live state already classified.
43
+ """
44
+
45
+ def to_json(self) -> dict[str, Any]:
46
+ """
47
+ This readiness as the one entry the item brief serializes for it.
48
+ """
49
+ live_state = self.dependency.live_state
50
+ return {
51
+ ReadinessField.IDENTIFIER.value: self.dependency.reference.text,
52
+ ReadinessField.TITLE.value: self.dependency.title,
53
+ ReadinessField.LIVE_STATE.value: live_state.value if live_state else None,
54
+ ReadinessField.IS_READY.value: (
55
+ self.dependency.is_ready_to_unblock_dependents()
56
+ ),
57
+ }
58
+
59
+ @classmethod
60
+ def of_item(
61
+ cls,
62
+ plan: Plan,
63
+ item_identifier: str,
64
+ live_pull_requests: LivePullRequests,
65
+ plan_directory: PlanDirectory | None = None,
66
+ ) -> list[DependencyReadiness]:
67
+ """
68
+ Classify every dependency of ``item_identifier`` as ready or not.
69
+
70
+ :param plan: The already-validated plan.
71
+ :param item_identifier: The effective identifier (``id`` or ``branch``) of the
72
+ item whose dependencies should be checked.
73
+ :param live_pull_requests: What was read of every repository referenced by the
74
+ plan's items, and by any plan they depend on.
75
+ :param plan_directory: The other plans a ``<plan-id>/<item-id>`` dependency
76
+ resolves against, or ``None`` when only this plan's own items are available.
77
+ :raises UnknownItemError: If ``item_identifier`` isn't in the plan.
78
+ :return: One readiness per entry in the item's ``depends_on``, in that order.
79
+ """
80
+ item = plan.items_by_identifier.get(item_identifier)
81
+ if item is None:
82
+ raise UnknownItemError(f"no item {item_identifier!r} in plan {plan.id!r}")
83
+
84
+ resolver = DependencyResolver(plan=plan, plan_directory=plan_directory)
85
+ resolver.classify_live_states(live_pull_requests)
86
+ return [cls(dependency) for dependency in resolver.dependencies_of(item)]
@@ -0,0 +1,445 @@
1
+ #!/usr/bin/env python3
2
+ """
3
+ Answer the two mechanical questions in ``scope-decision.md``: do the paths a piece of
4
+ work touches already exist on the base branch, and which unlanded branches already touch
5
+ them.
6
+
7
+ The judgement itself - fold or split - stays with the reader; this only gathers the
8
+ evidence, so the check is actually run rather than eyeballed. Pure git, so it needs no
9
+ network access and no GitHub API call.
10
+
11
+ Prints a one-line JSON object to stdout:
12
+ {"paths_absent_from_base": ["<path>", ...],
13
+ "candidates": [{"label": "<label>", "branch": "<branch>",
14
+ "shared_paths": ["<path>", ...],
15
+ "changed_paths": ["<path>", ...]}, ...]}
16
+
17
+ ``paths_absent_from_base`` holds the requested paths the base branch doesn't have yet -
18
+ non-empty means whichever unlanded branch introduces them is a candidate owner of the
19
+ work. ``shared_paths`` holds the files a candidate changes that the requested paths
20
+ cover, a directory covering every file below it; ``changed_paths`` is everything that
21
+ candidate changes, for comparing by purpose when two branches build the same thing under
22
+ different names.
23
+
24
+ A branch that doesn't resolve raises :class:`UnknownBranchError` rather than being
25
+ reported as no overlap.
26
+ """
27
+
28
+ from __future__ import annotations
29
+
30
+ import json
31
+ import subprocess
32
+ import sys
33
+ from collections.abc import Sequence
34
+ from dataclasses import dataclass
35
+ from enum import StrEnum
36
+ from pathlib import Path, PurePosixPath
37
+ from typing import Annotated, Any
38
+
39
+ from cyclopts import App, Parameter
40
+
41
+ from basstler.class_property import classproperty
42
+ from basstler.exit_codes import CommandFailure, ExitCode, ScopeOverlapExitCode
43
+ from basstler.standard_streams import StandardStreamHandler
44
+
45
+ logger = StandardStreamHandler.logger_for(__name__)
46
+ """
47
+ This module's logger, which is also what its command prints through.
48
+ """
49
+
50
+
51
+ class ReportKey(StrEnum):
52
+ """
53
+ The keys of the JSON document this script prints.
54
+
55
+ Named here so the reader that consumes the report and the code that builds it cannot
56
+ drift apart, and so a caller never spells one out as a bare string.
57
+ """
58
+
59
+ PATHS_ABSENT_FROM_BASE = "paths_absent_from_base"
60
+ """
61
+ The requested paths the base branch doesn't contain yet.
62
+ """
63
+
64
+ CANDIDATES = "candidates"
65
+ """
66
+ One overlap entry per requested candidate branch.
67
+ """
68
+
69
+ LABEL = "label"
70
+ """
71
+ How a candidate was named on the command line.
72
+ """
73
+
74
+ BRANCH = "branch"
75
+ """
76
+ The candidate's branch name.
77
+ """
78
+
79
+ SHARED_PATHS = "shared_paths"
80
+ """
81
+ The requested paths a candidate already changes.
82
+ """
83
+
84
+ CHANGED_PATHS = "changed_paths"
85
+ """
86
+ Every path a candidate changes, for comparing by purpose.
87
+ """
88
+
89
+
90
+ @dataclass
91
+ class UnknownBranchError(CommandFailure, ValueError):
92
+ """
93
+ Raised when a requested base or candidate branch doesn't resolve in the repository.
94
+ """
95
+
96
+ @classproperty
97
+ def exit_code(cls) -> ScopeOverlapExitCode:
98
+ """:return: The status this kind of error ends a command with."""
99
+ return ScopeOverlapExitCode.UNREADABLE_INPUT
100
+
101
+ git_command: str
102
+ """
103
+ The git command that failed.
104
+ """
105
+ result_stderr: str
106
+ """
107
+ The git error message.
108
+ """
109
+
110
+ def __str__(self) -> str:
111
+ return f"git {self.git_command} failed: {self.result_stderr}"
112
+
113
+
114
+ @dataclass
115
+ class MalformedCandidateError(CommandFailure, ValueError):
116
+ """
117
+ Raised when a ``--candidate`` argument isn't in ``<label>=<branch>`` form.
118
+ """
119
+
120
+ @classproperty
121
+ def exit_code(cls) -> ScopeOverlapExitCode:
122
+ """:return: The status this kind of error ends a command with."""
123
+ return ScopeOverlapExitCode.UNREADABLE_INPUT
124
+
125
+ expected_candidate: str
126
+ """
127
+ The expected format.
128
+ """
129
+ wrong_candidate: str
130
+ """
131
+ The argument that failed to parse.
132
+ """
133
+
134
+ def __str__(self) -> str:
135
+ return f"expected {self.expected_candidate!r}, got {self.wrong_candidate!r}"
136
+
137
+
138
+ # %% inputs and results
139
+
140
+
141
+ @dataclass(frozen=True)
142
+ class Candidate:
143
+ """
144
+ An unlanded branch the work might already belong to.
145
+ """
146
+
147
+ label: str
148
+ """
149
+ How the candidate is named back to the reader, typically a plan item id or pull
150
+ request title.
151
+ """
152
+
153
+ branch: str
154
+ """
155
+ The branch to compare against.
156
+ """
157
+
158
+ @classproperty
159
+ def separator(cls) -> str:
160
+ """
161
+ Separates a ``--candidate`` argument's label from its branch name.
162
+ """
163
+ return "="
164
+
165
+ @classmethod
166
+ def parse(cls, argument: str) -> Candidate:
167
+ """
168
+ Build a candidate from a ``<label>=<branch>`` command line argument.
169
+
170
+ :param argument: The raw argument value.
171
+ :raises MalformedCandidateError: If the separator is missing or either side is
172
+ empty.
173
+ :return: The parsed candidate.
174
+ """
175
+ label, separator, branch = argument.partition(cls.separator)
176
+ if not separator or not label.strip() or not branch.strip():
177
+ raise MalformedCandidateError(f"'<label>{cls.separator}<branch>'", argument)
178
+ return cls(label.strip(), branch.strip())
179
+
180
+
181
+ @dataclass(frozen=True)
182
+ class CandidateOverlap:
183
+ """
184
+ What one candidate branch changes, and how much of that the work would touch too.
185
+ """
186
+
187
+ candidate: Candidate
188
+ """
189
+ The branch this overlap was computed for.
190
+ """
191
+
192
+ shared_paths: list[str]
193
+ """
194
+ The files this candidate changes that the requested paths cover.
195
+ """
196
+
197
+ changed_paths: list[str]
198
+ """
199
+ Every path this candidate changes, relative to its merge base with the base branch.
200
+ """
201
+
202
+ def as_json(self) -> dict[str, Any]:
203
+ """
204
+ Render the overlap in the output shape documented in the module docstring.
205
+ """
206
+ return {
207
+ ReportKey.LABEL: self.candidate.label,
208
+ ReportKey.BRANCH: self.candidate.branch,
209
+ ReportKey.SHARED_PATHS: self.shared_paths,
210
+ ReportKey.CHANGED_PATHS: self.changed_paths,
211
+ }
212
+
213
+
214
+ @dataclass(frozen=True)
215
+ class RequestedPath:
216
+ """
217
+ A path the work touches: one file, or a directory with every file below it.
218
+ """
219
+
220
+ path: str
221
+ """
222
+ The path as requested, relative to the repository root.
223
+ """
224
+
225
+ def covers(self, file: str) -> bool:
226
+ """
227
+ :param file: A file's path, relative to the repository root.
228
+ :return: Whether the file is this path or lies below it.
229
+ """
230
+ return PurePosixPath(file).is_relative_to(self.path.rstrip("/"))
231
+
232
+
233
+ @dataclass(frozen=True)
234
+ class ScopeReport:
235
+ """
236
+ The full evidence for one scope decision.
237
+ """
238
+
239
+ paths_absent_from_base: list[str]
240
+ """
241
+ The requested paths the base branch doesn't contain yet.
242
+ """
243
+
244
+ candidates: list[CandidateOverlap]
245
+ """
246
+ One entry per requested candidate, in the order they were given.
247
+ """
248
+
249
+ def as_json(self) -> dict[str, Any]:
250
+ """
251
+ Render the report in the output shape documented in the module docstring.
252
+ """
253
+ return {
254
+ ReportKey.PATHS_ABSENT_FROM_BASE: self.paths_absent_from_base,
255
+ ReportKey.CANDIDATES: [overlap.as_json() for overlap in self.candidates],
256
+ }
257
+
258
+
259
+ # %% git plumbing
260
+
261
+
262
+ def run_git(repository_path: Path, *arguments: str) -> str:
263
+ """
264
+ Run git in *repository_path* and return its standard output.
265
+
266
+ :param repository_path: The repository to run in.
267
+ :param arguments: The arguments to pass to git.
268
+ :raises UnknownBranchError: If git reports a revision it cannot resolve.
269
+ :return: Git's standard output, stripped of the trailing newline.
270
+ """
271
+ result = subprocess.run(
272
+ ["git", *arguments],
273
+ cwd=repository_path,
274
+ capture_output=True,
275
+ encoding="utf-8",
276
+ )
277
+ if result.returncode != 0:
278
+ raise UnknownBranchError(f"git {' '.join(arguments)}", result.stderr.strip())
279
+ return result.stdout.rstrip("\n")
280
+
281
+
282
+ def paths_present_on(
283
+ repository_path: Path, branch: str, paths: Sequence[str]
284
+ ) -> set[str]:
285
+ """
286
+ Report which of *paths* the given branch's tree already contains.
287
+
288
+ :param repository_path: The repository to inspect.
289
+ :param branch: The branch whose tree to look in.
290
+ :param paths: The paths to look for.
291
+ :raises UnknownBranchError: If *branch* doesn't resolve.
292
+ :return: The subset of *paths* that exist there.
293
+ """
294
+ listing = run_git(
295
+ repository_path, "ls-tree", "-r", "--name-only", branch, "--", *paths
296
+ )
297
+ found = [line for line in listing.splitlines() if line]
298
+ return {
299
+ path
300
+ for path in paths
301
+ if any(RequestedPath(path).covers(file) for file in found)
302
+ }
303
+
304
+
305
+ def changed_paths_since_base(
306
+ repository_path: Path, base_branch: str, branch: str
307
+ ) -> list[str]:
308
+ """
309
+ List everything *branch* changes relative to its merge base with *base_branch*.
310
+
311
+ Using the merge base rather than the base branch's tip keeps commits that landed on
312
+ the base after *branch* forked out of the result.
313
+
314
+ :param repository_path: The repository to inspect.
315
+ :param base_branch: The branch the work ultimately targets.
316
+ :param branch: The candidate branch.
317
+ :raises UnknownBranchError: If either branch doesn't resolve.
318
+ :return: The changed paths, in git's own order.
319
+ """
320
+ merge_base = run_git(repository_path, "merge-base", base_branch, branch)
321
+ listing = run_git(repository_path, "diff", "--name-only", f"{merge_base}..{branch}")
322
+ return [line for line in listing.splitlines() if line]
323
+
324
+
325
+ # %% the report
326
+
327
+
328
+ def build_scope_report(
329
+ repository_path: Path,
330
+ base_branch: str,
331
+ paths: Sequence[str],
332
+ candidates: Sequence[Candidate],
333
+ ) -> ScopeReport:
334
+ """
335
+ Gather the evidence for one scope decision.
336
+
337
+ :param repository_path: The repository to inspect.
338
+ :param base_branch: The branch the work ultimately targets.
339
+ :param paths: The paths the work would create or modify.
340
+ :param candidates: The unlanded branches to compare against.
341
+ :raises UnknownBranchError: If the base or any candidate branch doesn't resolve.
342
+ :return: The assembled report.
343
+ """
344
+ present = paths_present_on(repository_path, base_branch, paths)
345
+ requested = [RequestedPath(path) for path in paths]
346
+ overlaps = []
347
+ for candidate in candidates:
348
+ changed = changed_paths_since_base(
349
+ repository_path, base_branch, candidate.branch
350
+ )
351
+ overlaps.append(
352
+ CandidateOverlap(
353
+ candidate,
354
+ [
355
+ file
356
+ for file in changed
357
+ if any(path.covers(file) for path in requested)
358
+ ],
359
+ changed,
360
+ )
361
+ )
362
+ return ScopeReport([path for path in paths if path not in present], overlaps)
363
+
364
+
365
+ class ScopeOverlapOption(StrEnum):
366
+ """
367
+ The options this script's command line takes.
368
+ """
369
+
370
+ REPOSITORY = "--repository"
371
+ """
372
+ The repository to inspect.
373
+ """
374
+
375
+ BASE = "--base"
376
+ """
377
+ The branch the work ultimately targets.
378
+ """
379
+
380
+ PATH = "--path"
381
+ """
382
+ A path the work would create or modify, repeated per path.
383
+ """
384
+
385
+ CANDIDATE = "--candidate"
386
+ """
387
+ An unlanded branch to compare against, as ``<label>=<branch>``, repeated per branch.
388
+ """
389
+
390
+
391
+ scope_overlap_app = App(
392
+ name="basstler.plan.check_scope_overlap",
393
+ help="Report which paths the base lacks and which unlanded branches touch them.",
394
+ )
395
+ """
396
+ This module's command line.
397
+ """
398
+
399
+
400
+ @scope_overlap_app.default
401
+ def check(
402
+ *,
403
+ base: Annotated[str, Parameter(name=ScopeOverlapOption.BASE)],
404
+ paths: Annotated[list[str], Parameter(name=ScopeOverlapOption.PATH)],
405
+ candidates: Annotated[
406
+ tuple[str, ...], Parameter(name=ScopeOverlapOption.CANDIDATE)
407
+ ] = (),
408
+ repository: Annotated[Path, Parameter(name=ScopeOverlapOption.REPOSITORY)] = Path(
409
+ "."
410
+ ),
411
+ ) -> ScopeOverlapExitCode:
412
+ """
413
+ Print the scope report as one line of JSON.
414
+
415
+ :param base: The branch the work ultimately targets.
416
+ :param paths: A path the work would create or modify; repeat for each one.
417
+ :param candidates: An unlanded branch to compare against, as
418
+ ``<label>=<branch>``; repeat for each one.
419
+ :param repository: The repository to inspect.
420
+ """
421
+ report = build_scope_report(
422
+ repository,
423
+ base,
424
+ paths,
425
+ [Candidate.parse(candidate) for candidate in candidates],
426
+ )
427
+ logger.info(json.dumps(report.as_json()))
428
+ return ScopeOverlapExitCode.SUCCESS
429
+
430
+
431
+ def main() -> ExitCode:
432
+ """
433
+ Run the command line, ending with the status a refusal carries.
434
+
435
+ :return: The process exit code.
436
+ """
437
+ try:
438
+ return scope_overlap_app(sys.argv[1:], result_action="return_value")
439
+ except CommandFailure as error:
440
+ logger.error(f"{error}")
441
+ return error.exit_code
442
+
443
+
444
+ if __name__ == "__main__":
445
+ sys.exit(main())