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.
- roadkeep/__init__.py +79 -0
- roadkeep/adopting.py +2347 -0
- roadkeep/attesting.py +293 -0
- roadkeep/authoring.py +2117 -0
- roadkeep/backlog.py +767 -0
- roadkeep/blocking.py +1622 -0
- roadkeep/briefing.py +970 -0
- roadkeep/budgeting.py +2056 -0
- roadkeep/capturing.py +1699 -0
- roadkeep/claiming.py +1019 -0
- roadkeep/cli.py +638 -0
- roadkeep/commanding.py +487 -0
- roadkeep/config.py +1832 -0
- roadkeep/counting.py +376 -0
- roadkeep/criteria.py +933 -0
- roadkeep/deferring.py +708 -0
- roadkeep/describing.py +568 -0
- roadkeep/exporting.py +808 -0
- roadkeep/fixing.py +629 -0
- roadkeep/governing.py +934 -0
- roadkeep/graph.py +395 -0
- roadkeep/guarding.py +1028 -0
- roadkeep/history.py +2403 -0
- roadkeep/ids.py +301 -0
- roadkeep/installing.py +2145 -0
- roadkeep/kernel/__init__.py +24 -0
- roadkeep/kernel/document.py +1719 -0
- roadkeep/kernel/schema.py +2308 -0
- roadkeep/linting.py +4420 -0
- roadkeep/locking.py +209 -0
- roadkeep/markers.py +172 -0
- roadkeep/merging.py +1159 -0
- roadkeep/picking.py +772 -0
- roadkeep/provenance.py +789 -0
- roadkeep/queueing.py +752 -0
- roadkeep/ranking.py +139 -0
- roadkeep/referring.py +231 -0
- roadkeep/remaining.py +336 -0
- roadkeep/remedying.py +1989 -0
- roadkeep/rendering.py +1601 -0
- roadkeep/renumbering.py +503 -0
- roadkeep/repairing.py +295 -0
- roadkeep/reverting.py +144 -0
- roadkeep/scoping.py +708 -0
- roadkeep/screening.py +196 -0
- roadkeep/sections.py +4121 -0
- roadkeep/serving.py +2909 -0
- roadkeep/shipping.py +3993 -0
- roadkeep/showing.py +613 -0
- roadkeep/storing.py +224 -0
- roadkeep/verbs/__init__.py +26 -0
- roadkeep/verbs/adopting.py +974 -0
- roadkeep/verbs/authoring.py +566 -0
- roadkeep/verbs/declaring.py +335 -0
- roadkeep/verbs/linting.py +645 -0
- roadkeep/verbs/querying.py +2138 -0
- roadkeep/verbs/reading.py +307 -0
- roadkeep/verbs/refusing.py +146 -0
- roadkeep/verbs/sections.py +1433 -0
- roadkeep/verbs/shipping.py +819 -0
- roadkeep/weighing.py +380 -0
- roadkeep-0.2.0.dist-info/METADATA +453 -0
- roadkeep-0.2.0.dist-info/RECORD +67 -0
- roadkeep-0.2.0.dist-info/WHEEL +5 -0
- roadkeep-0.2.0.dist-info/entry_points.txt +2 -0
- roadkeep-0.2.0.dist-info/licenses/LICENSE +202 -0
- 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))
|