roadkeep 0.2.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- roadkeep/__init__.py +79 -0
- roadkeep/adopting.py +2347 -0
- roadkeep/attesting.py +293 -0
- roadkeep/authoring.py +2117 -0
- roadkeep/backlog.py +767 -0
- roadkeep/blocking.py +1622 -0
- roadkeep/briefing.py +970 -0
- roadkeep/budgeting.py +2056 -0
- roadkeep/capturing.py +1699 -0
- roadkeep/claiming.py +1019 -0
- roadkeep/cli.py +638 -0
- roadkeep/commanding.py +487 -0
- roadkeep/config.py +1832 -0
- roadkeep/counting.py +376 -0
- roadkeep/criteria.py +933 -0
- roadkeep/deferring.py +708 -0
- roadkeep/describing.py +568 -0
- roadkeep/exporting.py +808 -0
- roadkeep/fixing.py +629 -0
- roadkeep/governing.py +934 -0
- roadkeep/graph.py +395 -0
- roadkeep/guarding.py +1028 -0
- roadkeep/history.py +2403 -0
- roadkeep/ids.py +301 -0
- roadkeep/installing.py +2145 -0
- roadkeep/kernel/__init__.py +24 -0
- roadkeep/kernel/document.py +1719 -0
- roadkeep/kernel/schema.py +2308 -0
- roadkeep/linting.py +4420 -0
- roadkeep/locking.py +209 -0
- roadkeep/markers.py +172 -0
- roadkeep/merging.py +1159 -0
- roadkeep/picking.py +772 -0
- roadkeep/provenance.py +789 -0
- roadkeep/queueing.py +752 -0
- roadkeep/ranking.py +139 -0
- roadkeep/referring.py +231 -0
- roadkeep/remaining.py +336 -0
- roadkeep/remedying.py +1989 -0
- roadkeep/rendering.py +1601 -0
- roadkeep/renumbering.py +503 -0
- roadkeep/repairing.py +295 -0
- roadkeep/reverting.py +144 -0
- roadkeep/scoping.py +708 -0
- roadkeep/screening.py +196 -0
- roadkeep/sections.py +4121 -0
- roadkeep/serving.py +2909 -0
- roadkeep/shipping.py +3993 -0
- roadkeep/showing.py +613 -0
- roadkeep/storing.py +224 -0
- roadkeep/verbs/__init__.py +26 -0
- roadkeep/verbs/adopting.py +974 -0
- roadkeep/verbs/authoring.py +566 -0
- roadkeep/verbs/declaring.py +335 -0
- roadkeep/verbs/linting.py +645 -0
- roadkeep/verbs/querying.py +2138 -0
- roadkeep/verbs/reading.py +307 -0
- roadkeep/verbs/refusing.py +146 -0
- roadkeep/verbs/sections.py +1433 -0
- roadkeep/verbs/shipping.py +819 -0
- roadkeep/weighing.py +380 -0
- roadkeep-0.2.0.dist-info/METADATA +453 -0
- roadkeep-0.2.0.dist-info/RECORD +67 -0
- roadkeep-0.2.0.dist-info/WHEEL +5 -0
- roadkeep-0.2.0.dist-info/entry_points.txt +2 -0
- roadkeep-0.2.0.dist-info/licenses/LICENSE +202 -0
- roadkeep-0.2.0.dist-info/top_level.txt +1 -0
|
@@ -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 "")
|