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/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