roadkeep 0.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 (67) hide show
  1. roadkeep/__init__.py +79 -0
  2. roadkeep/adopting.py +2347 -0
  3. roadkeep/attesting.py +293 -0
  4. roadkeep/authoring.py +2117 -0
  5. roadkeep/backlog.py +767 -0
  6. roadkeep/blocking.py +1622 -0
  7. roadkeep/briefing.py +970 -0
  8. roadkeep/budgeting.py +2056 -0
  9. roadkeep/capturing.py +1699 -0
  10. roadkeep/claiming.py +1019 -0
  11. roadkeep/cli.py +638 -0
  12. roadkeep/commanding.py +487 -0
  13. roadkeep/config.py +1832 -0
  14. roadkeep/counting.py +376 -0
  15. roadkeep/criteria.py +933 -0
  16. roadkeep/deferring.py +708 -0
  17. roadkeep/describing.py +568 -0
  18. roadkeep/exporting.py +808 -0
  19. roadkeep/fixing.py +629 -0
  20. roadkeep/governing.py +934 -0
  21. roadkeep/graph.py +395 -0
  22. roadkeep/guarding.py +1028 -0
  23. roadkeep/history.py +2403 -0
  24. roadkeep/ids.py +301 -0
  25. roadkeep/installing.py +2145 -0
  26. roadkeep/kernel/__init__.py +24 -0
  27. roadkeep/kernel/document.py +1719 -0
  28. roadkeep/kernel/schema.py +2308 -0
  29. roadkeep/linting.py +4420 -0
  30. roadkeep/locking.py +209 -0
  31. roadkeep/markers.py +172 -0
  32. roadkeep/merging.py +1159 -0
  33. roadkeep/picking.py +772 -0
  34. roadkeep/provenance.py +789 -0
  35. roadkeep/queueing.py +752 -0
  36. roadkeep/ranking.py +139 -0
  37. roadkeep/referring.py +231 -0
  38. roadkeep/remaining.py +336 -0
  39. roadkeep/remedying.py +1989 -0
  40. roadkeep/rendering.py +1601 -0
  41. roadkeep/renumbering.py +503 -0
  42. roadkeep/repairing.py +295 -0
  43. roadkeep/reverting.py +144 -0
  44. roadkeep/scoping.py +708 -0
  45. roadkeep/screening.py +196 -0
  46. roadkeep/sections.py +4121 -0
  47. roadkeep/serving.py +2909 -0
  48. roadkeep/shipping.py +3993 -0
  49. roadkeep/showing.py +613 -0
  50. roadkeep/storing.py +224 -0
  51. roadkeep/verbs/__init__.py +26 -0
  52. roadkeep/verbs/adopting.py +974 -0
  53. roadkeep/verbs/authoring.py +566 -0
  54. roadkeep/verbs/declaring.py +335 -0
  55. roadkeep/verbs/linting.py +645 -0
  56. roadkeep/verbs/querying.py +2138 -0
  57. roadkeep/verbs/reading.py +307 -0
  58. roadkeep/verbs/refusing.py +146 -0
  59. roadkeep/verbs/sections.py +1433 -0
  60. roadkeep/verbs/shipping.py +819 -0
  61. roadkeep/weighing.py +380 -0
  62. roadkeep-0.2.0.dist-info/METADATA +453 -0
  63. roadkeep-0.2.0.dist-info/RECORD +67 -0
  64. roadkeep-0.2.0.dist-info/WHEEL +5 -0
  65. roadkeep-0.2.0.dist-info/entry_points.txt +2 -0
  66. roadkeep-0.2.0.dist-info/licenses/LICENSE +202 -0
  67. roadkeep-0.2.0.dist-info/top_level.txt +1 -0
