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/fixing.py
ADDED
|
@@ -0,0 +1,629 @@
|
|
|
1
|
+
"""Normalizing what is mechanical, so the report left is one somebody acts on (RK16).
|
|
2
|
+
|
|
3
|
+
A first run against a real backlog reports dozens of violations, and a report that size
|
|
4
|
+
gets ignored wholesale — which makes the gate (RK14) worth exactly nothing on the file
|
|
5
|
+
that needed it most. So the findings split in two:
|
|
6
|
+
|
|
7
|
+
* **mechanical** — the dep annotation (derived data, RK8), a pointer the scheme derives
|
|
8
|
+
(RK27), a duplicate or unordered dep, an invisible codepoint stuck to the marker, and
|
|
9
|
+
whitespace around a field. Nothing here is anybody's prose, and every one of them is
|
|
10
|
+
recomputed from the parsed line rather than edited in place. The queue's dead entry is
|
|
11
|
+
the same class from the roadmap's third list, and the first repair that *removes* a line
|
|
12
|
+
rather than re-rendering one (RK328, :func:`_dequeue`); the criteria heading addressed
|
|
13
|
+
to nothing and holding nothing is the second (RK1318, :func:`_unaddress`);
|
|
14
|
+
* **editorial** — an over-long `why`, a symptom that is a sentence, a dep on a task in
|
|
15
|
+
neither file. Each needs a decision, and a tool that made it would be writing prose (L4).
|
|
16
|
+
|
|
17
|
+
`--fix` applies the first list and leaves the second, which is the whole point: what
|
|
18
|
+
remains is short enough to read.
|
|
19
|
+
|
|
20
|
+
**How this coexists with L3.** Every mutator in :mod:`roadkeep.kernel.document` refuses the
|
|
21
|
+
*whole file* when any line it parsed would render back differently, because a silent
|
|
22
|
+
rewrite of a line the parser misread is unreviewable corruption. That guard is exactly
|
|
23
|
+
what a normalizer has to get past — an invisible selector on the marker and a hand-chosen
|
|
24
|
+
anchor are both *non-canonical*, and they are the two things most worth fixing. So this
|
|
25
|
+
module does not relax the invariant, it discharges it per line:
|
|
26
|
+
|
|
27
|
+
1. a line is only ever replaced by ``schema.render`` of the task parsed **from that line**;
|
|
28
|
+
2. a line nobody chose to fix is carried through byte-for-byte, endings included;
|
|
29
|
+
3. the result is re-parsed before anything reaches the disk, and every line this pass
|
|
30
|
+
changed must come back canonical — otherwise **nothing is written at all**.
|
|
31
|
+
|
|
32
|
+
A line the grammar rejected is never touched: there is no parse to re-render, so a
|
|
33
|
+
"fix" would be a guess, and a guess is what rule 1 exists to forbid.
|
|
34
|
+
|
|
35
|
+
**One repair is not a re-render, and it is the one nothing else could reach** (RK126). Every
|
|
36
|
+
write verb takes a whole entry — `record add` appends one, `record drop` removes one, `ship`
|
|
37
|
+
writes one from a roadmap line — so a control character *inside* a line somebody wrote
|
|
38
|
+
correctly two years ago had no expressible repair at all: the guard denies the edit, and the
|
|
39
|
+
four commands its refusal names all operate on the entry. Measured on Shio: two `U+0008` in
|
|
40
|
+
an entry's continuation line, which is not an entry at all and which no parse reaches.
|
|
41
|
+
|
|
42
|
+
So the character pass runs **before** the re-render, over every raw line of a line-bearing
|
|
43
|
+
file, and writes only what :func:`~roadkeep.linting.repaired` allows — a deletion for
|
|
44
|
+
codepoints that are not text under any reading, and a space for the tab past an indentation
|
|
45
|
+
that this format writes as one. It is exempt from rule 1 and from nothing else: rule 2 still
|
|
46
|
+
carries every other byte through, and rule 3 still proves the whole file before the disk sees
|
|
47
|
+
it. What that pass may *not* do is lose work, so the verification asks the weaker question it
|
|
48
|
+
was always about — no id gone, no new line the grammar cannot read — because a control
|
|
49
|
+
character removed from a bullet the grammar was rejecting *because of it* turns a reject into
|
|
50
|
+
an entry, which is the outcome and not a failure.
|
|
51
|
+
|
|
52
|
+
The other two defects in that file stay where the split above puts them. The dead link in an
|
|
53
|
+
entry's prose is `record amend`'s (RK124), and a bullet with no `—` separator is a reject:
|
|
54
|
+
where the separator goes is a decision about where the symptom ends, and rule 1 is exactly
|
|
55
|
+
the rule that forbids guessing it.
|
|
56
|
+
"""
|
|
57
|
+
|
|
58
|
+
from __future__ import annotations
|
|
59
|
+
|
|
60
|
+
from collections.abc import Mapping
|
|
61
|
+
from dataclasses import dataclass, replace
|
|
62
|
+
from pathlib import Path
|
|
63
|
+
|
|
64
|
+
from roadkeep import criteria, queueing
|
|
65
|
+
from roadkeep.backlog import Backlog, id_order
|
|
66
|
+
from roadkeep.config import PROSE_ROLES, Config
|
|
67
|
+
from roadkeep.kernel.document import Document, StaleFile, ending, write_atomically
|
|
68
|
+
from roadkeep.linting import LINE_ROLES, MARK
|
|
69
|
+
from roadkeep.kernel.schema import indentation, repaired
|
|
70
|
+
from roadkeep.markers import derive
|
|
71
|
+
from roadkeep.kernel.schema import Dep, DepKind, Schema, Task
|
|
72
|
+
|
|
73
|
+
#: Which words each pass may produce, declared **beside the pass it belongs to** (RK1327).
|
|
74
|
+
#:
|
|
75
|
+
#: RK355 put the list here because six files tell a reader what is mechanical — this module,
|
|
76
|
+
#: `agents.md`, the shipped skill, the `lint` command, the README and
|
|
77
|
+
#: :class:`~roadkeep.guarding.Review`, which is the one an agent reads because the `Stop` hook
|
|
78
|
+
#: prints it — and RK328's sixth repair reached three of them. What that gate holds is one
|
|
79
|
+
#: direction: every declared word is stated in each copy. It never held that every repair is
|
|
80
|
+
#: *declared*, so the list was checked against the prose and not against the code, and RK1318
|
|
81
|
+
#: added a seventh repair with nothing going red.
|
|
82
|
+
#:
|
|
83
|
+
#: A word with no repair needs prose to judge and stays outside a gate (L4). A repair with no
|
|
84
|
+
#: word does not, and this is where it becomes decidable: a function producing repairs and
|
|
85
|
+
#: missing from these keys is a red in `tests/test_fixing.py`, and a word added here is a red
|
|
86
|
+
#: in each copy until it is stated. Both directions, from one declaration.
|
|
87
|
+
#:
|
|
88
|
+
#: Keyed by the **pass** and not by the repair, because one of them is not one word: the
|
|
89
|
+
#: re-render recomputes a line from its own parse and reports whichever of four it corrected.
|
|
90
|
+
_PASSES: Mapping[str, tuple[str, ...]] = {
|
|
91
|
+
"_fix_file": ("annotation", "pointer", "order", "whitespace"),
|
|
92
|
+
"_decontrol": ("codepoint",),
|
|
93
|
+
"_unmark_file": ("codepoint",),
|
|
94
|
+
"_dequeue": ("queue",),
|
|
95
|
+
"_unaddress": ("criteria",),
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
#: Every repair `--fix` makes, in declaration order — **derived** from the passes above, so
|
|
99
|
+
#: nobody joins two lists (RK1327). A word and not a sentence, because the phrasings are
|
|
100
|
+
#: deliberate — a hook message names the repair, the README explains it — and a test comparing
|
|
101
|
+
#: sentences would be a seventh statement of the list rather than a gate on the six. Nothing
|
|
102
|
+
#: imports this at run time: `guarding` stays out of this module's import path, which is
|
|
103
|
+
#: milliseconds RK260 already paid for, so the hook's copy is prose the test proves.
|
|
104
|
+
REPAIRS: tuple[str, ...] = tuple(
|
|
105
|
+
dict.fromkeys(word for words in _PASSES.values() for word in words)
|
|
106
|
+
)
|
|
107
|
+
|
|
108
|
+
|
|
109
|
+
@dataclass(frozen=True, slots=True)
|
|
110
|
+
class Repair:
|
|
111
|
+
"""One line, rewritten or removed, and the mechanical reasons it was."""
|
|
112
|
+
|
|
113
|
+
file: str
|
|
114
|
+
lineno: int
|
|
115
|
+
id: str
|
|
116
|
+
before: str
|
|
117
|
+
after: str
|
|
118
|
+
reasons: tuple[str, ...]
|
|
119
|
+
#: Whether the line is **gone** rather than rewritten (RK357). RK328's drop is the one
|
|
120
|
+
#: repair that is not a re-render, and `lineno` is the position it was read at — so after
|
|
121
|
+
#: the pass that address names whatever moved up into its place, and the two readings of
|
|
122
|
+
#: the same `file:line` were indistinguishable in a line a terminal renders as a link.
|
|
123
|
+
#:
|
|
124
|
+
#: A field here rather than a third report kind: `--json` would carry three lists where a
|
|
125
|
+
#: consumer reads one, and every caller that prints repairs would learn a second loop. The
|
|
126
|
+
#: cost a field is supposed to have — a boolean a reader has to know to check — is not paid,
|
|
127
|
+
#: because neither surface makes anybody check it: :meth:`__str__` says `gone` where it
|
|
128
|
+
#: says `fixed`, and the payload carries the key. Set and not derived from an empty
|
|
129
|
+
#: ``after``: :func:`_decontrol` can empty a final line that had nothing but control
|
|
130
|
+
#: characters on it, and that is a character repair rather than a removal.
|
|
131
|
+
removed: bool = False
|
|
132
|
+
|
|
133
|
+
def __str__(self) -> str:
|
|
134
|
+
# The id is empty on a line that is not an entry — the continuation line RK126 is
|
|
135
|
+
# about — and a report reading "fixed :" names a task that does not exist.
|
|
136
|
+
named = f"{self.id}: " if self.id else ""
|
|
137
|
+
# Five wide, which is the column `Skipped`'s `kept` already sits in: three states a
|
|
138
|
+
# report is read by, and a verb that pushed the reason across would be the fix for
|
|
139
|
+
# this defect making the report harder to read than the defect did.
|
|
140
|
+
verb = "gone" if self.removed else "fixed"
|
|
141
|
+
return f"{self.file}:{self.lineno} {verb:<5} {named}{', '.join(self.reasons)}"
|
|
142
|
+
|
|
143
|
+
|
|
144
|
+
@dataclass(frozen=True, slots=True)
|
|
145
|
+
class Skipped:
|
|
146
|
+
"""A mechanical fix that was *not* applied, because applying it breaks the line."""
|
|
147
|
+
|
|
148
|
+
file: str
|
|
149
|
+
lineno: int
|
|
150
|
+
id: str
|
|
151
|
+
reason: str
|
|
152
|
+
|
|
153
|
+
def __str__(self) -> str:
|
|
154
|
+
return f"{self.file}:{self.lineno} kept {self.id}: {self.reason}"
|
|
155
|
+
|
|
156
|
+
|
|
157
|
+
@dataclass(frozen=True, slots=True)
|
|
158
|
+
class Fix:
|
|
159
|
+
"""What a normalizing pass did, and every file it wrote."""
|
|
160
|
+
|
|
161
|
+
repairs: tuple[Repair, ...] = ()
|
|
162
|
+
skipped: tuple[Skipped, ...] = ()
|
|
163
|
+
files: tuple[str, ...] = ()
|
|
164
|
+
#: Why a file was left alone entirely. Non-empty means nothing was written to it.
|
|
165
|
+
refused: tuple[str, ...] = ()
|
|
166
|
+
|
|
167
|
+
@property
|
|
168
|
+
def changed(self) -> int:
|
|
169
|
+
return len(self.repairs)
|
|
170
|
+
|
|
171
|
+
def stated(self) -> list[str]:
|
|
172
|
+
"""Every line this pass normalized, and the two counts (RK16, RK357)."""
|
|
173
|
+
rows = [str(repair) for repair in self.repairs]
|
|
174
|
+
rows += [str(kept) for kept in self.skipped]
|
|
175
|
+
if self.repairs:
|
|
176
|
+
rows.append(f"{self.changed} line(s) normalized in {', '.join(self.files)}")
|
|
177
|
+
# Once per run and not on every line (RK357): a `gone` address is a position in the
|
|
178
|
+
# file as this pass *read* it, which is the reading git still has and the written
|
|
179
|
+
# file no longer does. Reporting it before the write is deliberate — the reader who
|
|
180
|
+
# wants to see what was taken needs the line, not the gap — so what was missing was
|
|
181
|
+
# the sentence saying which of the two trees the address is about.
|
|
182
|
+
left = sum(1 for repair in self.repairs if repair.removed)
|
|
183
|
+
if left:
|
|
184
|
+
rows.append(f"{left} of them removed, at the line each was read from")
|
|
185
|
+
return rows
|
|
186
|
+
|
|
187
|
+
def refusals(self) -> list[str]:
|
|
188
|
+
"""For **stderr**, and printed even under `--quiet`: a pass that could not prove its
|
|
189
|
+
own output wrote nothing, and silence about that is the difference between "clean"
|
|
190
|
+
and "unexamined"."""
|
|
191
|
+
return [f"roadkeep: refused, nothing written: {one}" for one in self.refused]
|
|
192
|
+
|
|
193
|
+
|
|
194
|
+
def fix(config: Config) -> Fix:
|
|
195
|
+
"""Normalize every governed line that can be normalized. Writes each file once."""
|
|
196
|
+
repairs: list[Repair] = []
|
|
197
|
+
skipped: list[Skipped] = []
|
|
198
|
+
written: list[str] = []
|
|
199
|
+
refused: list[str] = []
|
|
200
|
+
|
|
201
|
+
# One backlog for the whole pass: the annotation is derived from the *current* files,
|
|
202
|
+
# and re-reading them per line would let a fix to the roadmap change what the next
|
|
203
|
+
# line derives — a pass whose result depended on its own order.
|
|
204
|
+
backlog = Backlog.load(config)
|
|
205
|
+
for role in LINE_ROLES:
|
|
206
|
+
if not config.has(role) or not config.path(role).is_file():
|
|
207
|
+
continue
|
|
208
|
+
outcome = _fix_file(config, role, backlog)
|
|
209
|
+
repairs.extend(outcome.repairs)
|
|
210
|
+
skipped.extend(outcome.skipped)
|
|
211
|
+
written.extend(outcome.files)
|
|
212
|
+
refused.extend(outcome.refused)
|
|
213
|
+
for role in PROSE_ROLES:
|
|
214
|
+
if not config.has(role) or not config.path(role).is_file():
|
|
215
|
+
continue
|
|
216
|
+
outcome = _unmark_file(config, role)
|
|
217
|
+
repairs.extend(outcome.repairs)
|
|
218
|
+
written.extend(outcome.files)
|
|
219
|
+
refused.extend(outcome.refused)
|
|
220
|
+
return Fix(
|
|
221
|
+
repairs=tuple(repairs),
|
|
222
|
+
skipped=tuple(skipped),
|
|
223
|
+
files=tuple(written),
|
|
224
|
+
refused=tuple(refused),
|
|
225
|
+
)
|
|
226
|
+
|
|
227
|
+
|
|
228
|
+
def _unmark_file(config: Config, role: str) -> Fix:
|
|
229
|
+
"""Delete every byte-order mark from one prose file, and nothing else (RK1028).
|
|
230
|
+
|
|
231
|
+
The repair for the one finding a prose file can now carry. The character pass above does
|
|
232
|
+
not run here and must not — §RK34's argument is that a design explaining a lookalike has
|
|
233
|
+
to quote it — so this is the single codepoint that argument does not cover: no design
|
|
234
|
+
pastes a mark, and every mainstream Windows editor writes one.
|
|
235
|
+
|
|
236
|
+
Derived, so `--fix` may make it (RK16): a mark is not a word of anybody's, and deleting
|
|
237
|
+
one changes what the file *is* by zero characters of prose. The whole edit, so the offer
|
|
238
|
+
`lint` prints is one this pass keeps — a gate that names `--fix` and then writes nothing
|
|
239
|
+
is worse than one that names no door at all.
|
|
240
|
+
"""
|
|
241
|
+
document = config.document(role)
|
|
242
|
+
file = config.relative(config.path(role))
|
|
243
|
+
lines = list(document.lines)
|
|
244
|
+
repairs: list[Repair] = []
|
|
245
|
+
for index, raw in enumerate(lines):
|
|
246
|
+
if MARK not in raw:
|
|
247
|
+
continue
|
|
248
|
+
kept = raw.replace(MARK, "")
|
|
249
|
+
lines[index] = kept
|
|
250
|
+
repairs.append(
|
|
251
|
+
Repair(
|
|
252
|
+
file,
|
|
253
|
+
index + 1,
|
|
254
|
+
"",
|
|
255
|
+
raw.rstrip("\r\n"),
|
|
256
|
+
kept.rstrip("\r\n"),
|
|
257
|
+
(f"codepoint removed: U+{ord(MARK):04X}, a byte-order mark",),
|
|
258
|
+
)
|
|
259
|
+
)
|
|
260
|
+
if not repairs:
|
|
261
|
+
return Fix()
|
|
262
|
+
try:
|
|
263
|
+
document.assert_current()
|
|
264
|
+
except StaleFile as moved:
|
|
265
|
+
return Fix(refused=(str(moved),))
|
|
266
|
+
write_atomically(Path(config.path(role)), "".join(lines))
|
|
267
|
+
return Fix(repairs=tuple(repairs), files=(file,))
|
|
268
|
+
|
|
269
|
+
|
|
270
|
+
def _fix_file(config: Config, role: str, backlog: Backlog) -> Fix:
|
|
271
|
+
document = config.document(role)
|
|
272
|
+
file = config.relative(config.path(role))
|
|
273
|
+
before = document
|
|
274
|
+
repairs: list[Repair] = []
|
|
275
|
+
skipped: list[Skipped] = []
|
|
276
|
+
|
|
277
|
+
# The character pass first, and the document re-read from its result (RK126): a control
|
|
278
|
+
# character can be the whole reason a bullet was rejected, so the re-render below has to
|
|
279
|
+
# see the file as this pass leaves it rather than as it was read.
|
|
280
|
+
lines, stripped = _decontrol(document, file)
|
|
281
|
+
if stripped:
|
|
282
|
+
repairs.extend(stripped)
|
|
283
|
+
document = Document.parse(
|
|
284
|
+
"".join(lines), schema=document.schema, path=document.path
|
|
285
|
+
)
|
|
286
|
+
|
|
287
|
+
for entry in document.entries:
|
|
288
|
+
fixed, reasons = _normalize(document.schema, entry.task, backlog, role)
|
|
289
|
+
if not reasons:
|
|
290
|
+
continue
|
|
291
|
+
rendered = document.schema.render(fixed)
|
|
292
|
+
if rendered == entry.raw:
|
|
293
|
+
continue # the change was invisible in the rendering: not a repair
|
|
294
|
+
introduced = _introduced(document.schema, entry.task, fixed)
|
|
295
|
+
if introduced:
|
|
296
|
+
# The one case `markers.refresh` already meets: a derived ✅ makes the line two
|
|
297
|
+
# characters longer, and a line at the cap would go over. Reported, not forced.
|
|
298
|
+
skipped.append(
|
|
299
|
+
Skipped(file, entry.lineno, entry.task.id, f"fixing it would add {introduced}")
|
|
300
|
+
)
|
|
301
|
+
continue
|
|
302
|
+
lines[entry.index] = rendered + ending(lines[entry.index])
|
|
303
|
+
repairs.append(
|
|
304
|
+
Repair(file, entry.lineno, entry.task.id, entry.raw, rendered, tuple(reasons))
|
|
305
|
+
)
|
|
306
|
+
|
|
307
|
+
text = "".join(lines)
|
|
308
|
+
if repairs:
|
|
309
|
+
# Against the file as it was **read**, not as the character pass left it: the question
|
|
310
|
+
# rule 3 asks is whether this whole run lost anything.
|
|
311
|
+
problem = _verify(text, before, {r.lineno for r in repairs})
|
|
312
|
+
if problem is not None:
|
|
313
|
+
# Rule 3: the pass proves its own output before the disk sees any of it.
|
|
314
|
+
return Fix(skipped=tuple(skipped), refused=(f"{file}: {problem}",))
|
|
315
|
+
|
|
316
|
+
if role == "roadmap":
|
|
317
|
+
# The one repair that **removes** a line rather than re-rendering one (RK328), so it
|
|
318
|
+
# runs after the pass above has proved its own output and proves this one itself:
|
|
319
|
+
# rule 3 asks about line numbers, and a removal moves every line under it.
|
|
320
|
+
text, dequeued, problem = _dequeue(config, text, document, backlog, file)
|
|
321
|
+
if problem is not None:
|
|
322
|
+
return Fix(skipped=tuple(skipped), refused=(f"{file}: {problem}",))
|
|
323
|
+
repairs.extend(dequeued)
|
|
324
|
+
|
|
325
|
+
# `_dequeue`'s twin, one list over (RK1318): a `Done when` heading addressed to
|
|
326
|
+
# something no file answers, **with nothing under it**, is derived dead exactly as a
|
|
327
|
+
# shipped task's queue entry is. Runs after it and proves its own output for the same
|
|
328
|
+
# reason — a removal moves every line beneath it.
|
|
329
|
+
text, emptied, problem = _unaddress(config, text, document, backlog, file)
|
|
330
|
+
if problem is not None:
|
|
331
|
+
return Fix(skipped=tuple(skipped), refused=(f"{file}: {problem}",))
|
|
332
|
+
repairs.extend(emptied)
|
|
333
|
+
|
|
334
|
+
if not repairs:
|
|
335
|
+
return Fix(skipped=tuple(skipped))
|
|
336
|
+
try:
|
|
337
|
+
# The same question `save` asks (RK116), asked here because this pass writes the
|
|
338
|
+
# text and not the document: everything above happened after the file was read, and
|
|
339
|
+
# a repair applied on top of somebody else's write erases it as silently as any
|
|
340
|
+
# other. Reported rather than raised, because that is how this pass refuses.
|
|
341
|
+
document.assert_current()
|
|
342
|
+
except StaleFile as moved:
|
|
343
|
+
return Fix(skipped=tuple(skipped), refused=(str(moved),))
|
|
344
|
+
write_atomically(Path(config.path(role)), text)
|
|
345
|
+
return Fix(repairs=tuple(repairs), skipped=tuple(skipped), files=(file,))
|
|
346
|
+
|
|
347
|
+
|
|
348
|
+
def _dequeue(
|
|
349
|
+
config: Config, text: str, before: Document, backlog: Backlog, file: str
|
|
350
|
+
) -> tuple[str, list[Repair], str | None]:
|
|
351
|
+
"""Drop every queue entry naming work the ledger has already accounted for (RK328).
|
|
352
|
+
|
|
353
|
+
The queue is the roadmap's third list and the only mechanical repair it has: an entry
|
|
354
|
+
whose task **shipped or was retired** names work that has left the backlog for good, so
|
|
355
|
+
there is exactly one repair, it chooses nothing, and no sentence of anybody's is touched
|
|
356
|
+
— the same class as a stale dep annotation. RK327 closes the common case inside the
|
|
357
|
+
departure itself; what reaches here is the drift every other file already has a fixer
|
|
358
|
+
for: a hand edit, a merge that resolved into a list naming both sides' ids, an adopted
|
|
359
|
+
backlog whose order predates the section.
|
|
360
|
+
|
|
361
|
+
Four states stay **editorial**, and they are why this is not "make the queue match":
|
|
362
|
+
|
|
363
|
+
* **order**, which is the author's whole statement, so nothing here reorders;
|
|
364
|
+
* an entry naming a merely *blocked* task, which is live — dropping it would delete a
|
|
365
|
+
declaration because a dep has not landed yet;
|
|
366
|
+
* one naming a **deferred** task, which is coming back and whose place in the order is
|
|
367
|
+
the one thing the store could not keep, so restoring it is `resume`'s caller's;
|
|
368
|
+
* one naming an id no file carries, or a block with nothing open: an unknown id is as
|
|
369
|
+
likely a typo as a deletion, a block whose lines have all left is reopened by an
|
|
370
|
+
`add`, and one whose lines are in the store by a `resume` — which of those a label is
|
|
371
|
+
in is :class:`~roadkeep.backlog.Stage`'s answer and not a fourth reading of it (RK434).
|
|
372
|
+
|
|
373
|
+
Every drop is **named in the report** rather than removed in silence, and at the line it
|
|
374
|
+
was read from: a fixer that shortens a plan quietly is the one thing worse than the
|
|
375
|
+
stale entry. The removal itself is :func:`~roadkeep.queueing.without`'s, which is what
|
|
376
|
+
keeps the blank line a one-entry queue sits between from doubling.
|
|
377
|
+
"""
|
|
378
|
+
document = Document.parse(text, schema=before.schema, path=before.path)
|
|
379
|
+
gone = backlog.shipped() | frozenset(backlog.retired())
|
|
380
|
+
dead = [
|
|
381
|
+
entry
|
|
382
|
+
for entry in queueing.entries(document, config)
|
|
383
|
+
if entry.token in gone
|
|
384
|
+
]
|
|
385
|
+
if not dead:
|
|
386
|
+
return text, [], None
|
|
387
|
+
|
|
388
|
+
updated = document
|
|
389
|
+
for entry in dead:
|
|
390
|
+
updated, _ = queueing.without(updated, config, entry.token)
|
|
391
|
+
written = "".join(updated.lines)
|
|
392
|
+
|
|
393
|
+
# This pass proves its own output, for rule 3's reason and not by rule 3's test: what a
|
|
394
|
+
# removal must not do is take a task line or make a bullet the grammar stops reading.
|
|
395
|
+
reparsed = Document.parse(written, schema=before.schema, path=before.path)
|
|
396
|
+
if {e.task.id for e in reparsed.entries} != {e.task.id for e in document.entries}:
|
|
397
|
+
return text, [], "the queue pass changed which tasks the file holds"
|
|
398
|
+
if len(reparsed.rejects) > len(document.rejects):
|
|
399
|
+
return text, [], "the queue pass made a line the grammar no longer reads"
|
|
400
|
+
|
|
401
|
+
shipped = backlog.shipped()
|
|
402
|
+
return (
|
|
403
|
+
written,
|
|
404
|
+
[
|
|
405
|
+
Repair(
|
|
406
|
+
file,
|
|
407
|
+
entry.lineno,
|
|
408
|
+
entry.token,
|
|
409
|
+
entry.raw,
|
|
410
|
+
"",
|
|
411
|
+
(
|
|
412
|
+
"queued work that shipped"
|
|
413
|
+
if entry.token in shipped
|
|
414
|
+
else "queued work that was retired",
|
|
415
|
+
),
|
|
416
|
+
removed=True,
|
|
417
|
+
)
|
|
418
|
+
for entry in dead
|
|
419
|
+
],
|
|
420
|
+
None,
|
|
421
|
+
)
|
|
422
|
+
|
|
423
|
+
|
|
424
|
+
def _unaddress(
|
|
425
|
+
config: Config, text: str, before: Document, backlog: Backlog, file: str
|
|
426
|
+
) -> tuple[str, list[Repair], str | None]:
|
|
427
|
+
"""Remove every `Done when` heading addressed to nothing **and holding nothing** (RK1318).
|
|
428
|
+
|
|
429
|
+
:func:`_dequeue`'s twin and the same class: there is one repair, it chooses nothing, and no
|
|
430
|
+
sentence of anybody's is touched. What makes it derived rather than editorial is the pair —
|
|
431
|
+
the address no file answers, *and* no bullet under it. Either alone stays the author's:
|
|
432
|
+
|
|
433
|
+
* an orphaned list **with** bullets is `criterion drop <lead>`'s, which is the door the
|
|
434
|
+
finding names, because what goes is somebody's prose and a fixer may not spend it;
|
|
435
|
+
* an empty list under a **live** address is the state RK1265 built on purpose — a block
|
|
436
|
+
whose criteria all went is one somebody asked the question about, and deleting it would
|
|
437
|
+
turn an answer back into a silence.
|
|
438
|
+
|
|
439
|
+
So this takes the intersection, which nobody wrote and nothing reads. The heading survives
|
|
440
|
+
its bullets by design and stops surviving when the thing it asks about does too.
|
|
441
|
+
|
|
442
|
+
Silent where the project declared no `[criteria]`, which is `_criteria`'s own gate: a list
|
|
443
|
+
nothing governs is prose, and a fixer that deleted prose would be the write path this tool
|
|
444
|
+
exists to keep out of these files (L4).
|
|
445
|
+
"""
|
|
446
|
+
if config.criteria is None:
|
|
447
|
+
return text, [], None
|
|
448
|
+
document = Document.parse(text, schema=before.schema, path=before.path)
|
|
449
|
+
labels = backlog.declared_blocks()
|
|
450
|
+
alive = {entry.task.id for entry in document.entries}
|
|
451
|
+
if backlog.store is not None:
|
|
452
|
+
alive |= {entry.task.id for entry in backlog.store.entries}
|
|
453
|
+
dead = [
|
|
454
|
+
(at, about)
|
|
455
|
+
for at, about in criteria._regions(document) # noqa: SLF001 - the region reader is its own
|
|
456
|
+
if not criteria.read(document, about)
|
|
457
|
+
and about not in (alive if criteria.addresses_task(config.schema, about) else labels)
|
|
458
|
+
]
|
|
459
|
+
if not dead:
|
|
460
|
+
return text, [], None
|
|
461
|
+
|
|
462
|
+
updated = document
|
|
463
|
+
# Highest first, so an earlier removal never moves a later one's index.
|
|
464
|
+
for at, about in sorted(dead, reverse=True):
|
|
465
|
+
updated, _ = criteria.without(updated, about)
|
|
466
|
+
written = "".join(updated.lines)
|
|
467
|
+
|
|
468
|
+
reparsed = Document.parse(written, schema=before.schema, path=before.path)
|
|
469
|
+
if {e.task.id for e in reparsed.entries} != {e.task.id for e in document.entries}:
|
|
470
|
+
return text, [], "the criteria pass changed which tasks the file holds"
|
|
471
|
+
if len(reparsed.rejects) > len(document.rejects):
|
|
472
|
+
return text, [], "the criteria pass made a line the grammar no longer reads"
|
|
473
|
+
|
|
474
|
+
return (
|
|
475
|
+
written,
|
|
476
|
+
[
|
|
477
|
+
Repair(
|
|
478
|
+
file,
|
|
479
|
+
at + 1,
|
|
480
|
+
about,
|
|
481
|
+
document.lines[at].rstrip("\r\n"),
|
|
482
|
+
"",
|
|
483
|
+
("a criteria heading addressed to nothing, holding nothing",),
|
|
484
|
+
removed=True,
|
|
485
|
+
)
|
|
486
|
+
for at, about in dead
|
|
487
|
+
],
|
|
488
|
+
None,
|
|
489
|
+
)
|
|
490
|
+
|
|
491
|
+
|
|
492
|
+
def _decontrol(document: Document, file: str) -> tuple[list[str], list[Repair]]:
|
|
493
|
+
"""Delete every codepoint that is not text, on every line, keeping the endings (RK126).
|
|
494
|
+
|
|
495
|
+
The line **body** only, because `\\r` and `\\n` are control characters too and a pass
|
|
496
|
+
that took them would join the file into one line. The ending is put back exactly as it
|
|
497
|
+
was read, which is :func:`~roadkeep.kernel.document.ending`'s whole reason for being public.
|
|
498
|
+
|
|
499
|
+
The **indentation** is where a codepoint stops being decidable by itself (RK146): a tab
|
|
500
|
+
there is the nesting RK49 reads off the file, and past it the format writes a space —
|
|
501
|
+
so the position is passed and :func:`~roadkeep.linting.repaired` answers with the text,
|
|
502
|
+
which is a deletion for everything that is not text and a space for the one thing that
|
|
503
|
+
renders as one.
|
|
504
|
+
"""
|
|
505
|
+
lines = list(document.lines)
|
|
506
|
+
ids = {entry.lineno: entry.task.id for entry in document.entries}
|
|
507
|
+
repairs: list[Repair] = []
|
|
508
|
+
for index, raw in enumerate(lines):
|
|
509
|
+
body = raw.rstrip("\r\n")
|
|
510
|
+
head = indentation(body)
|
|
511
|
+
changed = [
|
|
512
|
+
(char, repaired(char, indent=position < head))
|
|
513
|
+
for position, char in enumerate(body)
|
|
514
|
+
]
|
|
515
|
+
kept = "".join(
|
|
516
|
+
char if written is None else written for char, written in changed
|
|
517
|
+
)
|
|
518
|
+
if kept == body:
|
|
519
|
+
continue
|
|
520
|
+
lineno = index + 1
|
|
521
|
+
lines[index] = kept + ending(raw)
|
|
522
|
+
touched = ", ".join(
|
|
523
|
+
dict.fromkeys(f"U+{ord(c):04X}" for c, written in changed if written is not None)
|
|
524
|
+
)
|
|
525
|
+
repairs.append(
|
|
526
|
+
Repair(
|
|
527
|
+
file,
|
|
528
|
+
lineno,
|
|
529
|
+
ids.get(lineno, ""),
|
|
530
|
+
body,
|
|
531
|
+
kept,
|
|
532
|
+
(f"control character(s) removed: {touched}",),
|
|
533
|
+
)
|
|
534
|
+
)
|
|
535
|
+
return lines, repairs
|
|
536
|
+
|
|
537
|
+
|
|
538
|
+
def _normalize(
|
|
539
|
+
schema: Schema, task: Task, backlog: Backlog, role: str
|
|
540
|
+
) -> tuple[Task, list[str]]:
|
|
541
|
+
"""The task as the format would write it, and the name of every change made."""
|
|
542
|
+
reasons: list[str] = []
|
|
543
|
+
fixed = task
|
|
544
|
+
|
|
545
|
+
# The variation selector on a marker used to be stripped here. It is not, any more: the
|
|
546
|
+
# character pass (RK126) removes every codepoint that is not text wherever it occurs, so
|
|
547
|
+
# a second rule about the marker slot alone would be the narrower half of one law.
|
|
548
|
+
for field in ("symptom", "why"):
|
|
549
|
+
value = getattr(fixed, field)
|
|
550
|
+
if value != value.strip():
|
|
551
|
+
fixed = replace(fixed, **{field: value.strip()})
|
|
552
|
+
reasons.append(f"{field} trimmed")
|
|
553
|
+
|
|
554
|
+
if schema.deps_field and fixed.deps:
|
|
555
|
+
deps, dep_reasons = _deps(schema, fixed, backlog, role)
|
|
556
|
+
if dep_reasons:
|
|
557
|
+
fixed = replace(fixed, deps=deps)
|
|
558
|
+
reasons.extend(dep_reasons)
|
|
559
|
+
|
|
560
|
+
if schema.ref_scheme == "id" and fixed.ref and fixed.ref != fixed.id:
|
|
561
|
+
# The pointer is derived in this scheme, so it is not the author's text — which is
|
|
562
|
+
# also what made RK27's own migration a throwaway script instead of a command.
|
|
563
|
+
fixed = replace(fixed, ref=fixed.id)
|
|
564
|
+
reasons.append("pointer derived from the id")
|
|
565
|
+
return fixed, reasons
|
|
566
|
+
|
|
567
|
+
|
|
568
|
+
def _deps(
|
|
569
|
+
schema: Schema, task: Task, backlog: Backlog, role: str
|
|
570
|
+
) -> tuple[tuple[Dep, ...], list[str]]:
|
|
571
|
+
reasons: list[str] = []
|
|
572
|
+
deps = task.deps
|
|
573
|
+
|
|
574
|
+
seen: dict[str, Dep] = {}
|
|
575
|
+
for dep in deps:
|
|
576
|
+
seen.setdefault(dep.id, dep)
|
|
577
|
+
if len(seen) != len(deps):
|
|
578
|
+
reasons.append("duplicate dep dropped")
|
|
579
|
+
deps = tuple(seen.values())
|
|
580
|
+
|
|
581
|
+
if role == "roadmap":
|
|
582
|
+
derived = derive(backlog, replace(task, deps=deps)).deps
|
|
583
|
+
if derived != deps:
|
|
584
|
+
reasons.append("dep annotation derived")
|
|
585
|
+
deps = derived
|
|
586
|
+
|
|
587
|
+
# Ordered only when every token is an id of this project. `Block P` and `real design
|
|
588
|
+
# partners` have no order, and sorting a mixed field would move prose somebody wrote.
|
|
589
|
+
if all(schema.classify_dep(d) is DepKind.TASK for d in deps):
|
|
590
|
+
ordered = tuple(sorted(deps, key=lambda d: id_order(d.id, schema)))
|
|
591
|
+
if ordered != deps:
|
|
592
|
+
reasons.append("deps ordered")
|
|
593
|
+
deps = ordered
|
|
594
|
+
return deps, reasons
|
|
595
|
+
|
|
596
|
+
|
|
597
|
+
def _introduced(schema: Schema, before: Task, after: Task) -> str:
|
|
598
|
+
"""Violations the fix would create that the line did not already have."""
|
|
599
|
+
had = {v.code for v in schema.validate(before)}
|
|
600
|
+
new = [v for v in schema.validate(after) if v.code not in had]
|
|
601
|
+
return "; ".join(str(v) for v in new)
|
|
602
|
+
|
|
603
|
+
|
|
604
|
+
def _verify(text: str, before: Document, changed: set[int]) -> str | None:
|
|
605
|
+
"""Rule 3: re-parse, and refuse unless every line this pass wrote came back canonical.
|
|
606
|
+
|
|
607
|
+
Also refuses a pass that changed how many lines the file has or **lost** an id or made a
|
|
608
|
+
line the grammar no longer reads: a normalizer that dropped a task is the failure no
|
|
609
|
+
per-line check would notice.
|
|
610
|
+
|
|
611
|
+
Lost, and not merely changed. The character pass (RK126) can turn a bullet the grammar
|
|
612
|
+
was rejecting *because of* a control character into an entry, which adds an id and
|
|
613
|
+
removes a reject — the outcome, not a failure. So the question is asked in the direction
|
|
614
|
+
that only a loss can fail.
|
|
615
|
+
"""
|
|
616
|
+
after = Document.parse(text, schema=before.schema, path=before.path)
|
|
617
|
+
if len(after.lines) != len(before.lines):
|
|
618
|
+
return f"the pass changed the line count ({len(before.lines)} → {len(after.lines)})"
|
|
619
|
+
lost = [
|
|
620
|
+
e.task.id for e in before.entries if e.task.id not in {a.task.id for a in after.entries}
|
|
621
|
+
]
|
|
622
|
+
if lost:
|
|
623
|
+
return f"the pass lost {', '.join(dict.fromkeys(lost))} out of the file"
|
|
624
|
+
if len(after.rejects) > len(before.rejects):
|
|
625
|
+
return "the pass made a line the grammar no longer reads"
|
|
626
|
+
offenders = [e.lineno for e in after.non_canonical if e.lineno in changed]
|
|
627
|
+
if offenders:
|
|
628
|
+
return f"line(s) {offenders} would not round-trip after the fix"
|
|
629
|
+
return None
|