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
@@ -0,0 +1,2308 @@
1
+ """A task line as data, before it is a line (RK1).
2
+
3
+ Everything else in roadkeep is downstream of this module: `add` validates here
4
+ before it renders, `lint` validates here instead of re-implementing the format as
5
+ regexes over prose, and the round-trip invariant (L3) compares against
6
+ :meth:`Schema.render`. A rule that lives in two places is a rule two places can
7
+ disagree about, so the schema lives in exactly one.
8
+
9
+ Seven fields carry a task: ``id``, ``status``, ``block``, ``deps``, ``symptom``,
10
+ ``why``, ``ref``. What the schema enforces:
11
+
12
+ * **Lengths** — ``symptom`` 120, ``why`` 200, rendered line 320. These are the P90
13
+ of the lines that already read well, not a round number.
14
+ * **One sentence for ``why``** — a second sentence is the signal that the content
15
+ belongs in the improvements file, which is what ``ref`` points at.
16
+ * **Shape** — id against the configured prefix, status in the configured marker
17
+ set, ``deps`` well-formed and non-self-referential, ``ref`` present and anchored.
18
+ Two of those slots are *per-file* rather than per-format: the ledger carries no
19
+ ``deps``, and a ledger where every entry shipped carries no marker either (RK43) —
20
+ which is a marker derived from the file instead of repeated on all 920 of its lines.
21
+ * **Nothing that would break a round-trip** — no newlines, no stray ``**``, no
22
+ leading or trailing whitespace in a field. These are refused rather than
23
+ trimmed: silently normalizing text the tool misunderstood is what L3 forbids.
24
+
25
+ What it deliberately does **not** enforce: that ``symptom`` states what does not
26
+ work rather than naming a fix. That rule matters as much as the lengths — a line
27
+ named after its solution cannot be falsified, so it never gets closed, only
28
+ abandoned — but it is not decidable by a schema, and a tool that guesses at prose
29
+ quality has started writing prose (L4). It stays a documented rule, enforced by
30
+ the skill and by review.
31
+ """
32
+
33
+ from __future__ import annotations
34
+
35
+ import math
36
+ import re
37
+ import unicodedata
38
+ from collections.abc import Callable, Mapping, Sequence
39
+ from dataclasses import dataclass, field, replace
40
+ from enum import StrEnum
41
+
42
+ # Status markers, as bare codepoints — no variation selectors, because the
43
+ # governed files carry none and a round-trip compares bytes.
44
+ DESIGNED = "\N{CLIPBOARD}" # 📋
45
+ #: The three C0 characters this module names rather than writes as an escape, so the source
46
+ #: says which one it means (RK407). `"\n"` in a predicate reads as punctuation at a glance.
47
+ LINE_FEED = "\N{LINE FEED}"
48
+ CARRIAGE_RETURN = "\N{CARRIAGE RETURN}"
49
+ TAB = "\N{CHARACTER TABULATION}"
50
+
51
+ #: What PowerShell's backtick expands to, by the codepoint it produces (RK407). Unicode gives
52
+ #: a C0 control no `name`, so `unicodedata` answers "" for every one of these — and a refusal
53
+ #: reading `U+0007` alone names the value without naming anything a caller recognises.
54
+ #: The escape beside it is the point: `` `a `` is what somebody typed, and seeing it is the
55
+ #: whole diagnosis.
56
+ _C0_NAMES: Mapping[str, tuple[str, str]] = {
57
+ "\x00": ("NUL", "`0"),
58
+ "\x07": ("BELL", "`a"),
59
+ "\x08": ("BACKSPACE", "`b"),
60
+ "\x0b": ("VERTICAL TAB", "`v"),
61
+ "\x0c": ("FORM FEED", "`f"),
62
+ "\x0d": ("CARRIAGE RETURN", "`r"),
63
+ "\x1b": ("ESCAPE", "`e"),
64
+ }
65
+
66
+ IDEA = "\N{THOUGHT BALLOON}" # 💭
67
+ PARTIAL = "\N{HOURGLASS WITH FLOWING SAND}" # ⏳
68
+ IN_PROGRESS = "\N{HAMMER AND WRENCH}" # 🛠
69
+ SHIPPED = "\N{WHITE HEAVY CHECK MARK}" # ✅
70
+ #: A line that left the roadmap without shipping (RK32). Lives in the ledger beside ✅,
71
+ #: under the block it belonged to: a departure is a departure, and the block is the one
72
+ #: piece of provenance worth keeping when the design itself is deleted.
73
+ RETIRED = "\N{WASTEBASKET}" # 🗑
74
+ #: A line set aside and still alive (RK96) — the one state that is neither open nor
75
+ #: terminal. It lives in the deferred store and nowhere else: a roadmap that can say
76
+ #: "paused" is a backlog counting work nobody is doing, and a ledger that can is a ledger
77
+ #: of departures one of which comes back.
78
+ DEFERRED = "\N{DOUBLE VERTICAL BAR}" # ⏸
79
+
80
+ #: What a pause wraps the author's sentence in, and what a resume takes back off (RK96).
81
+ #: Here rather than in :mod:`roadkeep.deferring`, which composes it, because the *length* of a
82
+ #: paused why is a question this file answers and the answer needs the prefix (RK1115): a
83
+ #: derived wrapper charged to the author's limit made a line written to its budget impossible
84
+ #: to pause at all — pportal's PP55 overflowed by 10 characters before a reason was written,
85
+ #: and the two remaining doors were both terminal. One spelling, one writer, and now one
86
+ #: reader: the door that composes it and the rule that measures around it cannot disagree.
87
+ PAUSED_OPEN = "set aside ("
88
+ PAUSED_CLOSE = "): "
89
+
90
+
91
+ def pause_reason(why: str) -> str | None:
92
+ """The reason a pause recorded, or None where the prefix is not the one above."""
93
+ if not why.startswith(PAUSED_OPEN) or PAUSED_CLOSE not in why:
94
+ return None
95
+ return why[len(PAUSED_OPEN) :].split(PAUSED_CLOSE, 1)[0]
96
+
97
+
98
+ def authored_why(why: str) -> str:
99
+ """The author's own sentence, with the derived prefix taken back off.
100
+
101
+ Left exactly as written when the prefix is not there: an `amend` may have replaced the
102
+ whole sentence while the line was paused, and stripping a prefix nothing wrote would be
103
+ this tool editing prose (L4).
104
+ """
105
+ if pause_reason(why) is None:
106
+ return why
107
+ return why.split(PAUSED_CLOSE, 1)[1]
108
+
109
+ #: The markers a roadmap line may carry. ✅ is not among them: shipped work lives
110
+ #: in the changelog, and a roadmap that can say "done" is a second source of truth.
111
+ OPEN_MARKERS = (DESIGNED, IDEA, PARTIAL, IN_PROGRESS)
112
+
113
+ #: Which of those mean the design is not written yet (RK83). Ready and implementable are
114
+ #: two different states, and only the markers know the difference: a 💭 line offered to a
115
+ #: caller who asked to execute a block hands it a design session. Not a readiness gate —
116
+ #: `pick` still offers these — but a fact the answer states, and one `--designed` can skip.
117
+ UNDESIGNED = (IDEA,)
118
+
119
+ EM_DASH = "\N{EM DASH}"
120
+ ARROW = "\N{RIGHTWARDS ARROW}"
121
+ NO_DEPS = EM_DASH
122
+
123
+ _PREFIX_RE = re.compile(r"^[A-Z][A-Z0-9]{0,7}$")
124
+ _BLOCK_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9.\-]{0,15}$")
125
+ #: A section, with any depth of subsection: "I.1", "XIV.8.7", and bare "XLV" —
126
+ #: Turing points at nine whole sections, and a pointer that resolves is the rule
127
+ #: (RK15), not the presence of a dot. [0-9] and not \d: an id is ASCII.
128
+ #: Public because it reads the *heading* too (RK44): under the outline scheme a heading
129
+ #: numbers itself and the number is what announces it, so one pattern has to answer both
130
+ #: ends of the pointer or the two disagree about which sections exist.
131
+ #: The final segment may be **one lowercase letter** (RK47), which is measured and not
132
+ #: guessed: it admits exactly Turing's 20 `VII.2.a` headings across both prose files, and
133
+ #: a general alphanumeric segment admits not one thing more while also admitting
134
+ #: `VII.2.beta`, where `§VII.2` stops telling an anchor from a title's first word.
135
+ #: The *first* segment may be **one uppercase letter followed by a dot** (RK101), the same
136
+ #: measured admission one level up: commitclerk numbers its rationale by the roadmap's own
137
+ #: block letters, `§B.2` to `§J.9`, of which only C and D were read before — because those
138
+ #: letters happen to be roman numerals. The dot is what keeps a title's capitalised first
139
+ #: word prose, and a bare `§B` names a block rather than a section, so it stays refused.
140
+ OUTLINE_ANCHOR_RE = re.compile(r"^(?:[0-9IVXLCDM]+|[A-Z](?=\.))(?:\.[0-9]+)*(?:\.[a-z])?$")
141
+
142
+ #: The namespace an outline address may name in front of itself (RK340). `ref_scheme` is
143
+ #: read once per project and every outline starts at `I`, so two prose files each numbering
144
+ #: their own headings land in one flat set: measured in an adopting project, `IMPROVEMENTS.md`
145
+ #: and `STRATEGY.md` both open at `§I` and both declare a `§III`, `lint` reports four
146
+ #: `section.ambiguous`, and ten pointers resolve to nothing. A prefix is what makes `§S:I`
147
+ #: and `§I` two addresses, and the **separator is a colon** for a reason the alternative
148
+ #: makes plain: a dot is what an outline already segments by, so `§S.I` would be a child of
149
+ #: something called `S` to every reader that splits one.
150
+ REF_PREFIX_RE = re.compile(r"^[A-Za-z][A-Za-z0-9]*$")
151
+ REF_SEPARATOR = ":"
152
+
153
+
154
+ def split_ref(ref: str) -> tuple[str, str]:
155
+ """`S:I.2` → `("S", "I.2")`, and a bare `I.2` → `("", "I.2")` (RK340).
156
+
157
+ One reader of the spelling, for the reason :func:`~roadkeep.sections.anchor_text` is one
158
+ writer of it: an address parsed one way by the gate and another by the write is the
159
+ disagreement that made the ambiguity unreportable in the first place. Partitioning and
160
+ not a match, so an anchor carrying two colons keeps the tail verbatim and fails the
161
+ *anchor* check with the text the author typed rather than being silently re-cut.
162
+ """
163
+ prefix, found, bare = ref.partition(REF_SEPARATOR)
164
+ return (prefix, bare) if found else ("", ref)
165
+
166
+ # A terminator followed by whitespace, i.e. a sentence that has a successor. A
167
+ # trailing period never matches because the field is measured stripped.
168
+ _SENTENCE_BREAK_RE = re.compile(r"[.!?][\"')\]]*\s")
169
+
170
+ # Abbreviations whose period is not a sentence boundary. Decimals ("3.11") and
171
+ # anchors ("§0.1") are already safe: no whitespace follows their period.
172
+ _ABBREVIATIONS = frozenset({"e.g.", "i.e.", "etc.", "vs.", "cf.", "al.", "no."})
173
+
174
+ _TERMINATORS = (".", "!", "?")
175
+
176
+ #: The violations that already carry the line's own limit into a field the author writes
177
+ #: (RK183), and therefore the ones `line.too-long` stands down for.
178
+ _LENGTH_CODES = frozenset({"symptom.too-long", "why.too-long", "part.too-long"})
179
+
180
+
181
+ #: The pointer's two addressing schemes (RK27). "id" is the default because it is the
182
+ #: one an author cannot get wrong; "outline" exists for backlogs already numbered.
183
+ REF_SCHEMES = frozenset({"id", "outline"})
184
+
185
+ # What a dep token names (RK28). Derived from the text the corpora already write —
186
+ # `Block P` in Shio, `real design partners` in Turing — because inventing a sigil
187
+ # would make two live backlogs wrong rather than describing them. The word is the
188
+ # project's (RK75); only the shape after it is the format's.
189
+ BLOCK_LABEL = r"[A-Za-z0-9][A-Za-z0-9.\-]{0,15}"
190
+ #: The word a project files work under. `Block` for the two corpora the format was read
191
+ #: off, and not for the others: Dumont writes `Track`, cursarei writes `Fase`.
192
+ DEFAULT_HEADING_WORD = "Block"
193
+ #: Anything shaped like an id: letters then a digit. `RK007`, `RK9x` and `SH341` are
194
+ #: mistakes to report, not external work to accept. Public as a fragment because the
195
+ #: parser asks the same question: a bullet leading with a bold one is a ledger line whose
196
+ #: marker slot is empty (RK43), and a second spelling of "id-shaped" would disagree with
197
+ #: this one on the first `**Delete**`.
198
+ ID_SHAPE = r"[A-Za-z]{1,8}[0-9][A-Za-z0-9]*"
199
+ _ID_SHAPE_RE = re.compile(rf"^{ID_SHAPE}$")
200
+ #: The sub-letter a split id may carry where a project declares one (RK106). Lowercase, so
201
+ #: it can never be read as a family — those are uppercase by :data:`_PREFIX_RE` — and one,
202
+ #: because `T24b` is what Turing writes and `T24beta` would put the letter back in prose.
203
+ SUB_LETTER = r"[a-z]"
204
+ # The shape of a range, without judging its direction, so that `RK9–RK5` can be
205
+ # reported instead of quietly becoming "outside the backlog".
206
+ _RANGE_SHAPE_RE = re.compile(r"^[A-Za-z]{1,8}[0-9]+\s*[-–—]\s*[A-Za-z]{0,8}[0-9]+$")
207
+
208
+
209
+ @dataclass(frozen=True, slots=True)
210
+ class Slot:
211
+ """One part of the task line, stated once for both directions (RK1063).
212
+
213
+ The line was written twice — :meth:`Schema.render` composed it and `document._task_re`
214
+ matched it — and the two agreed because a property test over three corpora said they
215
+ did. That is the right backstop and the wrong primary: L3 exists to catch a parser that
216
+ **misread** somebody else's line, and it was also carrying the case where the writer and
217
+ the reader were written from one intention and drifted, which is a duplication to remove
218
+ rather than a corruption to detect. RK109 made this argument about the id, where one
219
+ shape had two parsers that answered differently; this is that argument about the bullet.
220
+
221
+ :attr:`reads` and :attr:`writes` are deliberately **not** required to be inverses, and
222
+ the asymmetries are the reason this is a record rather than a format string. `deps` is
223
+ read as optional whatever the project declares, because an adopted ledger has lines
224
+ without it; `symptom` renders nothing and reads a bare separator where the slot is
225
+ turned off (RK48). Those were the two places the grammar was quietly looser than the
226
+ writer, and stating them here is what makes them a decision instead of a discovery.
227
+ """
228
+
229
+ name: str
230
+ #: The regex fragment, with this slot's named groups, given whether the file has it.
231
+ reads: Callable[[bool], str]
232
+ #: What the slot puts on the line, given the schema and the task. `""` is a slot that
233
+ #: contributes nothing, which is how an undeclared marker leaves no double space.
234
+ writes: Callable[[Schema, Task], str]
235
+ #: Whether this project's shape has the slot at all — the `[ledger]` questions (RK43,
236
+ #: RK48) plus `deps`, asked of the schema so one template serves every declared file.
237
+ present: Callable[[Schema], bool] = lambda _schema: True
238
+
239
+
240
+ def _reads_status(present: bool) -> str:
241
+ return r"(?P<status>\S+) " if present else ""
242
+
243
+
244
+ def _reads_head(_present: bool) -> str:
245
+ # The bold head, and the qualifier a **partial** entry carries inside it (RK121).
246
+ # Inside the bold because that is where the corpus already writes it — Shio has seven,
247
+ # from `- **SH96 (local half)** —` to `- **SH275 (partial)** —` — and a grammar that
248
+ # demanded the qualifier somewhere else would read those seven as no id at all.
249
+ return r"\*\*(?P<id>[A-Za-z0-9]+)(?: \((?P<part>[^)]+)\))?\*\*"
250
+
251
+
252
+ def _reads_deps(_present: bool) -> str:
253
+ # Optional whichever way the project declared it, and that is the asymmetry worth
254
+ # naming: `deps_field` decides whether this is *written*, never whether a line that
255
+ # has it can be read. An adopted roadmap carries both shapes in one file.
256
+ return r"(?: \(deps: (?P<deps>[^)]*)\))?"
257
+
258
+
259
+ def _reads_requires(_present: bool) -> str:
260
+ # Optional, and the asymmetry against `deps` is the whole reason this slot is cheap: an
261
+ # empty group is never *written*, so every line in every backlog that states no
262
+ # requirement is byte-for-byte the line this format had before the slot existed. A
263
+ # `present` gate would have been the other design and it buys nothing — a file where
264
+ # nobody writes one already renders none.
265
+ return r"(?: \(requires: (?P<requires>[^)]*)\))?"
266
+
267
+
268
+ def _reads_symptom(present: bool) -> str:
269
+ # Absent is a bare separator and not an empty match, which is the pair `_writes_symptom`
270
+ # keeps: a markerless, symptomless ledger line is `- **T1** — because.` (RK48).
271
+ return rf" \*\*(?P<symptom>.+?)\*\* {EM_DASH} " if present else f" {EM_DASH} "
272
+
273
+
274
+ def _reads_why(_present: bool) -> str:
275
+ # To the end of the head, the pointer having been split off before this runs: a regex
276
+ # for it over the whole line finds the one §RK15's own `why` quotes as an example and
277
+ # truncates the sentence there. That rule is `document._split_ref`'s and stays there —
278
+ # a template states the slots, and this is a decision about where the line ends.
279
+ return r"(?P<why>.+)$"
280
+
281
+
282
+ def _writes_status(schema: Schema, task: Task) -> str:
283
+ # Omitted, never emptied: `- **T1** …` is the shape both live ledgers already write,
284
+ # and `- **T1** …` would be a third one nobody has.
285
+ return f"{task.status} " if schema.marks(task.status) else ""
286
+
287
+
288
+ def _writes_head(_schema: Schema, task: Task) -> str:
289
+ named = f"{task.id} ({task.part})" if task.part else task.id
290
+ return f"**{named}**"
291
+
292
+
293
+ def _writes_deps(_schema: Schema, task: Task) -> str:
294
+ return f" (deps: {', '.join(d.render() for d in task.deps) or NO_DEPS})"
295
+
296
+
297
+ def _writes_requires(_schema: Schema, task: Task) -> str:
298
+ # Nothing at all where there are none, which is `_writes_deps`' em dash reversed and
299
+ # deliberately: `(deps: —)` says *this line was asked and waits on nothing*, and every
300
+ # roadmap answers that question. Almost none answer this one, so a `(requires: —)` on
301
+ # every line would be an axis charged to the backlogs that do not use it (RK1297).
302
+ return f" (requires: {', '.join(task.requires)})" if task.requires else ""
303
+
304
+
305
+ def _writes_symptom(schema: Schema, task: Task) -> str:
306
+ # Both shapes here rather than a `present` gate, mirroring `_reads_symptom`: a file
307
+ # without the slot still has the separator, so "absent" means an unwritten bold and
308
+ # never an unwritten em dash (RK48). A gate would have dropped both.
309
+ if not schema.symptom_field:
310
+ return f" {EM_DASH} "
311
+ return f" **{task.symptom}** {EM_DASH} "
312
+
313
+
314
+ def _writes_why(_schema: Schema, task: Task) -> str:
315
+ return task.why
316
+
317
+
318
+ #: The task line, once. Order is the line's order, and every reader and writer of the
319
+ #: format derives from this sequence rather than restating it (RK1063).
320
+ TEMPLATE: tuple[Slot, ...] = (
321
+ Slot("status", _reads_status, _writes_status),
322
+ Slot("head", _reads_head, _writes_head),
323
+ # The only slot a shape drops *whole*, and so the only one `present` is for: the marker
324
+ # and the symptom both leave something behind when a file has neither (RK43, RK48), and
325
+ # each says so in its own pair rather than by being gated away.
326
+ Slot("deps", _reads_deps, _writes_deps, lambda schema: schema.deps_field),
327
+ # After the deps and before the symptom, because the two groups answer adjacent
328
+ # questions — what this line waits on, and what it needs present to be done at all —
329
+ # and a reader scanning for "can I start this" reads both before the prose (RK1297).
330
+ Slot("requires", _reads_requires, _writes_requires),
331
+ Slot("symptom", _reads_symptom, _writes_symptom),
332
+ Slot("why", _reads_why, _writes_why),
333
+ )
334
+
335
+
336
+ #: Which `Schema` field each droppable slot turns off, by the name a project writes in
337
+ #: `[grammar.<role>] drop` (RK1064). A name and not a field, because `deps_field` and
338
+ #: `ref_required` are this package's spellings and a config is not a place to learn them —
339
+ #: and because the set is closed on purpose: what may be dropped is what a record can be
340
+ #: read without, which is a fact about the format rather than a knob.
341
+ DROPPABLE: Mapping[str, str] = {
342
+ "deps": "deps_field",
343
+ "ref": "ref_required",
344
+ "marker": "marker_field",
345
+ "symptom": "symptom_field",
346
+ }
347
+ #: Which `[markers]` key each marker name refers to. Names and not codepoints, because a
348
+ #: project declares its own glyphs and a grammar naming `✅` would be a second declaration
349
+ #: of the one `[markers] shipped` already makes.
350
+ MARKER_NAMES: Mapping[str, str] = {
351
+ "shipped": "shipped_marker",
352
+ "retired": "retired_marker",
353
+ "deferred": "deferred_marker",
354
+ }
355
+
356
+
357
+ @dataclass(frozen=True, slots=True)
358
+ class Grammar:
359
+ """How one role's records differ from the roadmap's, as a declaration (RK1064).
360
+
361
+ L6 already had the numbers, the markers, the paths and the id shape. What it did not
362
+ have was the **shape**: which fields a record carries and which it does not, so a
363
+ project could change every limit and no part of the line — and `Schema.as_ledger`, one
364
+ field dropped and the marker moved from the line to the file, was a method where it
365
+ could be a declaration beside the limits that already vary.
366
+
367
+ The boundary is the part to hold, and it is narrow on purpose: `markers` and `drop`,
368
+ both closed sets of *names*, and nothing that needs a traversal or an expression. A
369
+ declaration that grows conditionals is an interpreter to debug — Schematron is
370
+ expressive and nobody writes it — so what stays code stays code and registers here by
371
+ name, which is what keeps this the whole index of a role's shape rather than the half
372
+ that fit.
373
+
374
+ `extends` is the roadmap in both grammars the tool ships and is carried anyway: a role
375
+ that derived from another would say so here, and a field nobody can read is a field
376
+ the next role invents its own answer for.
377
+ """
378
+
379
+ #: The role whose grammar this one starts from. `""` is the base format itself.
380
+ extends: str = "roadmap"
381
+ #: The markers a record in this file may carry, by :data:`MARKER_NAMES` key. Empty
382
+ #: keeps the base set, which is what a role that only drops a field wants.
383
+ markers: tuple[str, ...] = ()
384
+ #: The slots this file's records do without, by :data:`DROPPABLE` key.
385
+ drop: tuple[str, ...] = ()
386
+ #: Which of the two "this file *is* the state" flags this role sets, if either — the
387
+ #: one part that is not a field of the line and so cannot be a `drop`.
388
+ states: str = ""
389
+
390
+
391
+ #: The grammars this tool ships, so no adopting project has to declare one it never chose
392
+ #: (RK1064). A project overrides a role with `[grammar.<role>]`; these are what it starts
393
+ #: from, and they are the two `as_ledger` and `as_deferred` were written out as.
394
+ DEFAULT_GRAMMARS: Mapping[str, Grammar] = {
395
+ # Marker ✅ or 🗑, no deps, no pointer — the rationale section is deleted when the task
396
+ # leaves, so a pointer to it could not resolve. A retired line (RK32) is this grammar
397
+ # again rather than a third: a departure with a different door.
398
+ "changelog": Grammar(
399
+ markers=("shipped", "retired"),
400
+ drop=("deps", "ref"),
401
+ states="shipped",
402
+ ),
403
+ # The roadmap's shape with one marker swapped and nothing dropped (RK96): a deferred
404
+ # line keeps the deps that are still deps, the symptom, and the pointer whose section
405
+ # is carried rather than deleted — which is what separates a pause from a departure.
406
+ "deferred": Grammar(markers=("deferred",), states="deferred"),
407
+ # The ledger's shape, and that is the finding rather than a shortcut (RK1269): a decision
408
+ # record is an id, a marker, one falsifiable claim and a reason, which is a line this
409
+ # format already writes. ✅ is a decision that stands and 🗑 one superseded — `retire
410
+ # --superseded-by`'s own two markers, so the departure needs no third. No deps, a
411
+ # decision being a constraint and not planned work; no pointer *demanded*, because the
412
+ # line is written at the moment the section it came from is deleted — and never that
413
+ # section copied whole, which is the accreting rationale file this tool exists to refuse.
414
+ #
415
+ # `drop` on `ref` sets `ref_required`, which is optional and not forbidden, and RK1361 is
416
+ # what that distinction turned out to be for: this file carries its own prose now, a body
417
+ # saying what was weighed rather than how the work was built, addressed `§<id>` under the
418
+ # id scheme and so reachable with no pointer on the line at all. Nothing here changes —
419
+ # the grammar was already right, and the role joined `PROSE_ROLES` instead.
420
+ "decisions": Grammar(markers=("shipped", "retired"), drop=("deps", "ref"), states="shipped"),
421
+ }
422
+
423
+
424
+ def grammar(marker: bool, symptom: bool) -> str:
425
+ """The task line as a pattern, for a file with or without each optional slot.
426
+
427
+ Composed from :data:`TEMPLATE` and anchored by the caller. `marker` and `symptom` are
428
+ passed rather than read off a schema because `document.ledger_slots` asks the question
429
+ the other way round — *which declaration would read this line* — and tries all four
430
+ combinations against a line it has no schema for yet (RK286).
431
+ """
432
+ has = {"status": marker, "symptom": symptom}
433
+ # Every slot, because `present` is about the *schema* and this question is asked without
434
+ # one: `deps` reads as optional either way, so a pattern built here is right for a file
435
+ # that declares the field and for one that does not.
436
+ return "".join(slot.reads(has.get(slot.name, True)) for slot in TEMPLATE)
437
+
438
+
439
+ #: Characters per word, for turning a budget that refuses into one that can be aimed at
440
+ #: (RK185). Measured over this repository's written `symptom` and `why` fields: at 392 of them
441
+ #: the median was 5.5 and the 95th percentile 6.36, and this is the first round number above
442
+ #: it — an author who lands on the word aim clears the character gate about nineteen times in
443
+ #: twenty, and the twentieth is the refusal that already names the surplus (RK184).
444
+ #:
445
+ #: **Re-measured at 1,756 fields**, where the 95th percentile is 6.52 and the first round
446
+ #: number above it is 6.6. Not a raise anyone argued for: the corpus grew and the ratio moved
447
+ #: with it, `tests/test_budgeting.py` failed as it is written to, and the figure follows the
448
+ #: reading exactly as it did the first time. Moving it up is the safe direction — the aim gets
449
+ #: shorter, so the gate is reached less often — and the rule it follows is the sentence above.
450
+ #:
451
+ #: Not configuration (L6). A project declares how long its lines may be; this is a property
452
+ #: of the prose those lines are written in, and a `roadkeep.toml` field for it would be a
453
+ #: project declaring a fact about English. The corpus that fixes it is the one the format is
454
+ #: proven by, and `tests/test_budgeting.py` re-measures it rather than trusting this comment.
455
+ #:
456
+ #: Here rather than in `budgeting`, which is where it was written and is still read from
457
+ #: (RK201): the refusal needs the same conversion the aim is published with, and a second
458
+ #: constant one layer down would be the second opinion an author stops trusting.
459
+ CHARS_PER_WORD = 6.6
460
+
461
+
462
+ #: How far a body composed *to* its word limit overshot the count `words` takes (RK301).
463
+ #: Measured filing five tasks in one session: four `section add` bodies aimed at a declared
464
+ #: 250 arrived at 250, 251, 253 and 266, thirteen refusals between them, each costing the
465
+ #: whole paragraph re-sent. An author counts sentences and this counts tokens the markup
466
+ #: between them puts in or leaves out, so a limit published as its own aim is a limit hit
467
+ #: from above. The first round figure above the worst of the four, 266 against 250.
468
+ #:
469
+ #: Not configuration, for `CHARS_PER_WORD`'s reason: a project declares how long a section
470
+ #: may be, and this is a property of counting prose by hand.
471
+ BODY_HEADROOM = 0.07
472
+
473
+
474
+ def width(text: str) -> int:
475
+ """How long a string is, counted the way the gates that read this file count (RK430).
476
+
477
+ Python's `len` counts **code points**. Java's `String.length`, C#'s, and JavaScript's
478
+ `.length` count **UTF-16 code units**, and a character outside the Basic Multilingual
479
+ Plane is one of the first and two of the second. Shio's ratchet test measured 321 on a
480
+ line `stats` had just reported at 320 of 320; neither number was wrong, and the single
481
+ character between them was `📋` — the status marker **this tool writes**. So the tool
482
+ emitted the character that made its own measurement disagree with its consumer's, then
483
+ certified a line that consumer rejects.
484
+
485
+ UTF-16 and not code points, because it is the stricter of the two: a line that passes
486
+ here is portable to a code-point counter and the reverse is not. It is also not
487
+ configuration (L6) — a project declares how long its lines may be, and a project
488
+ allowed to declare the *looser* unit is a project allowed to re-open this defect. The
489
+ markers `[markers]` declares are overwhelmingly astral (📋 💭 🛠 🗑; ✅ ⏳ ⏸ are not), so
490
+ every backlog this governs has the exposure whether or not it has met it yet.
491
+
492
+ Encoded rather than summed per character: it is the same arithmetic at C speed, and
493
+ `surrogatepass` is what keeps a lone surrogate — which `surrogateescape` decoding can
494
+ put in a `str` — from raising in a function whose whole job is to answer a length.
495
+
496
+ **The one measurement deliberately left in code points is `prose_width`**, which is a
497
+ `textwrap.fill` argument and not a gate: nothing refuses a wrapped paragraph, and
498
+ `textwrap` has no UTF-16 mode, so making it agree would mean re-wrapping every prose
499
+ file this tool has written to fix a number no gate reads.
500
+ """
501
+ return len(text.encode("utf-16-le", "surrogatepass")) // 2
502
+
503
+
504
+ #: The three units `[limits]` is declared in, named so a table that mixes them stops
505
+ #: implying one (RK437). RK430 settled *which* counter each figure uses and left the
506
+ #: config saying none of them: `symptom`, `why`, `line`, and the two `[non_goals]` keys
507
+ #: refuse in UTF-16 code units; `section` is a word budget; and `prose` is the column a
508
+ #: paragraph is filled to, which is the one figure still measured in code points.
509
+ #:
510
+ #: That last one is not an oversight left standing. `prose` is a `textwrap.fill` argument
511
+ #: and not a gate — nothing refuses a wrapped paragraph — and `textwrap` measures with
512
+ #: `len` and has no other mode, so agreeing would mean writing a wrapper and re-flowing
513
+ #: every paragraph this tool has written to move a number nothing reads. What was missing
514
+ #: was never the agreement; it was saying so where the figure is declared and reported.
515
+ UTF16_UNITS = "utf-16-code-units"
516
+ CODE_POINTS = "code-points"
517
+ WORDS = "words"
518
+
519
+
520
+ def points(text: str) -> int:
521
+ """The same string as the counter an author's editor shows (RK430).
522
+
523
+ Only ever reported beside :func:`width`, and only where the two disagree: the whole
524
+ cost of the defect was that both numbers look right and the difference is one.
525
+ """
526
+ return len(text)
527
+
528
+
529
+ def words(chars: int) -> int:
530
+ """A character budget as the word count it is safe to aim at.
531
+
532
+ Floored, never rounded: an aim that rounds up is an aim that lands over the gate half
533
+ the time it is hit exactly, which is the retry this exists to remove.
534
+ """
535
+ return max(0, int(chars // CHARS_PER_WORD))
536
+
537
+
538
+ def body_aim(limit: int) -> int:
539
+ """A word limit as the word count it is safe to compose to (RK301).
540
+
541
+ :func:`words` for a budget already declared in words. There is no unit to convert, so
542
+ what the aim buys is the headroom instead: composing to exactly the limit is what the
543
+ thirteen measured refusals did, and a figure published as both the ceiling and the target
544
+ is a target that lands over half the time it is hit. Floored, for :func:`words`' reason.
545
+ """
546
+ return max(0, int(limit / (1 + BODY_HEADROOM)))
547
+
548
+
549
+ def words_over(chars: int) -> int:
550
+ """A character *surplus* as the words it takes to clear it (RK201).
551
+
552
+ Ceiled, where :func:`words` floors, and for the same reason read backwards: an aim
553
+ that rounds up overshoots the gate, and a cut that rounds down stops short of it.
554
+ Naming four words to delete against a 29-character overrun sends the author back to
555
+ the same refusal, which is the retry the figure exists to remove.
556
+ """
557
+ return max(1, math.ceil(chars / CHARS_PER_WORD))
558
+
559
+
560
+ def over_by(
561
+ actual: int,
562
+ limit: int,
563
+ unit: str = "character",
564
+ because: str = "",
565
+ measured: str = "",
566
+ *,
567
+ prose: bool = True,
568
+ source: str = "",
569
+ ) -> str:
570
+ """The arithmetic every length refusal opens with, spelled in one place (RK184).
571
+
572
+ An author handed a total and a limit derives the surplus and then does not act on it:
573
+ the sequence measured against 320 was 327, then 303, then 300 — three rewrites where
574
+ one subtraction would have done, because "move the remainder" is editorial advice and
575
+ an author who takes it recomposes the sentence. A rewrite re-rolls the length.
576
+
577
+ So the number to remove is stated, and the verb is **delete**: subtracting a count
578
+ from a sentence is an operation that succeeds on the first attempt, where writing to a
579
+ target length is one that converges by feedback. Where the text goes is still true and
580
+ still said — after the arithmetic, because it answers a different question.
581
+
582
+ One function, because a refusal spelled five ways is five things that drift apart, and
583
+ the unit is a parameter for the two refusals counted in words rather than characters.
584
+
585
+ **And the surplus is restated in words** (RK201). A character count is exact and it is
586
+ not a unit the author composing the retry can count, which is the whole argument RK185
587
+ made for publishing every aim in words — and it left this surface, the one an author
588
+ reaches *after* the overrun, in characters alone. The exact figure stays first, because
589
+ the approximation is derived from it; the word one follows, hedged, because it is. A
590
+ refusal already counted in words gets no second copy of itself.
591
+
592
+ ``source`` is where the number came from (RK1067): every code this gate reports resolves
593
+ to a door and prints it, and the one whose remedy is *changing the rule* had none — an
594
+ author told their `why` is over 200 was left to find where 200 was set, which in an
595
+ adopting project is a file they have never opened. Passed rather than looked up, because
596
+ this function is the kernel's and a config is not: :meth:`Schema.source_of` composes it
597
+ from what the project recorded, and the empty string is a caller with nothing to cite.
598
+
599
+ ``prose`` is the caller's answer to whether a shorter *sentence* is the remedy (RK243).
600
+ It is the caller's because only they know: `line.too-long` fires when no field is over
601
+ the budget the line left it, so what does not fit is the structure around the prose —
602
+ and its own message says exactly that, in the sentence the word figure would be
603
+ appended to. Naming an edit that cannot work, beside the clause explaining why, is
604
+ worse than naming no edit at all (RK16). One spelling either way, which is what this
605
+ function exists for, so the switch is a parameter and not a second composer.
606
+ """
607
+ surplus = actual - limit
608
+ deletion = f"delete {surplus} {_plural(surplus, unit)}"
609
+ if prose and unit == "character":
610
+ aim = words_over(surplus)
611
+ deletion += f" {EM_DASH} about {aim} {_plural(aim, 'word')}"
612
+ return (
613
+ f"{actual} {_plural(actual, unit)}{_counted(actual, measured)}, "
614
+ f"limit is {limit}{source}{because}: {deletion}"
615
+ )
616
+
617
+
618
+ def _counted(actual: int, measured: str) -> str:
619
+ """The unit, named only where naming it settles an argument (RK430).
620
+
621
+ Silent on the overwhelming majority of refusals, where the two counters agree and a
622
+ parenthesis about UTF-16 would be noise on every one of them. It appears exactly when
623
+ an author's editor shows a different number from the one being refused — which is the
624
+ whole cost of the defect, both figures looking right and the difference being one.
625
+ """
626
+ if not measured or points(measured) == actual:
627
+ return ""
628
+ return (
629
+ f" (UTF-16 code units, {points(measured)} code points: the limit is the stricter "
630
+ f"count, because the gates that read this file use it)"
631
+ )
632
+
633
+
634
+ def _plural(count: int, unit: str) -> str:
635
+ return unit if count == 1 else f"{unit}s"
636
+
637
+
638
+ class DepKind(StrEnum):
639
+ """The four things a dep can name, as the live backlogs already write them.
640
+
641
+ The distinction exists because they resolve differently and one of them does not
642
+ resolve at all: an :attr:`EXTERNAL` dep is unresolvable *by construction*, and
643
+ reporting it as pending makes a permanently blocked task read like the next one
644
+ to start. :attr:`RANGE` is here for the opposite reason — Turing's
645
+ `(deps: T451–T457)` *is* resolvable, so calling it external would be a false
646
+ statement rather than a missing one.
647
+ """
648
+
649
+ TASK = "task"
650
+ BLOCK = "block"
651
+ RANGE = "range"
652
+ EXTERNAL = "external"
653
+
654
+ @property
655
+ def collective(self) -> bool:
656
+ """Whether one token names many lines — the two kinds `Backlog.expand` expands.
657
+
658
+ A property rather than a tuple spelled at each call site (RK432). Three rules turn
659
+ on it — the graph expands one into member hops, the gate reports what one hides,
660
+ and the annotation refuses to put a single marker on one — and a classification
661
+ three modules each keep their own copy of is one three modules can come to
662
+ disagree about.
663
+ """
664
+ return self in (DepKind.BLOCK, DepKind.RANGE)
665
+
666
+
667
+ class SchemaError(ValueError):
668
+ """Raised by :meth:`Schema.check`, carrying every violation, not the first.
669
+
670
+ A refusal that reports one problem per run turns a single fix into a
671
+ conversation, so the exception is a batch.
672
+ """
673
+
674
+ def __init__(self, violations: tuple[Violation, ...]) -> None:
675
+ self.violations = tuple(violations)
676
+ #: An address a refusal above this layer computed while explaining itself, for the
677
+ #: surface that can offer a retry (RK1149). Empty here and always: the kernel derives
678
+ #: no anchor and knows no outline — what it declares is the *channel*, so a reader is
679
+ #: a field access rather than a `getattr` guess, and a violation stays a rule broken
680
+ #: rather than growing a field only one code would ever fill.
681
+ self.offered = ""
682
+ #: A refusal from the **other** class of check that is also true of this call
683
+ #: (RK1256), as the sentence that refusal renders. Empty here and always: the kernel
684
+ #: knows one class — its own rules — and what it declares is the channel, so the
685
+ #: caller that can see both fills it and a reader is a field access.
686
+ #:
687
+ #: Filled only where the second answer is *answerable*. `add --block ZZ` with an
688
+ #: over-long `why` has both, because the block is checked against a document already
689
+ #: read and nothing about it depends on the prose; `ship` on an id nothing carries
690
+ #: does not, because there is no task to validate a `why` against and a second
691
+ #: sentence would be about a line that does not exist.
692
+ self.beside = ""
693
+ #: How the fields below relate to the **flags the caller typed** (RK1262). Empty here
694
+ #: and always, for the reason the two above are: the kernel validates a task and knows
695
+ #: nothing about an argv, so what it declares is the channel and the caller that holds
696
+ #: both fills it.
697
+ #:
698
+ #: Filled only where the two spellings differ. A `why` refused on an `add` came from
699
+ #: `--why` and needs no sentence; a `why` refused on a `ship --part` came from
700
+ #: `--remainder`, which *becomes* that field, and there the field name alone names the
701
+ #: wrong argument — with the right one adjacent on the same command line.
702
+ self.about = ""
703
+ super().__init__("; ".join(str(v) for v in self.violations))
704
+
705
+
706
+ #: The door appended to an over-long prose field: where the words that will not fit go. A
707
+ #: **named constant and not an inline clause** (RK1285), because it is advice and not the rule
708
+ #: — `<field>.too-long` is a code, a count and a limit — and one caller now has a case where
709
+ #: it is false: `ship --decides` is refused over a claim it inherited, and the section this
710
+ #: names is the one that ship is deleting. So the carrier removes it by identity rather than
711
+ #: by guessing at its words, and a rewording moves both ends at once.
712
+ ELSEWHERE = "; the remainder belongs in the improvements section rather than compressed away"
713
+
714
+
715
+ @dataclass(frozen=True, slots=True)
716
+ class Violation:
717
+ """One rule, broken once. ``code`` is stable; ``message`` is for a human."""
718
+
719
+ code: str
720
+ field: str
721
+ message: str
722
+
723
+ def __str__(self) -> str:
724
+ return f"{self.field}: {self.message} [{self.code}]"
725
+
726
+
727
+ @dataclass(frozen=True, slots=True)
728
+ class Dep:
729
+ """A dependency, and the status its target carried when the line was written.
730
+
731
+ ``marker`` is a cache of another line's status, derived on write (RK8); the
732
+ model carries it because the rendered line does. It is any marker and not only
733
+ ✅ — Shio's backlog annotates ⏳ and 📋 deps too, and since the marker is
734
+ derived from the target's status there is no reason one status would be
735
+ unrepresentable.
736
+ """
737
+
738
+ id: str
739
+ marker: str | None = None
740
+
741
+ @property
742
+ def shipped(self) -> bool:
743
+ return self.marker == SHIPPED
744
+
745
+ def render(self) -> str:
746
+ return f"{self.id} {self.marker}" if self.marker else self.id
747
+
748
+
749
+ @dataclass(frozen=True, slots=True)
750
+ class Task:
751
+ """The six-field task line as data. Construction never validates.
752
+
753
+ Validation is a separate call so that a caller can collect every violation
754
+ (``lint``) or refuse before rendering (``add``) — a constructor that raises
755
+ can only ever report the first problem, and cannot hold a line long enough
756
+ to explain what is wrong with it.
757
+ """
758
+
759
+ id: str
760
+ status: str
761
+ block: str
762
+ symptom: str
763
+ why: str
764
+ deps: tuple[Dep, ...] = ()
765
+ #: What has to be **present** for this line to be finishable at all (RK1297) — a
766
+ #: DualSense on the desk, a PS4 and a PS5 to measure against each other. Tokens of a
767
+ #: vocabulary `roadkeep.toml` declares, never prose (L4), and not deps: a dep is work
768
+ #: this backlog or another one does, and shipping something satisfies it. Nothing
769
+ #: satisfies one of these; a caller either has it or does not, which is why it is a
770
+ #: fact about the line and the answer is a fact about who is asking.
771
+ #:
772
+ #: `requires` and not `needs`, which is the word the line would read best with: an
773
+ #: `Insertion.needs` one module up is the follow-up an `add` left owing, and it prints a
774
+ #: row under that name beside the rows this field produces. One word, one thing.
775
+ requires: tuple[str, ...] = ()
776
+ ref: str | None = None
777
+ #: Which part of the work this entry records, where only part of it landed (RK121).
778
+ #: A **ledger** field and the third state the model did not have: open in the roadmap
779
+ #: and recorded in the changelog were the only two, so work delivered in halves was
780
+ #: neither, and every project using this invented the same escape — `SH96 (local
781
+ #: half)`, `SH275 (partial)` — in a spelling the grammar could not read. None is the
782
+ #: ordinary entry: a shipment that needs no qualifier is not a partial one.
783
+ part: str | None = None
784
+ #: The whitespace the line starts with, kept verbatim (RK49). Part of the line and so
785
+ #: part of the model: Shio nests four live tasks under the line that shipped their
786
+ #: parent, and a render that dropped two spaces would stop 4 files from round-tripping.
787
+ #: Never invented — no write sets it, so a nested line stays nested and nothing else is.
788
+ indent: str = ""
789
+
790
+ def __post_init__(self) -> None:
791
+ # Accept plain ids for convenience; keep the field a tuple of Dep so
792
+ # rendering and validation have one shape to handle.
793
+ coerced = tuple(Dep(d) if isinstance(d, str) else d for d in self.deps)
794
+ object.__setattr__(self, "deps", coerced)
795
+
796
+ @property
797
+ def dep_ids(self) -> tuple[str, ...]:
798
+ return tuple(d.id for d in self.deps)
799
+
800
+ @property
801
+ def in_halves(self) -> bool:
802
+ """Does this record declare that only part of the work landed? (RK121, RK1080)
803
+
804
+ One question with two readers and, until now, two implementations:
805
+ `shipping._already_recorded` decides whether a line can be closed against the entry
806
+ beside it, and `linting._in_halves` decides whether to report the pair — and the
807
+ second's docstring said it *applied* the first's test while restating it. Narrowing
808
+ both to the qualifier took two edits in two tasks (RK1075 moved the verb, RK1076
809
+ moved the gate), one decision arriving twice because nothing made it one. They
810
+ agreed for the whole time they were wrong, which is the shape a drifting duplicate
811
+ never has and the reason this is worth folding rather than watching.
812
+
813
+ Here rather than beside either caller, and that is measured rather than assumed: the
814
+ dependency runs `shipping` → `linting` (lazily, RK497), so a predicate in the verb
815
+ that the gate imported would close a cycle. It belongs here anyway — the qualifier is
816
+ a field of this record and the question is decidable from the record alone, which is
817
+ the line RK1066 draws between what a declaration answers and what needs a traversal.
818
+ """
819
+ return bool(self.part)
820
+
821
+
822
+ @dataclass(frozen=True, slots=True)
823
+ class Id:
824
+ """One id, taken apart by the declaration that spells it (RK109).
825
+
826
+ The three parts are exactly the three `[ids]` declares — the family (RK74), the
827
+ number the next-id maximum is taken over (RK4), and the sub-letter a split task
828
+ carries (RK106) — so a caller reads the same shape whatever the project wrote, and
829
+ ``sub`` is `""` at a project that declares none rather than a case to remember.
830
+
831
+ Produced only by :meth:`Schema.parse_id`, which is the *same* fragment
832
+ :meth:`Schema.id_pattern` refuses a line with: a string this exists for is a string
833
+ the gate admits, and the two used to be able to disagree.
834
+ """
835
+
836
+ family: str
837
+ number: int
838
+ sub: str = ""
839
+
840
+
841
+ def number_fragment(pad: int = 1) -> str:
842
+ """The numeric part of an id, as a regex fragment, for a project that pads to ``pad``.
843
+
844
+ **One spelling per number** is the whole rule (RK106). A number shorter than the
845
+ declared width is zero-filled to it, a longer one is written out, and nothing else
846
+ matches — so ``pad = 2`` admits `01`…`09`, `10`…`99` and `100` upward while refusing
847
+ both `1` and `001`. That is what makes a declared width safe where padding in general
848
+ is not: the hazard is a backlog that pads *sometimes*, and a project stating a width
849
+ has said which of `D1` and `D01` is the id.
850
+
851
+ ``pad = 1`` is the unpadded default, spelled as the bare ``[1-9][0-9]*`` a reader
852
+ recognises rather than a one-branch alternation that means the same thing.
853
+ """
854
+ if pad < 2:
855
+ return "[1-9][0-9]*"
856
+ # One branch per significant-digit count below the width, each with the zeros that
857
+ # fill it out, then one for everything at or above it. Written as repeated literals
858
+ # rather than `{n}` counts because a declared width is 2 or 3 in practice, and
859
+ # `0[1-9]` is read at a glance where `0{1}[1-9][0-9]{0}` is decoded.
860
+ branches = ["0" * (pad - k) + "[1-9]" + "[0-9]" * (k - 1) for k in range(1, pad)]
861
+ branches.append("[1-9]" + "[0-9]" * (pad - 1) + "[0-9]*")
862
+ return "(?:" + "|".join(branches) + ")"
863
+
864
+
865
+ def _check_prefixes(prefixes: tuple[str, ...]) -> None:
866
+ """Every family this backlog numbers has to be readable, and readable as one thing."""
867
+ if not prefixes:
868
+ raise ValueError("prefix must name at least one family")
869
+ for prefix in prefixes:
870
+ if not _PREFIX_RE.match(prefix):
871
+ raise ValueError(f"prefix must be uppercase alphanumeric: {prefix!r}")
872
+ if len(set(prefixes)) != len(prefixes):
873
+ raise ValueError(f"prefix names a family twice: {list(prefixes)}")
874
+ for prefix in prefixes:
875
+ # `C` beside `C1` makes `C12` two ids — `C`+12 and `C1`+2 — and which one it is
876
+ # would depend on the order the alternation happens to be written in.
877
+ other = next((p for p in prefixes if p != prefix and p.startswith(prefix)), None)
878
+ if other is not None:
879
+ raise ValueError(
880
+ f"prefix {prefix!r} and {other!r} cannot both be families: an id "
881
+ f"starting {other!r} would read as either, and no rule breaks the tie"
882
+ )
883
+
884
+
885
+ @dataclass(frozen=True, slots=True)
886
+ class Schema:
887
+ """The format, as configuration (L6).
888
+
889
+ The defaults are this repository's, which is also the conformance fixture:
890
+ if a limit here cannot express `docs/ROADMAP.md`, the limit is wrong and not
891
+ the lines. `roadkeep.toml` (RK3) builds one of these instead of the tool
892
+ hardcoding any project's vocabulary.
893
+ """
894
+
895
+ #: Every family this backlog numbers, the first being the one new ids are minted
896
+ #: under. One is the common case and three of the four live corpora; cursarei numbers
897
+ #: six tracks and the letter *is* which track the work belongs to (RK74), so a single
898
+ #: string would have made 521 of its lines unreadable rather than non-conforming.
899
+ #: Nothing maps a family to anything — a track is not a block and not an owner.
900
+ prefixes: tuple[str, ...] = ("RK",)
901
+ #: The width the number is zero-filled to, `[ids] pad` (RK106). 1 is unpadded, which is
902
+ #: what three of the four live corpora write; Dumont writes `D01` through `D09` on every
903
+ #: line and was getting a finding for each. Declared rather than tolerated: the tool
904
+ #: refuses padding in general because `D1` and `D01` would be two names for one task,
905
+ #: and a *width* is the project answering that — every number has exactly one spelling
906
+ #: again, and both the unpadded `D1` and the over-padded `D001` stay refused.
907
+ id_pad: int = 1
908
+ #: Whether an id may end in one lowercase letter, `[ids] suffix` (RK106) — Turing's
909
+ #: `T24b`, a task split after its number was already cited in commits and issues, which
910
+ #: is the thing an id is for. Off by default, because a letter is a second address for
911
+ #: one number and only a backlog that already spells it should be able to. Never
912
+ #: minted: :meth:`spell_id` counts, and a split is a `renumber --to`.
913
+ id_suffix: bool = False
914
+ markers: tuple[str, ...] = OPEN_MARKERS
915
+ shipped_marker: str = SHIPPED
916
+ #: The ledger's other legal marker (RK32). Not an open marker: a retired line is a
917
+ #: record of a departure, and a roadmap that can say "retired" is a roadmap holding
918
+ #: work nobody will do.
919
+ retired_marker: str = RETIRED
920
+ #: The deferred store's only legal marker (RK96) — the state between open and terminal.
921
+ #: Held to the same rule as the two above and for the same reason: the file a line
922
+ #: sits in is what says whether it is being worked, so a marker legal in two files is
923
+ #: two files that can both claim one task.
924
+ deferred_marker: str = DEFERRED
925
+ #: The open markers whose design is still to be written (RK83), `[markers] undesigned`.
926
+ #: A subset of :attr:`markers` — checked where it is typed, like the shipped/deferred
927
+ #: clash, because this list only ever meets the open set inside `pick`. Nothing here
928
+ #: refuses a line for carrying one: what it changes is what an answer *says*, and what
929
+ #: `--designed` sets aside, since the bias belongs to the caller and not to the ranking.
930
+ undesigned: tuple[str, ...] = UNDESIGNED
931
+ #: The vocabulary a `(requires: …)` group draws on, `[requirements] declared` (RK1297).
932
+ #: Empty by default, which makes the axis opt-in *and* makes it refusable: a project
933
+ #: that has declared nothing refuses every token, so the first one an author writes
934
+ #: is answered with the `govern`-shaped edit that declares it rather than with a line
935
+ #: nobody can act on. Held here beside :attr:`undesigned` for the same reason — both are
936
+ #: a project's own words for a distinction `pick` acts on, and neither is a format.
937
+ requirements: tuple[str, ...] = ()
938
+ symptom_max: int = 120
939
+ why_max: int = 200
940
+ #: How long a partial entry's qualifier may be (RK121). Short by design — it names
941
+ #: *which half*, and the sentence about what landed is the `why` two characters away.
942
+ #: The default clears the longest the corpus wrote (`the SH22 half`, 13) many times over
943
+ #: and still refuses a qualifier that has become a second summary.
944
+ part_max: int = 40
945
+ #: Whether `why` is held to one sentence, and to ending in a stop. True everywhere by
946
+ #: default, because the rule is what keeps a `why` from becoming the rationale — and
947
+ #: switchable per role (`[rules.<role>]`, RK52) because a ledger written before the
948
+ #: tool is 233 paragraphs of history, and a rule cannot be obeyed retroactively.
949
+ one_sentence: bool = True
950
+ terminator: bool = True
951
+ line_max: int = 320
952
+ #: A rationale section's budget, in **words** — the unit a paragraph has (RK9). The
953
+ #: default clears the longest section in this repository (181 words) and no more:
954
+ #: the file that motivated the tool reached 539 KB one honest paragraph at a time.
955
+ section_max: int = 250
956
+ #: The width prose is filled to when a section is written, in **code points** — the one
957
+ #: figure here counted that way, and :data:`CODE_POINTS` is where the reason lives. A
958
+ #: table or a list is left exactly as the author wrote it; only plain paragraphs are
959
+ #: re-flowed.
960
+ prose_width: int = 88
961
+ #: Whether a line must point at a rationale section. True by default and switchable per
962
+ #: role (`[rules.<role>]`, RK66), because it is a project's convention and not a fact
963
+ #: about the format: one that derives its anchors from ids can demand the pointer, the
964
+ #: section being one command away and the anchor unable to be wrong, while one that
965
+ #: numbers by hand may have a task whose design is a single line — and inventing a
966
+ #: section to satisfy a linter is the accretion this tool exists to refuse. What is never
967
+ #: negotiable is the other direction: a pointer that *is* written must resolve.
968
+ ref_required: bool = True
969
+ #: The ledger's own status *is* ✅, so it is the one file where the shipped
970
+ #: marker is legal. Set by :meth:`as_ledger`, never by hand.
971
+ shipped_allowed: bool = False
972
+ #: The same claim for the deferred store, whose own status is ⏸ (RK96). Set by
973
+ #: :meth:`as_deferred`, never by hand.
974
+ deferred_allowed: bool = False
975
+ #: The ledger carries no `(deps: …)` group: a dependency is a planning fact
976
+ #: about unshipped work, and a shipped line has none left to state.
977
+ deps_field: bool = True
978
+ #: Whether the line carries a status slot at all. False is a **ledger** stating once
979
+ #: what every entry in it would otherwise repeat (RK43): both live ledgers write
980
+ #: `- **T1** — …`, 755 lines in Turing and 234 in Shio, and the marker of a file
981
+ #: where everything shipped is derivable from the file. Set by :meth:`as_ledger`.
982
+ marker_field: bool = True
983
+ #: Whether the line carries a bold symptom before the em dash. False is the other
984
+ #: shape both live ledgers write — `- **T1** — <prose>`, 761 lines in Turing and 234
985
+ #: in Shio — where the whole tail is the `why` and the split has no consumer, because
986
+ #: nothing picks, blocks on or budgets a line that already shipped (RK48). Set by
987
+ #: :meth:`as_ledger`.
988
+ symptom_field: bool = True
989
+ #: The project's declaration of the two above — `[ledger] marker` and `[ledger]
990
+ #: symptom` in `roadkeep.toml` (L6). Read only by :meth:`as_ledger`: in the roadmap
991
+ #: the marker *is* the status, so a roadmap without one could not tell 📋 from 🛠, and
992
+ #: a roadmap without a symptom would be a backlog of reasons with no faults.
993
+ ledger_marker: bool = True
994
+ ledger_symptom: bool = True
995
+ #: The word a heading files work under (RK75). `Block` by default, so nothing changes
996
+ #: for a project that never declares it; `Track`, `Fase` or anything else for the three
997
+ #: of four adopting corpora that chose their own. Only the word is configuration — a
998
+ #: heading still declares exactly one label, and a dep still resolves against that same
999
+ #: list, because that is what `pick`, `stats` and every block dep are over.
1000
+ heading_word: str = DEFAULT_HEADING_WORD
1001
+ #: How the rationale section is addressed (RK27). ``"id"`` derives the pointer
1002
+ #: from the line's own id — nothing to choose when writing, nothing to renumber
1003
+ #: when shipping. ``"outline"`` is the hand-numbered `§x.y` that Shio and Turing
1004
+ #: already use, kept because migrating a live outline is a separate decision
1005
+ #: from adopting the tool.
1006
+ ref_scheme: str = "id"
1007
+ #: The namespace this role's outline addresses live in (`[refs]`, RK340). Empty is every
1008
+ #: project that has not declared one, and every role under `ref_scheme = "id"`, where the
1009
+ #: anchor is the id and the ids are already one namespace the format keeps unique. Where
1010
+ #: it is set, this role answers **only** prefixed addresses and no bare one — which is
1011
+ #: what makes `§S:I` and `§I` two addresses rather than one read twice.
1012
+ ref_prefix: str = ""
1013
+ #: Where each limit this schema carries was declared, by field name — `"why_max"` →
1014
+ #: `"roadkeep.toml:34 [limits].why"` (RK1067). A refusal is the one place an author is
1015
+ #: standing over a number they may want changed, and it named the number and not the
1016
+ #: line. Plain strings and never a `Config`: this module imports nothing above itself
1017
+ #: (RK1065), so the citation is composed by whoever read the file and carried here as
1018
+ #: text. A field absent means the project declared none, which is a different answer
1019
+ #: from an unknown one and is exactly the fact the author needs.
1020
+ #:
1021
+ #: Pairs and not a mapping, because a schema is a **cache key**: `document._parsed` is
1022
+ #: keyed by `(bytes, schema)`, so a field that is not hashable makes every parse in the
1023
+ #: package a `TypeError`. Five entries at most, so the lookup is a scan.
1024
+ origins: tuple[tuple[str, str], ...] = ()
1025
+
1026
+ def source_of(self, limit: str) -> str:
1027
+ """The parenthesis :func:`over_by` prints after a limit, or the tool's own default.
1028
+
1029
+ Never invented: a project that declared nothing is told so, because *which of these
1030
+ two numbers did I choose* is the whole question a refusal over a limit raises, and a
1031
+ citation guessed for an undeclared one would answer it wrongly in the reassuring
1032
+ direction.
1033
+ """
1034
+ where = next((at for name, at in self.origins if name == limit), "")
1035
+ return f" ({where})" if where else " (this tool's default)"
1036
+
1037
+ def __post_init__(self) -> None:
1038
+ if self.ref_scheme not in REF_SCHEMES:
1039
+ raise ValueError(
1040
+ f"ref_scheme must be one of {', '.join(sorted(REF_SCHEMES))}, "
1041
+ f"got {self.ref_scheme!r}"
1042
+ )
1043
+ if self.ref_prefix and not REF_PREFIX_RE.match(self.ref_prefix):
1044
+ raise ValueError(
1045
+ f"ref prefix must be one word of letters and digits starting with a "
1046
+ f"letter, got {self.ref_prefix!r}: it is written in front of an address "
1047
+ f"as {self.ref_prefix}{REF_SEPARATOR}<x.y>, so a dot in it would read as "
1048
+ f"an outline segment"
1049
+ )
1050
+ _check_prefixes(self.prefixes)
1051
+ if self.id_pad < 1:
1052
+ raise ValueError(
1053
+ f"id_pad must be at least 1, got {self.id_pad}: 1 is an unpadded id, and "
1054
+ f"there is no width below it to declare"
1055
+ )
1056
+ if not self.heading_word.strip() or self.heading_word != self.heading_word.strip():
1057
+ raise ValueError(
1058
+ f"heading word must be one bare word: {self.heading_word!r} — it is "
1059
+ f"joined to the label by exactly one space, on both the heading and the dep"
1060
+ )
1061
+ if not self.markers:
1062
+ raise ValueError("markers must not be empty")
1063
+ if self.shipped_marker in self.markers and not self.shipped_allowed:
1064
+ raise ValueError(
1065
+ f"{self.shipped_marker} is the shipped marker and may not also be an "
1066
+ "open marker: a roadmap that can say 'done' disagrees with the changelog"
1067
+ )
1068
+ if self.deferred_marker in self.markers and not self.deferred_allowed:
1069
+ raise ValueError(
1070
+ f"{self.deferred_marker} is the deferred marker and may not also be an "
1071
+ "open marker: a roadmap that can say 'paused' is a backlog `pick` reads "
1072
+ "as work waiting to be started"
1073
+ )
1074
+ for name in (
1075
+ "symptom_max",
1076
+ "why_max",
1077
+ "part_max",
1078
+ "line_max",
1079
+ "section_max",
1080
+ "prose_width",
1081
+ ):
1082
+ if getattr(self, name) < 1:
1083
+ raise ValueError(f"{name} must be positive")
1084
+
1085
+ @property
1086
+ def prefix(self) -> str:
1087
+ """The family a new id is minted under when the caller names none (RK74).
1088
+
1089
+ The first declared, and not a default the tool chose: a project that numbers one
1090
+ family reads this as "the prefix", and one that numbers six has already said which
1091
+ track is its main line by writing it first.
1092
+ """
1093
+ return self.prefixes[0]
1094
+
1095
+ @property
1096
+ def prefix_alternation(self) -> str:
1097
+ """The families as one regex fragment, ready to embed. `RK`, or `(?:C|G|L)`.
1098
+
1099
+ One family stays bare, so a single-track project's `id_pattern` is still the
1100
+ `^RK[1-9][0-9]*$` a reader recognises — an MCP client shows this string, and a
1101
+ group nothing alternates over is punctuation that has to be read past.
1102
+
1103
+ Longest first, so `CX` would win over `C`. A tie is impossible —
1104
+ :func:`_check_prefixes` refuses a family that starts another — but the alternation
1105
+ is still ordered, because a regex that only works because no input reaches its
1106
+ ambiguity is one that reads as though the order did not matter.
1107
+ """
1108
+ if len(self.prefixes) == 1:
1109
+ return re.escape(self.prefixes[0])
1110
+ ordered = sorted(self.prefixes, key=lambda p: (-len(p), p))
1111
+ return "(?:" + "|".join(re.escape(prefix) for prefix in ordered) + ")"
1112
+
1113
+ @property
1114
+ def number_fragment(self) -> str:
1115
+ """The number an id of this project carries, as a regex fragment (RK106)."""
1116
+ return number_fragment(self.id_pad)
1117
+
1118
+ def _fragment(self, named: bool, *, sub_required: bool = False) -> str:
1119
+ """The join itself, spelled once, with or without the three parts named (RK109).
1120
+
1121
+ Two spellings of one fragment and not two fragments: a caller that embeds an id in
1122
+ a larger pattern cannot use named groups twice, and a caller that takes an id apart
1123
+ cannot count anonymous ones — so the *joining* is here, and each caller asks for the
1124
+ form it can read rather than reassembling the three declarations for itself.
1125
+
1126
+ ``sub_required`` makes the sub-letter mandatory instead of optional, which is the
1127
+ one caller that wants the ids :meth:`spell_id` cannot reach rather than the ids a
1128
+ line may carry (:meth:`split_id_pattern`, RK111). A third form and not a third
1129
+ fragment, for the same reason there are two: the three declarations still join here.
1130
+ """
1131
+ family = self.prefix_alternation
1132
+ number = self.number_fragment
1133
+ tail = ""
1134
+ if self.id_suffix:
1135
+ tail = SUB_LETTER if sub_required else f"{SUB_LETTER}?"
1136
+ if not named:
1137
+ return f"{family}{number}{tail}"
1138
+ # An empty group where the project declares no sub-letter, so `parse_id` reads
1139
+ # `sub` unconditionally and a project without one is not a second code path.
1140
+ return f"(?P<family>{family})(?P<number>{number})(?P<sub>{tail})"
1141
+
1142
+ @property
1143
+ def id_fragment(self) -> str:
1144
+ """A whole id as a regex fragment: the family, the number, and the sub-letter.
1145
+
1146
+ The one place the three declarations are joined, because an id is matched in five —
1147
+ :meth:`id_pattern`, the scan the next id is a maximum over, both ends of a range
1148
+ dep, and the bold id `lint` and `origin` read out of prose — and a spelling only
1149
+ four of them knew would make an id legal on the line and invisible to the counter,
1150
+ which is how a number gets minted twice.
1151
+ """
1152
+ return self._fragment(named=False)
1153
+
1154
+ @property
1155
+ def id_groups(self) -> str:
1156
+ """The same fragment with its three parts named `family`, `number` and `sub`.
1157
+
1158
+ For the two callers that take an id *apart* rather than test one: :meth:`parse_id`,
1159
+ and the scan the next id is a maximum over (RK4), which used to build its own
1160
+ three-group copy — a third reader of a shape declared once. Embeddable exactly once
1161
+ in a pattern, named groups being unique; :attr:`id_fragment` is the other form.
1162
+ """
1163
+ return self._fragment(named=True)
1164
+
1165
+ def parse_id(self, text: str) -> Id | None:
1166
+ """An id of this project taken apart, or None if this is not one (RK109).
1167
+
1168
+ The single parse both the pattern and the ordering are derived from. Anything
1169
+ :meth:`id_pattern` refuses returns None here — under `pad = 2` that includes the
1170
+ `D1` the ordering used to read as 1 — so a caller cannot hold half the declaration:
1171
+ it either has all three parts or it has no id, and there is no third answer where a
1172
+ number was read out of a string the gate would reject.
1173
+ """
1174
+ match = re.fullmatch(self.id_groups, text)
1175
+ if match is None:
1176
+ return None
1177
+ return Id(match.group("family"), int(match.group("number")), match.group("sub"))
1178
+
1179
+ def spell_id(self, family: str, number: int) -> str:
1180
+ """How this project writes an id — the one place a number becomes a name (RK106).
1181
+
1182
+ Zero-filled to `[ids] pad`, so a project that pads gets `D10` from the counter and
1183
+ never a `D1` its own gate would then refuse. No sub-letter: the letter addresses a
1184
+ split of an id that already exists, and nothing derives that.
1185
+ """
1186
+ return f"{family}{number:0{self.id_pad}d}"
1187
+
1188
+ def block_dep_pattern(self) -> re.Pattern[str]:
1189
+ """`<word> <label>` as a dep names it (RK28, RK75)."""
1190
+ return re.compile(rf"^{re.escape(self.heading_word)} ({BLOCK_LABEL})$")
1191
+
1192
+ def heading_pattern(self) -> re.Pattern[str]:
1193
+ """`<word> <label>` as a heading declares it — the same label shape as the dep.
1194
+
1195
+ The same, and not merely similar: a heading that declared `D` where the dep spells
1196
+ `D.1` would make `pick --block D.1` an answer about a block nothing declares, and
1197
+ the disagreement would be invisible because both halves parse.
1198
+ """
1199
+ return re.compile(
1200
+ rf"^{re.escape(self.heading_word)} (?P<label>{BLOCK_LABEL})(?:\s|$)"
1201
+ )
1202
+
1203
+ def block_named(self, label: str) -> str:
1204
+ """How a report names a block — the project's word, so a refusal it prints is
1205
+ the text its own files carry rather than a vocabulary it never adopted."""
1206
+ return f"{self.heading_word} {label}"
1207
+
1208
+ def _families(self) -> str:
1209
+ """The families as a refusal names them: `RK`, or `C/L/S/P/G/V` in declared order.
1210
+
1211
+ Declared order and not the alternation's, because a message is read by the author
1212
+ who wrote the config and a reordering they did not make reads as a second list.
1213
+ """
1214
+ return "/".join(self.prefixes)
1215
+
1216
+ def _id_shape(self) -> str:
1217
+ """How a refusal spells this project's id, including what `[ids]` declared (RK106).
1218
+
1219
+ Derived, because the alternative is a message naming the built-in shape at a
1220
+ project whose own config legalised another — which is a refusal that reads as a
1221
+ bug in the tool and gets the config edited back.
1222
+ """
1223
+ shape = (
1224
+ f"{self._families()}<n> with no leading zero"
1225
+ if self.id_pad == 1
1226
+ else f"{self._families()}<n> zero-filled to {self.id_pad} digits"
1227
+ )
1228
+ return shape + (", plus at most one lowercase letter" if self.id_suffix else "")
1229
+
1230
+ @property
1231
+ def is_ledger(self) -> bool:
1232
+ """This is the ledger's configuration — the one file whose own status is ✅.
1233
+
1234
+ Named because two things read it and "shipped_allowed" only implies it: the marker
1235
+ that may be absent is the ledger's (RK43), and so is the advice a reject gives.
1236
+ """
1237
+ return self.shipped_allowed
1238
+
1239
+ def as_ledger(self) -> Schema:
1240
+ """The same format as the changelog reads it (L6, applied to a sibling file).
1241
+
1242
+ Marker ✅ or 🗑, no deps, no pointer — the rationale section is deleted when the
1243
+ task leaves, so a pointer to it could not resolve. One schema with two
1244
+ configurations beats two grammars that drift apart, and a retired line (RK32) is
1245
+ the same grammar again rather than a third: a departure with a different door.
1246
+
1247
+ Two slots are the part a project can drop, both declared in `[ledger]`: the marker
1248
+ (RK43), because a ledger where every entry shipped says so once in the file rather
1249
+ than on every line, and the symptom (RK48), because `- **T1** — <prose>` is what a
1250
+ ledger written before this tool already spells — and on a shipped line the split
1251
+ between the fault and its outcome has no reader left.
1252
+
1253
+ The body is :meth:`under` since RK1064, applied to a declaration rather than
1254
+ written out: this method is now the *name* of that grammar and no longer a second
1255
+ statement of it, which is what lets a project override the shape as it already
1256
+ overrides the numbers.
1257
+ """
1258
+ return self.under(DEFAULT_GRAMMARS["changelog"])
1259
+
1260
+ @property
1261
+ def is_deferred(self) -> bool:
1262
+ """This is the deferred store's configuration — the one file whose status is ⏸."""
1263
+ return self.deferred_allowed
1264
+
1265
+ def as_deferred(self) -> Schema:
1266
+ """The same format as the deferred store reads it (RK96, L6 again).
1267
+
1268
+ The roadmap's shape with one marker swapped, and nothing else dropped. One marker,
1269
+ because the file *is* the state: a store that could also hold 📋 would be a second
1270
+ roadmap, and two files that both say a task is open eventually disagree about which
1271
+ one it is. Everything else stays, and that is what separates a pause from the
1272
+ ledger's two departures — the id every dependent names, the deps that are still
1273
+ deps, the symptom, and the `→ §id` pointer whose section is carried rather than
1274
+ deleted. :meth:`as_ledger` drops all three because a shipped line has no design and
1275
+ no blocker left; a deferred one has both, and a return that had to reinvent them
1276
+ would be a re-add under a new id.
1277
+ """
1278
+ return self.under(DEFAULT_GRAMMARS["deferred"])
1279
+
1280
+ def under(self, declared: Grammar) -> Schema:
1281
+ """This format as one role's declaration shapes it (RK1064).
1282
+
1283
+ The one place a :class:`Grammar` becomes a schema, so a role's shape is applied by
1284
+ the same code whether the tool shipped the declaration or a project wrote it —
1285
+ which is the whole of what makes the shape configurable rather than merely named.
1286
+
1287
+ `[ledger]`'s two keys survive as what they always were: `marker` and `symptom` are
1288
+ the slots *that* file may drop, so they join `drop` here rather than staying a
1289
+ second mechanism beside it. A role whose declaration says nothing gets the base
1290
+ shape, which is a roadmap line — the honest default for a file nobody has spoken
1291
+ about, and the reason `extends` is carried rather than assumed.
1292
+ """
1293
+ dropped = set(declared.drop)
1294
+ if declared.states == "shipped":
1295
+ # The two `[ledger]` already declares, folded into the same set rather than
1296
+ # kept as their own arguments: they are droppable fields and the file that may
1297
+ # drop them is this one, so a second spelling would be what RK1064 removes.
1298
+ dropped.update(
1299
+ name
1300
+ for name, kept in (
1301
+ ("marker", self.ledger_marker),
1302
+ ("symptom", self.ledger_symptom),
1303
+ )
1304
+ if not kept
1305
+ )
1306
+ changed: dict[str, object] = {DROPPABLE[name]: False for name in dropped}
1307
+ if declared.markers:
1308
+ changed["markers"] = tuple(
1309
+ getattr(self, MARKER_NAMES[name]) for name in declared.markers
1310
+ )
1311
+ if declared.states:
1312
+ changed[f"{declared.states}_allowed"] = True
1313
+ return replace(self, **changed)
1314
+
1315
+ def needs_design(self, status: str) -> bool:
1316
+ """Whether a line carrying this marker still has its design to write (RK83).
1317
+
1318
+ A method rather than a comparison at the call site for the reason every other
1319
+ marker question is one: which codepoint means "idea" is `[markers] undesigned` and
1320
+ never a constant a query hardcoded. A ledger or deferred schema answers False for
1321
+ its own markers by the same rule, which is right — neither file is picked from.
1322
+ """
1323
+ return status in self.undesigned
1324
+
1325
+ def marks(self, status: str) -> bool:
1326
+ """Whether a line carrying this status writes the marker slot at all (RK43, RK125).
1327
+
1328
+ True everywhere except the ledger a project declared markerless — and there too for
1329
+ the one status that file cannot state about itself. `[ledger] marker = false` says
1330
+ *every entry in this file shipped*, which is exactly why the one that did not has to
1331
+ say so on its own line: there is no other slot for a departure, and a file whose
1332
+ lines carry no marker has nothing for this one to be inconsistent with.
1333
+
1334
+ That is what keeps `retire` a door on an adopting project (RK125). The alternative
1335
+ reachable before this was `ship` with an outcome saying the work was decided against
1336
+ — a ✅ over work nobody did, which is the lie `marker = false` was declared to
1337
+ prevent — and the two are not interchangeable to this tool either: `Backlog.retired`
1338
+ and the projected status block both read the marker, so a retirement recorded without
1339
+ one is *counted as a shipment*.
1340
+ """
1341
+ return self.marker_field or (self.is_ledger and status == self.retired_marker)
1342
+
1343
+ @property
1344
+ def dep_markers(self) -> tuple[str, ...]:
1345
+ """The statuses a dep annotation may cache (RK8) — the open set, ✅ and ⏸.
1346
+
1347
+ Derived from the target's status, so what a file may *hold* and what an annotation
1348
+ may *say* are the same list or the re-derivation writes a line the gate then
1349
+ refuses (RK96). 🗑 is not among them for the one reason that is not symmetry: a
1350
+ retired target leaves no line to derive from, and the dep on it is unresolvable
1351
+ rather than annotated (RK28).
1352
+ """
1353
+ return tuple(
1354
+ dict.fromkeys((*self.markers, self.shipped_marker, self.deferred_marker))
1355
+ )
1356
+
1357
+ # -- rendering ---------------------------------------------------------
1358
+
1359
+ def render(self, task: Task) -> str:
1360
+ """The canonical line. The only writer of this format.
1361
+
1362
+ `lint`'s comparison, `add`'s output and the round-trip test all read the
1363
+ line from here, so "canonical" is a fact about one function rather than a
1364
+ claim in a document.
1365
+
1366
+ Composed from :data:`TEMPLATE` since RK1063, which is the same sequence the parser
1367
+ matches against: a slot rendered here that no slot reads back is not a bug this can
1368
+ have any more, it is a line the template cannot state. What the loop cannot express
1369
+ stays outside it — the indentation is the *line's* and not the format's (RK49), read
1370
+ off the file and written back unchanged, and the pointer is split off before the
1371
+ grammar runs (`document._split_ref`), so both bracket the loop rather than joining it.
1372
+ """
1373
+ # The leading space belongs to the dash; every slot after the head carries its own
1374
+ # separator, exactly as its pattern does, so writing the line is a concatenation.
1375
+ line = task.indent + "- " + "".join(
1376
+ slot.writes(self, task) for slot in TEMPLATE if slot.present(self)
1377
+ )
1378
+ if task.ref:
1379
+ # In the id scheme the pointer is *derived*, not echoed: a line carrying
1380
+ # the wrong anchor stops round-tripping instead of being preserved, which
1381
+ # is what makes the anchor impossible to get wrong rather than merely
1382
+ # discouraged.
1383
+ anchor = task.id if self.ref_scheme == "id" else task.ref
1384
+ line += f" {ARROW} §{anchor}"
1385
+ return line
1386
+
1387
+ # -- validation --------------------------------------------------------
1388
+
1389
+ def id_pattern(self) -> re.Pattern[str]:
1390
+ """Ids are ``<prefix><n>``, non-contiguous, and spelled as this project spells them.
1391
+
1392
+ Unpadded by default, because ``RK01`` and ``RK1`` would otherwise be two spellings
1393
+ of one id and the next-id maximum (RK4) is taken over these strings. A project that
1394
+ pads *every* line has already answered that, and says so as `[ids] pad` (RK106) —
1395
+ as it says `[ids] suffix` for the sub-letter a split task carries. Every declared
1396
+ family matches (RK74): a backlog that numbers by track is one backlog, so `C14` and
1397
+ `V05` are both ids of it and a dep from one to the other is an ordinary dep.
1398
+ """
1399
+ return re.compile(rf"^{self.id_fragment}$")
1400
+
1401
+ def ids_named(self, text: str) -> tuple[str, ...]:
1402
+ """Every id of this project written **inside** a string, in order (RK389).
1403
+
1404
+ :meth:`id_pattern` answers *is this an id*, which is the question every other reader
1405
+ has. This one answers *does this mention one*, and it exists for the dep arm that
1406
+ matches nothing: `RK5 + RK7` is not an id, not a block and not a range, so it is
1407
+ accepted as work outside the backlog — a statement about two ids that are in it.
1408
+
1409
+ Bounded on both sides by an alphanumeric lookaround rather than `\\b`, because an id
1410
+ ends in a digit and `\\b` would find `RK5` inside `RK55`. The same reason
1411
+ :attr:`id_fragment` exists at all: a spelling only some readers know is how a number
1412
+ gets counted twice.
1413
+ """
1414
+ pattern = rf"(?<![A-Za-z0-9]){self.id_fragment}(?![A-Za-z0-9])"
1415
+ return tuple(match.group() for match in re.finditer(pattern, text))
1416
+
1417
+ @staticmethod
1418
+ def _spell_ids(ids: Sequence[str]) -> str:
1419
+ """`RK5`, or `RK5 and RK7`, or `2 ids (RK5, RK7, …)` — a refusal names what it read."""
1420
+ if len(ids) == 1:
1421
+ return ids[0]
1422
+ if len(ids) == 2:
1423
+ return f"{ids[0]} and {ids[1]}"
1424
+ return f"{len(ids)} ids ({', '.join(ids)})"
1425
+
1426
+ def split_id_pattern(self) -> re.Pattern[str]:
1427
+ """The ids :meth:`spell_id` cannot reach: the same shape with the letter **required**.
1428
+
1429
+ :meth:`id_pattern` admits the sub-letter where `[ids] suffix` declares one, because a
1430
+ line may carry it. This one demands it, which makes the two patterns exactly the ids
1431
+ the counter derives and the ids it never will — and the second set is the whole reason
1432
+ a caller is ever allowed to *choose* an id instead (RK111).
1433
+
1434
+ Matches nothing where no suffix is declared, which is the honest answer rather than a
1435
+ second code path: there, every legal id is one the counter produces. Spelled as an
1436
+ empty character class rather than an empty lookahead, because this string is handed to
1437
+ a client to validate against and the class is the form every regex engine reads.
1438
+ """
1439
+ if not self.id_suffix:
1440
+ return re.compile(r"[^\s\S]")
1441
+ return re.compile(rf"^{self._fragment(named=False, sub_required=True)}$")
1442
+
1443
+ def prose_budget(self, task: Task) -> int:
1444
+ """How many characters this line's prose fields have between them (RK183).
1445
+
1446
+ The line limit minus what the line costs before a word is written: the dash, the
1447
+ marker, the bold id, the `(deps: …)` group, the em dash and the `→ §<id>` pointer.
1448
+ Measured by rendering the line with both fields emptied rather than by adding up a
1449
+ second copy of the format — :meth:`render` is the only writer of it (L3), and a
1450
+ constant here would be a second one that drifts the first time a slot moves.
1451
+
1452
+ Everything it needs is known before the prose exists: `add` derives the id, the
1453
+ marker, the deps and the pointer, so the budget is a fact about the line the author
1454
+ is *about* to write rather than a verdict on one they already wrote.
1455
+ """
1456
+ return self.line_max - width(self.render(replace(task, symptom="", why="")))
1457
+
1458
+ def why_budget(self, task: Task) -> int:
1459
+ """The smaller of the `why`'s own limit and what this line has left for it (RK183).
1460
+
1461
+ `symptom_max` plus `why_max` is at or over `line_max` on every default this ships
1462
+ and on both live corpora, so an author writing to the two published numbers is
1463
+ refused by the third — one that is measured on a string they never write and whose
1464
+ overhead moves with the dep count. The `why` is where the remainder is taken from
1465
+ because it is the field whose overflow has somewhere to go: the rationale section
1466
+ the line already points at. The symptom is the claim the line *is*, and compressing
1467
+ it is how a falsifiable line becomes a slogan.
1468
+
1469
+ A symptom over its own limit is reported as itself and takes no room from the
1470
+ `why`: deriving a remainder from an illegal field would refuse one sentence for
1471
+ another field's overrun, and the author would fix twice what was wrong once.
1472
+ """
1473
+ taken = width(task.symptom) if self.symptom_field else 0
1474
+ if taken > self.symptom_max:
1475
+ return self.why_max
1476
+ return min(self.why_max, max(0, self.prose_budget(task) - taken))
1477
+
1478
+ def validate(self, task: Task) -> tuple[Violation, ...]:
1479
+ """Every violation, in field order. Empty means the task conforms."""
1480
+ out: list[Violation] = []
1481
+ out.extend(self._check_identity(task))
1482
+ out.extend(self._check_deps(task))
1483
+ out.extend(self._check_requires(task))
1484
+ out.extend(self._check_symptom(task))
1485
+ out.extend(self._check_why(task))
1486
+ out.extend(self._check_ref(task))
1487
+
1488
+ rendered = self.render(task)
1489
+ # The backstop, and only that (RK183): where a field's own budget already carries
1490
+ # the line's limit, the same overrun reported twice is one defect with two numbers
1491
+ # and the author cutting both. What is left for this to catch is an overrun no
1492
+ # field explains — a line whose *structure* does not fit, which no prose edit fixes.
1493
+ # Which is why this one asks for no word figure (RK243): the hint is aimed at a
1494
+ # sentence, and the clause after it says a sentence is not what is over.
1495
+ if width(rendered) > self.line_max and not any(
1496
+ violation.code in _LENGTH_CODES for violation in out
1497
+ ):
1498
+ out.append(
1499
+ Violation(
1500
+ "line.too-long",
1501
+ "line",
1502
+ f"the rendered line is "
1503
+ f"{over_by(width(rendered), self.line_max, measured=rendered, prose=False, source=self.source_of('line_max'))}; "
1504
+ f"no field is over the budget this line left it, so what does "
1505
+ f"not fit is the structure around them",
1506
+ )
1507
+ )
1508
+ return tuple(out)
1509
+
1510
+ def _check_identity(self, task: Task) -> list[Violation]:
1511
+ out: list[Violation] = []
1512
+ if not self.id_pattern().match(task.id):
1513
+ out.append(
1514
+ Violation(
1515
+ "id.format",
1516
+ "id",
1517
+ f"expected {self._id_shape()}, got {task.id!r}",
1518
+ )
1519
+ )
1520
+ out.extend(self._check_part(task))
1521
+ if not self.marks(task.status) and task.status != self.shipped_marker:
1522
+ # A markerless ledger states one status for the whole file, so every marker but
1523
+ # the departure it cannot state is unwritable there: an open line filed as
1524
+ # shipped work would read as shipped and no slot would say otherwise. 🗑 is the
1525
+ # exception `marks` carries (RK125) — it writes the marker on that line alone.
1526
+ out.append(
1527
+ Violation(
1528
+ "status.unrepresentable",
1529
+ "status",
1530
+ f"this project declares a ledger with no marker "
1531
+ f"([ledger] marker = false), so {task.status!r} cannot be told from "
1532
+ f"{self.shipped_marker}: only {self.retired_marker} carries a marker "
1533
+ f"there, a departure being the one status the file does not state",
1534
+ )
1535
+ )
1536
+ elif task.status == self.shipped_marker and not self.shipped_allowed:
1537
+ out.append(
1538
+ Violation(
1539
+ "status.shipped",
1540
+ "status",
1541
+ f"{self.shipped_marker} belongs in the changelog, not the roadmap",
1542
+ )
1543
+ )
1544
+ elif task.status not in self.markers:
1545
+ out.append(
1546
+ Violation(
1547
+ "status.unknown",
1548
+ "status",
1549
+ f"{task.status!r} is not one of {' '.join(self.markers)}",
1550
+ )
1551
+ )
1552
+ if not task.block:
1553
+ # Shio keeps a "## Priority queue" section above its blocks; a task
1554
+ # parked there has no block, and inferring one would file it under
1555
+ # whatever heading happened to precede it.
1556
+ out.append(
1557
+ Violation(
1558
+ "block.missing", "block", "a task line lives under a block heading"
1559
+ )
1560
+ )
1561
+ elif not _BLOCK_RE.match(task.block):
1562
+ out.append(
1563
+ Violation("block.format", "block", f"not a block label: {task.block!r}")
1564
+ )
1565
+ return out
1566
+
1567
+ def _check_part(self, task: Task) -> list[Violation]:
1568
+ """A partial entry's qualifier: legal in the ledger, and nowhere else (RK121).
1569
+
1570
+ Refused on a roadmap line because the roadmap already has a word for work in
1571
+ halves — ⏳, an open marker — and a line that said it twice would be two places to
1572
+ read the same claim. The ledger is where the statement is new: *this much of it is
1573
+ done*, which an entry could not previously make without leaving the grammar.
1574
+ """
1575
+ if task.part is None:
1576
+ return []
1577
+ if not self.is_ledger:
1578
+ return [
1579
+ Violation(
1580
+ "part.unexpected",
1581
+ "id",
1582
+ f"({task.part}) qualifies a partial entry and this is not the ledger: "
1583
+ f"an open line says the same thing with a marker",
1584
+ )
1585
+ ]
1586
+ if not task.part.strip() or task.part != task.part.strip():
1587
+ return [
1588
+ Violation(
1589
+ "part.blank", "id", f"the qualifier is not a phrase: {task.part!r}"
1590
+ )
1591
+ ]
1592
+ if width(task.part) > self.part_max:
1593
+ return [
1594
+ Violation(
1595
+ "part.too-long",
1596
+ "id",
1597
+ f"the qualifier is "
1598
+ f"{over_by(width(task.part), self.part_max, measured=task.part, source=self.source_of('part_max'))}; "
1599
+ f"it names which half, it is not the why",
1600
+ )
1601
+ ]
1602
+ return []
1603
+
1604
+ def classify_dep(self, dep: Dep) -> DepKind:
1605
+ """What this dep names — a task, a block, a range, or work outside the backlog.
1606
+
1607
+ Ordered so that neither a mistake nor a resolvable dep can hide as external:
1608
+ `Block P` first, then a range, then anything id-shaped (valid or not), and
1609
+ only what none of those match is external.
1610
+ """
1611
+ if self.block_dep_pattern().match(dep.id):
1612
+ return DepKind.BLOCK
1613
+ if self.range_of_dep(dep) is not None:
1614
+ return DepKind.RANGE
1615
+ if _ID_SHAPE_RE.match(dep.id):
1616
+ return DepKind.TASK
1617
+ return DepKind.EXTERNAL
1618
+
1619
+ def block_of_dep(self, dep: Dep) -> str | None:
1620
+ """The block label a block dep names, or None if it names something else."""
1621
+ match = self.block_dep_pattern().match(dep.id)
1622
+ return match.group(1) if match else None
1623
+
1624
+ def range_of_dep(self, dep: Dep) -> tuple[int, int] | None:
1625
+ """The inclusive `(first, last)` a range dep names, or None.
1626
+
1627
+ Both `T451–T457` and `T451–457` occur in the wild, and the dash may be a
1628
+ hyphen or an en dash. A descending range is not a range: it is returned as
1629
+ None so the token falls through and gets reported instead of resolved.
1630
+
1631
+ Both ends are the *same* family: `C14–V05` spans two tracks that number
1632
+ independently, so the pair it names is not a range of anything (RK74).
1633
+ """
1634
+ match = self._range_match(dep)
1635
+ if not match:
1636
+ return None
1637
+ first, last = int(match.group(2)), int(match.group(3))
1638
+ return (first, last) if first <= last else None
1639
+
1640
+ def family_of_dep(self, dep: Dep) -> str | None:
1641
+ """Which family a range dep counts in (RK74), or None if it names no range.
1642
+
1643
+ A range is bounded twice — by its numbers and by its track — and only the numbers
1644
+ used to be read, which was correct while `C14–C20` was the only kind of range a
1645
+ project could write. On a backlog that numbers six tracks it would also swallow
1646
+ `V15`, and a dep reported satisfied by work in another track is worse than one
1647
+ reported unresolvable.
1648
+ """
1649
+ match = self._range_match(dep)
1650
+ return match.group("family") if match else None
1651
+
1652
+ def _range_match(self, dep: Dep) -> re.Match[str] | None:
1653
+ # Both ends are spelled the way this project spells a number (RK106), so a padded
1654
+ # backlog's `D01–D09` is the range it reads as rather than a `deps.range` finding.
1655
+ # The sub-letter is not admitted here and nowhere else is it withheld: a range is
1656
+ # bounded by numbers, and `T24b` is a name for a task and not for a bound.
1657
+ families = self.prefix_alternation
1658
+ number = self.number_fragment
1659
+ pattern = re.compile(
1660
+ rf"^(?P<family>{families})({number})"
1661
+ rf"\s*[-–—]\s*(?P=family)?({number})$"
1662
+ )
1663
+ return pattern.match(dep.id)
1664
+
1665
+ def _unrenderable(self, task: Task) -> list[Violation]:
1666
+ """A dep whose text the line it is written into cannot carry back (RK1229).
1667
+
1668
+ Measured: `amend --dep "FreeWilly DD133 (Docker drops its pipe mid-build)"` was
1669
+ accepted and **written**. The deps group is `\\(deps: [^)]*\\)`, so the inner `)` closed
1670
+ it early, the grammar stopped reading the line, and `lint` reported `line.unparsed`
1671
+ with `section.orphan` beside it.
1672
+
1673
+ What makes that more than bad input is what came after. `amend`, `restate`, `retire`
1674
+ and `defer` all answered *nothing there carries that id* — correct, the grammar cannot
1675
+ read the line — `repair` listed both findings as decisions with no complete command,
1676
+ `--fix` names a control character as its one cause, and the guard denies the hand edit.
1677
+ **The tool wrote a state none of its verbs reaches and its own gate forbids repairing
1678
+ by hand.** The task was re-filed under a new id, spending one, and the line stayed.
1679
+
1680
+ Asked by **round-tripping the slot** and never by listing characters: the group is
1681
+ rendered and read back with the pattern that reads it, so a capture that differs is
1682
+ the defect whatever produced it. The arrow is the one thing that check cannot see —
1683
+ `document._split_ref` cuts the pointer off *before* the grammar runs, so a dep
1684
+ carrying one moves where the line ends — and it is asked separately for that reason.
1685
+
1686
+ The message names the characters rather than the arithmetic, because a caller holding
1687
+ a refusal wants to know which part of what they typed to change.
1688
+ """
1689
+ if not task.deps or not self.deps_field:
1690
+ return []
1691
+ # What the slot actually writes, `NO_DEPS` included: a caller clearing the group hands
1692
+ # over one empty dep, the join is `""`, and `_writes_deps` renders the em dash — so
1693
+ # comparing against the join alone reports the clear as unrenderable. Measured by
1694
+ # `test_amend_replaces_the_whole_dep_group` the moment this check existed.
1695
+ written = ", ".join(dep.render() for dep in task.deps) or NO_DEPS
1696
+ found = re.fullmatch(_reads_deps(True), _writes_deps(self, task))
1697
+ arrowed = [dep.render() for dep in task.deps if ARROW in dep.render()]
1698
+ if (found is not None and found.group("deps") == written) and not arrowed:
1699
+ return []
1700
+ named = [
1701
+ dep.render()
1702
+ for dep in task.deps
1703
+ if ")" in dep.render() or "(" in dep.render() or ARROW in dep.render()
1704
+ ] or [written]
1705
+ return [
1706
+ Violation(
1707
+ "deps.unrenderable",
1708
+ "deps",
1709
+ f"{', '.join(repr(one) for one in named)} cannot survive the line it is "
1710
+ f"written into: the deps group closes at the first ')' and the pointer is "
1711
+ f"split at the first '{ARROW}', so a line carrying this stops parsing and "
1712
+ f"no verb reaches it — put the parenthetical in the section, not the dep",
1713
+ )
1714
+ ]
1715
+
1716
+ def _check_requires(self, task: Task) -> list[Violation]:
1717
+ """Every requirement is one of this project's declared words (RK1297).
1718
+
1719
+ The rule L1 asks for: a token is refused **where the line is created**, so a
1720
+ requirement nobody can act on never reaches the file. An undeclared token is the
1721
+ interesting refusal and it is not a typo check — `pick` sets a line aside by
1722
+ matching these words against what the caller says it has, so a token no vocabulary
1723
+ carries would silence the line for every caller and be visible to none.
1724
+
1725
+ The vocabulary is empty by default, which is what makes the axis opt-in: a project
1726
+ that never declared one refuses the first requirement it is handed, and the message
1727
+ names the table rather than listing nothing.
1728
+ """
1729
+ out: list[Violation] = []
1730
+ seen: set[str] = set()
1731
+ for token in task.requires:
1732
+ if not token or token.strip() != token:
1733
+ out.append(
1734
+ Violation(
1735
+ "requires.format",
1736
+ "requires",
1737
+ f"{token!r} is not a requirement: the group is a comma-separated "
1738
+ f"list of declared words, and an empty one names nothing",
1739
+ )
1740
+ )
1741
+ elif any(char in token for char in "(),") or ARROW in token:
1742
+ # The deps group's rule one slot over, and the same failure: the group
1743
+ # closes at the first ')' and the pointer is split at the first arrow, so a
1744
+ # line carrying either stops parsing and no verb reaches it again.
1745
+ out.append(
1746
+ Violation(
1747
+ "requires.unrenderable",
1748
+ "requires",
1749
+ f"{token!r} cannot survive the line it is written into: the "
1750
+ f"requires group closes at the first ')', separates on ',' and the "
1751
+ f"pointer is split at the first '{ARROW}' — a requirement is one word",
1752
+ )
1753
+ )
1754
+ elif token not in self.requirements:
1755
+ out.append(
1756
+ Violation(
1757
+ "requires.unknown",
1758
+ "requires",
1759
+ f"{token!r} is not declared: `pick` sets a line aside by matching "
1760
+ f"these words against what a caller has, so an undeclared one "
1761
+ f"hides the line from everybody — {self._declared_requirements()}",
1762
+ )
1763
+ )
1764
+ if token in seen:
1765
+ out.append(
1766
+ Violation("requires.duplicate", "requires", f"{token!r} listed twice")
1767
+ )
1768
+ seen.add(token)
1769
+ return out
1770
+
1771
+ def _declared_requirements(self) -> str:
1772
+ """What `[requirements] declared` says, ready to print after a refusal."""
1773
+ if not self.requirements:
1774
+ return (
1775
+ "this project declares no [requirements], so the group has no vocabulary "
1776
+ "to draw on yet"
1777
+ )
1778
+ return f"[requirements] declared names {', '.join(self.requirements)}"
1779
+
1780
+ def _check_deps(self, task: Task) -> list[Violation]:
1781
+ if task.deps and not self.deps_field:
1782
+ return [
1783
+ Violation(
1784
+ "deps.unexpected",
1785
+ "deps",
1786
+ "this file carries no deps field: a shipped line has no "
1787
+ "dependency left to state",
1788
+ )
1789
+ ]
1790
+ out: list[Violation] = []
1791
+ out += self._unrenderable(task)
1792
+ ids = self.id_pattern()
1793
+ seen: set[str] = set()
1794
+ allowed = self.dep_markers
1795
+ for dep in task.deps:
1796
+ kind = self.classify_dep(dep)
1797
+ # An id-shaped token that is not an id of this project is a typo or a
1798
+ # paste from another backlog. Prose is not: real work waits on a whole
1799
+ # block, and on things that are not work at all (RK28).
1800
+ if kind is DepKind.TASK and not ids.match(dep.id):
1801
+ out.append(
1802
+ Violation(
1803
+ "deps.format", "deps", f"not an id of this project: {dep.id!r}"
1804
+ )
1805
+ )
1806
+ elif kind is not DepKind.RANGE and _RANGE_SHAPE_RE.match(dep.id):
1807
+ # It looks like a range and did not parse as one, so it would resolve
1808
+ # as "outside the backlog" — a false statement, not a missing one.
1809
+ out.append(
1810
+ Violation(
1811
+ "deps.range",
1812
+ "deps",
1813
+ f"{dep.id!r} reads as a range but does not ascend from a "
1814
+ f"{self._families()} id",
1815
+ )
1816
+ )
1817
+ elif kind is DepKind.EXTERNAL and (named := self.ids_named(dep.id)):
1818
+ # The same argument as the range above, one arm over (RK389): free text is
1819
+ # the arm nothing matches, so `RK5 + RK7` lands whole and resolves as
1820
+ # "outside the backlog: shipping cannot satisfy it" — about two ids that are
1821
+ # in the backlog, one of which may already have shipped.
1822
+ one = len(named) == 1
1823
+ out.append(
1824
+ Violation(
1825
+ "deps.compound",
1826
+ "deps",
1827
+ f"{dep.id!r} names {self._spell_ids(named)} of this project inside "
1828
+ f"work outside it: pass "
1829
+ f"{'it as its own dep' if one else 'a dep each'}, or spell the "
1830
+ f"external work without {'it' if one else 'them'}",
1831
+ )
1832
+ )
1833
+ if dep.marker is not None and dep.marker not in allowed:
1834
+ out.append(
1835
+ Violation(
1836
+ "deps.marker",
1837
+ "deps",
1838
+ f"{dep.marker!r} is not a status marker: a dep annotation "
1839
+ f"caches the target's status and nothing else",
1840
+ )
1841
+ )
1842
+ if dep.id == task.id:
1843
+ out.append(
1844
+ Violation("deps.self", "deps", f"{task.id} depends on itself")
1845
+ )
1846
+ if dep.id in seen:
1847
+ out.append(Violation("deps.duplicate", "deps", f"{dep.id} listed twice"))
1848
+ seen.add(dep.id)
1849
+ return out
1850
+
1851
+ def _check_symptom(self, task: Task) -> list[Violation]:
1852
+ if not self.symptom_field:
1853
+ # The slot does not exist in this file (RK48), so there is no field to judge
1854
+ # and an empty one is not a violation: `- **T1** — <prose>` is the whole line.
1855
+ return []
1856
+ out = self._check_text(
1857
+ "symptom", task.symptom, self.symptom_max, source=self.source_of("symptom_max")
1858
+ )
1859
+ if "**" in task.symptom:
1860
+ # Only the symptom reserves '**': it is what closes the field. Bold
1861
+ # inside a `why` round-trips (25 of Shio's lines use it), and grading
1862
+ # emphasis in someone's sentence is prose-grading, which is not the
1863
+ # tool's job (L4).
1864
+ out.append(
1865
+ Violation(
1866
+ "symptom.markup",
1867
+ "symptom",
1868
+ "'**' closes the symptom and cannot appear inside it",
1869
+ )
1870
+ )
1871
+ if task.symptom.strip().endswith(_TERMINATORS):
1872
+ out.append(
1873
+ Violation(
1874
+ "symptom.sentence",
1875
+ "symptom",
1876
+ "symptom is a phrase naming what does not work, not a sentence: "
1877
+ "drop the terminating punctuation",
1878
+ )
1879
+ )
1880
+ return out
1881
+
1882
+ def _check_why(self, task: Task) -> list[Violation]:
1883
+ # The author's half and never the derived wrapper, on the one file that carries one
1884
+ # (RK1115). The limit is what a *sentence* may cost — every other derived part of a
1885
+ # line, the annotation and the pointer, is charged to nobody — and charging this one
1886
+ # made "written to the budget" and "can be paused" mutually exclusive: the 14-character
1887
+ # prefix alone overflowed pportal's limit before a reason existed, so the only doors
1888
+ # left to a line that was neither shipped nor abandoned were the two terminal ones.
1889
+ # The whole line is still bounded: `line.too-long` measures what is rendered, and on a
1890
+ # paused line the structure around the prose is exactly what it names.
1891
+ measured = authored_why(task.why) if self.is_deferred else task.why
1892
+ budget = self.why_budget(task)
1893
+ because = ""
1894
+ if budget < self.why_max:
1895
+ # Said only where the two differ, and then it is the whole explanation: the
1896
+ # number the author was given is not the number that refused them, and which
1897
+ # line they are writing is why (RK183).
1898
+ taken = width(task.symptom) if self.symptom_field else 0
1899
+ because = (
1900
+ f" (the line's own limit of {self.line_max} leaves "
1901
+ f"{self.prose_budget(task)} for prose, and the symptom takes {taken})"
1902
+ )
1903
+ out = self._check_text(
1904
+ "why",
1905
+ task.why,
1906
+ budget,
1907
+ because,
1908
+ source=self.source_of("why_max"),
1909
+ charged=measured,
1910
+ )
1911
+ why = measured.strip()
1912
+ if why and self.terminator and not why.endswith(_TERMINATORS):
1913
+ out.append(
1914
+ Violation(
1915
+ "why.no-terminator",
1916
+ "why",
1917
+ f"why is a sentence: end it{_costs_a_character(measured, budget)}",
1918
+ )
1919
+ )
1920
+ if self.one_sentence and _sentence_count(why) > 1:
1921
+ out.append(
1922
+ Violation(
1923
+ "why.sentences",
1924
+ "why",
1925
+ "why is one sentence; a second sentence is the signal that it "
1926
+ "belongs in the improvements section this line points at",
1927
+ )
1928
+ )
1929
+ return out
1930
+
1931
+ def _check_ref(self, task: Task) -> list[Violation]:
1932
+ if not task.ref:
1933
+ if self.ref_required:
1934
+ return [
1935
+ Violation(
1936
+ "ref.missing", "ref", "every task points at its rationale section"
1937
+ )
1938
+ ]
1939
+ return []
1940
+ if task.ref.startswith("§"):
1941
+ return [
1942
+ Violation(
1943
+ "ref.sigil", "ref", f"store the anchor without §: {task.ref.lstrip('§')!r}"
1944
+ )
1945
+ ]
1946
+ if self.ref_scheme == "id":
1947
+ if task.ref != task.id:
1948
+ return [
1949
+ Violation(
1950
+ "ref.mismatch",
1951
+ "ref",
1952
+ f"the pointer is the task's own id ({task.id}), derived on "
1953
+ f"render; {task.ref!r} names a section chosen by hand",
1954
+ )
1955
+ ]
1956
+ return []
1957
+ # The namespace a project may put in front of an address (RK340). Checked for shape
1958
+ # and never for membership: which prefixes exist is `[refs]`, and a line naming one
1959
+ # this project does not declare is a pointer at nothing — `ref.unresolved`, reported
1960
+ # by the gate against the files, rather than a format violation about a legal
1961
+ # spelling. The roadmap's own schema carries no prefix and could not answer anyway.
1962
+ prefix, bare = split_ref(task.ref)
1963
+ if prefix and not REF_PREFIX_RE.match(prefix):
1964
+ return [
1965
+ Violation(
1966
+ "ref.format",
1967
+ "ref",
1968
+ f"not a <prefix>:<x.y> anchor: {task.ref!r} — a namespace is one word "
1969
+ f"of letters and digits, starting with a letter",
1970
+ )
1971
+ ]
1972
+ if not OUTLINE_ANCHOR_RE.match(bare):
1973
+ return [Violation("ref.format", "ref", f"not an <x.y> anchor: {task.ref!r}")]
1974
+ return []
1975
+
1976
+ def check(self, task: Task) -> Task:
1977
+ """Return the task, or raise :class:`SchemaError` with every violation."""
1978
+ violations = self.validate(task)
1979
+ if violations:
1980
+ raise SchemaError(violations)
1981
+ return task
1982
+
1983
+ def _check_text(
1984
+ self,
1985
+ field: str,
1986
+ value: str,
1987
+ limit: int,
1988
+ because: str = "",
1989
+ source: str = "",
1990
+ charged: str | None = None,
1991
+ ) -> list[Violation]:
1992
+ """The checks that apply to both prose fields, including round-trip safety.
1993
+
1994
+ ``source`` is which declaration set `limit`, passed by the caller for the reason
1995
+ :func:`over_by` takes one (RK1067): this method is handed a number and only the
1996
+ caller knows which field's it is.
1997
+
1998
+ ``charged`` is the part of ``value`` the *limit* applies to, where a file wraps the
1999
+ field in something derived (RK1115). Only the limit: every other check here is about
2000
+ text this tool must not accept at all — a control character in the wrapper is as
2001
+ unrenderable as one in the sentence — so relaxing them with the number would let a
2002
+ `defer --reason` smuggle in the codepoints an author is refused for.
2003
+ """
2004
+ measured = value if charged is None else charged
2005
+ out: list[Violation] = []
2006
+ if not value.strip():
2007
+ out.append(Violation(f"{field}.empty", field, "must not be empty"))
2008
+ return out
2009
+ # A control character that is **not** a plain line break is never authorial (RK407).
2010
+ # Every field this tool refuses is prose composed in a shell, and one shell rewrites
2011
+ # it on the way in: PowerShell reads a backtick as its escape character, so a `why`
2012
+ # quoting `renderItem` arrives carrying a carriage return the author never typed and
2013
+ # cannot see in the answer. Reported as `newline` that was accurate about the value
2014
+ # and wrong about the cause — and the cause is the half a caller has to fix, so the
2015
+ # message sent them to re-read a sentence that was already correct.
2016
+ stray = _control(value)
2017
+ if stray:
2018
+ where, char = stray[0]
2019
+ out.append(
2020
+ Violation(
2021
+ f"{field}.control",
2022
+ field,
2023
+ f"{_named_codepoint(char)} at position {where + 1}, which nothing types "
2024
+ f"on purpose: in a PowerShell double-quoted string a backtick is the "
2025
+ f"escape character, so prose quoting an identifier becomes this — pass "
2026
+ f"the field on stdin with `-` and no shell rewrites it",
2027
+ )
2028
+ )
2029
+ elif "\n" in value or "\r" in value:
2030
+ out.append(
2031
+ Violation(
2032
+ f"{field}.newline",
2033
+ field,
2034
+ "a task is one line: no newlines — and if you typed none, a PowerShell "
2035
+ "double-quoted string expands `` `n ``; `-` reads the field from stdin",
2036
+ )
2037
+ )
2038
+ if value != value.strip():
2039
+ out.append(
2040
+ Violation(
2041
+ f"{field}.whitespace",
2042
+ field,
2043
+ "leading or trailing whitespace (refused, not trimmed: the tool "
2044
+ "does not silently rewrite text it did not author)",
2045
+ )
2046
+ )
2047
+ out += _codepoints(field, value)
2048
+ if width(measured) > limit:
2049
+ out.append(
2050
+ Violation(
2051
+ f"{field}.too-long",
2052
+ field,
2053
+ over_by(
2054
+ width(measured),
2055
+ limit,
2056
+ because=because,
2057
+ measured=measured,
2058
+ source=source,
2059
+ )
2060
+ + ELSEWHERE,
2061
+ )
2062
+ )
2063
+ return out
2064
+
2065
+
2066
+ def _codepoints(field: str, value: str) -> list[Violation]:
2067
+ """A tab, an invisible codepoint or a space that is not one, refused at the door (RK499).
2068
+
2069
+ :func:`suspect` is the whole rule and it is the gate's own, one function down — so a
2070
+ caller filtering on `char.tab` filters the same defect whether `add` refused it or
2071
+ `lint` found it, which is what :class:`~roadkeep.linting.Finding` already promises about
2072
+ every code the two surfaces share.
2073
+
2074
+ Measured by RK498's register: these were three of the five findings a write accepted.
2075
+ Every prose door took them — `add --why`, `amend --why`, `restate --symptom`, `record
2076
+ add --why` — while the *same field* refused a leading or trailing space and said so, so
2077
+ one whitespace rule held at the door and the neighbouring one did not.
2078
+
2079
+ **Refused rather than repaired, and RK407's note beside `_control` used to argue the
2080
+ other way**: that the format normalizes a tab, so refusing one here would refuse at the
2081
+ door what the gate repairs. That conflates two files. `--fix` is the backstop for text
2082
+ this tool did not write — an imported backlog, a hand edit, a merge — and it stays that;
2083
+ what a *door* accepts is L1, and the three differ in what the fixer would do anyway: it
2084
+ replaces a tab, deletes a format character, and **leaves a `Zs` alone**, because turning
2085
+ one into a space is a change to text only the author may make. That last one is a gate
2086
+ finding no command clears, which is precisely the state RK146 called the one that teaches
2087
+ a reader to stop reading the report.
2088
+
2089
+ The **first** one only, for :func:`_control`'s reason: one mis-pasted paragraph carries
2090
+ several and the first already sends the reader to the cause.
2091
+
2092
+ ``indent=False`` throughout: a field is not a line, so it has no indentation for a tab to
2093
+ be text in. That span exists in the file and never in the argument.
2094
+ """
2095
+ for at, char in enumerate(value):
2096
+ # A C0 control is `_control`'s, whose message names the shell escape that wrote it —
2097
+ # the better diagnosis of the two. The tab is the one it hands over.
2098
+ if not suspect(char) or (char != TAB and ord(char) < 0x20):
2099
+ continue
2100
+ code, because = CODEPOINT_KINDS[codepoint_kind(char)]
2101
+ return [
2102
+ Violation(
2103
+ code,
2104
+ field,
2105
+ f"{_named_codepoint(char)} at position {at + 1}: {because} — pass the "
2106
+ f"field on stdin with `-`, where nothing rewrites it",
2107
+ )
2108
+ ]
2109
+ return []
2110
+
2111
+
2112
+ def codepoint_kind(char: str) -> str:
2113
+ """Which of the three codepoint findings this one is (RK499).
2114
+
2115
+ Public because :func:`~roadkeep.linting._named` asks it too: the gate names a column and
2116
+ the door names a position in an argument, and everything else about the answer — the
2117
+ code and the clause saying what is wrong — is one fact that may not have two spellings
2118
+ depending on which surface met the character.
2119
+ """
2120
+ if char == TAB:
2121
+ return "tab"
2122
+ return "space" if unicodedata.category(char) == "Zs" else "invisible"
2123
+
2124
+
2125
+ #: What each of the three is wrong about, in the gate's own words (RK34): name the byte, not
2126
+ #: its consequence. A tab is visible and still wrong; a `Zs` renders as a space and compares
2127
+ #: unequal to one; everything else cannot be seen at all.
2128
+ CODEPOINT_KINDS = {
2129
+ "tab": (
2130
+ "char.tab",
2131
+ "the format separates fields with a space, so a tab is a separator the grammar "
2132
+ "reads as part of a field",
2133
+ ),
2134
+ "space": (
2135
+ "char.space",
2136
+ "it renders as a space and is not one, so the grammar reads a word where a "
2137
+ "separator was meant",
2138
+ ),
2139
+ "invisible": (
2140
+ "char.invisible",
2141
+ "invisible in an editor, so every other diagnosis of this line would name the "
2142
+ "consequence instead",
2143
+ ),
2144
+ }
2145
+
2146
+
2147
+ def _costs_a_character(text: str, budget: int) -> str:
2148
+ """What ending this sentence costs, where there is no room for it (RK1255).
2149
+
2150
+ The pair that costs two round trips for one sentence, and the second of them is knowable
2151
+ at the first. A `why` at exactly its limit and unterminated is refused for the terminator;
2152
+ the caller adds the character the refusal asked for and is refused again, now one over.
2153
+ Reproduced against `ship`: 200 of 200 unterminated, then 201 of 200.
2154
+
2155
+ Nothing about what is accepted changes. The **length** rule is unmoved — the text as sent
2156
+ is not over, and a violation on it would be this tool refusing a sentence nobody wrote.
2157
+ What changes is that the refusal for the rule that *is* broken states the cost of obeying
2158
+ it, which the same call already has every number for.
2159
+
2160
+ Silent where there is room, which is almost always: this fires at the limit and past it,
2161
+ so it is a clause on a refusal already being printed rather than a sentence every caller
2162
+ reads (RK16).
2163
+ """
2164
+ room = budget - width(text.rstrip())
2165
+ if room > 0:
2166
+ return ""
2167
+ # Said where the text is already **over** too, and not only at the boundary: a caller
2168
+ # told to delete five, who deletes five and stops, lands exactly at the limit and meets
2169
+ # this refusal on the next call — the same two round trips, one step later. So the number
2170
+ # here is the whole cut, and it is stated as superseding the one beside it rather than
2171
+ # sitting next to it as a second answer.
2172
+ needed = 1 - room
2173
+ plural = "" if needed == 1 else "s"
2174
+ return (
2175
+ f", and there is no room for it: cut {needed} character{plural} in all — "
2176
+ f"the text is {width(text.rstrip())} of {budget}, and one of them is the terminator"
2177
+ )
2178
+
2179
+
2180
+ def _sentence_count(text: str) -> int:
2181
+ """Sentences in a stripped one-line field, ignoring known abbreviations."""
2182
+ count = 1 if text else 0
2183
+ for match in _SENTENCE_BREAK_RE.finditer(text):
2184
+ token = text[: match.start() + 1].split()[-1].lower()
2185
+ if token in _ABBREVIATIONS or len(token) == 2 and token[0].isalpha():
2186
+ continue # "e.g. ", "A. Oliveira" — a period, not a boundary
2187
+ count += 1
2188
+ return count
2189
+
2190
+
2191
+ #: Variation selectors, which are `Mn` and not a format category: invisible all the same,
2192
+ #: and the class the parser already had to defend against (`_looks_like_marker`, RK2).
2193
+ _VARIATION_SELECTORS = frozenset(
2194
+ chr(point) for point in (*range(0xFE00, 0xFE10), *range(0xE0100, 0xE01F0))
2195
+ )
2196
+
2197
+
2198
+ def suspect(char: str, *, indent: bool = False) -> bool:
2199
+ """Is this codepoint invisible, or a space that is not the space?
2200
+
2201
+ Defined by Unicode category rather than a hand-kept list, so a control or format
2202
+ character nobody has met yet is caught too: `Cc` and `Cf` are not text, `Zl` and `Zp`
2203
+ are line breaks inside a line, and a `Zs` other than U+0020 renders as a space while
2204
+ comparing unequal to one. Variation selectors are `Mn` and named explicitly — U+FE0F
2205
+ on a marker is the case the parser already had to defend against (RK2).
2206
+
2207
+ `indent` is where the one control character that **renders** stops being suspect at all
2208
+ (RK146). A tab is `Cc`, so this reported it as "invisible in an editor", which of a tab
2209
+ is untrue — and RK126 rightly withheld it from `--fix`, because the indentation of a
2210
+ nested line is read off the file and written back verbatim (RK49). Two correct decisions
2211
+ left a project that indents with tabs holding a finding no command could ever clear,
2212
+ which is what teaches a reader to stop reading the report. In the indentation a tab is
2213
+ text; past it, it is a separator where this format writes a space, and :func:`_named`
2214
+ says so instead.
2215
+ """
2216
+ if char in _VARIATION_SELECTORS:
2217
+ return True
2218
+ if char == TAB:
2219
+ return not indent
2220
+ # **U+0000 is not a character an author produced** (RK454). It is `Cc` and would be
2221
+ # caught below, but RK118 wrote every byte of a governed file and none was ever one — so
2222
+ # a NUL is a lost write, `within` states it once about the file, and reporting it here
2223
+ # too was the same loss counted a second time per byte, under a code whose `--fix`
2224
+ # claims it and changes nothing.
2225
+ if char == "\x00":
2226
+ return False
2227
+ category = unicodedata.category(char)
2228
+ return category in ("Cc", "Cf", "Zl", "Zp") or (category == "Zs" and char != " ")
2229
+
2230
+
2231
+ #: What a line may be indented with, and the span :func:`suspect` reads a tab as text in.
2232
+ _INDENT = " " + TAB
2233
+
2234
+
2235
+ def indentation(body: str) -> int:
2236
+ """How many leading characters of this line are its indentation, tabs included.
2237
+
2238
+ One reading, shared by the gate and the fixer, because a tab is text in this span and a
2239
+ separator past it — and two functions deciding where the span ends is one pair that
2240
+ would disagree about a line somebody nested (RK146).
2241
+ """
2242
+ return len(body) - len(body.lstrip(_INDENT))
2243
+
2244
+
2245
+ def repaired(char: str, *, indent: bool = False) -> str | None:
2246
+ """What `--fix` writes in place of a suspect codepoint, or None to leave it (RK126).
2247
+
2248
+ :func:`suspect` is what the gate reports; this is what a normalizer may act on, and the
2249
+ split is RK16's own: a control or format character is **not text under any reading**, so
2250
+ removing it is not a decision about anybody's prose — while a `Zs` that is not U+0020
2251
+ *renders* as a space, and turning one into a space is a change to text that the author
2252
+ is the one to make.
2253
+
2254
+ A tab is the case that needs the position (RK146): inside the indentation it is left
2255
+ alone, because deleting it re-parents somebody's task, and past it the repair is a
2256
+ **space** rather than a deletion — the format writes one there, and removing the
2257
+ separator would glue two fields into a line that no longer parses.
2258
+
2259
+ Here rather than in :mod:`roadkeep.fixing` because it is the same law as the report one
2260
+ function up, and a second list of codepoints is the one that would drift.
2261
+ """
2262
+ if char == TAB:
2263
+ return None if indent else " "
2264
+ if char in _VARIATION_SELECTORS:
2265
+ return ""
2266
+ if unicodedata.category(char) in ("Cc", "Cf", "Zl", "Zp"):
2267
+ return ""
2268
+ return None
2269
+
2270
+
2271
+ def _control(value: str) -> list[tuple[int, str]]:
2272
+ """Every control character in a prose field that is not part of a line break (RK407).
2273
+
2274
+ A line feed is excluded, and so is the carriage return **of a CRLF pair**: a pasted
2275
+ paragraph produces both honestly, and `{field}.newline` is already the right answer
2276
+ there. A *lone* carriage return is not that — it is what PowerShell writes for `` `r ``,
2277
+ which is what a `why` quoting an identifier like `renderItem` becomes — so it belongs
2278
+ here with the bell, the form feed, the escape and the NUL: characters that arrive from a
2279
+ shell or from nowhere, and never from an author.
2280
+
2281
+ A tab is excluded for a different reason: this format normalizes one rather than refusing
2282
+ it (`char.tab` is `--fix`'s), so reporting it as unauthorial here would refuse at the
2283
+ door what the gate one file over repairs.
2284
+
2285
+ The **first** one only, because the report is read to act on: a `why` mangled by one
2286
+ stray backtick carries one, and a sentence carrying six is six symptoms of a single
2287
+ quoting mistake that the first already sends the reader to.
2288
+ """
2289
+ out: list[tuple[int, str]] = []
2290
+ for at, char in enumerate(value):
2291
+ if char in (LINE_FEED, TAB):
2292
+ continue
2293
+ if char == CARRIAGE_RETURN and value[at + 1 : at + 2] == LINE_FEED:
2294
+ continue
2295
+ if ord(char) < 0x20 or ord(char) == 0x7F:
2296
+ out.append((at, char))
2297
+ return out
2298
+
2299
+
2300
+ def _named_codepoint(char: str) -> str:
2301
+ """`U+000D CARRIAGE RETURN (`` `r ``)`, naming the escape that most likely wrote it."""
2302
+ named, escape = _C0_NAMES.get(char, ("", ""))
2303
+ if not named:
2304
+ import unicodedata # noqa: PLC0415 - one refusal path, never a successful write
2305
+
2306
+ named = unicodedata.name(char, "")
2307
+ spelled = f"U+{ord(char):04X}" + (f" {named}" if named else "")
2308
+ return spelled + (f" (`` {escape} ``)" if escape else "")