roadkeep/repairing.py ADDED
@@ -0,0 +1,295 @@
1
+ """Running the report back, so a clean tree costs one call instead of one per finding (RK422).
2
+
3
+ RK420 made the remedy a fact; this is the verb that spends it. Without one, a caller holding
4
+ eight findings composes eight command lines, makes eight tool calls and gets eight chances to
5
+ mistype a flag — which is the cost that task *measured* and did not remove. An agent pays it
6
+ in turns, and a turn is the unit this whole tool is trying to save.
7
+
8
+ **Three classes, and only the first two are run.** The mechanical pass (`--fix`) goes first,
9
+ unchanged and reused rather than reimplemented, because a normalizer written twice is two
10
+ normalizers to keep in step. Then every finding whose remedy is a complete argv is executed
11
+ in the order the report gives. What is left — a title to write, a sentence to shorten, a
12
+ choice between two doors — is *printed*, because that is where the caller's judgement was
13
+ always required and where L4 says the tool stops. The exit code stays the gate's: 0 when the
14
+ tree came back clean, 1 when a decision is still outstanding.
15
+
16
+ **One repair per pass, and the report re-read between them.** This is the decision that makes
17
+ the verb correct rather than merely convenient. Half the remedies address a line by number —
18
+ `record drop <id> --line 275` — and the first write moves every line after it, so a batch
19
+ computed from one report and applied in sequence would address the file as it *was* from the
20
+ second command on. Re-linting after each write costs a parse per repair and buys the property
21
+ that every argv is derived from the tree it runs against. A repair that leaves the report
22
+ unchanged ends the loop: no progress is the one state a retry cannot improve, and it is also
23
+ what stops a rule that reports what its own remedy writes from spinning.
24
+
25
+ **`--dry-run` prints and runs nothing**, for two reasons that point the same way. A verb that
26
+ rewrites four governed files unasked is the opposite of a barrier; and the printed list is
27
+ itself the answer for a caller who wants to read before it acts, which is the same argument
28
+ `install --check` and `adopt` are built on.
29
+
30
+ The runner is **injected** rather than imported. `repair` executes roadkeep's own subcommands,
31
+ which live in :mod:`roadkeep.cli`, which imports this module — so the dependency is passed in
32
+ at the call site and this file stays a thing the tests can drive with a recording stub.
33
+ """
34
+
35
+ from __future__ import annotations
36
+
37
+ from collections.abc import Callable, Sequence
38
+ from dataclasses import dataclass, field
39
+
40
+ from .config import Config
41
+ from .fixing import Fix, fix
42
+ from .linting import Finding, Report, lint
43
+ from .remedying import Door, Remedy, remedy
44
+
45
+ #: The bound on the loop. Not a budget — a backstop. Progress is what actually ends the loop
46
+ #: (a pass that changes nothing stops it), and this only decides what happens if a repair and
47
+ #: a rule ever disagree forever. High enough that no honest backlog reaches it, low enough
48
+ #: that the disagreement surfaces as a report rather than as a hung process.
49
+ MAX_PASSES = 200
50
+
51
+
52
+ @dataclass(frozen=True, slots=True)
53
+ class Step:
54
+ """One command this run executed, or would have."""
55
+
56
+ code: str
57
+ where: str
58
+ argv: tuple[str, ...]
59
+ what: str
60
+ #: The command's own exit code. ``None`` under `--dry-run`, where nothing was run.
61
+ exit: int | None = None
62
+
63
+ @property
64
+ def ok(self) -> bool:
65
+ return self.exit in (0, None)
66
+
67
+ def __str__(self) -> str:
68
+ mark = "would" if self.exit is None else ("ran " if self.ok else "FAILED")
69
+ return f"{mark} {' '.join(self.argv)} — {self.what}"
70
+
71
+
72
+ @dataclass(frozen=True, slots=True)
73
+ class Left:
74
+ """One finding this run did not close, and what it is waiting for."""
75
+
76
+ finding: Finding
77
+ remedy: Remedy | None
78
+
79
+ def __str__(self) -> str:
80
+ if self.remedy is None:
81
+ # The state RK421's test exists to make impossible. Printed rather than hidden:
82
+ # a finding with no door is a defect in this tool, and saying so is how it gets
83
+ # reported instead of worked around.
84
+ return f"{self.finding}\n no remedy is declared for {self.finding.code}"
85
+ return f"{self.finding}\n" + "\n".join(
86
+ f" {line}" for line in str(self.remedy).splitlines()
87
+ )
88
+
89
+
90
+ @dataclass(frozen=True, slots=True)
91
+ class Repaired:
92
+ """What one run did, what it could not do, and whether the gate passes now."""
93
+
94
+ steps: tuple[Step, ...] = ()
95
+ left: tuple[Left, ...] = ()
96
+ applied: Fix = field(default_factory=Fix)
97
+ passes: int = 0
98
+ clean: bool = False
99
+ dry_run: bool = False
100
+ #: Set when the loop stopped on :data:`MAX_PASSES` rather than on running out of work.
101
+ exhausted: bool = False
102
+
103
+ @property
104
+ def failed(self) -> tuple[Step, ...]:
105
+ return tuple(step for step in self.steps if not step.ok)
106
+
107
+ def stated(self, root: str) -> str:
108
+ """What ran, what is left, and the two numbers that are not one (RK422, RK471).
109
+
110
+ Beside :meth:`payload` since RK1170. Runs and attempts are counted apart: this counted
111
+ the steps, so a run that dispatched three and had two refused closed with `3 repair(s)
112
+ ran` three lines under two the same output had already marked `FAILED` — and the count
113
+ is the line a person acts on, so a caller read `3 ran` against `34 left` and concluded
114
+ the tree moved three findings closer when it moved one. `Step.ok` already separates
115
+ them at the point they are decided; only the sum did not ask.
116
+
117
+ The exit code is untouched and stays 1 while anything is left: two refusals are not a
118
+ failure of `repair`, whose whole design is that what it cannot close it prints.
119
+ """
120
+ from roadkeep.rendering import _tree # noqa: PLC0415 - RK260
121
+
122
+ rows = self.applied.stated()
123
+ rows += [str(step) for step in self.steps]
124
+ rows += [str(left) for left in self.left]
125
+ verb = "would run" if self.dry_run else "ran"
126
+ ran = len(self.steps) - len(self.failed)
127
+ refused = f", {len(self.failed)} refused" if self.failed else ""
128
+ rows.append(
129
+ f"{ran} repair(s) {verb}{refused}, {len(self.left)} left for you{_tree(root)}"
130
+ )
131
+ return "\n".join(rows)
132
+
133
+ def warnings(self) -> list[str]:
134
+ """What this run has to say on **stderr**: a pass that wrote nothing, and a loop that
135
+ stopped on its own ceiling rather than on running out of work."""
136
+ rows = self.applied.refusals()
137
+ if self.exhausted:
138
+ rows.append(
139
+ f"roadkeep: stopped after {MAX_PASSES} repairs with work still reported: a "
140
+ f"rule and its own remedy disagree, which is a defect in this tool"
141
+ )
142
+ return rows
143
+
144
+ def payload(self, root: str, served: str = "") -> dict[str, object]:
145
+ return {
146
+ "root": root,
147
+ "clean": self.clean,
148
+ "dry_run": self.dry_run,
149
+ "passes": self.passes,
150
+ "exhausted": self.exhausted,
151
+ "steps": [
152
+ {
153
+ "code": step.code,
154
+ "where": step.where,
155
+ "argv": list(step.argv),
156
+ "what": step.what,
157
+ "exit": step.exit,
158
+ }
159
+ for step in self.steps
160
+ ],
161
+ "left": [
162
+ {
163
+ "code": left.finding.code,
164
+ "where": left.finding.where,
165
+ "message": left.finding.message,
166
+ **(
167
+ {}
168
+ if left.remedy is None
169
+ else {"remedy": left.remedy.payload(served)}
170
+ ),
171
+ }
172
+ for left in self.left
173
+ ],
174
+ }
175
+
176
+
177
+ def repair(
178
+ config: Config,
179
+ run: Callable[[Sequence[str]], int],
180
+ *,
181
+ dry_run: bool = False,
182
+ ) -> Repaired:
183
+ """Close every finding that has a runnable remedy; report the rest.
184
+
185
+ ``run`` takes an argv without the program name and returns its exit code — the CLI
186
+ passes its own dispatcher, and a test passes a stub that records.
187
+ """
188
+ if dry_run:
189
+ # One read and no loop: nothing is written, so every later pass would report the
190
+ # same file. What comes back is the list in report order — what this would do, not
191
+ # a simulation of what each one would then reveal.
192
+ report = lint(config)
193
+ return Repaired(
194
+ steps=tuple(_mechanical(report, config) + _every(report, config)),
195
+ left=tuple(
196
+ Left(finding, remedy(finding, config))
197
+ for finding in report.findings
198
+ if not _taken(finding, config)
199
+ ),
200
+ passes=0,
201
+ clean=report.clean,
202
+ dry_run=True,
203
+ )
204
+
205
+ applied = fix(config)
206
+ steps: list[Step] = []
207
+ passes = 0
208
+ #: Every argv already attempted. A command that ran and left its own finding standing is
209
+ #: not retried: the second attempt writes the same bytes, and the loop would become the
210
+ #: retry loop this verb exists to remove, one level up.
211
+ tried: set[tuple[str, ...]] = set()
212
+ exhausted = False
213
+
214
+ while passes < MAX_PASSES:
215
+ step = _next(lint(config), config, tried)
216
+ if step is None:
217
+ break
218
+ passes += 1
219
+ tried.add(step.argv)
220
+ steps.append(Step(step.code, step.where, step.argv, step.what, run(step.argv)))
221
+ else:
222
+ exhausted = True
223
+
224
+ # Everything still standing is left over, and no second rule is needed to say which:
225
+ # the loop only stopped because nothing runnable remained, so a finding here either
226
+ # never had a door or had one that ran and did not close it.
227
+ final = lint(config)
228
+ return Repaired(
229
+ steps=tuple(steps),
230
+ left=tuple(
231
+ Left(finding, remedy(finding, config)) for finding in final.findings
232
+ ),
233
+ applied=applied,
234
+ passes=passes,
235
+ clean=final.clean and not applied.refused,
236
+ exhausted=exhausted,
237
+ )
238
+
239
+
240
+ def _next(report: Report, config: Config, tried: set[tuple[str, ...]]) -> Step | None:
241
+ """The first finding in this report with a complete argv nothing has attempted yet."""
242
+ for step in _every(report, config):
243
+ if step.argv not in tried:
244
+ return step
245
+ return None
246
+
247
+
248
+ def _every(report: Report, config: Config) -> list[Step]:
249
+ """Every finding in this report whose remedy is one command, in report order."""
250
+ steps: list[Step] = []
251
+ seen: set[tuple[str, ...]] = set()
252
+ for finding in report.findings:
253
+ door = _door(finding, config)
254
+ # Deduplicated, because several findings can share one remedy — five stale README
255
+ # counts are one `export`, and running it five times is four writes of the same bytes.
256
+ if door is None or door.argv in seen:
257
+ continue
258
+ seen.add(door.argv)
259
+ steps.append(Step(finding.code, finding.where, door.argv, door.what))
260
+ return steps
261
+
262
+
263
+ def _mechanical(report: Report, config: Config) -> list[Step]:
264
+ """The normalizing pass, as one step, where this report has anything for it.
265
+
266
+ A real run calls :func:`~roadkeep.fixing.fix` before the loop and never reaches here.
267
+ The dry run has to state it anyway and has to state it *once*: listing `lint --fix`
268
+ under each of nine character findings is the report the mechanical class was folded
269
+ into a summary line to avoid (RK420), arriving through the verb built to shorten it.
270
+ """
271
+ for finding in report.findings:
272
+ found = remedy(finding, config)
273
+ if found is not None and found.kind == "fix":
274
+ door = found.doors[0]
275
+ return [Step("(mechanical)", finding.file, door.argv, door.what)]
276
+ return []
277
+
278
+
279
+ def _taken(finding: Finding, config: Config) -> bool:
280
+ """Whether a dry run would close this one, by either of the two passes it lists."""
281
+ found = remedy(finding, config)
282
+ return found is not None and found.kind in ("fix", "run") and found.runnable
283
+
284
+
285
+ def _door(finding: Finding, config: Config) -> Door | None:
286
+ """The one complete command that closes this finding, where there is exactly one.
287
+
288
+ `fix` is excluded because the pass at the top of :func:`repair` already ran it, and
289
+ `compose` and `decide` are excluded because both are the caller's — the first needs a
290
+ sentence the tool may not write (L4), the second a choice it may not make.
291
+ """
292
+ found = remedy(finding, config)
293
+ if found is None or found.kind != "run" or not found.runnable:
294
+ return None
295
+ return found.doors[0]
roadkeep/reverting.py ADDED
@@ -0,0 +1,144 @@
1
+ """Which decisions the ledger has already undone (RK416).
2
+
3
+ `origin <id>` reads a claim out of history and `gaps` resolves an id in neither file, so
4
+ history is queryable — but not for the question worth asking *before* a line is written:
5
+ **has this been tried and undone?**
6
+
7
+ A reversal is recorded as a delivery, and that is the whole defect. RK395 made the record
8
+ honest: `record add --supersedes <id>` writes the entry saying the work did not hold *and*
9
+ appends the forward pointer to the entry saying it shipped, so both records of one decision
10
+ name each other. What it did not do is make the pair *findable*. A duplicate check that asks
11
+ "did a shipped entry already do this" answers yes about the revert — because a revert is a
12
+ ✅ entry like any other — and misses that the new line is asking to undo it again.
13
+
14
+ The cost is worse than a duplicate's. A duplicate wastes an id; this wastes an id *plus the
15
+ argument the revert already had*, and the argument is the expensive half. Measured on a real
16
+ corpus: two tasks proposed automatic CI triggers, a third shipped the revert naming both by
17
+ id and saying the state a reader takes for an oversight is deliberate — and a fourth proposal
18
+ would still have been filed without a word.
19
+
20
+ **Nothing new is stored.** The forward pointer RK395 already writes is the whole signal, and
21
+ this reads it back: an entry whose sentence carries `(superseded by <id>)` is a decision that
22
+ was reversed, and the entry naming it is the argument. That is the same discipline as every
23
+ other query here — the store is the repository (L2), and a second index of what the ledger
24
+ already says is a second thing to keep in step.
25
+
26
+ What this deliberately does **not** do is refuse an `add`. Re-proposing something that was
27
+ reverted is sometimes exactly right — the revert may have been about a broken implementation
28
+ rather than a wrong idea — so the answer is a read the author makes, not a gate that decides
29
+ for them. A tool that judged which would be judging the prose (L4).
30
+ """
31
+
32
+ from __future__ import annotations
33
+
34
+ import re
35
+ from dataclasses import dataclass
36
+
37
+ from .backlog import Backlog
38
+ from .config import Config
39
+ from roadkeep.kernel.document import Entry
40
+
41
+ #: How :data:`~roadkeep.shipping._SUPERSEDED` renders, read back. Built from that constant
42
+ #: rather than spelled again: the writer and the reader of one clause disagreeing is the
43
+ #: defect this package is about, and a second literal here is how it would start.
44
+ _MARK = re.compile(r"\(superseded by ([^)]+)\)")
45
+
46
+
47
+ @dataclass(frozen=True, slots=True)
48
+ class Reversal:
49
+ """One decision the ledger recorded and then undid."""
50
+
51
+ #: The id whose entry carries the forward pointer — the work that shipped and did not hold.
52
+ undone: str
53
+ #: The id of the entry that reversed it, which is where the argument is.
54
+ by: str
55
+ undone_entry: Entry
56
+ by_entry: Entry | None = None
57
+
58
+ @property
59
+ def why(self) -> str:
60
+ """The reversing entry's sentence, which is the argument a new proposal is against."""
61
+ return "" if self.by_entry is None else self.by_entry.task.why
62
+
63
+ def __str__(self) -> str:
64
+ where = f"{self.undone_entry.lineno}"
65
+ return f"{self.undone:<8} undone by {self.by:<8} ledger:{where} {self.why}"
66
+
67
+
68
+ @dataclass(frozen=True, slots=True)
69
+ class Reversed:
70
+ """What the ledger already undid, as one answer (RK416).
71
+
72
+ The result that read had none of (RK1170): the door filtered the list, composed a header
73
+ out of a count and a flag, and built the payload beside it — so the two registers agreed
74
+ about the narrowing by hand.
75
+
76
+ :attr:`asked` is the caller's question and not a fact of the ledger, which is why it is a
77
+ field rather than something derived: `--id` narrows the same read, and the header has to
78
+ say so or a listing of one reads as a ledger with one reversal in it.
79
+ """
80
+
81
+ found: tuple[Reversal, ...]
82
+ where: str
83
+ root: str
84
+ #: The id the caller asked about, or `""` where the question was the whole ledger.
85
+ asked: str = ""
86
+
87
+ @property
88
+ def gated(self) -> bool:
89
+ """Whether `--id` found its answer, which is what an exit code carries (RK416).
90
+
91
+ Exit 1 is "this was tried and undone" and never "you may not" — the read states a
92
+ fact, and whether the revert was about a broken implementation or a wrong idea is the
93
+ one thing nobody here can tell.
94
+ """
95
+ return bool(self.asked and self.found)
96
+
97
+ def stated(self) -> str:
98
+ rows = [str(one) for one in self.found]
99
+ rows.append(
100
+ f"{len(self.found)} reversal(s) in {self.where}"
101
+ + (f" for {self.asked}" if self.asked else "")
102
+ )
103
+ return chr(10).join(rows)
104
+
105
+ def payload(self) -> dict[str, object]:
106
+ return {
107
+ "root": self.root,
108
+ "asked": self.asked or None,
109
+ "reversed": [
110
+ {
111
+ "undone": one.undone,
112
+ "by": one.by,
113
+ "line": one.undone_entry.lineno,
114
+ "why": one.why,
115
+ }
116
+ for one in self.found
117
+ ],
118
+ }
119
+
120
+
121
+ def reversals(config: Config) -> tuple[Reversal, ...]:
122
+ """Every entry the ledger marks as superseded, and the entry that superseded it.
123
+
124
+ In ledger order, which is block order: a reader scanning for "was this area already
125
+ settled" is scanning by subject, and the file is already arranged that way.
126
+ """
127
+ backlog = Backlog.load(config)
128
+ ledger = backlog.ledger
129
+ if ledger is None:
130
+ return ()
131
+ entries = ledger.by_id()
132
+ out: list[Reversal] = []
133
+ for task_id, entry in entries.items():
134
+ found = _MARK.search(entry.task.why)
135
+ if found is None:
136
+ continue
137
+ by = found.group(1).strip()
138
+ out.append(Reversal(task_id, by, entry, entries.get(by)))
139
+ return tuple(out)
140
+
141
+
142
+ def undone(config: Config) -> frozenset[str]:
143
+ """The ids alone — what a caller checks a fresh proposal against."""
144
+ return frozenset(one.undone for one in reversals(config))