roadkeep 0.2.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- roadkeep/__init__.py +79 -0
- roadkeep/adopting.py +2347 -0
- roadkeep/attesting.py +293 -0
- roadkeep/authoring.py +2117 -0
- roadkeep/backlog.py +767 -0
- roadkeep/blocking.py +1622 -0
- roadkeep/briefing.py +970 -0
- roadkeep/budgeting.py +2056 -0
- roadkeep/capturing.py +1699 -0
- roadkeep/claiming.py +1019 -0
- roadkeep/cli.py +638 -0
- roadkeep/commanding.py +487 -0
- roadkeep/config.py +1832 -0
- roadkeep/counting.py +376 -0
- roadkeep/criteria.py +933 -0
- roadkeep/deferring.py +708 -0
- roadkeep/describing.py +568 -0
- roadkeep/exporting.py +808 -0
- roadkeep/fixing.py +629 -0
- roadkeep/governing.py +934 -0
- roadkeep/graph.py +395 -0
- roadkeep/guarding.py +1028 -0
- roadkeep/history.py +2403 -0
- roadkeep/ids.py +301 -0
- roadkeep/installing.py +2145 -0
- roadkeep/kernel/__init__.py +24 -0
- roadkeep/kernel/document.py +1719 -0
- roadkeep/kernel/schema.py +2308 -0
- roadkeep/linting.py +4420 -0
- roadkeep/locking.py +209 -0
- roadkeep/markers.py +172 -0
- roadkeep/merging.py +1159 -0
- roadkeep/picking.py +772 -0
- roadkeep/provenance.py +789 -0
- roadkeep/queueing.py +752 -0
- roadkeep/ranking.py +139 -0
- roadkeep/referring.py +231 -0
- roadkeep/remaining.py +336 -0
- roadkeep/remedying.py +1989 -0
- roadkeep/rendering.py +1601 -0
- roadkeep/renumbering.py +503 -0
- roadkeep/repairing.py +295 -0
- roadkeep/reverting.py +144 -0
- roadkeep/scoping.py +708 -0
- roadkeep/screening.py +196 -0
- roadkeep/sections.py +4121 -0
- roadkeep/serving.py +2909 -0
- roadkeep/shipping.py +3993 -0
- roadkeep/showing.py +613 -0
- roadkeep/storing.py +224 -0
- roadkeep/verbs/__init__.py +26 -0
- roadkeep/verbs/adopting.py +974 -0
- roadkeep/verbs/authoring.py +566 -0
- roadkeep/verbs/declaring.py +335 -0
- roadkeep/verbs/linting.py +645 -0
- roadkeep/verbs/querying.py +2138 -0
- roadkeep/verbs/reading.py +307 -0
- roadkeep/verbs/refusing.py +146 -0
- roadkeep/verbs/sections.py +1433 -0
- roadkeep/verbs/shipping.py +819 -0
- roadkeep/weighing.py +380 -0
- roadkeep-0.2.0.dist-info/METADATA +453 -0
- roadkeep-0.2.0.dist-info/RECORD +67 -0
- roadkeep-0.2.0.dist-info/WHEEL +5 -0
- roadkeep-0.2.0.dist-info/entry_points.txt +2 -0
- roadkeep-0.2.0.dist-info/licenses/LICENSE +202 -0
- roadkeep-0.2.0.dist-info/top_level.txt +1 -0
roadkeep/linting.py
ADDED
|
@@ -0,0 +1,4420 @@
|
|
|
1
|
+
"""The gate: every governed line, validated where nothing else was watching (RK14).
|
|
2
|
+
|
|
3
|
+
`add` refuses a field at the moment it is typed (L1), which is where the saving is — but
|
|
4
|
+
a file also drifts by the paths `add` does not own: a hand edit, a merge that resolved
|
|
5
|
+
into a half-line, a `roadkeep.toml` limit lowered after the lines were written. So this
|
|
6
|
+
is the backstop, and the one thing that makes it a gate rather than advice is the exit
|
|
7
|
+
code: **exit 1 when anything drifted**, so a pre-commit hook and an Action (RK17) can
|
|
8
|
+
both call the same command and neither has to parse a report.
|
|
9
|
+
|
|
10
|
+
It re-validates rather than re-implements. Every rule read here comes from
|
|
11
|
+
:meth:`Schema.validate`, every line from :class:`Document`, every dep resolution from
|
|
12
|
+
:mod:`roadkeep.backlog` — a linter with its own regexes over prose would be a second
|
|
13
|
+
statement of the format, and the two would disagree in the direction nobody tests.
|
|
14
|
+
|
|
15
|
+
What it reports, and why each one is a defect the other commands cannot see:
|
|
16
|
+
|
|
17
|
+
* **A schema violation** on a line that exists — the limit that was raised after the
|
|
18
|
+
line was written, or the line that never went through `add`.
|
|
19
|
+
* **A line that does not round-trip** (L3). Reported and never repaired: normalizing a
|
|
20
|
+
line the parser may have misread is the corruption the whole invariant exists to
|
|
21
|
+
prevent, so what this prints is the canonical rendering and the fix stays a human's.
|
|
22
|
+
* **A marker-bearing bullet the grammar rejected** — the silent miss `audit` (RK10)
|
|
23
|
+
prints at exit 0. `audit` reports; this fails.
|
|
24
|
+
* **One id in two places** — twice in one file, or in both the roadmap and the ledger.
|
|
25
|
+
Two lines carrying one id is two answers to "is this done?", and nothing says which.
|
|
26
|
+
* **A dep nothing can satisfy** — an id in neither file (a typo, or a line deleted by
|
|
27
|
+
hand), a dep on a task that was retired (RK32: the record says the work will not
|
|
28
|
+
happen, so the dependent line is the author's next edit), or `Block X` where no
|
|
29
|
+
heading declares X (RK37). An *external* dep is not a finding: real work waits on
|
|
30
|
+
things this backlog does not track, and Turing writes them on purpose.
|
|
31
|
+
* **A stale `(deps: … ✅)` annotation** — derived on every write (RK8), so a divergence
|
|
32
|
+
here means the file was edited by something that is not this tool.
|
|
33
|
+
* **A cycle** — three tasks waiting on each other are three tasks nothing can start
|
|
34
|
+
(RK13), which is a defect and not a shape.
|
|
35
|
+
* **A queue entry naming work that has left** (RK326) — the same resolution, applied to
|
|
36
|
+
the one list that outranks the id order: shipped, retired, set aside, naming nothing,
|
|
37
|
+
or naming a block whose every line has left or been set aside. Written as deps, most already
|
|
38
|
+
failed here; written as a priority they passed at exit 0 while `pick` said only that
|
|
39
|
+
the queue "names nothing ready".
|
|
40
|
+
|
|
41
|
+
And the same question asked of the prose file, which is RK15's half: **a pointer that
|
|
42
|
+
resolves to nothing reads exactly like a design that exists**, which is worse than no
|
|
43
|
+
pointer because it makes a reader stop looking. So the `→ §RK<n>` is resolved against
|
|
44
|
+
the improvements file, in both directions — a pointer with no section, and a section no
|
|
45
|
+
line points at — plus the section's word budget and the paths a line claims. The
|
|
46
|
+
pointer is read from the parsed ``ref`` field and never from the line's text: §RK15's
|
|
47
|
+
own `why` quotes a pointer as an example, and a scan over the line would report that
|
|
48
|
+
quotation as the broken pointer it is not. And once from the prose end alone (RK239): two
|
|
49
|
+
files declaring one anchor is a defect at both headings whether or not a line reached it.
|
|
50
|
+
|
|
51
|
+
And the one block the tool writes **outside** a governed file: a projection of the backlog
|
|
52
|
+
is derived rather than restated (RK39), and nothing held the derivation to the files it came
|
|
53
|
+
from — so a commit that ships a task and forgets `export` left a README contradicting the
|
|
54
|
+
ledger, caught here by a pytest fixture an adopting project does not install (RK104). The
|
|
55
|
+
markers are the author's declaration, so a file carrying none is silent; a file carrying them
|
|
56
|
+
is spliced in memory and compared, and a difference is one finding naming the command.
|
|
57
|
+
|
|
58
|
+
And one file the tool never writes: **an always-loaded instruction file has a budget, and
|
|
59
|
+
a budget stated in its own prose is what let Shio's `agents.md` reach 186 KB** while
|
|
60
|
+
declaring 150 lines at the bottom of itself (RK30). So `roadkeep.toml` declares it and the
|
|
61
|
+
exit code holds it, in lines and in bytes — the two units the reader actually pays.
|
|
62
|
+
|
|
63
|
+
**Two tiers, because the exit code is the contract.** A :class:`Finding` fails the build;
|
|
64
|
+
a :class:`Note` is something the gate says at exit 0. Both exist because two real defects
|
|
65
|
+
cannot be refused without failing an honest file: `Block P` is a legitimate dep that
|
|
66
|
+
happens to name forty-eight open tasks (RK35), and a rationale section edited without its
|
|
67
|
+
task line is the shape of a smuggled requirement *and* of a typo fix (RK36). Refusing
|
|
68
|
+
either would produce a gate that gets bypassed, which is worth less than a sentence read
|
|
69
|
+
at the moment of the commit — the same split `audit` (RK10) makes.
|
|
70
|
+
|
|
71
|
+
Everything above is decidable from the files as they are. The checks that are about a
|
|
72
|
+
*change* are opt-in through ``since``, because `lint` has to keep working in a checkout with
|
|
73
|
+
no history: `--since HEAD` in a commit hook, the base branch in CI. The second of them is a
|
|
74
|
+
block this commit **emptied or reopened** (RK269) — the transition `ship` computes, states
|
|
75
|
+
once to a console and records nowhere, which is what left a project's derived per-block index
|
|
76
|
+
claiming a finished block was active while `lint` called the tree clean four times running.
|
|
77
|
+
|
|
78
|
+
**And one question the absolute count cannot answer: did this change make it worse (RK84).**
|
|
79
|
+
An adopting project arrives with history — one live corpus lints at 317 problems, none of
|
|
80
|
+
them the current change's — so the gate cannot be wired to its CI, and the number moving by
|
|
81
|
+
one or two per task carries no signal. ``baseline`` reads the governed files *at a revision*,
|
|
82
|
+
runs everything above over those, and reports only the excess: what this working tree added,
|
|
83
|
+
with the standing debt named and forgiven. It exits non-zero on the difference alone, which
|
|
84
|
+
is the shape that lets a repository adopt the gate before it has paid the debt off. Two
|
|
85
|
+
things it deliberately does **not** vary: the configuration, because a limit is the ruler and
|
|
86
|
+
not the thing measured, and the repository, because what a baseline run stashes is the three
|
|
87
|
+
files — which is what the hand procedure it replaces did, four commands at a time.
|
|
88
|
+
|
|
89
|
+
What is deliberately *not* here: normalizing what is mechanical, which is a write and lives
|
|
90
|
+
in :mod:`roadkeep.fixing` (RK16). This module answers one question completely and never
|
|
91
|
+
writes: *is every line in the governed files a line this format accepts, does everything it
|
|
92
|
+
points at exist, and did anything loaded every turn outgrow what it was allowed?*
|
|
93
|
+
"""
|
|
94
|
+
|
|
95
|
+
from __future__ import annotations
|
|
96
|
+
|
|
97
|
+
import os
|
|
98
|
+
import re
|
|
99
|
+
import unicodedata
|
|
100
|
+
import functools
|
|
101
|
+
from collections.abc import Callable, Sequence
|
|
102
|
+
from typing import Any
|
|
103
|
+
from dataclasses import dataclass, field, replace
|
|
104
|
+
from pathlib import Path
|
|
105
|
+
|
|
106
|
+
from roadkeep import criteria, queueing, scoping
|
|
107
|
+
from roadkeep.backlog import Backlog, DepStatus, Stage, id_order
|
|
108
|
+
from roadkeep.blocking import removable
|
|
109
|
+
from roadkeep.config import LINE_ROLES as _LINE_ROLES
|
|
110
|
+
from roadkeep.config import PROSE_ROLES, ROLES, Config, spent, translated
|
|
111
|
+
from roadkeep.kernel.document import Document, Entry, Heading, ending
|
|
112
|
+
from roadkeep.exporting import (
|
|
113
|
+
BEGIN,
|
|
114
|
+
DEFAULTS,
|
|
115
|
+
NoMarkers,
|
|
116
|
+
enclosing,
|
|
117
|
+
project,
|
|
118
|
+
splice,
|
|
119
|
+
target_of,
|
|
120
|
+
)
|
|
121
|
+
from roadkeep.graph import Graph
|
|
122
|
+
from roadkeep.history import (
|
|
123
|
+
HistoryUnavailable,
|
|
124
|
+
check_ignore,
|
|
125
|
+
blob_at,
|
|
126
|
+
content_at,
|
|
127
|
+
resolves,
|
|
128
|
+
touched_since,
|
|
129
|
+
tracked_at,
|
|
130
|
+
tracked_now,
|
|
131
|
+
)
|
|
132
|
+
from roadkeep.markers import derive
|
|
133
|
+
from roadkeep.referring import PAIRS
|
|
134
|
+
from roadkeep.kernel.schema import (
|
|
135
|
+
CODEPOINT_KINDS,
|
|
136
|
+
TAB,
|
|
137
|
+
Dep,
|
|
138
|
+
DepKind,
|
|
139
|
+
Task,
|
|
140
|
+
codepoint_kind,
|
|
141
|
+
indentation,
|
|
142
|
+
over_by,
|
|
143
|
+
suspect,
|
|
144
|
+
)
|
|
145
|
+
from roadkeep.sections import Section, anchored, find, references
|
|
146
|
+
from roadkeep.sections import owners as section_owners
|
|
147
|
+
from roadkeep.showing import known_directories, on_disk, paths_in
|
|
148
|
+
from roadkeep.provenance import invocation
|
|
149
|
+
|
|
150
|
+
#: The governed files whose unit is a task line. The prose files are paragraphs, so
|
|
151
|
+
#: their gate is a pointer and a budget — RK15 and RK30, not this. The deferred store is
|
|
152
|
+
#: one of them (RK96): a line set aside is still a line, and a store nothing gated would
|
|
153
|
+
#: be the one place the format is a convention again.
|
|
154
|
+
#: "Nobody has asked yet", which None cannot say here: None is the answer meaning "git
|
|
155
|
+
#: could not tell us", and the two have to be different things (RK217).
|
|
156
|
+
_UNASKED = object()
|
|
157
|
+
|
|
158
|
+
#: `decisions` is the fourth (RK1269), and for the store's own argument: a decision record is
|
|
159
|
+
#: a line, so a file this gate did not read would be the one place the format is a convention
|
|
160
|
+
#: again — which is precisely what an ADR kept by hand already was.
|
|
161
|
+
#:
|
|
162
|
+
#: Declared in `config` since RK1361 and re-exported here, where every reader of it already
|
|
163
|
+
#: looks: that role is now a prose file too, so "not a prose role" stopped deriving this set
|
|
164
|
+
#: and `govern` needed the same four. One authority, two importers.
|
|
165
|
+
LINE_ROLES = _LINE_ROLES
|
|
166
|
+
|
|
167
|
+
#: The two whose lines are still alive, so their rationale section is still there: open
|
|
168
|
+
#: work, and work set aside (RK96). The ledger is not among them — `ship` and `retire`
|
|
169
|
+
#: delete the section in the transaction that writes the entry.
|
|
170
|
+
LIVE_ROLES = ("roadmap", "deferred")
|
|
171
|
+
|
|
172
|
+
#: The codes both surfaces raise, where this file's own scan is the better half (RK499). The
|
|
173
|
+
#: schema refuses these at the door, naming a position inside the argument the caller retypes;
|
|
174
|
+
#: `_characters` finds them anywhere in the file, naming the line and the column. One defect,
|
|
175
|
+
#: two readings, and the gate prints the one addressed to a reader of the file.
|
|
176
|
+
_SCANNED = frozenset({"char.tab", "char.space", "char.invisible"})
|
|
177
|
+
|
|
178
|
+
_ENDING_NAMES = {"\r\n": "CRLF", "\n": "LF", "\r": "CR"}
|
|
179
|
+
|
|
180
|
+
|
|
181
|
+
@dataclass(frozen=True, slots=True)
|
|
182
|
+
class Finding:
|
|
183
|
+
"""One defect, at one place. ``code`` is stable; ``message`` names the fix.
|
|
184
|
+
|
|
185
|
+
The code is the same string :class:`~roadkeep.kernel.schema.Violation` uses where the
|
|
186
|
+
finding came from the schema, so a caller filtering on `why.sentences` filters the
|
|
187
|
+
same rule whether it was refused at `add` or found here.
|
|
188
|
+
"""
|
|
189
|
+
|
|
190
|
+
code: str
|
|
191
|
+
file: str
|
|
192
|
+
message: str
|
|
193
|
+
#: 1-based, as an editor counts. ``None`` when the finding is about the file itself.
|
|
194
|
+
lineno: int | None = None
|
|
195
|
+
id: str = ""
|
|
196
|
+
#: 1-based column, for a finding about one character (RK34). An invisible codepoint
|
|
197
|
+
#: cannot be found by eye, so the offset is half of what makes the report usable.
|
|
198
|
+
column: int | None = None
|
|
199
|
+
#: What the remedy is *about*, where that is not the id and not printable as a prefix
|
|
200
|
+
#: (RK420). `id` already doubles as the subject on most codes — a block label, a section
|
|
201
|
+
#: anchor — because it is printed in front of the message and reads correctly there. A
|
|
202
|
+
#: queue token does not: the message opens `queues RK12, …`, so putting it in `id` would
|
|
203
|
+
#: render `RK12: queues RK12`. Last field, so every positional call site still means what
|
|
204
|
+
#: it did.
|
|
205
|
+
subject: str = ""
|
|
206
|
+
#: What this finding has in common with its siblings, where a whole group of them is one
|
|
207
|
+
#: fact and one edit (RK469). Empty on every code but the one that needed it: a report
|
|
208
|
+
#: whose bulk is one sentence repeated is one a reader learns to skip (RK146), and it
|
|
209
|
+
#: buries the findings that are each about a different line.
|
|
210
|
+
#:
|
|
211
|
+
#: Declared by the **emitter**, which is the only place that knows what is shared —
|
|
212
|
+
#: string surgery on the message would be a second reading of a sentence this file
|
|
213
|
+
#: composes. Read only by the terminal report: `--json` keeps one entry per address,
|
|
214
|
+
#: because a consumer acting per address needs the line, and the count that follows the
|
|
215
|
+
#: findings is about addresses either way.
|
|
216
|
+
shared: str = ""
|
|
217
|
+
#: The file this finding is *about*, where that is not the file it is filed against
|
|
218
|
+
#: (RK1070). One code needs it: `grammar.unreadable` lands on `roadkeep.toml`, because
|
|
219
|
+
#: the declaration that broke the file is there and so is the edit (RK1067), and it
|
|
220
|
+
#: explains every per-line failure in the file it names. Two addresses and not one —
|
|
221
|
+
#: `file` is where a reader clicks, `about` is what the finding covers — because
|
|
222
|
+
#: conflating them is how a suppression silences the wrong file.
|
|
223
|
+
about: str = ""
|
|
224
|
+
|
|
225
|
+
@property
|
|
226
|
+
def token(self) -> str:
|
|
227
|
+
"""What a remedy substitutes: the explicit subject, or the id it usually is."""
|
|
228
|
+
return self.subject or self.id
|
|
229
|
+
|
|
230
|
+
@property
|
|
231
|
+
def where(self) -> str:
|
|
232
|
+
if self.lineno is None:
|
|
233
|
+
return self.file
|
|
234
|
+
if self.column is None:
|
|
235
|
+
return f"{self.file}:{self.lineno}"
|
|
236
|
+
return f"{self.file}:{self.lineno}:{self.column}"
|
|
237
|
+
|
|
238
|
+
def __str__(self) -> str:
|
|
239
|
+
subject = f"{self.id}: " if self.id else ""
|
|
240
|
+
return f"{self.where} {self.code} {subject}{self.message}"
|
|
241
|
+
|
|
242
|
+
|
|
243
|
+
@dataclass(frozen=True, slots=True)
|
|
244
|
+
class Note:
|
|
245
|
+
"""Something the gate says and does not fail on (RK35).
|
|
246
|
+
|
|
247
|
+
A separate list from :class:`Finding` because the exit code is the contract: `Block P`
|
|
248
|
+
is a legitimate dep (RK28) and failing a build over one would fail the honest backlog
|
|
249
|
+
this tool was measured against. But it is one token naming forty-eight open tasks, and
|
|
250
|
+
a reader counting deps to judge how blocked a line is has no way to see that from the
|
|
251
|
+
line — so the expansion is stated, at exit 0, which is the same split `audit` (RK10)
|
|
252
|
+
makes between reporting a miss and being the gate.
|
|
253
|
+
"""
|
|
254
|
+
|
|
255
|
+
code: str
|
|
256
|
+
file: str
|
|
257
|
+
message: str
|
|
258
|
+
lineno: int | None = None
|
|
259
|
+
id: str = ""
|
|
260
|
+
#: The same field :class:`Finding` grew for the same reason (RK420): a note carries a
|
|
261
|
+
#: remedy too, and the thing it is about is not always printable in front of a message.
|
|
262
|
+
subject: str = ""
|
|
263
|
+
|
|
264
|
+
@property
|
|
265
|
+
def token(self) -> str:
|
|
266
|
+
return self.subject or self.id
|
|
267
|
+
|
|
268
|
+
def __str__(self) -> str:
|
|
269
|
+
where = self.file if self.lineno is None else f"{self.file}:{self.lineno}"
|
|
270
|
+
subject = f"{self.id}: " if self.id else ""
|
|
271
|
+
return f"{where} {self.code} {subject}{self.message}"
|
|
272
|
+
|
|
273
|
+
|
|
274
|
+
@dataclass(slots=True)
|
|
275
|
+
class Tree:
|
|
276
|
+
"""Where one run reads the governed files from: this working tree, or a revision (RK84).
|
|
277
|
+
|
|
278
|
+
Every disk touch a run makes on a file it *governs* goes through here, which is the whole
|
|
279
|
+
of how a baseline is taken — the documents, the budgeted files, and whether a declared
|
|
280
|
+
file is there at all. What does not go through here is the rest of the repository: a
|
|
281
|
+
baseline varies the three files and holds the code constant, because that is the question
|
|
282
|
+
being asked, and because resolving a whole tree would make the comparison a checkout.
|
|
283
|
+
|
|
284
|
+
Bytes, and not text: a governed file is compared to its own rendering byte for byte (L3)
|
|
285
|
+
and a budget is spent in them (RK30), so a revision read through newline translation
|
|
286
|
+
would answer both wrongly.
|
|
287
|
+
"""
|
|
288
|
+
|
|
289
|
+
config: Config
|
|
290
|
+
#: ``None`` for the working tree — the run every other command makes.
|
|
291
|
+
rev: str | None = None
|
|
292
|
+
#: The revision's paths, read once and only if something asks (`ls-tree` is not free).
|
|
293
|
+
_names: frozenset[str] | None = field(default=None, repr=False)
|
|
294
|
+
#: One read per file: `_absent` asks whether it is there and everything else asks what
|
|
295
|
+
#: is in it, which at a revision is two subprocesses for one answer.
|
|
296
|
+
_blobs: dict[Path, bytes | None] = field(default_factory=dict, repr=False)
|
|
297
|
+
#: Every tail of every tracked path, built once (RK173). Unbuilt until something asks,
|
|
298
|
+
#: because only one check needs it and a `ls-files` per run of `show` would be a cost
|
|
299
|
+
#: paid by the callers that never ask about an artefact at all.
|
|
300
|
+
_tails: frozenset[str] | None = field(default=None, repr=False)
|
|
301
|
+
#: What the repository declared untracked, per token (RK213, keyed by RK219). A dict
|
|
302
|
+
#: and not a set-of-the-first-answer: the key is the question, so a second caller — or
|
|
303
|
+
#: a second pass — is answered about what it asked rather than about what came first.
|
|
304
|
+
_ignored: dict[str, bool] = field(default_factory=dict, repr=False)
|
|
305
|
+
#: The directories a path claim is decided against (RK217), or None where git could not
|
|
306
|
+
#: say — a sentinel rather than None-means-unasked, because None is itself the answer.
|
|
307
|
+
_directories: frozenset[str] | None | object = field(default=_UNASKED, repr=False)
|
|
308
|
+
#: The root as a normalised string, so the constant half of a spelling is built once.
|
|
309
|
+
_root: str | None = field(default=None, repr=False)
|
|
310
|
+
|
|
311
|
+
def document(self, role: str) -> Document | None:
|
|
312
|
+
"""One governed file under its role's schema, or ``None`` when this tree lacks it."""
|
|
313
|
+
if not self.config.has(role):
|
|
314
|
+
return None
|
|
315
|
+
if self.rev is None:
|
|
316
|
+
path = self.config.path(role)
|
|
317
|
+
return self.config.document(role) if path.is_file() else None
|
|
318
|
+
raw = self.blob(self.config.path(role))
|
|
319
|
+
if raw is None:
|
|
320
|
+
return None
|
|
321
|
+
# Deliberately parsed without its path: a document of how a file *was* must not be
|
|
322
|
+
# one call away from being saved over the file as it is.
|
|
323
|
+
return Document.parse(
|
|
324
|
+
raw.decode("utf-8", errors="replace"), schema=self.config.schema_for(role)
|
|
325
|
+
)
|
|
326
|
+
|
|
327
|
+
def blob(self, path: Path) -> bytes | None:
|
|
328
|
+
if path in self._blobs:
|
|
329
|
+
return self._blobs[path]
|
|
330
|
+
if self.rev is not None:
|
|
331
|
+
found = blob_at(self.config, self.rev, path)
|
|
332
|
+
else:
|
|
333
|
+
found = path.read_bytes() if path.is_file() else None
|
|
334
|
+
self._blobs[path] = found
|
|
335
|
+
return found
|
|
336
|
+
|
|
337
|
+
def present(self, path: Path) -> bool:
|
|
338
|
+
"""Whether this tree carried the file at all, without reading one to find out."""
|
|
339
|
+
return path.is_file() if self.rev is None else self.blob(path) is not None
|
|
340
|
+
|
|
341
|
+
def carries(self, token: str, near: Path) -> bool:
|
|
342
|
+
"""Did this tree have the artefact a line names, under either convention (RK51)?
|
|
343
|
+
|
|
344
|
+
Asked only of a revision, and only to *withhold* a `path.missing` the baseline should
|
|
345
|
+
never have credited: a file that was there at the ref and is not here now was deleted
|
|
346
|
+
by this change, and forgiving that would forgive the one true finding this check has
|
|
347
|
+
produced on a live corpus — a class the ledger still names under the directory it was
|
|
348
|
+
renamed inside.
|
|
349
|
+
"""
|
|
350
|
+
if self.rev is None:
|
|
351
|
+
return False
|
|
352
|
+
return any(spelling in self.listing() for spelling in self.spellings(token, near))
|
|
353
|
+
|
|
354
|
+
def declared_untracked(self, tokens: Sequence[tuple[str, Path]]) -> frozenset[str]:
|
|
355
|
+
"""Which tokens name a path the repository has declared it will never track (RK213).
|
|
356
|
+
|
|
357
|
+
The next shape along from RK173's widening, and the one an adopter hit first. Claude
|
|
358
|
+
Code Tray's ledger names `bin/Release/net10.0-windows/win-x64/ClaudeTray.exe` while
|
|
359
|
+
explaining why its CI builds rather than publishes — a correct sentence about where
|
|
360
|
+
the build output lands. `bin/` is the first line of its `.gitignore`, and its
|
|
361
|
+
roadkeep job is `checkout` then the action, so `lint` exited 1 on every push and 0
|
|
362
|
+
on the machine of anyone who had just compiled. Invisible locally, and in CI the
|
|
363
|
+
only finding, so the job was simply red.
|
|
364
|
+
|
|
365
|
+
**Asked of git, not of a list.** A table of `bin/`, `dist/`, `target/`, `build/`
|
|
366
|
+
here would be convention where the repository already has a declaration (L6), and
|
|
367
|
+
it would be wrong for the project that tracks its `dist/` on purpose.
|
|
368
|
+
`check-ignore` reads the same `.gitignore`, `.git/info/exclude` and core.excludesFile
|
|
369
|
+
the developer's own `git status` reads, so the tool and the author cannot disagree
|
|
370
|
+
about what this repository tracks.
|
|
371
|
+
|
|
372
|
+
One call for every candidate, because the candidates are what survived `exists`,
|
|
373
|
+
`carries` and `anywhere` — one or two on a live corpus — and a subprocess each would
|
|
374
|
+
price a check by how broken the file is. Both spellings are asked (RK51): a token is
|
|
375
|
+
relative to the ledger's directory or to the root, and either may be the ignored one.
|
|
376
|
+
|
|
377
|
+
No git, no answer, and the finding stands: withholding where the question could not
|
|
378
|
+
be asked would turn "this repository says so" into "nobody could say otherwise".
|
|
379
|
+
|
|
380
|
+
Every token asked is recorded, ignored or not, so a repeat costs nothing and a new
|
|
381
|
+
one costs the batch it arrives in (RK219). What is *not* recorded is the difference
|
|
382
|
+
between "git said no" and "git could not be asked", because within one tree that
|
|
383
|
+
cannot change: a run has one repository, and it either has git or it does not.
|
|
384
|
+
"""
|
|
385
|
+
unknown = [(token, near) for token, near in tokens if token not in self._ignored]
|
|
386
|
+
if unknown:
|
|
387
|
+
declared = _declared_untracked(self.config, unknown)
|
|
388
|
+
for token, _ in unknown:
|
|
389
|
+
self._ignored[token] = token in declared
|
|
390
|
+
return frozenset(token for token, _ in tokens if self._ignored[token])
|
|
391
|
+
|
|
392
|
+
def spellings(self, token: str, near: Path) -> tuple[str, ...]:
|
|
393
|
+
"""How git could spell this token, from each base it may be relative to (RK51).
|
|
394
|
+
|
|
395
|
+
Computed once and passed down (RK228): `holds` used to ask `carries`, which spelled
|
|
396
|
+
the token, and then spell it again for the directory set — two answers to one
|
|
397
|
+
question, and the profile's largest remaining row was the second one.
|
|
398
|
+
|
|
399
|
+
The root prefix is the constant half, so it is normalised once for the whole run
|
|
400
|
+
rather than 34133 times through `os.path.relpath`, which normcases both ends of
|
|
401
|
+
every call. Nothing about the answer changes; only how often the part that cannot
|
|
402
|
+
differ is recomputed.
|
|
403
|
+
"""
|
|
404
|
+
return tuple(
|
|
405
|
+
spelling
|
|
406
|
+
for base in (near, self.config.root)
|
|
407
|
+
if (spelling := _spelled(self._prefix(), str(base), token)) is not None
|
|
408
|
+
)
|
|
409
|
+
|
|
410
|
+
def _prefix(self) -> str:
|
|
411
|
+
"""The repository root as a normalised prefix, with its separator, built once."""
|
|
412
|
+
if self._root is None:
|
|
413
|
+
self._root = os.path.normpath(str(self.config.root))
|
|
414
|
+
return self._root
|
|
415
|
+
|
|
416
|
+
def listing(self) -> frozenset[str]:
|
|
417
|
+
"""Every path this tree still **has**, read once (RK173, RK217).
|
|
418
|
+
|
|
419
|
+
Two checks want it — the tail index and the revision's membership test — so it is
|
|
420
|
+
the tree's rather than each one's, and a run costs one listing however many ask.
|
|
421
|
+
"""
|
|
422
|
+
if self._names is None:
|
|
423
|
+
self._names = (
|
|
424
|
+
tracked_now(self.config)
|
|
425
|
+
if self.rev is None
|
|
426
|
+
else tracked_at(self.config, self.rev)
|
|
427
|
+
)
|
|
428
|
+
return self._names
|
|
429
|
+
|
|
430
|
+
def holds(self, token: str, near: Path) -> bool:
|
|
431
|
+
"""Does the tree this run is judging have what this token names? (RK84, RK218)
|
|
432
|
+
|
|
433
|
+
The working tree answers from the disk, which is its subject. A revision answers
|
|
434
|
+
from git, and from **both** shapes a token can name: a file is a tracked path, and
|
|
435
|
+
a directory is a prefix of one — `docs`, `create-shio-app` and thirty-three more
|
|
436
|
+
across the two pins are named as directories and were only ever admitted because
|
|
437
|
+
they happened to be on somebody's disk.
|
|
438
|
+
|
|
439
|
+
`exists` is a fact about *now*, so a run naming a revision may not consult it: an
|
|
440
|
+
untracked file created since the ref, which git has never seen, used to silence a
|
|
441
|
+
finding that revision genuinely had.
|
|
442
|
+
"""
|
|
443
|
+
if self.rev is None:
|
|
444
|
+
return on_disk(token, self.config.root, near)
|
|
445
|
+
spellings = self.spellings(token, near)
|
|
446
|
+
if any(spelling in self.listing() for spelling in spellings):
|
|
447
|
+
return True
|
|
448
|
+
directories = self.directories() or frozenset()
|
|
449
|
+
return any(spelling in directories for spelling in spellings)
|
|
450
|
+
|
|
451
|
+
def directories(self) -> frozenset[str] | None:
|
|
452
|
+
"""Which directories this repository knows, for deciding a claim (RK217).
|
|
453
|
+
|
|
454
|
+
Not :meth:`listing`, and the difference is the defect: that one drops a file
|
|
455
|
+
deleted from the working tree, which is right for "does the tree still have it" and
|
|
456
|
+
exactly wrong here — a ledger naming `lib/gone.py` after `lib/` was removed would
|
|
457
|
+
stop being a claim instead of becoming a finding. At a revision the two coincide,
|
|
458
|
+
there being no working tree to have deleted anything from.
|
|
459
|
+
"""
|
|
460
|
+
if self._directories is _UNASKED:
|
|
461
|
+
# At HEAD the function's own default is the index, which is the listing this
|
|
462
|
+
# question wants (RK221); at a revision the tree's listing already is that.
|
|
463
|
+
self._directories = known_directories(
|
|
464
|
+
self.config, None if self.rev is None else self.listing()
|
|
465
|
+
)
|
|
466
|
+
return self._directories
|
|
467
|
+
|
|
468
|
+
def anywhere(self, token: str) -> bool:
|
|
469
|
+
"""Does this tree hold the artefact this token names, under **any** prefix? (RK173)
|
|
470
|
+
|
|
471
|
+
A monorepo entry writes the path its reader is standing in — the frontend app, the
|
|
472
|
+
showcase skill — because that is what a developer pastes from a terminal already
|
|
473
|
+
inside it. Resolving from the repository root alone reported the difference as a
|
|
474
|
+
missing file: of Turing's eight `path.missing` findings, six named artefacts the
|
|
475
|
+
repository has, which is a signal ratio at which the class stops being read. Worse,
|
|
476
|
+
it points at history — these are shipped entries, so the remedy the wording implies
|
|
477
|
+
is editing what already happened.
|
|
478
|
+
|
|
479
|
+
The question this check asks is whether the **repository has the artefact** (RK51),
|
|
480
|
+
so the tail is what answers it, and a rename inside a directory — the one true
|
|
481
|
+
finding this check has produced on a live corpus — still matches nothing.
|
|
482
|
+
|
|
483
|
+
**Measured coming out, too** (RK189), because a widening whose cost is an argument
|
|
484
|
+
is a widening nobody can price. Over both pins: Shio exercises the rule zero times
|
|
485
|
+
in 1278 files, and Turing's ledger leaves six tokens unresolved, of which this
|
|
486
|
+
silences five and reports the moved file. Four of the five are two-segment tokens
|
|
487
|
+
matching exactly one tracked file — the match identifies the artefact rather than
|
|
488
|
+
finding a name — and the fifth is the `./package.json` that motivated the rule,
|
|
489
|
+
matching thirteen. So a one-segment token is admitted deliberately: requiring a
|
|
490
|
+
slash would re-report that one and change none of the others. The exposure it
|
|
491
|
+
accepts is real and unrealised — 17% of the files in each tree share a basename —
|
|
492
|
+
and `tests/test_linting.py` is where all four numbers are held.
|
|
493
|
+
"""
|
|
494
|
+
if self._tails is None:
|
|
495
|
+
names = self.listing()
|
|
496
|
+
self._tails = frozenset(
|
|
497
|
+
"/".join(segments[start:])
|
|
498
|
+
for name in names
|
|
499
|
+
for segments in (name.split("/"),)
|
|
500
|
+
for start in range(len(segments))
|
|
501
|
+
)
|
|
502
|
+
wanted = token.replace("\\", "/")
|
|
503
|
+
while wanted.startswith("./"):
|
|
504
|
+
wanted = wanted[2:]
|
|
505
|
+
return wanted in self._tails
|
|
506
|
+
|
|
507
|
+
|
|
508
|
+
@dataclass(frozen=True, slots=True)
|
|
509
|
+
class Baseline:
|
|
510
|
+
"""What the same gate said at a revision, so this run can report only what it added.
|
|
511
|
+
|
|
512
|
+
``forgiven`` is the standing debt *as it still stands* — findings this working tree has
|
|
513
|
+
and the revision had too. ``resolved`` is the other direction, and it is here for the
|
|
514
|
+
reading that nearly hid a real defect: a run that deleted 160 lines of rationale it
|
|
515
|
+
should not have took the count down by eight, and the drop read as an improvement until
|
|
516
|
+
the two findings it *added* were looked at individually. One number cannot say both.
|
|
517
|
+
"""
|
|
518
|
+
|
|
519
|
+
rev: str
|
|
520
|
+
forgiven: tuple[Finding, ...] = ()
|
|
521
|
+
resolved: tuple[Finding, ...] = ()
|
|
522
|
+
|
|
523
|
+
@property
|
|
524
|
+
def standing(self) -> int:
|
|
525
|
+
return len(self.forgiven)
|
|
526
|
+
|
|
527
|
+
|
|
528
|
+
@dataclass(frozen=True, slots=True)
|
|
529
|
+
class Report:
|
|
530
|
+
"""What was checked, and everything wrong with it. Emptiness is the pass."""
|
|
531
|
+
|
|
532
|
+
findings: tuple[Finding, ...]
|
|
533
|
+
#: The files this run **judged**, as the project spells them — printed even when clean,
|
|
534
|
+
#: because a gate that passed by reading nothing is the failure mode of every gate. Judged
|
|
535
|
+
#: and not merely read, so every finding's file is in here (RK354): `roadkeep.toml` is one
|
|
536
|
+
#: where it carries a queue and is not one where it only said which files to open.
|
|
537
|
+
checked: tuple[str, ...]
|
|
538
|
+
lines: int
|
|
539
|
+
#: Anchored sections read in the prose file — the other half of what was checked.
|
|
540
|
+
sections: int = 0
|
|
541
|
+
#: Always-loaded files whose budget was measured (RK30).
|
|
542
|
+
budgets: int = 0
|
|
543
|
+
#: What the gate observed without failing on it (RK35). Never affects the exit code.
|
|
544
|
+
notes: tuple[Note, ...] = ()
|
|
545
|
+
#: The revision this run was measured against, when it was (RK84). Present means
|
|
546
|
+
#: ``findings`` holds the difference and nothing else.
|
|
547
|
+
baseline: Baseline | None = None
|
|
548
|
+
|
|
549
|
+
@property
|
|
550
|
+
def clean(self) -> bool:
|
|
551
|
+
return not self.findings
|
|
552
|
+
|
|
553
|
+
@property
|
|
554
|
+
def problems(self) -> int:
|
|
555
|
+
return len(self.findings)
|
|
556
|
+
|
|
557
|
+
def stated(self, config: Config, applied: Fix, root: str, quiet: bool) -> None:
|
|
558
|
+
"""The gate's report, written as it is composed (RK14, RK35, RK420).
|
|
559
|
+
|
|
560
|
+
Beside :meth:`payload` since RK1170 — one answer, on the record both readings are
|
|
561
|
+
about. It **writes** rather than returning rows, which is the one exception this task
|
|
562
|
+
leaves standing: a finding's remedy is fetched per finding and the mechanical class is
|
|
563
|
+
counted while the rest are printed, so building the whole report as a list would hold
|
|
564
|
+
a corpus-sized report in memory to hand it straight to `print`.
|
|
565
|
+
|
|
566
|
+
`quiet` is the caller's: what it silences is the *body*, never the summary and never
|
|
567
|
+
the refusals, because a pass that could not prove its own output wrote nothing.
|
|
568
|
+
"""
|
|
569
|
+
_report_rows(config, self, applied, root, quiet)
|
|
570
|
+
|
|
571
|
+
def payload(self, config: Config, applied: Fix, root: str) -> dict[str, object]:
|
|
572
|
+
"""The same answer as data, rooted first (RK299).
|
|
573
|
+
|
|
574
|
+
Every path in it is relative to `root`, and a payload a second tool files against the
|
|
575
|
+
wrong project is worse than one it cannot file at all — so the key comes first, spelled
|
|
576
|
+
the way `install --json` already spells it.
|
|
577
|
+
"""
|
|
578
|
+
return _lint_json(config, self, applied, root)
|
|
579
|
+
|
|
580
|
+
def codes(self) -> dict[str, int]:
|
|
581
|
+
"""Findings per code, most first — the summary a report of ninety is read by."""
|
|
582
|
+
found: dict[str, int] = {}
|
|
583
|
+
for finding in self.findings:
|
|
584
|
+
found[finding.code] = found.get(finding.code, 0) + 1
|
|
585
|
+
return dict(sorted(found.items(), key=lambda pair: (-pair[1], pair[0])))
|
|
586
|
+
|
|
587
|
+
|
|
588
|
+
def lint(
|
|
589
|
+
config: Config,
|
|
590
|
+
since: str | None = None,
|
|
591
|
+
baseline: str | None = None,
|
|
592
|
+
at: str | None = None,
|
|
593
|
+
) -> Report:
|
|
594
|
+
"""Read every governed file and return every defect. Writes nothing, ever.
|
|
595
|
+
|
|
596
|
+
``at`` runs the whole gate over a **revision** instead of the working tree (RK210) —
|
|
597
|
+
the read ``baseline`` already makes, given a name so a caller can make it alone. Both
|
|
598
|
+
ends move together, which is the point: the governed files come from the revision *and*
|
|
599
|
+
so does the repository the path check asks about, so nothing in the answer is half about
|
|
600
|
+
this afternoon. Library-only, with no flag beside it: `--baseline` is the question a
|
|
601
|
+
person asks at a terminal, and "what did the gate say at a revision" has one caller —
|
|
602
|
+
the pinned-corpus fixture, whose whole difficulty was that a config can carry one root
|
|
603
|
+
and a pinned run needs the governed files copied and the tree left where git can read it.
|
|
604
|
+
|
|
605
|
+
``since`` adds the checks that are about a *change* rather than a state — a section edited
|
|
606
|
+
without its line (RK36), and a block this change emptied or reopened (RK269) — against a
|
|
607
|
+
revision, `HEAD` in a pre-commit hook and the base branch in CI. Both are notes, and both
|
|
608
|
+
are only askable of a diff: as states they are "somebody edited prose once" and "this
|
|
609
|
+
block is empty", which are true forever and read by nobody.
|
|
610
|
+
|
|
611
|
+
``baseline`` answers the other question about a change (RK84): the same gate is run over
|
|
612
|
+
the governed files as they were at that revision, and what comes back is the excess —
|
|
613
|
+
so a repository with standing debt gets an exit code about *its own* commit. The two
|
|
614
|
+
compose, and the baseline run makes no ``since`` comparison of its own: a note about a
|
|
615
|
+
section edited since a ref is about this working tree either way.
|
|
616
|
+
"""
|
|
617
|
+
if at is not None and not resolves(config, at):
|
|
618
|
+
raise HistoryUnavailable(f"{at} is not a revision this repository knows")
|
|
619
|
+
report = _examine(config, since=since, tree=Tree(config, at))
|
|
620
|
+
if baseline is None:
|
|
621
|
+
return report
|
|
622
|
+
if not resolves(config, baseline):
|
|
623
|
+
# Unlike `since`, this one cannot degrade to silence: the exit code is the answer,
|
|
624
|
+
# and a run that could not read its baseline would report the whole debt as new.
|
|
625
|
+
raise HistoryUnavailable(f"{baseline} is not a revision this repository knows")
|
|
626
|
+
return _subtract(
|
|
627
|
+
report, _examine(config, since=None, tree=Tree(config, baseline)), baseline
|
|
628
|
+
)
|
|
629
|
+
|
|
630
|
+
|
|
631
|
+
def _examine(config: Config, since: str | None, tree: Tree) -> Report:
|
|
632
|
+
"""Every check, over whichever tree is being judged.
|
|
633
|
+
|
|
634
|
+
A **loop over a declared domain** since RK1172, where it was 21 hand-wired calls whose scan
|
|
635
|
+
kind lived in their parameter lists. What each rule reads is now a field on it, so the five
|
|
636
|
+
inputs are built once here and each kind's iteration — the whole tree, every line-bearing
|
|
637
|
+
role, one role, the prose with its anchor index — is written once below rather than at every
|
|
638
|
+
call site. Adding a rule that scans something new says so; adding one that scans something
|
|
639
|
+
already known costs a row.
|
|
640
|
+
"""
|
|
641
|
+
documents: dict[str, Document] = {}
|
|
642
|
+
for role in LINE_ROLES:
|
|
643
|
+
document = tree.document(role)
|
|
644
|
+
if document is not None:
|
|
645
|
+
documents[role] = document
|
|
646
|
+
prose: dict[str, Document] = {}
|
|
647
|
+
for role in PROSE_ROLES:
|
|
648
|
+
document = tree.document(role)
|
|
649
|
+
if document is not None:
|
|
650
|
+
prose[role] = document
|
|
651
|
+
anchors = {role: anchored(document) for role, document in prose.items()}
|
|
652
|
+
sections = tuple(section for found in anchors.values() for section in found)
|
|
653
|
+
scanned = _Scan(
|
|
654
|
+
config=config,
|
|
655
|
+
tree=tree,
|
|
656
|
+
documents=documents,
|
|
657
|
+
prose=prose,
|
|
658
|
+
anchors=anchors,
|
|
659
|
+
since=since,
|
|
660
|
+
# Read before the rules that want it, and not a check: a projection target is a fact
|
|
661
|
+
# about the tree that two rules and the file list all ask for (RK1110).
|
|
662
|
+
targets=_targets(config, tree),
|
|
663
|
+
)
|
|
664
|
+
|
|
665
|
+
findings: list[Finding] = []
|
|
666
|
+
notes: list[Note] = []
|
|
667
|
+
for rule in _rules():
|
|
668
|
+
for one in rule.run(scanned):
|
|
669
|
+
(notes if isinstance(one, Note) else findings).append(one)
|
|
670
|
+
|
|
671
|
+
targets = scanned.targets
|
|
672
|
+
checked = _checked(config, documents, prose, targets)
|
|
673
|
+
# The second phase, run as the list it is (RK1172). Every rule above reads the *project*;
|
|
674
|
+
# these three read what those produced — a whole file's worth of findings is evidence about
|
|
675
|
+
# the rule rather than about a line (RK1068), what another finding already explains is not a
|
|
676
|
+
# second finding, and the printed order is a fact about the report. Nested calls said the
|
|
677
|
+
# same thing and said it inside out: `_ordered(_untainted(findings), checked)` puts the last
|
|
678
|
+
# step first, and where a fourth fold goes was a question about parentheses.
|
|
679
|
+
for fold in _FOLDS:
|
|
680
|
+
findings = list(fold(findings, config=config, documents=documents, checked=checked))
|
|
681
|
+
return Report(
|
|
682
|
+
findings=tuple(findings),
|
|
683
|
+
checked=checked,
|
|
684
|
+
lines=sum(len(d.entries) for d in documents.values()),
|
|
685
|
+
sections=len(sections),
|
|
686
|
+
budgets=len(config.budgets),
|
|
687
|
+
notes=tuple(notes),
|
|
688
|
+
)
|
|
689
|
+
|
|
690
|
+
|
|
691
|
+
@dataclass(frozen=True, slots=True)
|
|
692
|
+
class _Scan:
|
|
693
|
+
"""Every input a rule can read, built once (RK1172).
|
|
694
|
+
|
|
695
|
+
The five kinds the measurement found — the governed **tree**, the **documents** carrying task
|
|
696
|
+
lines, the **prose** files, the **anchor** index derived from them, and a git **revision** —
|
|
697
|
+
plus the projection targets, which are a reading of the tree that three rules share.
|
|
698
|
+
|
|
699
|
+
One record and not a parameter list, so a rule that starts reading a second input changes its
|
|
700
|
+
own row and nothing else: the signature `(config, documents, prose, targets)` was the fourth
|
|
701
|
+
shape invented at a call site, and each new one made `_examine` the only place that knew.
|
|
702
|
+
"""
|
|
703
|
+
|
|
704
|
+
config: Config
|
|
705
|
+
tree: Tree
|
|
706
|
+
documents: dict[str, Document]
|
|
707
|
+
prose: dict[str, Document]
|
|
708
|
+
anchors: dict[str, tuple[Section, ...]]
|
|
709
|
+
since: str | None
|
|
710
|
+
targets: tuple[Target, ...]
|
|
711
|
+
|
|
712
|
+
@property
|
|
713
|
+
def governed(self) -> dict[str, Document]:
|
|
714
|
+
"""Both halves, for the rules decided against the whole set and not one file (RK417)."""
|
|
715
|
+
return {**self.documents, **self.prose}
|
|
716
|
+
|
|
717
|
+
|
|
718
|
+
@dataclass(frozen=True, slots=True)
|
|
719
|
+
class _Rule:
|
|
720
|
+
"""One gate rule: what it reads, and what it reports (RK1172).
|
|
721
|
+
|
|
722
|
+
`remedying.py` has been a table keyed by code since RK420, and its argument — that a central
|
|
723
|
+
domain is what a test can be total over — was only half applied: the *remedy* was a table and
|
|
724
|
+
the *check* was sixty functions with signatures invented where they were called.
|
|
725
|
+
|
|
726
|
+
:attr:`reads` is the field that removes the hand-wiring. It names one of the kinds
|
|
727
|
+
:class:`_Scan` holds, and the loop below turns that name into the iteration: `role` runs the
|
|
728
|
+
rule once per line-bearing document, `prose_role` once per prose file, `whole` once. A rule
|
|
729
|
+
that fits none of them is the evidence the set is wrong, which is what this task asked for.
|
|
730
|
+
"""
|
|
731
|
+
|
|
732
|
+
reads: str
|
|
733
|
+
run: Callable[[_Scan], Sequence[Finding | Note]]
|
|
734
|
+
|
|
735
|
+
|
|
736
|
+
# Cached rather than built at import: `within` and half the rules below are defined further down
|
|
737
|
+
# this file, and a domain whose construction depended on definition order would break when a rule
|
|
738
|
+
# moves. One call, and the tuple is a value a test can be total over.
|
|
739
|
+
@functools.lru_cache(maxsize=1)
|
|
740
|
+
def _rules() -> tuple[_Rule, ...]:
|
|
741
|
+
"""The domain, in the order it runs (RK1172).
|
|
742
|
+
|
|
743
|
+
Order is the reader's convenience and not a rule's requirement: `_ordered` sorts the report by
|
|
744
|
+
file and line, and the two folds before it read the whole population — so nothing here depends
|
|
745
|
+
on running before anything else, which is what makes a declared list safe.
|
|
746
|
+
"""
|
|
747
|
+
|
|
748
|
+
def per_role(one: Callable[[Config, str, Document], Sequence[Finding]]) -> Callable[[_Scan], list[Finding]]:
|
|
749
|
+
return lambda scan: [
|
|
750
|
+
found
|
|
751
|
+
for role, document in scan.documents.items()
|
|
752
|
+
for found in one(scan.config, role, document)
|
|
753
|
+
]
|
|
754
|
+
|
|
755
|
+
def characters(scan: _Scan) -> list[Finding]:
|
|
756
|
+
# The character pass is a second walk over the same file, so the rule `within` holds has
|
|
757
|
+
# to be read here too or the 3,301 findings it exists to replace come back from the other
|
|
758
|
+
# side (RK451). The same predicate and not a second statement of it: `within` owns what
|
|
759
|
+
# "not text" means and this asks it.
|
|
760
|
+
return [
|
|
761
|
+
found
|
|
762
|
+
for role, document in scan.documents.items()
|
|
763
|
+
if not _voided(document)
|
|
764
|
+
for found in _characters(scan.config, role, document)
|
|
765
|
+
]
|
|
766
|
+
|
|
767
|
+
def resolved(scan: _Scan) -> list[Finding]:
|
|
768
|
+
if not scan.prose:
|
|
769
|
+
return []
|
|
770
|
+
found = list(_pointers(scan.config, scan.documents, scan.anchors))
|
|
771
|
+
found += _citations(scan.config, scan.prose, scan.anchors)
|
|
772
|
+
found += _crossing(scan.config, scan.prose, scan.anchors)
|
|
773
|
+
# The fourth kind of citation (RK1380), asked of every governed file and not of the
|
|
774
|
+
# prose ones alone: a law is cited from a ledger sentence and a roadmap `why` as
|
|
775
|
+
# readily as from a design.
|
|
776
|
+
found += _laws(scan.config, scan.documents, scan.prose)
|
|
777
|
+
for role, document in scan.prose.items():
|
|
778
|
+
found += _orphans(
|
|
779
|
+
scan.config, scan.documents, document, scan.anchors, role=role
|
|
780
|
+
)
|
|
781
|
+
return found
|
|
782
|
+
|
|
783
|
+
def against_baseline(scan: _Scan) -> list[Note]:
|
|
784
|
+
if scan.since is None:
|
|
785
|
+
return []
|
|
786
|
+
found = list(_turned(scan.config, scan.documents, scan.since))
|
|
787
|
+
if scan.prose:
|
|
788
|
+
found += _unpaired(
|
|
789
|
+
scan.config, scan.anchors.get("improvements", ()), scan.since
|
|
790
|
+
)
|
|
791
|
+
# And the mirror of it (RK1228): prose that moved without its line, then source
|
|
792
|
+
# that moved under a line nobody closed.
|
|
793
|
+
found += _worked(
|
|
794
|
+
scan.config,
|
|
795
|
+
scan.documents,
|
|
796
|
+
scan.anchors.get("improvements", ()),
|
|
797
|
+
scan.since,
|
|
798
|
+
)
|
|
799
|
+
return found
|
|
800
|
+
|
|
801
|
+
def budgeted(scan: _Scan) -> list[Finding | Note]:
|
|
802
|
+
found, said = _budgets(scan.config, scan.tree)
|
|
803
|
+
return [*found, *said]
|
|
804
|
+
|
|
805
|
+
def queued(scan: _Scan) -> list[Finding | Note]:
|
|
806
|
+
found, said = _queue(scan.config, scan.documents)
|
|
807
|
+
return [*found, *said]
|
|
808
|
+
|
|
809
|
+
return (
|
|
810
|
+
_Rule("tree", lambda scan: _absent(scan.config, scan.tree)),
|
|
811
|
+
_Rule("role", per_role(within)),
|
|
812
|
+
_Rule("role", characters),
|
|
813
|
+
_Rule("documents", lambda scan: _across(scan.config, scan.documents)),
|
|
814
|
+
_Rule("documents", lambda scan: _scope(scan.config, scan.documents.get("roadmap"))),
|
|
815
|
+
# The positive twin of the rule above (RK1265), read from the same document and
|
|
816
|
+
# opt-in on its own declaration: a project may govern one list and not the other.
|
|
817
|
+
_Rule(
|
|
818
|
+
"documents",
|
|
819
|
+
lambda scan: _criteria(
|
|
820
|
+
scan.config, scan.documents.get("roadmap"), scan.documents
|
|
821
|
+
),
|
|
822
|
+
),
|
|
823
|
+
_Rule("documents", queued),
|
|
824
|
+
_Rule("documents", lambda scan: _collective(scan.config, scan.documents)),
|
|
825
|
+
_Rule("tree", lambda scan: _disagreeing(scan.config, scan.tree)),
|
|
826
|
+
_Rule("revision", against_baseline),
|
|
827
|
+
_Rule("prose_role", lambda scan: [
|
|
828
|
+
found
|
|
829
|
+
for role, document in scan.prose.items()
|
|
830
|
+
for found in _marks(scan.config, role, document)
|
|
831
|
+
]),
|
|
832
|
+
_Rule("anchors", resolved),
|
|
833
|
+
_Rule("governed", lambda scan: _repeated(scan.config, scan.governed)),
|
|
834
|
+
_Rule("tree", lambda scan: _paths(scan.config, scan.documents, scan.tree)),
|
|
835
|
+
_Rule("governed", lambda scan: _projections(scan.config, scan.governed, scan.targets)),
|
|
836
|
+
_Rule("tree", budgeted),
|
|
837
|
+
# Its own rule and not a tail of `budgeted` (RK1192): what a surface costs and whether
|
|
838
|
+
# it is the one this engine ships are two questions, and a check folded into another's
|
|
839
|
+
# return is one nobody finds by reading the list of what this gate asks.
|
|
840
|
+
_Rule("config", lambda scan: _wired(scan.config)),
|
|
841
|
+
# And the other half of the same pin (RK1238): `_wired` asks whether the surfaces are
|
|
842
|
+
# behind the engine, and this asks whether the engine judging them is behind the one
|
|
843
|
+
# the project chose.
|
|
844
|
+
_Rule("config", lambda scan: _judged(scan.config)),
|
|
845
|
+
)
|
|
846
|
+
|
|
847
|
+
|
|
848
|
+
|
|
849
|
+
def _folding(name: str) -> Callable[..., Any]:
|
|
850
|
+
"""One rule of the reporting phase, adapted to the one shape a fold has (RK1172).
|
|
851
|
+
|
|
852
|
+
The three read different things — a document set, the findings alone, the file order — so
|
|
853
|
+
an adapter is what lets the phase be a list. Written here rather than by changing each
|
|
854
|
+
rule's own signature: what a rule wants is a fact about that rule, and a uniform parameter
|
|
855
|
+
list that every caller then ignores half of is the hand-wiring one layer up.
|
|
856
|
+
"""
|
|
857
|
+
def fold(findings: list[Finding], **inputs: Any) -> Sequence[Finding]:
|
|
858
|
+
if name == "grammatical":
|
|
859
|
+
return _grammatical(inputs["config"], inputs["documents"], findings)
|
|
860
|
+
if name == "untainted":
|
|
861
|
+
return _untainted(findings)
|
|
862
|
+
return _ordered(findings, inputs["checked"])
|
|
863
|
+
|
|
864
|
+
fold.__name__ = f"fold_{name}"
|
|
865
|
+
return fold
|
|
866
|
+
|
|
867
|
+
|
|
868
|
+
#: The reporting phase, in the order it runs (RK1172). The fold before the drop before the sort,
|
|
869
|
+
#: because each reads what the one before it left: the inference needs the whole population, the
|
|
870
|
+
#: drop needs the fold's own finding to exist before it can suppress what that explains, and the
|
|
871
|
+
#: order is over whatever survived. Three names in a list, where the order used to be the shape
|
|
872
|
+
#: of an expression.
|
|
873
|
+
_FOLDS: tuple[Callable[..., Sequence[Finding]], ...] = (
|
|
874
|
+
_folding("grammatical"),
|
|
875
|
+
_folding("untainted"),
|
|
876
|
+
_folding("ordered"),
|
|
877
|
+
)
|
|
878
|
+
|
|
879
|
+
|
|
880
|
+
def _checked(
|
|
881
|
+
config: Config,
|
|
882
|
+
documents: dict[str, Document],
|
|
883
|
+
prose: dict[str, Document],
|
|
884
|
+
targets: tuple[Target, ...],
|
|
885
|
+
) -> tuple[str, ...]:
|
|
886
|
+
"""Every file this run judged, in the order its findings print in (RK365).
|
|
887
|
+
|
|
888
|
+
One place, because the list is two things at once: what the report *says* was read, and
|
|
889
|
+
the sort key :func:`_ordered` applies to every finding. It was appended to at five points
|
|
890
|
+
down `_examine`'s body, three of them conditional, so the order findings print in was
|
|
891
|
+
decided by where a check happened to be added rather than by anything anybody wrote down.
|
|
892
|
+
|
|
893
|
+
The order is the reader's. The line-bearing files first, because they are what this format
|
|
894
|
+
is about; the prose they point into next; then the files this tool does not own — a
|
|
895
|
+
projection target, an instruction file with a budget — and `roadkeep.toml` last, judged
|
|
896
|
+
only where it carries a queue (RK354) and not a governed file at all.
|
|
897
|
+
|
|
898
|
+
Conditional membership is the rule and not the exception: a budgeted file is here because
|
|
899
|
+
`[budgets]` names it, a target because a marked block asked to be projected into it, and
|
|
900
|
+
the config because it declared an order. What decides each is one expression, all four in
|
|
901
|
+
view of each other.
|
|
902
|
+
"""
|
|
903
|
+
checked = [config.relative(config.path(role)) for role in documents]
|
|
904
|
+
checked.extend(config.relative(config.path(role)) for role in prose)
|
|
905
|
+
checked.extend(target.where for target in targets)
|
|
906
|
+
checked.extend(config.relative(budget.path) for budget in config.budgets)
|
|
907
|
+
# By path and not by role (RK1361): `decisions` is read twice — once for its lines and
|
|
908
|
+
# once for its sections — and the report is a list of *files*, so naming it twice said
|
|
909
|
+
# this run judged five where it judged four. The order is still the first mention's,
|
|
910
|
+
# which is the reader's order above: a file sorts where it was first read.
|
|
911
|
+
checked = list(dict.fromkeys(checked))
|
|
912
|
+
# The config is judged where it declares a queue (RK354) and where it declares what a
|
|
913
|
+
# served tool may cost (RK1059) — the second being the one budget whose subject is not
|
|
914
|
+
# a file, so `roadkeep.toml` is both what declared it and the only place to name.
|
|
915
|
+
if config.priority or config.tool_characters is not None:
|
|
916
|
+
checked.append(_configured(config))
|
|
917
|
+
return tuple(checked)
|
|
918
|
+
|
|
919
|
+
|
|
920
|
+
#: How many lines a file must hold before *all* of them failing the round-trip reads as the
|
|
921
|
+
#: rule rather than the lines (RK1068). Two, because one line disagreeing with the schema is
|
|
922
|
+
#: an edited line and is exactly what `line.non-canonical` is for — the inference is about a
|
|
923
|
+
#: population, and a population of one is a line.
|
|
924
|
+
_A_POPULATION = 2
|
|
925
|
+
|
|
926
|
+
|
|
927
|
+
def _grammatical(
|
|
928
|
+
config: Config, documents: Mapping[str, Document], findings: list[Finding]
|
|
929
|
+
) -> list[Finding]:
|
|
930
|
+
"""Fold a whole file's worth of non-canonical lines into one defect at the rule (RK1068).
|
|
931
|
+
|
|
932
|
+
The cost a declared grammar does not remove, caught at the end it is actually about. A
|
|
933
|
+
grammar given as data (RK1064) can be one that cannot read back what it writes, and the
|
|
934
|
+
round-trip guard then refuses the whole file — correctly and by law — so a separator
|
|
935
|
+
declared one character too loose presents as **every line in the corpus** being
|
|
936
|
+
non-canonical, and the report blames a hundred lines for the one line of config that
|
|
937
|
+
broke them.
|
|
938
|
+
|
|
939
|
+
**Both ways a line can fail it**, which measuring made the point of: a declaration too
|
|
940
|
+
*loose* renders what it read differently and the file comes back `line.non-canonical`,
|
|
941
|
+
and one too *narrow* — a slot dropped that the file has — stops matching at all and the
|
|
942
|
+
same file comes back `line.unparsed`. The second is what a wrong `drop` actually
|
|
943
|
+
produces, so a fold that watched only the first would miss the failure it was written
|
|
944
|
+
for. A bullet counts either way, which is why the population is entries **and** rejects.
|
|
945
|
+
|
|
946
|
+
The inference is deliberately narrow: *every* line-shaped bullet in a role's file, and
|
|
947
|
+
at least :data:`_A_POPULATION` of them. One line differing from its rendering is an
|
|
948
|
+
edited line and is what `line.non-canonical` already says; a file where not one bullet
|
|
949
|
+
survives is not a file somebody hand-edited into that state.
|
|
950
|
+
|
|
951
|
+
Paired with RK1067, which is what makes the answer actionable rather than merely
|
|
952
|
+
correct: the finding lands on the declaration's own line, so the report reads as one
|
|
953
|
+
defect at one config line instead of a corpus that stopped conforming.
|
|
954
|
+
"""
|
|
955
|
+
explained = next(rule for rule in EXPLAINS if rule.by == "grammar.")
|
|
956
|
+
out = list(findings)
|
|
957
|
+
for role, document in documents.items():
|
|
958
|
+
population = len(document.entries) + len(document.rejects)
|
|
959
|
+
if population < _A_POPULATION:
|
|
960
|
+
continue
|
|
961
|
+
where = config.relative(config.path(role))
|
|
962
|
+
# Counted against the same rule that will suppress them (RK1070), so "which failures
|
|
963
|
+
# is this an explanation of" is one declaration and not a literal here and a
|
|
964
|
+
# predicate there. Nothing is removed by this function: it *reports*, and
|
|
965
|
+
# :func:`_untainted` drops what the report explains — which is what keeps the
|
|
966
|
+
# removal from being identity over a dataclass, where two findings that compare
|
|
967
|
+
# equal on one line went together or not at all.
|
|
968
|
+
broken = sum(
|
|
969
|
+
1 for finding in out if finding.file == where and explained.explains(finding)
|
|
970
|
+
)
|
|
971
|
+
if broken < population:
|
|
972
|
+
continue
|
|
973
|
+
declared = config.grammars.get(role)
|
|
974
|
+
out.append(
|
|
975
|
+
Finding(
|
|
976
|
+
"grammar.unreadable",
|
|
977
|
+
_configured(config) if declared else where,
|
|
978
|
+
f"the grammar for {role} fails on {population} of {population} bullets: "
|
|
979
|
+
f"this is the rule and not the lines, and a file where none survives is "
|
|
980
|
+
f"not one somebody hand-edited"
|
|
981
|
+
+ (
|
|
982
|
+
f" — `[grammar.{role}]` is what to look at"
|
|
983
|
+
if declared
|
|
984
|
+
else " — no [grammar] is declared, so the file was written under "
|
|
985
|
+
"another format"
|
|
986
|
+
),
|
|
987
|
+
subject=role,
|
|
988
|
+
# What it covers, which is not where it is filed (RK1070): the declaration
|
|
989
|
+
# is in the config and the lines it explains are in the governed file.
|
|
990
|
+
about=where,
|
|
991
|
+
)
|
|
992
|
+
)
|
|
993
|
+
return out
|
|
994
|
+
|
|
995
|
+
|
|
996
|
+
@dataclass(frozen=True, slots=True)
|
|
997
|
+
class Explains:
|
|
998
|
+
"""One finding that makes another one noise, declared (RK1070).
|
|
999
|
+
|
|
1000
|
+
Two checks in this module do this and neither said so: a codepoint nobody typed makes
|
|
1001
|
+
every other diagnosis of that line a consequence (RK34), and a grammar that fails on a
|
|
1002
|
+
whole file makes every per-line failure in it an effect (RK1068). Both were a predicate
|
|
1003
|
+
and a set comprehension written out at the call site — so a third arriving is folded
|
|
1004
|
+
only if somebody remembers, and *at what scope* was a tuple that happened to be built
|
|
1005
|
+
the same way twice.
|
|
1006
|
+
|
|
1007
|
+
:attr:`scope` is the whole of what differs between the two. A codepoint explains the
|
|
1008
|
+
other findings **on its line**, because the byte is in that line and the next one is
|
|
1009
|
+
judged normally; a grammar explains them **in its file**, because the rule is what
|
|
1010
|
+
every line in it was read under. Naming that is what makes the two one mechanism rather
|
|
1011
|
+
than two loops that resemble each other.
|
|
1012
|
+
"""
|
|
1013
|
+
|
|
1014
|
+
#: The code that explains, or its prefix where the family is what explains — `char.`
|
|
1015
|
+
#: is nine codes and every one of them makes the same point about the line it is on.
|
|
1016
|
+
by: str
|
|
1017
|
+
#: What it explains, matched the same way.
|
|
1018
|
+
over: tuple[str, ...]
|
|
1019
|
+
#: `line` or `file` — how far the explanation reaches.
|
|
1020
|
+
scope: str
|
|
1021
|
+
|
|
1022
|
+
def explains(self, finding: Finding) -> bool:
|
|
1023
|
+
return any(finding.code.startswith(code) for code in self.over)
|
|
1024
|
+
|
|
1025
|
+
def spoken_by(self, finding: Finding) -> bool:
|
|
1026
|
+
return finding.code.startswith(self.by)
|
|
1027
|
+
|
|
1028
|
+
def where(self, finding: Finding, *, speaking: bool = False) -> tuple[str, int | None]:
|
|
1029
|
+
"""The key two findings share when one explains the other.
|
|
1030
|
+
|
|
1031
|
+
``speaking`` lets an explanation be filed somewhere other than what it is about,
|
|
1032
|
+
which the grammar one has to be: it lands on `roadkeep.toml`, where the declaration
|
|
1033
|
+
that broke the file is and where the edit goes (RK1067), and it explains findings in
|
|
1034
|
+
the file it names. `about` carries that second address, so the two are not confused
|
|
1035
|
+
— the finding's own `file` is where a reader clicks and never what it covers.
|
|
1036
|
+
"""
|
|
1037
|
+
under = finding.about if speaking and finding.about else finding.file
|
|
1038
|
+
return (under, finding.lineno if self.scope == "line" else None)
|
|
1039
|
+
|
|
1040
|
+
|
|
1041
|
+
#: Every explanation this gate makes, which is the index RK1070 asked for: a reader asking
|
|
1042
|
+
#: "does a finding suppress another" reads four lines rather than two functions.
|
|
1043
|
+
EXPLAINS: tuple[Explains, ...] = (
|
|
1044
|
+
# A line carrying a byte nobody typed is not a line this format can judge (RK34): the
|
|
1045
|
+
# parser read a string the author cannot see, so every other diagnosis of it names a
|
|
1046
|
+
# consequence. Report the codepoint; the rest is decidable on the next run.
|
|
1047
|
+
Explains(by="char.", over=("",), scope="line"),
|
|
1048
|
+
# A rule that fails on every bullet in a file is what broke them (RK1068), so the
|
|
1049
|
+
# per-line failures are the effect and the report is one defect at one declaration.
|
|
1050
|
+
Explains(
|
|
1051
|
+
by="grammar.",
|
|
1052
|
+
over=("line.non-canonical", "line.unparsed"),
|
|
1053
|
+
scope="file",
|
|
1054
|
+
),
|
|
1055
|
+
)
|
|
1056
|
+
|
|
1057
|
+
|
|
1058
|
+
def _untainted(findings: list[Finding]) -> list[Finding]:
|
|
1059
|
+
"""Every finding except the ones another already explains (RK34, RK1068, RK1070).
|
|
1060
|
+
|
|
1061
|
+
One pass over :data:`EXPLAINS` rather than a function per relation: what each row says
|
|
1062
|
+
is which code speaks, which it speaks over and how far, and the loop under that is the
|
|
1063
|
+
same four lines it always was. An explanation never suppresses another explanation —
|
|
1064
|
+
a codepoint on a line whose file has a bad grammar is still worth reporting, both being
|
|
1065
|
+
causes rather than effects.
|
|
1066
|
+
"""
|
|
1067
|
+
kept = list(findings)
|
|
1068
|
+
for rule in EXPLAINS:
|
|
1069
|
+
# A line-scoped rule needs a line to be about: a finding filed against the file
|
|
1070
|
+
# itself explains nothing on any particular one, and taking it as evidence would
|
|
1071
|
+
# silence every other file-level finding there.
|
|
1072
|
+
spoken = {
|
|
1073
|
+
rule.where(f, speaking=True)
|
|
1074
|
+
for f in kept
|
|
1075
|
+
if rule.spoken_by(f) and (rule.scope == "file" or f.lineno)
|
|
1076
|
+
}
|
|
1077
|
+
kept = [
|
|
1078
|
+
f
|
|
1079
|
+
for f in kept
|
|
1080
|
+
# Never an explanation: a codepoint on a line whose file has a bad grammar is
|
|
1081
|
+
# still worth reporting, both being causes rather than effects of each other.
|
|
1082
|
+
if any(one.spoken_by(f) for one in EXPLAINS)
|
|
1083
|
+
or not rule.explains(f)
|
|
1084
|
+
or rule.where(f) not in spoken
|
|
1085
|
+
]
|
|
1086
|
+
return kept
|
|
1087
|
+
|
|
1088
|
+
|
|
1089
|
+
def _ordered(findings: list[Finding], checked: tuple[str, ...]) -> tuple[Finding, ...]:
|
|
1090
|
+
"""Every finding, in the order the report prints them (RK365).
|
|
1091
|
+
|
|
1092
|
+
`checked` **is** the order, so a file sorts where the reader was told it was read, and the
|
|
1093
|
+
two halves of the report cannot disagree about which file came first.
|
|
1094
|
+
|
|
1095
|
+
A finding whose file the list does not name sorts **last**, by falling off the end of the
|
|
1096
|
+
index. That was right by accident until RK354 put the config in `checked`, and it is stated
|
|
1097
|
+
here rather than left in a `dict.get` default: the report is read against the list, so
|
|
1098
|
+
anything the list does not name belongs after everything it does.
|
|
1099
|
+
"""
|
|
1100
|
+
order = {name: index for index, name in enumerate(checked)}
|
|
1101
|
+
return tuple(
|
|
1102
|
+
sorted(findings, key=lambda f: (order.get(f.file, len(order)), f.lineno or 0, f.code))
|
|
1103
|
+
)
|
|
1104
|
+
|
|
1105
|
+
|
|
1106
|
+
def _subtract(now: Report, before: Report, rev: str) -> Report:
|
|
1107
|
+
"""The findings this working tree added, and the ones it inherited (RK84).
|
|
1108
|
+
|
|
1109
|
+
**Counted per (file, code, task), and never per line number.** A line moves when
|
|
1110
|
+
anything above it is inserted, so an identity that included the position would report
|
|
1111
|
+
the whole file as new the first time a task was added at the top — which is the failure
|
|
1112
|
+
mode that makes a delta gate worth less than no gate. What is compared is therefore how
|
|
1113
|
+
many findings of one kind one line has, and the excess is what this change wrote.
|
|
1114
|
+
|
|
1115
|
+
Within a kind the ones that did not move are forgiven first. It changes no count; it
|
|
1116
|
+
means the finding *reported* is the one at a position the revision did not have, which
|
|
1117
|
+
is the one a reader is being sent to look at.
|
|
1118
|
+
"""
|
|
1119
|
+
standing: dict[tuple[str, str, str], list[Finding]] = {}
|
|
1120
|
+
for finding in before.findings:
|
|
1121
|
+
standing.setdefault(_debt(finding), []).append(finding)
|
|
1122
|
+
|
|
1123
|
+
here: dict[tuple[str, str, str], list[int]] = {}
|
|
1124
|
+
for index, finding in enumerate(now.findings):
|
|
1125
|
+
here.setdefault(_debt(finding), []).append(index)
|
|
1126
|
+
|
|
1127
|
+
forgiven: set[int] = set()
|
|
1128
|
+
resolved: list[Finding] = []
|
|
1129
|
+
for key, indices in here.items():
|
|
1130
|
+
there = standing.pop(key, [])
|
|
1131
|
+
places = {finding.lineno for finding in there}
|
|
1132
|
+
stayed = [i for i in indices if now.findings[i].lineno in places]
|
|
1133
|
+
moved = [i for i in indices if now.findings[i].lineno not in places]
|
|
1134
|
+
forgiven.update((stayed + moved)[: len(there)])
|
|
1135
|
+
resolved.extend(there[len(indices) :])
|
|
1136
|
+
for left in standing.values():
|
|
1137
|
+
resolved.extend(left)
|
|
1138
|
+
|
|
1139
|
+
return replace(
|
|
1140
|
+
now,
|
|
1141
|
+
findings=tuple(f for i, f in enumerate(now.findings) if i not in forgiven),
|
|
1142
|
+
baseline=Baseline(
|
|
1143
|
+
rev=rev,
|
|
1144
|
+
forgiven=tuple(now.findings[i] for i in sorted(forgiven)),
|
|
1145
|
+
resolved=tuple(resolved),
|
|
1146
|
+
),
|
|
1147
|
+
)
|
|
1148
|
+
|
|
1149
|
+
|
|
1150
|
+
def _debt(finding: Finding) -> tuple[str, str, str]:
|
|
1151
|
+
"""What makes two findings the same standing problem: one kind, one line's worth."""
|
|
1152
|
+
return (finding.file, finding.code, finding.id)
|
|
1153
|
+
|
|
1154
|
+
|
|
1155
|
+
def _characters(config: Config, role: str, document: Document) -> list[Finding]:
|
|
1156
|
+
"""Name the byte, not its consequence (RK34).
|
|
1157
|
+
|
|
1158
|
+
The format is structural Unicode — `—`, `→`, `§` and four emoji markers — so every
|
|
1159
|
+
lookalike a human editor produces is invisible exactly where it fails. Measured
|
|
1160
|
+
against this parser: `📋` plus U+FE0F is reported as `status.unknown`, which prints as
|
|
1161
|
+
"'📋️' is not one of 📋"; a no-break space before the pointer is reported as
|
|
1162
|
+
`why.no-terminator`, naming the one thing the line does not lack. Both are correct and
|
|
1163
|
+
unusable, because the character that caused them cannot be seen.
|
|
1164
|
+
|
|
1165
|
+
Only the line-bearing files. A paragraph has no parse for an invisible byte to corrupt,
|
|
1166
|
+
and §RK34 had to *quote* a variation selector to explain the defect — which a scan over
|
|
1167
|
+
prose would have reported as the defect itself.
|
|
1168
|
+
|
|
1169
|
+
**Which codepoints occur is asked before where they are** (RK227). The rule stays
|
|
1170
|
+
:func:`suspect`'s — a Unicode category and not a hand-kept list, so a format character
|
|
1171
|
+
nobody has met yet is still caught — but it is asked once per *distinct* codepoint
|
|
1172
|
+
instead of once per character: 800215 calls over Turing's ledger, every answer no, for
|
|
1173
|
+
148 ms of a 660 ms gate. A clean file leaves the walk below unentered, and every file
|
|
1174
|
+
this gate passes is a clean file.
|
|
1175
|
+
|
|
1176
|
+
The bodies and not the raw lines, because a line ending is `Cc` and therefore the one
|
|
1177
|
+
thing every file would have flagged — :func:`_endings` is what judges those, and a
|
|
1178
|
+
sweep that always said "dirty" would have been the loop with a longer preamble.
|
|
1179
|
+
"""
|
|
1180
|
+
file = config.relative(config.path(role))
|
|
1181
|
+
ids = {entry.lineno: entry.task.id for entry in document.entries}
|
|
1182
|
+
out = _endings(document, file)
|
|
1183
|
+
bodies = [raw.rstrip("\r\n") for raw in document.lines]
|
|
1184
|
+
# `indent=False`, so a tab counts as a candidate wherever it sits; the walk is what
|
|
1185
|
+
# knows whether one is indentation, which is the only place it reads as text (RK146).
|
|
1186
|
+
candidates = {char for char in set("".join(bodies)) if suspect(char)}
|
|
1187
|
+
if not candidates:
|
|
1188
|
+
return out
|
|
1189
|
+
found = re.compile(f"[{''.join(re.escape(char) for char in sorted(candidates))}]")
|
|
1190
|
+
for number, body in enumerate(bodies, start=1):
|
|
1191
|
+
head = indentation(body)
|
|
1192
|
+
for match in found.finditer(body):
|
|
1193
|
+
column = match.start() + 1
|
|
1194
|
+
if not suspect(match.group(), indent=column <= head):
|
|
1195
|
+
continue
|
|
1196
|
+
out.append(_named(file, number, column, match.group(), ids.get(number, "")))
|
|
1197
|
+
return out
|
|
1198
|
+
|
|
1199
|
+
|
|
1200
|
+
#: The one codepoint a prose file is swept for (RK1028). Not the rest of :func:`suspect`'s
|
|
1201
|
+
#: domain, and §RK34 is why: a design explaining a lookalike has to **quote** it, so a scan
|
|
1202
|
+
#: over prose would report the paragraph that documents the defect as the defect. A mark is
|
|
1203
|
+
#: the exception that proves the rule — no design pastes one, they name it `U+FEFF`, and no
|
|
1204
|
+
#: keyboard produces it. What does produce it is every mainstream Windows editor, ahead of a
|
|
1205
|
+
#: file `--body-file` then reads whole.
|
|
1206
|
+
MARK = ""
|
|
1207
|
+
|
|
1208
|
+
|
|
1209
|
+
def _marks(config: Config, role: str, document: Document) -> list[Finding]:
|
|
1210
|
+
"""A byte-order mark anywhere in a prose file, which is never something anybody wrote.
|
|
1211
|
+
|
|
1212
|
+
The gate half of RK1028. The writer now strips one at position 1 of a stream or a file,
|
|
1213
|
+
where it is the encoder's; this is the file that already carries one — from an editor,
|
|
1214
|
+
from a paste, from the route that was open before the strip — and it is invisible by
|
|
1215
|
+
definition, so the first reader to notice is whoever greps a heading and finds nothing.
|
|
1216
|
+
|
|
1217
|
+
Anywhere and not only at the start, because that is where the hole was: a body read from
|
|
1218
|
+
a path lands **mid-file**, under whatever heading the section was placed at, and a rule
|
|
1219
|
+
about position 1 would have reported nothing. The code is `char.bom` either way — one
|
|
1220
|
+
byte, one meaning, one door.
|
|
1221
|
+
"""
|
|
1222
|
+
file = config.relative(config.path(role))
|
|
1223
|
+
out: list[Finding] = []
|
|
1224
|
+
for number, raw in enumerate(document.lines, start=1):
|
|
1225
|
+
column = raw.find(MARK)
|
|
1226
|
+
while column >= 0:
|
|
1227
|
+
out.append(
|
|
1228
|
+
Finding(
|
|
1229
|
+
"char.bom",
|
|
1230
|
+
file,
|
|
1231
|
+
"U+FEFF byte-order mark inside the prose: not text, invisible in an "
|
|
1232
|
+
"editor, and a byte the round-trip compares",
|
|
1233
|
+
number,
|
|
1234
|
+
"",
|
|
1235
|
+
column + 1,
|
|
1236
|
+
)
|
|
1237
|
+
)
|
|
1238
|
+
column = raw.find(MARK, column + 1)
|
|
1239
|
+
return out
|
|
1240
|
+
|
|
1241
|
+
|
|
1242
|
+
def _named(file: str, lineno: int, column: int, char: str, task_id: str) -> Finding:
|
|
1243
|
+
point = f"U+{ord(char):04X}"
|
|
1244
|
+
name = unicodedata.name(char, "unnamed control character").lower()
|
|
1245
|
+
if lineno == 1 and column == 1 and char == "":
|
|
1246
|
+
# Its own answer: a byte-order mark is not text at all, and it lands on whatever
|
|
1247
|
+
# the first line happens to be — which is a heading, so nothing else reports it.
|
|
1248
|
+
return Finding(
|
|
1249
|
+
"char.bom",
|
|
1250
|
+
file,
|
|
1251
|
+
f"{point} byte-order mark at the start of the file: not text, and a byte the "
|
|
1252
|
+
f"round-trip compares",
|
|
1253
|
+
lineno,
|
|
1254
|
+
task_id,
|
|
1255
|
+
column,
|
|
1256
|
+
)
|
|
1257
|
+
# The code and the clause are the schema's (RK499), which is where the door raises the
|
|
1258
|
+
# same three about a *field*: a tab past the indentation is a separator this format does
|
|
1259
|
+
# not write, a `Zs` renders as a space and is not one, and everything else cannot be seen.
|
|
1260
|
+
# What is this function's own is the place — a line and a column, which is what a report
|
|
1261
|
+
# is read for and what an argument has none of.
|
|
1262
|
+
code, because = CODEPOINT_KINDS[codepoint_kind(char)]
|
|
1263
|
+
named = "tab" if char == TAB else name
|
|
1264
|
+
return Finding(code, file, f"{point} {named} at column {column}: {because}", lineno, task_id, column)
|
|
1265
|
+
|
|
1266
|
+
|
|
1267
|
+
def _endings(document: Document, file: str) -> list[Finding]:
|
|
1268
|
+
"""Two kinds of line ending in one file — one line edited by something else.
|
|
1269
|
+
|
|
1270
|
+
A file that is *uniformly* CRLF is not a defect and is not reported: `Document` keeps
|
|
1271
|
+
every ending verbatim, so it round-trips, and a repository that checks out CRLF is a
|
|
1272
|
+
configuration rather than a mistake (L6). Mixed is the byte nobody typed.
|
|
1273
|
+
"""
|
|
1274
|
+
found: dict[str, int] = {}
|
|
1275
|
+
for line in document.lines:
|
|
1276
|
+
terminator = ending(line)
|
|
1277
|
+
if terminator:
|
|
1278
|
+
found[terminator] = found.get(terminator, 0) + 1
|
|
1279
|
+
if len(found) < 2:
|
|
1280
|
+
return []
|
|
1281
|
+
spelled = ", ".join(
|
|
1282
|
+
f"{count}× {_ENDING_NAMES[terminator]}" for terminator, count in sorted(found.items())
|
|
1283
|
+
)
|
|
1284
|
+
return [
|
|
1285
|
+
Finding(
|
|
1286
|
+
"char.mixed-endings",
|
|
1287
|
+
file,
|
|
1288
|
+
f"two kinds of line ending in one file ({spelled}): one of them was written "
|
|
1289
|
+
f"by something that is not this tool, and the round-trip compares bytes",
|
|
1290
|
+
)
|
|
1291
|
+
]
|
|
1292
|
+
|
|
1293
|
+
|
|
1294
|
+
def _budgets(config: Config, tree: Tree) -> tuple[list[Finding], list[Note]]:
|
|
1295
|
+
"""Every always-loaded file, against what it declared it may cost (RK30).
|
|
1296
|
+
|
|
1297
|
+
Measured in bytes off the tree and lines by counting terminators, so nothing here has
|
|
1298
|
+
to decode a file the tool does not govern: a budget is about what a loader pays, and
|
|
1299
|
+
an instruction file is not a format this tool has any business parsing (L4). Off the
|
|
1300
|
+
tree and not off disk for RK84's reason — an `agents.md` pushed over its budget by this
|
|
1301
|
+
change is the finding a baseline exists to keep, and both runs reading the same bytes
|
|
1302
|
+
would forgive it.
|
|
1303
|
+
|
|
1304
|
+
Which is exactly why the count is normalised (RK1105): with no baseline the tree *is*
|
|
1305
|
+
disk, so this read is a working tree's bytes, and with one it is a git blob's — the same
|
|
1306
|
+
gate answering two numbers for one commit, 311 bytes apart on the corpus that found it.
|
|
1307
|
+
`spent` drops the terminator's second byte and the second half of that is here, as a
|
|
1308
|
+
note: the checkout's real cost is stated and never charged.
|
|
1309
|
+
"""
|
|
1310
|
+
out: list[Finding] = []
|
|
1311
|
+
notes: list[Note] = []
|
|
1312
|
+
for budget in config.budgets:
|
|
1313
|
+
where = config.relative(budget.path)
|
|
1314
|
+
raw = tree.blob(budget.path)
|
|
1315
|
+
if raw is None:
|
|
1316
|
+
out.append(
|
|
1317
|
+
Finding(
|
|
1318
|
+
"budget.absent",
|
|
1319
|
+
where,
|
|
1320
|
+
"declares a budget and is not on disk: the entry holds nothing",
|
|
1321
|
+
)
|
|
1322
|
+
)
|
|
1323
|
+
continue
|
|
1324
|
+
# One measurement, called and not repeated (RK345): `budget --file` reports the room
|
|
1325
|
+
# this refuses, and a second count here is a gate disagreeing with the read that
|
|
1326
|
+
# composed the edit.
|
|
1327
|
+
measured_in = spent(raw)
|
|
1328
|
+
for unit, measured, allowed in (
|
|
1329
|
+
("lines", measured_in["lines"], budget.lines),
|
|
1330
|
+
("bytes", measured_in["bytes"], budget.bytes),
|
|
1331
|
+
):
|
|
1332
|
+
if allowed is not None and measured > allowed:
|
|
1333
|
+
out.append(
|
|
1334
|
+
Finding(
|
|
1335
|
+
f"budget.{unit}",
|
|
1336
|
+
where,
|
|
1337
|
+
f"{measured} {unit}, budget is {allowed}: this is loaded every "
|
|
1338
|
+
f"turn, so the overrun is paid on every turn",
|
|
1339
|
+
)
|
|
1340
|
+
)
|
|
1341
|
+
extra = translated(raw)
|
|
1342
|
+
if extra and budget.bytes is not None:
|
|
1343
|
+
notes.append(
|
|
1344
|
+
Note(
|
|
1345
|
+
"budget.translated",
|
|
1346
|
+
where,
|
|
1347
|
+
f"{measured_in['bytes']} bytes counted and {extra} more on this "
|
|
1348
|
+
f"checkout, whose lines end CRLF: the ceiling is the commit's, so a "
|
|
1349
|
+
f"number declared against a working tree has that much room it never "
|
|
1350
|
+
f"voted for",
|
|
1351
|
+
subject=where,
|
|
1352
|
+
)
|
|
1353
|
+
)
|
|
1354
|
+
over, said = _reads(config)
|
|
1355
|
+
return out + _served(config) + over, notes + said
|
|
1356
|
+
|
|
1357
|
+
|
|
1358
|
+
def _reads(config: Config) -> tuple[list[Finding], list[Note]]:
|
|
1359
|
+
"""The briefs a session is about to ask for, against what one may cost (RK1286, RK1287).
|
|
1360
|
+
|
|
1361
|
+
`_served`' argument about a **read** rather than about the schema. RK30 held the resident
|
|
1362
|
+
prose, RK1059 the served surface, and the one answer this project recommends *over*
|
|
1363
|
+
reading the file had no figure at all — while growing four arithmetic rows in one session,
|
|
1364
|
+
each argued and none counted.
|
|
1365
|
+
|
|
1366
|
+
**Bounded, and it says by how much.** A brief costs tens of milliseconds, so pricing every
|
|
1367
|
+
open line put a project that declared a ceiling at O(open) of them on every commit. What
|
|
1368
|
+
this prices is `pick`'s own answer and the alternatives it already names — the reads a
|
|
1369
|
+
session is about to make — and the note says how many lines that left out and which
|
|
1370
|
+
command prices them all. Never a silent cap: a report that omits without saying so reads
|
|
1371
|
+
as one that covered everything.
|
|
1372
|
+
|
|
1373
|
+
Filed against `roadkeep.toml`, which declared it and is the only file involved — a brief
|
|
1374
|
+
is composed per call and there is no path a reader could open to see it, which is
|
|
1375
|
+
`_served`'s own reason. Silent where nothing is declared, and **composed only there**.
|
|
1376
|
+
"""
|
|
1377
|
+
if config.brief_read is None:
|
|
1378
|
+
return [], []
|
|
1379
|
+
from roadkeep.budgeting import brief_budget # noqa: PLC0415 - RK260
|
|
1380
|
+
|
|
1381
|
+
where = config.relative(config.source or config.root)
|
|
1382
|
+
found = brief_budget(config, offered=True)
|
|
1383
|
+
out = [
|
|
1384
|
+
Finding(
|
|
1385
|
+
"read.over",
|
|
1386
|
+
where,
|
|
1387
|
+
f"{one.id}'s brief is {one.characters} characters against a budget of "
|
|
1388
|
+
f"{config.brief_read}: this is the read that replaces reading the file, so one "
|
|
1389
|
+
f"that does not fit a tool result is a task a session opens the roadmap for — "
|
|
1390
|
+
f"`{invocation()} cost --brief` ranks every one and names what each costs",
|
|
1391
|
+
subject=one.id,
|
|
1392
|
+
)
|
|
1393
|
+
for one in found.over
|
|
1394
|
+
]
|
|
1395
|
+
# A line the ranking could not measure is the one most likely to have been the widest
|
|
1396
|
+
# (RK1288), so its absence is a finding and not a note: `read.over` is derived from this
|
|
1397
|
+
# ranking, and a project can be over its ceiling on a line nothing reported.
|
|
1398
|
+
out += [
|
|
1399
|
+
Finding(
|
|
1400
|
+
"read.unpriced",
|
|
1401
|
+
where,
|
|
1402
|
+
f"{one.id}'s brief would not compose, so it is not in the ranking `[reads] "
|
|
1403
|
+
f"brief` is held against: {one.because} — the widest is the bound, and a line "
|
|
1404
|
+
f"this read could not measure is the shape most likely to be it",
|
|
1405
|
+
subject=one.id,
|
|
1406
|
+
)
|
|
1407
|
+
for one in found.unpriced
|
|
1408
|
+
]
|
|
1409
|
+
notes = (
|
|
1410
|
+
[
|
|
1411
|
+
Note(
|
|
1412
|
+
"read.priced",
|
|
1413
|
+
where,
|
|
1414
|
+
f"{len(found.briefs)} of {found.open_lines} open line(s) priced against "
|
|
1415
|
+
f"`[reads] brief`"
|
|
1416
|
+
+ (f", {len(found.unpriced)} refused" if found.unpriced else "")
|
|
1417
|
+
+ f", {found.elided} not asked for — the ones `pick` offers next, so what is "
|
|
1418
|
+
f"left out is what nobody is about to brief, and the next run prices "
|
|
1419
|
+
f"whatever the answer has become; `{invocation()} cost --brief` ranks "
|
|
1420
|
+
f"every one now",
|
|
1421
|
+
)
|
|
1422
|
+
]
|
|
1423
|
+
# **More left out than priced** (RK1290), which is `_collective`'s shape and not a
|
|
1424
|
+
# tuned ratio: below it this gate saw the majority of the backlog and there is no
|
|
1425
|
+
# surprise to report, and above it the ceiling is held against a minority — which is
|
|
1426
|
+
# the fact worth a line. Without a threshold it fired on every clean run of any real
|
|
1427
|
+
# backlog, and a reader who meets the same sentence every time stops reading the
|
|
1428
|
+
# notes, so the next one that matters arrives under a heading they learnt to skip.
|
|
1429
|
+
#
|
|
1430
|
+
# Never about the **refused**: those are `read.unpriced` findings, and a threshold
|
|
1431
|
+
# here silences nothing this report would otherwise have said.
|
|
1432
|
+
if found.elided > len(found.briefs)
|
|
1433
|
+
else []
|
|
1434
|
+
)
|
|
1435
|
+
return out, notes
|
|
1436
|
+
|
|
1437
|
+
|
|
1438
|
+
def _wired(config: Config) -> list[Note]:
|
|
1439
|
+
"""The vendored surfaces behind the engine answering here (RK1192).
|
|
1440
|
+
|
|
1441
|
+
`install --check` already answers this exactly, and that is the whole problem: it is a
|
|
1442
|
+
command nobody thinks to run. Nothing prompts it, no failure names it, and a project
|
|
1443
|
+
reaches it only by already suspecting what it reports.
|
|
1444
|
+
|
|
1445
|
+
Measured on another project. Its committed launcher predated RK1116, so it forwarded
|
|
1446
|
+
`guard` and `mcp` and nothing else; the MCP server had not connected; and the skill that
|
|
1447
|
+
session read named that launcher as the entry point. Every door was shut at once, and the
|
|
1448
|
+
way out was guessing a version directory under the plugin cache — the one route no
|
|
1449
|
+
document mentions, because it is not meant to be one.
|
|
1450
|
+
|
|
1451
|
+
So the gate asks it, being what runs anyway: `lint` fires every turn through the `Stop`
|
|
1452
|
+
hook, it already reports drift between what a file says and what this tool would write,
|
|
1453
|
+
and a wired surface behind the version answering is drift of exactly that kind. The
|
|
1454
|
+
remedy is `install`, which is the complete command, so `repair` closes it too.
|
|
1455
|
+
|
|
1456
|
+
**Against the engine answering here and never the newest one.** :func:`~roadkeep.installing.stale`
|
|
1457
|
+
plans from `_source()`, the checkout this process is, so what is compared is the copy that
|
|
1458
|
+
would do the writing. Three copies are allowed to differ and `engines` is what adjudicates
|
|
1459
|
+
that (RK415); a second opinion here about which version is *right* would be this gate
|
|
1460
|
+
taking a side in a question another verb exists to report.
|
|
1461
|
+
|
|
1462
|
+
**Filed at the surface**, unlike `budget.tool` one function down: there is a path a reader
|
|
1463
|
+
can open, and it is the file that drifted.
|
|
1464
|
+
|
|
1465
|
+
Silent where nothing is vendored, which is every plugin-served project — there is no copy
|
|
1466
|
+
to be behind. Silent too where `[install] pinned` says the version is the project's choice
|
|
1467
|
+
(L6): a finding on every turn about a decision already taken is noise, and a gate carrying
|
|
1468
|
+
noise is one that stops being read.
|
|
1469
|
+
|
|
1470
|
+
Cheap, and measured before it was put on a per-turn path: :func:`~roadkeep.installing.stale`
|
|
1471
|
+
is **0.07 ms** unwired — one `is_file` — and **0.86 ms** wired, against RK176's 43 ms
|
|
1472
|
+
floor. It declines the workflow gauge, which is the 40 ms of that, by the same field that
|
|
1473
|
+
makes the workflow the adopter's after the first write.
|
|
1474
|
+
|
|
1475
|
+
**A note, so the exit code does not move** (RK1308), which is `engine.disagreement`'s rule
|
|
1476
|
+
one function over and for the same reason: what this gate is *for* is whether the governed
|
|
1477
|
+
lines drifted, and whether this checkout's installed surface matches the engine is
|
|
1478
|
+
maintenance — true of the machine rather than of the branch. Observed in pportal,
|
|
1479
|
+
2026-08-22: `lint` exited 1 on a backlog `ship` had just written and that had drifted in no
|
|
1480
|
+
way at all, reporting `311 line(s), 32 section(s) … clean` in the same breath. That exit
|
|
1481
|
+
code is the whole contract of the CI job this project publishes, so a repository whose only
|
|
1482
|
+
gate is `roadkeep lint` went red on every push, for every contributor.
|
|
1483
|
+
|
|
1484
|
+
The consequence to keep: `repair` walks findings, so it no longer reaches this — and that
|
|
1485
|
+
is the argument rather than a loss. `install` writes into `.claude/` and not into the
|
|
1486
|
+
backlog, so in a project holding one task to one commit it has to become a commit of its
|
|
1487
|
+
own; a repair loop that ran it inside whatever was being shipped is the state this task
|
|
1488
|
+
describes, arrived at from the other side.
|
|
1489
|
+
"""
|
|
1490
|
+
if config.install_pinned:
|
|
1491
|
+
return []
|
|
1492
|
+
from roadkeep.installing import stale # noqa: PLC0415 - RK260
|
|
1493
|
+
|
|
1494
|
+
# Every failure inside is silence, as it is for the session-start notice this shares a
|
|
1495
|
+
# reader with (RK82, RK234): a gate that fails because a checkout moved is worse than one
|
|
1496
|
+
# that says nothing, and `install --check` still answers on demand.
|
|
1497
|
+
return [
|
|
1498
|
+
Note(
|
|
1499
|
+
"install.stale",
|
|
1500
|
+
where,
|
|
1501
|
+
f"this surface is behind the roadkeep answering here, so a session reads a "
|
|
1502
|
+
f"skill, hook or launcher older than the engine it names — "
|
|
1503
|
+
f"`{invocation()} install` rewrites the ones this checkout ships",
|
|
1504
|
+
subject=where,
|
|
1505
|
+
)
|
|
1506
|
+
for where in stale(config.root)
|
|
1507
|
+
]
|
|
1508
|
+
|
|
1509
|
+
|
|
1510
|
+
def _judged(config: Config) -> list[Note]:
|
|
1511
|
+
"""Whose rules this verdict is, where the project said which copy's it should be (RK1238).
|
|
1512
|
+
|
|
1513
|
+
RK1235 guards the **pen**: a governed write from a copy behind the pinned one is refused
|
|
1514
|
+
before the lock. The gate was left alone, and it is the same copy — so on a pinned project
|
|
1515
|
+
running a stale engine the writes stop and this keeps answering from rules that have
|
|
1516
|
+
moved. It reports clean, and the action CI runs at its own ref disagrees.
|
|
1517
|
+
|
|
1518
|
+
That is RK1235's failure with the halves swapped, and worse in one way. A refused write is
|
|
1519
|
+
a message, read at the moment somebody asked for something. A gate that passes is
|
|
1520
|
+
**silence** — which is exactly what the shipped `Stop` hook produces on every turn that
|
|
1521
|
+
changed nothing, so there is no moment at which a reader is looking.
|
|
1522
|
+
|
|
1523
|
+
A **note**, and the shape is the whole task. A refusal is wrong: `lint` exiting 2 because a
|
|
1524
|
+
copy is old turns one stale plugin into a repository nobody can commit in, which is the
|
|
1525
|
+
state `guard` is written to survive (RK22). A finding is wrong for RK1192's stated reason:
|
|
1526
|
+
it fires every turn until somebody updates, and a gate carrying noise stops being read.
|
|
1527
|
+
What a note does is qualify the verdict beside it — printed before the findings and before
|
|
1528
|
+
a clean summary alike (RK35) — so a clean report says *whose* clean it is.
|
|
1529
|
+
|
|
1530
|
+
Both of RK1235's conditions and for its reasons: `behind` and never `unpinnable`, because
|
|
1531
|
+
a modified checkout is where a developer lives; and only where `[install] enforced` is
|
|
1532
|
+
declared, that key being the project saying the registered plugin is the copy that should
|
|
1533
|
+
write here (L6, RK1240) rather than this tool guessing at a setup it cannot see. Filed at
|
|
1534
|
+
`roadkeep.toml`, which is where that decision is written and what a reader would open.
|
|
1535
|
+
|
|
1536
|
+
**2 ms**, and that is why it can be on the gate at all: :func:`~roadkeep.installing.behind`
|
|
1537
|
+
compares versions before it asks git anything (RK1237), so the case this fires on — two
|
|
1538
|
+
copies at two versions — is answered without a subprocess.
|
|
1539
|
+
"""
|
|
1540
|
+
if not config.install_enforced:
|
|
1541
|
+
return []
|
|
1542
|
+
from roadkeep.installing import behind, engines # noqa: PLC0415 - RK260
|
|
1543
|
+
|
|
1544
|
+
# Silence on every failure inside, as `_wired` is and for its reason (RK82, RK234): a gate
|
|
1545
|
+
# that fails because a registry moved is worse than one that says nothing, and `engines`
|
|
1546
|
+
# still answers on demand.
|
|
1547
|
+
try:
|
|
1548
|
+
if not behind(config.root):
|
|
1549
|
+
return []
|
|
1550
|
+
read = engines(config.root)
|
|
1551
|
+
except OSError:
|
|
1552
|
+
return []
|
|
1553
|
+
return [
|
|
1554
|
+
Note(
|
|
1555
|
+
"gate.behind",
|
|
1556
|
+
_configured(config),
|
|
1557
|
+
f"this gate is {read.running.version} and the project pinned "
|
|
1558
|
+
f"{read.plugin.version if read.plugin else '—'}, so a clean report here is that "
|
|
1559
|
+
f"copy's clean — `{invocation()} engines` names all three",
|
|
1560
|
+
subject="pinned",
|
|
1561
|
+
)
|
|
1562
|
+
]
|
|
1563
|
+
|
|
1564
|
+
|
|
1565
|
+
def _served(config: Config) -> list[Finding]:
|
|
1566
|
+
"""Every served tool against what one may cost a session (RK1059).
|
|
1567
|
+
|
|
1568
|
+
`_budgets`' argument, about the surface instead of about a file. RK30 held the resident
|
|
1569
|
+
prose and RK464 measured the schema and stopped there, deliberately: what a ceiling
|
|
1570
|
+
would be *per* was a decision it declined to make without a number in front of it. Here
|
|
1571
|
+
it is per tool, because a total names nothing — it fails on whichever tool is added
|
|
1572
|
+
last — and a per-tool one is refused by the tool whose description somebody just edited.
|
|
1573
|
+
|
|
1574
|
+
Filed against `roadkeep.toml`, which is the file that declared it and the only file
|
|
1575
|
+
involved: the cost is composed per session from the parser, the config and the `TOOLS`
|
|
1576
|
+
table, so there is no path a reader could open to see it. `cost --tools` is what
|
|
1577
|
+
prints it, and the message says so.
|
|
1578
|
+
|
|
1579
|
+
Silent where nothing is declared, which is every adopting project until it looks at the
|
|
1580
|
+
number — a gate that arrived with a ceiling this tool chose would be the guess RK464
|
|
1581
|
+
refused to make.
|
|
1582
|
+
|
|
1583
|
+
**And it is cheap, which RK1061 was filed believing it was not.** That task measured 201
|
|
1584
|
+
ms against 80 and read it as this check building 52 descriptors on a command CI, the
|
|
1585
|
+
pre-commit hook and the Stop hook each run. Measured again, warm: `descriptors` is 1 ms
|
|
1586
|
+
and this whole function is **1.4 ms**. The 121 ms was one-time import cost — `serving`
|
|
1587
|
+
and the CLI it reaches — attributed to the check by an in-process comparison whose first
|
|
1588
|
+
call paid it. The import is still real and is 13 ms on a path where `cli` is already
|
|
1589
|
+
loaded, which every path this runs on is. Left as it is, and the measurement kept here
|
|
1590
|
+
because the next reader will make the same inference from the same shape.
|
|
1591
|
+
"""
|
|
1592
|
+
if config.tool_characters is None:
|
|
1593
|
+
return []
|
|
1594
|
+
from roadkeep.serving import surface
|
|
1595
|
+
|
|
1596
|
+
allowed = config.tool_characters
|
|
1597
|
+
where = _configured(config)
|
|
1598
|
+
sent = surface(config)
|
|
1599
|
+
# The same payload `cost --tools` measures, through the same function (RK345): a
|
|
1600
|
+
# second estimate here is a gate disagreeing with the read that composed the edit. In
|
|
1601
|
+
# its order too — largest first — because the message sends the reader to that ranking,
|
|
1602
|
+
# and a report listing the offenders in a different one is two answers to one question.
|
|
1603
|
+
out = [
|
|
1604
|
+
Finding(
|
|
1605
|
+
"budget.tool",
|
|
1606
|
+
where,
|
|
1607
|
+
f"the {name} tool is {size} characters, budget is {allowed}: this is sent to "
|
|
1608
|
+
f"every session that connects the server, so the overrun is paid before the "
|
|
1609
|
+
f"first call — `{invocation()} cost --tools` ranks them",
|
|
1610
|
+
subject=name,
|
|
1611
|
+
)
|
|
1612
|
+
for name, size in sent.tools
|
|
1613
|
+
if size > allowed
|
|
1614
|
+
]
|
|
1615
|
+
# And the sum, where the project declared one (RK1097). Second and not instead: this one
|
|
1616
|
+
# names no author, so a report carrying only it would refuse the verb added last for a
|
|
1617
|
+
# size the other 51 built.
|
|
1618
|
+
#
|
|
1619
|
+
# Appended after the per-tool findings and printed before them, which is not a
|
|
1620
|
+
# contradiction left standing: every finding here is filed at `roadkeep.toml` with no
|
|
1621
|
+
# line, so `_ordered` breaks the tie on the code and `budget.session` sorts under
|
|
1622
|
+
# `budget.tool`. Left that way rather than special-cased — one address, one documented
|
|
1623
|
+
# order, and the message says no single tool is at fault, which is what a reader arriving
|
|
1624
|
+
# at it first needs to know.
|
|
1625
|
+
# `held` and not `characters` (RK1334): the handshake names which tree answered, and the
|
|
1626
|
+
# commit, the `modified` flag and the absolute path are the checkout's rather than the
|
|
1627
|
+
# surface's. Refusing the total made the verdict move with the environment, and the two
|
|
1628
|
+
# environments a gate actually runs in are the two that differ most — a pre-commit hook
|
|
1629
|
+
# always sees a dirty tree, and a CI checkout is never at the author's path.
|
|
1630
|
+
if config.tool_session is not None and sent.held > config.tool_session:
|
|
1631
|
+
out.append(
|
|
1632
|
+
Finding(
|
|
1633
|
+
"budget.session",
|
|
1634
|
+
where,
|
|
1635
|
+
f"the served surface is {sent.held} characters — {len(sent.tools)} "
|
|
1636
|
+
f"tool(s) and the handshake, less what names the checkout — against a budget "
|
|
1637
|
+
f"of {config.tool_session}: "
|
|
1638
|
+
# The ranking and not the total (RK1336): naming `--session` here restated the
|
|
1639
|
+
# figure this sentence had just given, and the reader's next act is to pick a
|
|
1640
|
+
# description. The doors beneath carry both, in the order the work goes.
|
|
1641
|
+
f"every session pays this at connect before it calls anything, and no one "
|
|
1642
|
+
f"tool is at fault — `{invocation()} cost --tools` ranks every description "
|
|
1643
|
+
f"against this ceiling and prints the room each has",
|
|
1644
|
+
subject="session",
|
|
1645
|
+
)
|
|
1646
|
+
)
|
|
1647
|
+
return out
|
|
1648
|
+
|
|
1649
|
+
|
|
1650
|
+
def _collective(config: Config, documents: dict[str, Document]) -> list[Note]:
|
|
1651
|
+
"""What a `Block X` or a range actually names, said out loud (RK35).
|
|
1652
|
+
|
|
1653
|
+
Only when it expands to **two or more** open tasks, which is precisely the case the
|
|
1654
|
+
line hides: at one there is no surprise to report, and at zero there is nothing to
|
|
1655
|
+
name — whether waiting is over there is the standing's answer and not this note's, a
|
|
1656
|
+
label with no open member being finished, paused or a heading opened before its lines,
|
|
1657
|
+
and only the first of those annotating ✅ (RK8, RK432). A note per token below that
|
|
1658
|
+
threshold would be output nobody reads, which is the failure mode RK16 exists to avoid.
|
|
1659
|
+
|
|
1660
|
+
**One row per token and not per line** (RK1299), which is RK1165's shape at the gate: a
|
|
1661
|
+
run of rows saying one thing is one row with its count. Measured on winwright the moment
|
|
1662
|
+
its first block finished — a clean `lint --json` was 25,823 characters, 42 notes, all of
|
|
1663
|
+
them this code, and between them they stated six facts; eleven lines depending on Block G
|
|
1664
|
+
contributed the same sentence eleven times, each with a `remedy` whose prose was the same
|
|
1665
|
+
78 characters. That is five times the text form of the same run, for a verdict of `clean`,
|
|
1666
|
+
on the read that runs at the end of every turn.
|
|
1667
|
+
|
|
1668
|
+
So the expansion is stated once and the lines waiting on it are named beside it. Filed at
|
|
1669
|
+
the **first** of them, which is what keeps the address real and the remedy runnable: `deps`
|
|
1670
|
+
resolves a task and not a label, so a row anchored on the token would carry a command
|
|
1671
|
+
nothing answers. The other lines are named only where there are other lines — a list of
|
|
1672
|
+
one is the id this note already carries, and printing it twice is the repetition this is.
|
|
1673
|
+
"""
|
|
1674
|
+
roadmap = documents.get("roadmap")
|
|
1675
|
+
if roadmap is None:
|
|
1676
|
+
return []
|
|
1677
|
+
backlog = Backlog.during(
|
|
1678
|
+
config,
|
|
1679
|
+
roadmap=roadmap,
|
|
1680
|
+
ledger=documents.get("changelog"),
|
|
1681
|
+
store=documents.get("deferred"),
|
|
1682
|
+
)
|
|
1683
|
+
file = config.relative(config.path("roadmap"))
|
|
1684
|
+
# Keyed by the token and in first-appearance order, which is file order: the rows a reader
|
|
1685
|
+
# scans stay in the order the lines that raised them do. The dep travels with the group
|
|
1686
|
+
# because `expand` resolves the parsed token and not the string it renders as.
|
|
1687
|
+
waiting: dict[str, tuple[object, list[str]]] = {}
|
|
1688
|
+
where: dict[str, int | None] = {}
|
|
1689
|
+
for entry in roadmap.entries:
|
|
1690
|
+
for dep in entry.task.deps:
|
|
1691
|
+
if not config.schema.classify_dep(dep).collective:
|
|
1692
|
+
continue
|
|
1693
|
+
found = waiting.setdefault(dep.id, (dep, []))
|
|
1694
|
+
found[1].append(entry.task.id)
|
|
1695
|
+
where.setdefault(dep.id, entry.lineno)
|
|
1696
|
+
out: list[Note] = []
|
|
1697
|
+
for token, (dep, ids) in waiting.items():
|
|
1698
|
+
members = backlog.expand(dep) # type: ignore[arg-type]
|
|
1699
|
+
if len(members) < 2:
|
|
1700
|
+
continue
|
|
1701
|
+
shown = ", ".join(members[:6]) + (" …" if len(members) > 6 else "")
|
|
1702
|
+
message = f"{token} is one token naming {len(members)} open tasks: {shown}"
|
|
1703
|
+
if len(ids) > 1:
|
|
1704
|
+
listed = ", ".join(ids[:6]) + (" …" if len(ids) > 6 else "")
|
|
1705
|
+
message += f" — and {len(ids)} lines wait on it: {listed}"
|
|
1706
|
+
out.append(Note("deps.collective", file, message, where[token], ids[0]))
|
|
1707
|
+
return out
|
|
1708
|
+
|
|
1709
|
+
|
|
1710
|
+
def _turned(config: Config, documents: dict[str, Document], since: str) -> list[Note]:
|
|
1711
|
+
"""A block that emptied or reopened in this change (RK269).
|
|
1712
|
+
|
|
1713
|
+
`ship` is the only verb that computes it — `event T282 Block AI finished` — and says it once,
|
|
1714
|
+
to a console. Nothing records it, no later verb can ask, and `lint` reports a clean tree
|
|
1715
|
+
either way, which is the gate an author actually trusts. Measured in a repository keeping a
|
|
1716
|
+
per-block index beside its ledger, one `(active — see ROADMAP)` per row: two ships emptied a
|
|
1717
|
+
block and two adds reopened it across four commits, every row was flipped by hand, and every
|
|
1718
|
+
time `lint` passed on the wrong one. The discrepancy was caught by that project's own test
|
|
1719
|
+
suite, which asserts the index against the roadmap because this tool does not.
|
|
1720
|
+
|
|
1721
|
+
Three shapes were open and this is the cheapest of them, which is also the one that would
|
|
1722
|
+
have caught all four. Not a query verb: `stats --json` already answers which blocks hold
|
|
1723
|
+
nothing, so a project's check can be written against roadkeep today. Not ownership of the
|
|
1724
|
+
index row either — that is a projection, and a projection roadkeep writes is `export`'s
|
|
1725
|
+
contract (RK39), which wants a declared shape rather than a guess at somebody's table.
|
|
1726
|
+
|
|
1727
|
+
Reported with ``since`` and never as a state, which is the whole reason it is quiet enough
|
|
1728
|
+
to keep: the shipped pre-commit hook runs `lint --since HEAD`, so this lands at the moment of
|
|
1729
|
+
the commit that moved it — while "Block A is empty" is true of this repository forever and a
|
|
1730
|
+
line printed forever is a line nobody reads (RK16).
|
|
1731
|
+
|
|
1732
|
+
A **note**, because emptying a block is what finishing one looks like. Only blocks *both*
|
|
1733
|
+
trees declare: one that arrived is `block add`'s own event and one that left is `block drop`,
|
|
1734
|
+
and neither is a transition of state.
|
|
1735
|
+
|
|
1736
|
+
Emptiness is `Document.holds` and nothing wider — the same *call* the event line makes and
|
|
1737
|
+
not a second spelling of it (RK300), because two answers to "is that block empty" is this
|
|
1738
|
+
defect with the arrow reversed (RK92: a deferred line is set aside, not open). The counts
|
|
1739
|
+
below are presentation and not the decision: how many lines a block held is a fact about
|
|
1740
|
+
the baseline that the event line never computes, so it is read where it is printed.
|
|
1741
|
+
"""
|
|
1742
|
+
roadmap = documents.get("roadmap")
|
|
1743
|
+
if roadmap is None:
|
|
1744
|
+
return []
|
|
1745
|
+
if not resolves(config, since):
|
|
1746
|
+
# A repository with no commits has no HEAD, which is the shipped hook's default.
|
|
1747
|
+
if since == "HEAD":
|
|
1748
|
+
return []
|
|
1749
|
+
raise HistoryUnavailable(f"{since} is not a revision this repository knows")
|
|
1750
|
+
before = Tree(config, since).document("roadmap")
|
|
1751
|
+
if before is None:
|
|
1752
|
+
return []
|
|
1753
|
+
file = config.relative(config.path("roadmap"))
|
|
1754
|
+
declared = {h.label for h in before.headings if h.label}
|
|
1755
|
+
held = {label for label in declared if before.holds(label)}
|
|
1756
|
+
out: list[Note] = []
|
|
1757
|
+
for heading in roadmap.headings:
|
|
1758
|
+
label = heading.label
|
|
1759
|
+
if label is None or label not in declared:
|
|
1760
|
+
continue
|
|
1761
|
+
now = roadmap.holds(label)
|
|
1762
|
+
if label in held and not now:
|
|
1763
|
+
out.append(
|
|
1764
|
+
Note(
|
|
1765
|
+
"block.emptied",
|
|
1766
|
+
file,
|
|
1767
|
+
f"held {len(before.block(label))} open line(s) at {since} and holds none "
|
|
1768
|
+
f"now: a projection that states which blocks are active is a row this "
|
|
1769
|
+
f"commit moves, and nothing else here will say so",
|
|
1770
|
+
heading.lineno,
|
|
1771
|
+
label,
|
|
1772
|
+
)
|
|
1773
|
+
)
|
|
1774
|
+
elif now and label not in held:
|
|
1775
|
+
out.append(
|
|
1776
|
+
Note(
|
|
1777
|
+
"block.reopened",
|
|
1778
|
+
file,
|
|
1779
|
+
f"held no open line at {since} and holds {len(roadmap.block(label))} now: "
|
|
1780
|
+
f"the same row, in the other direction",
|
|
1781
|
+
heading.lineno,
|
|
1782
|
+
label,
|
|
1783
|
+
)
|
|
1784
|
+
)
|
|
1785
|
+
return out
|
|
1786
|
+
|
|
1787
|
+
|
|
1788
|
+
def _worked(
|
|
1789
|
+
config: Config, documents: dict[str, Document], sections: tuple[Section, ...], since: str
|
|
1790
|
+
) -> list[Note]:
|
|
1791
|
+
"""Source moved under an open task while its line stood still (RK1228).
|
|
1792
|
+
|
|
1793
|
+
:func:`_unpaired` checks the shape where the *prose* moved and the line did not. This is
|
|
1794
|
+
the mirror, and it was unchecked: source can change under everything a task's section
|
|
1795
|
+
names, the tests for it can pass, and the line stays open with nobody told.
|
|
1796
|
+
|
|
1797
|
+
Observed here across a working session. A task's section named the component and the
|
|
1798
|
+
library module it needed; both were rewritten, a dozen assertions were added and passed,
|
|
1799
|
+
the outcome was reported as delivered — and `ship` was never called. `lint` said clean,
|
|
1800
|
+
because the files it governs were internally consistent, and they were: the entry simply
|
|
1801
|
+
did not exist. It surfaced two blocks later, when a block that should have been finished
|
|
1802
|
+
still counted one open line.
|
|
1803
|
+
|
|
1804
|
+
**A note and never a finding**, which is the whole judgement and the same one RK36 made: a
|
|
1805
|
+
path named in a section changes for plenty of reasons that are not the task — a rename, a
|
|
1806
|
+
neighbouring fix, a refactor that crossed it — so refusing would produce a gate that gets
|
|
1807
|
+
bypassed within a week. Saying it once, at the moment of the commit, is the whole value.
|
|
1808
|
+
|
|
1809
|
+
Nothing here is semantic. The signal is a coincidence of two facts this run already holds:
|
|
1810
|
+
the paths a section names, which `show` resolves, and the diff, which `--since` has.
|
|
1811
|
+
|
|
1812
|
+
**The block reading replaces its members** (RK1234). Per line this fires once and reads as
|
|
1813
|
+
a coincidence, which is what it is; per block it reads as a diagnosis, and saying the weak
|
|
1814
|
+
thing five times and then the strong one about the same five lines is noise. So a block
|
|
1815
|
+
that qualifies emits `block.worked` and its members emit nothing.
|
|
1816
|
+
|
|
1817
|
+
Qualifying is deliberately narrow, because the aggregate should be worth reading every
|
|
1818
|
+
time it appears. **Every** open line in the block names at least one path and every one of
|
|
1819
|
+
those lines moved: one line whose section names no path makes the block unreachable, which
|
|
1820
|
+
is the honest cost of not letting a prose-only line report on an unrelated edit. And two
|
|
1821
|
+
lines at minimum — on a block holding one, "every line moved" is the per-line note with a
|
|
1822
|
+
heading's lineno, so the members' own reading is the truer one.
|
|
1823
|
+
"""
|
|
1824
|
+
if not sections or not documents.get("roadmap"):
|
|
1825
|
+
return []
|
|
1826
|
+
from roadkeep.history import changed_paths # noqa: PLC0415 - RK260
|
|
1827
|
+
|
|
1828
|
+
moved = changed_paths(config, since)
|
|
1829
|
+
if not moved:
|
|
1830
|
+
return []
|
|
1831
|
+
roadmap = documents["roadmap"]
|
|
1832
|
+
where = config.relative(config.path("roadmap"))
|
|
1833
|
+
by_anchor = {one.anchor: one for one in sections}
|
|
1834
|
+
named_by_id: dict[str, set[str]] = {}
|
|
1835
|
+
touched_by_id: dict[str, list[str]] = {}
|
|
1836
|
+
for entry in roadmap.entries:
|
|
1837
|
+
section = by_anchor.get(entry.task.ref or entry.task.id)
|
|
1838
|
+
if section is None:
|
|
1839
|
+
continue
|
|
1840
|
+
named_by_id[entry.task.id] = {
|
|
1841
|
+
one.path
|
|
1842
|
+
for one in paths_in(
|
|
1843
|
+
section.body,
|
|
1844
|
+
config.root,
|
|
1845
|
+
near=config.path("improvements").parent
|
|
1846
|
+
if config.has("improvements")
|
|
1847
|
+
else None,
|
|
1848
|
+
known=lambda: known_directories(config),
|
|
1849
|
+
)
|
|
1850
|
+
}
|
|
1851
|
+
touched_by_id[entry.task.id] = sorted(named_by_id[entry.task.id] & moved)
|
|
1852
|
+
out: list[Note] = []
|
|
1853
|
+
aggregated: set[str] = set()
|
|
1854
|
+
for heading in roadmap.headings:
|
|
1855
|
+
label = heading.label
|
|
1856
|
+
if label is None:
|
|
1857
|
+
continue
|
|
1858
|
+
held = roadmap.block(label)
|
|
1859
|
+
if len(held) < 2:
|
|
1860
|
+
continue
|
|
1861
|
+
if not all(named_by_id.get(one.task.id) for one in held):
|
|
1862
|
+
continue
|
|
1863
|
+
if not all(touched_by_id.get(one.task.id) for one in held):
|
|
1864
|
+
continue
|
|
1865
|
+
aggregated.update(one.task.id for one in held)
|
|
1866
|
+
out.append(
|
|
1867
|
+
Note(
|
|
1868
|
+
"block.worked",
|
|
1869
|
+
where,
|
|
1870
|
+
f"this change touches a path every one of the {len(held)} open line(s) filed "
|
|
1871
|
+
f"here names, and none of them shipped — a block finished and not closed "
|
|
1872
|
+
f"looks exactly like this",
|
|
1873
|
+
heading.lineno,
|
|
1874
|
+
label,
|
|
1875
|
+
)
|
|
1876
|
+
)
|
|
1877
|
+
for entry in roadmap.entries:
|
|
1878
|
+
if entry.task.id in aggregated or not touched_by_id.get(entry.task.id):
|
|
1879
|
+
continue
|
|
1880
|
+
section = by_anchor[entry.task.ref or entry.task.id]
|
|
1881
|
+
out.append(
|
|
1882
|
+
Note(
|
|
1883
|
+
"task.worked",
|
|
1884
|
+
where,
|
|
1885
|
+
f"this change touches {', '.join(touched_by_id[entry.task.id])}, which "
|
|
1886
|
+
f"§{section.anchor} names, and the line is still open — `ship` if that is "
|
|
1887
|
+
f"what landed",
|
|
1888
|
+
entry.lineno,
|
|
1889
|
+
entry.task.id,
|
|
1890
|
+
)
|
|
1891
|
+
)
|
|
1892
|
+
# Both readings address one file, so they are reported in its order and not in the order
|
|
1893
|
+
# the two passes happened to compute them.
|
|
1894
|
+
return sorted(out, key=lambda one: one.lineno)
|
|
1895
|
+
|
|
1896
|
+
|
|
1897
|
+
def _unpaired(config: Config, sections: tuple[Section, ...], since: str) -> list[Note]:
|
|
1898
|
+
"""A rationale section edited without touching the line that carries its status (RK36).
|
|
1899
|
+
|
|
1900
|
+
RK15 refuses a pointer at a section that does not exist; this is the mirror, and the
|
|
1901
|
+
more expensive direction: the line is the only thing `pick` reads and the section is
|
|
1902
|
+
deleted on ship, so a requirement written only into the rationale cannot be picked,
|
|
1903
|
+
cannot be shipped, and leaves with the section that held it. It happened three times in
|
|
1904
|
+
one session here, every time by an author who had just learned something and wrote it
|
|
1905
|
+
where the reasoning was rather than where the status is.
|
|
1906
|
+
|
|
1907
|
+
A **note**, not a finding, and this is the whole judgement: the check cannot tell a
|
|
1908
|
+
typo in a paragraph from a smuggled requirement, and a gate that failed every honest
|
|
1909
|
+
rationale edit would be bypassed within a week — which is worth less than a sentence
|
|
1910
|
+
read at the moment of the commit. It is deliberately not semantic (§RK36 says so): the
|
|
1911
|
+
signal is that the section was open and the line was not.
|
|
1912
|
+
"""
|
|
1913
|
+
if not resolves(config, since):
|
|
1914
|
+
# A repository with no commits has no HEAD, which is the shipped hook's default —
|
|
1915
|
+
# so the initial commit is not the thing this fails on.
|
|
1916
|
+
if since == "HEAD":
|
|
1917
|
+
return []
|
|
1918
|
+
raise HistoryUnavailable(f"{since} is not a revision this repository knows")
|
|
1919
|
+
|
|
1920
|
+
edited = touched_since(config, since, "improvements")
|
|
1921
|
+
if not edited.changes:
|
|
1922
|
+
return []
|
|
1923
|
+
ids = config.schema.id_pattern()
|
|
1924
|
+
mentioned = re.compile(rf"\*\*({config.schema.id_fragment})\*\*")
|
|
1925
|
+
touched_ids = {
|
|
1926
|
+
found
|
|
1927
|
+
for role in LINE_ROLES
|
|
1928
|
+
for line in touched_since(config, since, role).lines
|
|
1929
|
+
for found in mentioned.findall(line)
|
|
1930
|
+
}
|
|
1931
|
+
# The file as it was, so a *removal* is attributed to the section that held it. Without
|
|
1932
|
+
# this a deleted section lands in whichever one now precedes the hole — and the section
|
|
1933
|
+
# `ship` just deleted would be reported against its innocent neighbour every time.
|
|
1934
|
+
before = anchored(
|
|
1935
|
+
Document.parse(content_at(config, since, "improvements"), schema=config.schema)
|
|
1936
|
+
)
|
|
1937
|
+
|
|
1938
|
+
opened: set[str] = set()
|
|
1939
|
+
for change in edited.changes:
|
|
1940
|
+
if not change.text.strip():
|
|
1941
|
+
# A blank belongs to no section's prose, and counting it would attribute an
|
|
1942
|
+
# appended section to the one whose trailing blank line it starts on.
|
|
1943
|
+
continue
|
|
1944
|
+
anchor = _section_at(sections if change.added else before, change.lineno)
|
|
1945
|
+
if anchor is not None:
|
|
1946
|
+
opened.add(anchor)
|
|
1947
|
+
|
|
1948
|
+
here = {section.anchor: section for section in sections}
|
|
1949
|
+
out: list[Note] = []
|
|
1950
|
+
for anchor in sorted(opened):
|
|
1951
|
+
section = here.get(anchor)
|
|
1952
|
+
if section is None or not ids.match(anchor) or anchor in touched_ids:
|
|
1953
|
+
continue
|
|
1954
|
+
out.append(
|
|
1955
|
+
Note(
|
|
1956
|
+
"section.unpaired",
|
|
1957
|
+
config.relative(config.path("improvements")),
|
|
1958
|
+
f"§{anchor} was edited and {anchor}'s line was not: the line is the only "
|
|
1959
|
+
f"thing `pick` reads, and this section is deleted on ship — so a "
|
|
1960
|
+
f"requirement written only here goes with it",
|
|
1961
|
+
section.first,
|
|
1962
|
+
anchor,
|
|
1963
|
+
)
|
|
1964
|
+
)
|
|
1965
|
+
return out
|
|
1966
|
+
|
|
1967
|
+
|
|
1968
|
+
def _section_at(sections: tuple[Section, ...], lineno: int) -> str | None:
|
|
1969
|
+
"""The anchor whose span holds this line, or None for prose under no anchor."""
|
|
1970
|
+
return next(
|
|
1971
|
+
(s.anchor for s in sections if s.first <= lineno <= s.last),
|
|
1972
|
+
None,
|
|
1973
|
+
)
|
|
1974
|
+
|
|
1975
|
+
|
|
1976
|
+
def characters_in(config: Config, role: str, document: Document) -> list[Finding]:
|
|
1977
|
+
"""The byte-level walk over one file, for a caller that holds only that file (RK1351).
|
|
1978
|
+
|
|
1979
|
+
`within` is not the place, which one run of the corpora settled: the merge driver gates
|
|
1980
|
+
its **own output** with it, and folding this in made a merge of Shio's rationale file with
|
|
1981
|
+
itself refuse over a variation selector that was already there. A defect the driver
|
|
1982
|
+
inherited is not one it introduced, and a project that cannot merge until it cleans a
|
|
1983
|
+
codepoint is a worse answer than the blindness.
|
|
1984
|
+
|
|
1985
|
+
So the estimate asks for it by name. `adopt` prices what adoption costs, and a BOM the
|
|
1986
|
+
fixer closes with no decision is a cost — `lint` on the same bytes reported `char.bom` and
|
|
1987
|
+
named `--fix` while the estimate named it nothing at all.
|
|
1988
|
+
"""
|
|
1989
|
+
return _characters(config, role, document)
|
|
1990
|
+
|
|
1991
|
+
|
|
1992
|
+
def resolving(config: Config, role: str, roadmap: Document) -> list[Finding]:
|
|
1993
|
+
"""The dep questions one file cannot answer, asked of a candidate roadmap (RK1353).
|
|
1994
|
+
|
|
1995
|
+
`within` is *everything decidable from one file alone*, and whether a dep names a line
|
|
1996
|
+
the backlog carries is not: it needs the roadmap, the ledger and the store together. So
|
|
1997
|
+
the merge driver — which holds three versions of one path and gates what it composed —
|
|
1998
|
+
could not see the one class a merge is uniquely able to create. Measured: one branch adds
|
|
1999
|
+
`RK3 (deps: RK2)` while the other removes `RK2`, and the merged file, held by neither
|
|
2000
|
+
side, lands clean and fails `lint` afterwards.
|
|
2001
|
+
|
|
2002
|
+
The candidate stands in for the roadmap and the other roles are read from disk, which is
|
|
2003
|
+
where a merge runs: git calls a driver in a worktree, so the ledger and the store are the
|
|
2004
|
+
committed ones. `_present` answers `None` for a role that is undeclared or not yet
|
|
2005
|
+
written, so a project holding only a roadmap asks a narrower question rather than failing
|
|
2006
|
+
— the same tolerance `Backlog.load` gives every other reader.
|
|
2007
|
+
|
|
2008
|
+
Roadmap only, deliberately: a ledger entry carries no deps, so asking would be composing
|
|
2009
|
+
a question the grammar has no field for.
|
|
2010
|
+
"""
|
|
2011
|
+
from roadkeep.backlog import Backlog, _present # noqa: PLC0415 - RK260's edge back
|
|
2012
|
+
|
|
2013
|
+
if role != "roadmap":
|
|
2014
|
+
return []
|
|
2015
|
+
backlog = Backlog(
|
|
2016
|
+
config=config,
|
|
2017
|
+
roadmap=roadmap,
|
|
2018
|
+
ledger=_present(config, "changelog"),
|
|
2019
|
+
store=_present(config, "deferred"),
|
|
2020
|
+
)
|
|
2021
|
+
file = config.relative(config.path(role))
|
|
2022
|
+
# All four kinds and not the three `_deps` holds (RK1354). A cycle is the purer case of
|
|
2023
|
+
# what only a merge writes: a dangling dep is visible on the branch that wrote it, as a
|
|
2024
|
+
# dep on an id that branch does not carry, while a cycle is well-formed on both sides and
|
|
2025
|
+
# exists in the merged file alone — a state neither author can review, neither having had
|
|
2026
|
+
# it. Measured: one branch adding `RK2 (deps: RK3)` and the other `RK3 (deps: RK2)` merged
|
|
2027
|
+
# clean and linted `deps.cycle`. The group's id is stable — the same cycle answers `RK2`
|
|
2028
|
+
# with or without a line above it — so an inherited one is still told from a composed one.
|
|
2029
|
+
return [
|
|
2030
|
+
*(
|
|
2031
|
+
found
|
|
2032
|
+
for entry in roadmap.entries
|
|
2033
|
+
for found in _deps(backlog, entry.task, file, entry.lineno)
|
|
2034
|
+
),
|
|
2035
|
+
*_cycles(backlog, file),
|
|
2036
|
+
]
|
|
2037
|
+
|
|
2038
|
+
|
|
2039
|
+
def _voided(document: Document) -> bool:
|
|
2040
|
+
"""Whether this file's every byte is NUL — the shape a lost write leaves (RK451).
|
|
2041
|
+
|
|
2042
|
+
Not a heuristic about looking binary, which would be a judgement about files this tool
|
|
2043
|
+
did not write. The decidable question is narrower and is the one the failure produces:
|
|
2044
|
+
RK118 wrote every byte of a governed file, and none of them was ever a NUL, so a file
|
|
2045
|
+
that is nothing but NUL is one whose content did not reach the disk. An empty file is a
|
|
2046
|
+
different state — a scaffold before its first line — and stays the gate's other business.
|
|
2047
|
+
"""
|
|
2048
|
+
if not document.lines:
|
|
2049
|
+
return False
|
|
2050
|
+
return all(character == "\x00" for line in document.lines for character in line)
|
|
2051
|
+
|
|
2052
|
+
|
|
2053
|
+
def _absent(config: Config, tree: Tree) -> list[Finding]:
|
|
2054
|
+
"""A declared file that is not on disk (`init` creates it: RK18).
|
|
2055
|
+
|
|
2056
|
+
Asked of the tree and not of disk, so a baseline says *was it there then*: a governed
|
|
2057
|
+
file deleted since the ref is a finding this change made, and one added since is a file
|
|
2058
|
+
the ref cannot be asked to account for.
|
|
2059
|
+
"""
|
|
2060
|
+
return [
|
|
2061
|
+
Finding(
|
|
2062
|
+
"file.missing",
|
|
2063
|
+
config.relative(config.path(role)),
|
|
2064
|
+
f"declared as the {role} file and not on disk",
|
|
2065
|
+
)
|
|
2066
|
+
for role in ROLES
|
|
2067
|
+
if config.has(role) and not tree.present(config.path(role))
|
|
2068
|
+
]
|
|
2069
|
+
|
|
2070
|
+
|
|
2071
|
+
def within(config: Config, role: str, document: Document) -> list[Finding]:
|
|
2072
|
+
"""Everything decidable from one file alone.
|
|
2073
|
+
|
|
2074
|
+
Public because the merge driver gates its own output with it (RK120): a driver holds
|
|
2075
|
+
three versions of one file and none of the others, so this is exactly the half of the
|
|
2076
|
+
gate it can run — and a second statement of these rules would be a second gate to keep
|
|
2077
|
+
in step with this one.
|
|
2078
|
+
"""
|
|
2079
|
+
file = config.relative(config.path(role))
|
|
2080
|
+
out: list[Finding] = []
|
|
2081
|
+
|
|
2082
|
+
# Before the line reader (RK451, RK454). A NUL in a governed file is a **lost write**
|
|
2083
|
+
# and not a character somebody typed: RK118 wrote every byte of this file and none of
|
|
2084
|
+
# them was ever one, so the diagnosis `char.invisible` gives is wrong in kind and the
|
|
2085
|
+
# `--fix` it names is worse — on a file a crash left entirely NUL that pass would strip
|
|
2086
|
+
# every byte and report the tree clean, and on a partly-lost one it claims all 400
|
|
2087
|
+
# findings, writes nothing, and returns the identical report on the next run.
|
|
2088
|
+
#
|
|
2089
|
+
# So the file states it once. Whole-file rather than per-byte because the loss is,
|
|
2090
|
+
# and because a column is a fact about a line that no longer says anything.
|
|
2091
|
+
lost = sum(line.count("\x00") for line in document.lines)
|
|
2092
|
+
if lost:
|
|
2093
|
+
held = sum(len(line) for line in document.lines)
|
|
2094
|
+
out.append(
|
|
2095
|
+
Finding(
|
|
2096
|
+
"file.not-text",
|
|
2097
|
+
file,
|
|
2098
|
+
(
|
|
2099
|
+
f"holds {held} character(s) and not one of them is text: every byte is "
|
|
2100
|
+
f"NUL"
|
|
2101
|
+
if lost == held
|
|
2102
|
+
else f"holds {lost} NUL byte(s) among its {held} character(s)"
|
|
2103
|
+
)
|
|
2104
|
+
+ ", which is what a crash between a write and its rename leaves — the "
|
|
2105
|
+
"content is gone rather than malformed",
|
|
2106
|
+
)
|
|
2107
|
+
)
|
|
2108
|
+
# Nothing below can read a file with no text in it, and every rule here asks what a
|
|
2109
|
+
# *line* says. A file that kept some of its lines is a different answer (RK454): its
|
|
2110
|
+
# surviving lines have defects of their own, and hiding them would answer a question
|
|
2111
|
+
# nobody asked.
|
|
2112
|
+
if lost == held:
|
|
2113
|
+
return out
|
|
2114
|
+
|
|
2115
|
+
for reject in document.rejects:
|
|
2116
|
+
# The line the parser could not read at all. It is reported here and counted
|
|
2117
|
+
# nowhere else, which is the difference between `audit` and a gate.
|
|
2118
|
+
out.append(Finding("line.unparsed", file, reject.reason, reject.lineno))
|
|
2119
|
+
|
|
2120
|
+
seen: dict[str, int] = {}
|
|
2121
|
+
for entry in document.entries:
|
|
2122
|
+
task = entry.task
|
|
2123
|
+
for violation in document.schema.validate(task):
|
|
2124
|
+
if violation.code in _SCANNED:
|
|
2125
|
+
# RK499 put the codepoint rule at the door too, and `_characters` already
|
|
2126
|
+
# walks every line of this file for it — so surfacing both would report one
|
|
2127
|
+
# tab twice under one code, at two different numbers: a position inside a
|
|
2128
|
+
# field, and the column of the line. The scan's is what a report is read
|
|
2129
|
+
# for, and the schema's is what a *refusal* is read for.
|
|
2130
|
+
continue
|
|
2131
|
+
out.append(
|
|
2132
|
+
Finding(violation.code, file, violation.message, entry.lineno, task.id)
|
|
2133
|
+
)
|
|
2134
|
+
canonical = document.schema.render(task)
|
|
2135
|
+
if canonical != entry.raw:
|
|
2136
|
+
# Named, not fixed (L3): the tool may not rewrite a line it might have
|
|
2137
|
+
# misread, so the report carries the rendering and the edit stays a human's.
|
|
2138
|
+
out.append(
|
|
2139
|
+
Finding(
|
|
2140
|
+
"line.non-canonical",
|
|
2141
|
+
file,
|
|
2142
|
+
f"written differently from what the schema renders: {canonical!r}",
|
|
2143
|
+
entry.lineno,
|
|
2144
|
+
task.id,
|
|
2145
|
+
)
|
|
2146
|
+
)
|
|
2147
|
+
if task.id in config.reserved:
|
|
2148
|
+
# The check that RK1031 is a fix and not a suppression. A reservation says the
|
|
2149
|
+
# address is spoken for and never written as a line; a line that carries one is
|
|
2150
|
+
# the two statements disagreeing, and the deriver has been handing out numbers
|
|
2151
|
+
# past it on the strength of the declaration.
|
|
2152
|
+
out.append(
|
|
2153
|
+
Finding(
|
|
2154
|
+
"id.reserved",
|
|
2155
|
+
file,
|
|
2156
|
+
"declared in `reserved_ids` and written here as a line: a reservation "
|
|
2157
|
+
"is an address nothing carries, so one of the two has to go",
|
|
2158
|
+
entry.lineno,
|
|
2159
|
+
task.id,
|
|
2160
|
+
)
|
|
2161
|
+
)
|
|
2162
|
+
first = seen.get(task.id)
|
|
2163
|
+
if first is not None:
|
|
2164
|
+
out.append(
|
|
2165
|
+
Finding(
|
|
2166
|
+
"id.duplicate",
|
|
2167
|
+
file,
|
|
2168
|
+
f"already carried by line {first}: two lines with one id are two "
|
|
2169
|
+
f"answers to whether it is done",
|
|
2170
|
+
entry.lineno,
|
|
2171
|
+
task.id,
|
|
2172
|
+
)
|
|
2173
|
+
)
|
|
2174
|
+
seen.setdefault(task.id, entry.lineno)
|
|
2175
|
+
return out
|
|
2176
|
+
|
|
2177
|
+
|
|
2178
|
+
def _scope(config: Config, roadmap: Document | None) -> list[Finding]:
|
|
2179
|
+
"""The non-goals, for a project that declared them governed (RK70).
|
|
2180
|
+
|
|
2181
|
+
Silent otherwise, and that is the whole of the opt-in: two live corpora wrote their lists
|
|
2182
|
+
as free prose years before this grammar existed, and a gate that reported fifteen findings
|
|
2183
|
+
on the first run is a gate that gets bypassed rather than adopted (RK66).
|
|
2184
|
+
|
|
2185
|
+
What is judged is what the schema can judge — the shape, the two lengths, and a lead
|
|
2186
|
+
claimed twice. Not the wrap: a filled bullet is written at insertion (L1) and a
|
|
2187
|
+
hand-wrapped one is whitespace inside prose, which `--fix` is the door for (RK16).
|
|
2188
|
+
"""
|
|
2189
|
+
if roadmap is None or config.non_goals is None:
|
|
2190
|
+
return []
|
|
2191
|
+
file = config.relative(config.path("roadmap"))
|
|
2192
|
+
out: list[Finding] = []
|
|
2193
|
+
for lineno, raw in scoping.rejects(roadmap):
|
|
2194
|
+
out.append(
|
|
2195
|
+
Finding(
|
|
2196
|
+
scoping.SHAPE,
|
|
2197
|
+
file,
|
|
2198
|
+
f"a governed non-goal is `- **<lead>** <why>`, so this bullet has no lead "
|
|
2199
|
+
f"to be addressed by: {raw.strip()[:60]!r}",
|
|
2200
|
+
lineno,
|
|
2201
|
+
# The **lead as this file reads it** (RK1266), which is the address every
|
|
2202
|
+
# door here takes: `scoping` gives an unshaped bullet one on purpose, so the
|
|
2203
|
+
# remedy is a complete command rather than a blank.
|
|
2204
|
+
subject=_led(roadmap, lineno),
|
|
2205
|
+
)
|
|
2206
|
+
)
|
|
2207
|
+
seen: dict[str, int] = {}
|
|
2208
|
+
for non_goal in scoping.read(roadmap):
|
|
2209
|
+
# The two lengths, only where the shape held (RK233). A bullet the reader now returns
|
|
2210
|
+
# unshaped already carries the finding above, whose remedy is the rewrite — charging
|
|
2211
|
+
# its sentence-lead against `lead` on top of that is a second finding the first one
|
|
2212
|
+
# subsumes, and Turing's `is **not** a path` would add a third for the `*` a bold run
|
|
2213
|
+
# this module never wrote is made of.
|
|
2214
|
+
if non_goal.shaped:
|
|
2215
|
+
for violation in scoping.validate(config, non_goal.lead, non_goal.why):
|
|
2216
|
+
out.append(
|
|
2217
|
+
Finding(
|
|
2218
|
+
violation.code,
|
|
2219
|
+
file,
|
|
2220
|
+
violation.message,
|
|
2221
|
+
non_goal.first,
|
|
2222
|
+
subject=non_goal.lead,
|
|
2223
|
+
)
|
|
2224
|
+
)
|
|
2225
|
+
# The address is checked for every bullet, because every bullet now has one: two
|
|
2226
|
+
# constraints a reader looks up by the same words are two answers about one scope
|
|
2227
|
+
# whichever shape they are written in, and `drop` would take the later one either way.
|
|
2228
|
+
lead = scoping.address(non_goal.lead)
|
|
2229
|
+
first = seen.get(lead)
|
|
2230
|
+
if first is not None:
|
|
2231
|
+
out.append(
|
|
2232
|
+
Finding(
|
|
2233
|
+
"non-goal.duplicate",
|
|
2234
|
+
file,
|
|
2235
|
+
f"already led on line {first}: the lead is the address, so two bullets "
|
|
2236
|
+
f"carrying it are two answers about one scope",
|
|
2237
|
+
non_goal.first,
|
|
2238
|
+
subject=non_goal.lead,
|
|
2239
|
+
)
|
|
2240
|
+
)
|
|
2241
|
+
seen.setdefault(lead, non_goal.first)
|
|
2242
|
+
return out
|
|
2243
|
+
|
|
2244
|
+
|
|
2245
|
+
def _criteria(
|
|
2246
|
+
config: Config, roadmap: Document | None, documents: dict[str, Document]
|
|
2247
|
+
) -> list[Finding]:
|
|
2248
|
+
"""The criteria, for a project that declared them governed (RK1265).
|
|
2249
|
+
|
|
2250
|
+
:func:`_scope`'s three checks one list over, and silent otherwise for its reason: an
|
|
2251
|
+
adopting project's `Done when` prose was written before this grammar, and a gate that
|
|
2252
|
+
reported on it before anybody opted in is a gate that gets bypassed.
|
|
2253
|
+
|
|
2254
|
+
The address is the **pair** here, so a lead is judged against the leads of its own list: a
|
|
2255
|
+
criterion reading "Every write has a door" under two blocks is two claims about two bodies
|
|
2256
|
+
of work and not one written twice, which is the one place this differs from the non-goals
|
|
2257
|
+
and the reason the seen-set is keyed by both. A task's list is the same pair with an id in
|
|
2258
|
+
it (RK1268), and keys the same way for the same reason.
|
|
2259
|
+
"""
|
|
2260
|
+
if roadmap is None or config.criteria is None:
|
|
2261
|
+
return []
|
|
2262
|
+
file = config.relative(config.path("roadmap"))
|
|
2263
|
+
out: list[Finding] = []
|
|
2264
|
+
for lineno, raw in criteria.rejects(roadmap):
|
|
2265
|
+
out.append(
|
|
2266
|
+
Finding(
|
|
2267
|
+
criteria.SHAPE,
|
|
2268
|
+
file,
|
|
2269
|
+
f"a governed criterion is `- **<lead>** <why>`, so this bullet has no lead "
|
|
2270
|
+
f"to be addressed by: {raw.strip()[:60]!r}",
|
|
2271
|
+
lineno,
|
|
2272
|
+
# The **lead as this file reads it**, which is the address every door here
|
|
2273
|
+
# takes (RK420): where the shape did not hold, `criteria` still gives the
|
|
2274
|
+
# bullet one, so the remedy is a complete command rather than a blank.
|
|
2275
|
+
subject=_leading(roadmap, lineno),
|
|
2276
|
+
)
|
|
2277
|
+
)
|
|
2278
|
+
seen: dict[tuple[str, str], int] = {}
|
|
2279
|
+
for one in criteria.read(roadmap):
|
|
2280
|
+
# The two lengths, only where the shape held — `_scope`'s rule and its whole argument:
|
|
2281
|
+
# the unshaped bullet already carries the finding above, whose remedy is the rewrite.
|
|
2282
|
+
if one.shaped:
|
|
2283
|
+
for violation in criteria.validate(config, one.lead, one.why):
|
|
2284
|
+
out.append(
|
|
2285
|
+
Finding(
|
|
2286
|
+
violation.code,
|
|
2287
|
+
file,
|
|
2288
|
+
violation.message,
|
|
2289
|
+
one.first,
|
|
2290
|
+
subject=one.lead,
|
|
2291
|
+
)
|
|
2292
|
+
)
|
|
2293
|
+
address = (one.about, criteria.address(one.lead))
|
|
2294
|
+
first = seen.get(address)
|
|
2295
|
+
if first is not None:
|
|
2296
|
+
out.append(
|
|
2297
|
+
Finding(
|
|
2298
|
+
"criterion.duplicate",
|
|
2299
|
+
file,
|
|
2300
|
+
f"already led on line {first} under "
|
|
2301
|
+
f"{criteria.named(config.schema, one.about)}: the lead is the "
|
|
2302
|
+
f"address, so two bullets carrying it are two answers about one claim",
|
|
2303
|
+
one.first,
|
|
2304
|
+
subject=one.lead,
|
|
2305
|
+
)
|
|
2306
|
+
)
|
|
2307
|
+
seen.setdefault(address, one.first)
|
|
2308
|
+
return out + _orphaned(config, roadmap, documents, file)
|
|
2309
|
+
|
|
2310
|
+
|
|
2311
|
+
def _orphaned(
|
|
2312
|
+
config: Config, roadmap: Document, documents: dict[str, Document], file: str
|
|
2313
|
+
) -> list[Finding]:
|
|
2314
|
+
"""A `Done when` list whose address stopped existing (RK1318).
|
|
2315
|
+
|
|
2316
|
+
The gate reads what a schema can read — shape, the two lengths, a lead stated twice inside
|
|
2317
|
+
one list — and never whether the block or the id it is addressed to is still there.
|
|
2318
|
+
`criteria._addressed` validates that at the write, which is L1 and right; nothing re-asks
|
|
2319
|
+
once the address has gone, and the write path cannot, the block having been there when the
|
|
2320
|
+
bullet was written.
|
|
2321
|
+
|
|
2322
|
+
Two states reached it, and both are closed at their own door now: `block drop` withdrawing
|
|
2323
|
+
a label whose list stayed (RK1316), and `renumber` spending the id a list is addressed to
|
|
2324
|
+
(RK1317). So this is the **backstop** those two make rare and never impossible — a hand
|
|
2325
|
+
edit, a textual merge, a tree governed before either of them shipped.
|
|
2326
|
+
|
|
2327
|
+
One finding per **region** and not per bullet, filed at the heading: what is orphaned is
|
|
2328
|
+
the list, and a bullet under it is not wrong about anything. The subject is the first
|
|
2329
|
+
lead, because the door is `criterion drop <lead>` *bare* — the addressed form is refused,
|
|
2330
|
+
the address being exactly what stopped existing, so a remedy spelling `--block` would name
|
|
2331
|
+
a command that cannot run (RK16). A region the last drop leaves empty carries no lead and
|
|
2332
|
+
therefore no door: the heading survives its bullets by design (RK1265), and `--fix` is what
|
|
2333
|
+
takes that one.
|
|
2334
|
+
"""
|
|
2335
|
+
backlog = Backlog.during(
|
|
2336
|
+
config,
|
|
2337
|
+
roadmap=roadmap,
|
|
2338
|
+
ledger=documents.get("changelog"),
|
|
2339
|
+
store=documents.get("deferred"),
|
|
2340
|
+
)
|
|
2341
|
+
labels = backlog.declared_blocks()
|
|
2342
|
+
open_ids = {entry.task.id for entry in roadmap.entries}
|
|
2343
|
+
if documents.get("deferred") is not None:
|
|
2344
|
+
# A paused line still exists and a `resume` brings it back, so its list is not an
|
|
2345
|
+
# orphan — the address is spent by a departure and never by setting work aside (RK92).
|
|
2346
|
+
open_ids |= {entry.task.id for entry in documents["deferred"].entries}
|
|
2347
|
+
out: list[Finding] = []
|
|
2348
|
+
for at, about in criteria._regions(roadmap): # noqa: SLF001 - the region reader is its own
|
|
2349
|
+
addresses_task = criteria.addresses_task(config.schema, about)
|
|
2350
|
+
if about in (open_ids if addresses_task else labels):
|
|
2351
|
+
continue
|
|
2352
|
+
named = criteria.named(config.schema, about)
|
|
2353
|
+
held = criteria.read(roadmap, about)
|
|
2354
|
+
out.append(
|
|
2355
|
+
Finding(
|
|
2356
|
+
"criterion.orphan",
|
|
2357
|
+
file,
|
|
2358
|
+
f"nothing answers {named} any more, so this list asks what would finish work "
|
|
2359
|
+
f"that has "
|
|
2360
|
+
+ ("left the backlog" if addresses_task else "no heading in any file")
|
|
2361
|
+
+ ": a criterion is addressed by the pair, and half of it is gone",
|
|
2362
|
+
at + 1,
|
|
2363
|
+
# The lead of the first bullet, which is what the bare `criterion drop` takes.
|
|
2364
|
+
# Empty where the region has none, and the remedy table answers no door for a
|
|
2365
|
+
# blank subject — which is the state `--fix` is for.
|
|
2366
|
+
subject=held[0].lead if held else "",
|
|
2367
|
+
)
|
|
2368
|
+
)
|
|
2369
|
+
return out
|
|
2370
|
+
|
|
2371
|
+
|
|
2372
|
+
def _led(roadmap: Document, lineno: int) -> str:
|
|
2373
|
+
"""The lead of the non-goal at this line, for the door a shape finding names (RK1266).
|
|
2374
|
+
|
|
2375
|
+
:func:`_leading`'s twin one list over, and read back for its reason: `scoping.rejects`
|
|
2376
|
+
answers the gate's question — which bullets are unshaped — and the address is a second
|
|
2377
|
+
question the same records already hold.
|
|
2378
|
+
"""
|
|
2379
|
+
return next((one.lead for one in scoping.read(roadmap) if one.first == lineno), "")
|
|
2380
|
+
|
|
2381
|
+
|
|
2382
|
+
def _leading(roadmap: Document, lineno: int) -> str:
|
|
2383
|
+
"""The lead of the criterion at this line, for the door a shape finding names (RK1265).
|
|
2384
|
+
|
|
2385
|
+
Read back rather than threaded through :func:`criteria.rejects`: that reader answers the
|
|
2386
|
+
gate's question — which bullets are unshaped — and the address is a second question the
|
|
2387
|
+
same records already hold.
|
|
2388
|
+
"""
|
|
2389
|
+
return next((one.lead for one in criteria.read(roadmap) if one.first == lineno), "")
|
|
2390
|
+
|
|
2391
|
+
|
|
2392
|
+
def _configured(config: Config) -> str:
|
|
2393
|
+
"""Where a finding about `roadkeep.toml`'s own keys goes, as the project spells it.
|
|
2394
|
+
|
|
2395
|
+
One expression, because :attr:`Report.checked` names this file and `_queue` files against
|
|
2396
|
+
it: two spellings of the same path is a count and a finding disagreeing (RK354).
|
|
2397
|
+
"""
|
|
2398
|
+
return config.relative(config.source) if config.source else "roadkeep.toml"
|
|
2399
|
+
|
|
2400
|
+
|
|
2401
|
+
def _queue(
|
|
2402
|
+
config: Config, documents: dict[str, Document]
|
|
2403
|
+
) -> tuple[list[Finding], list[Note]]:
|
|
2404
|
+
"""Every entry in the queue that outranks the id order, resolved (RK326).
|
|
2405
|
+
|
|
2406
|
+
`Config._check_priority` types a token and stops there, a config parser having no
|
|
2407
|
+
roadmap to resolve it against — so `priority = ["QQ1", "Block Z", "QQ9"]` with QQ1
|
|
2408
|
+
shipped, no heading declaring Z and QQ9 in no file lints clean, while `pick` answers
|
|
2409
|
+
"the declared priority names nothing ready": one sentence covering three deaths and
|
|
2410
|
+
naming none. Written as deps, two of those tokens are already findings here.
|
|
2411
|
+
|
|
2412
|
+
Since RK325 the list is in the roadmap, so the resolution is the one
|
|
2413
|
+
:class:`~roadkeep.backlog.Backlog` already does and the codes are the states a token
|
|
2414
|
+
can be **dead** in: shipped, retired, set aside, naming nothing, and naming a block
|
|
2415
|
+
whose every line has left or is set aside — plus one named twice, which is two answers
|
|
2416
|
+
about where the same work sits. At `file:line:column` like everything else (RK34).
|
|
2417
|
+
|
|
2418
|
+
Two states are deliberately **not** findings. An entry naming a merely blocked task is
|
|
2419
|
+
a queue doing its job — that is what a queue is *for* — and a declared block holding
|
|
2420
|
+
nothing **yet** is legitimate, `block add` writing the heading before the lines. Which
|
|
2421
|
+
of those a label is in is :class:`~roadkeep.backlog.Stage`'s answer and not this
|
|
2422
|
+
module's (RK434); what stays here is which code and which tier each state costs a queue.
|
|
2423
|
+
|
|
2424
|
+
And a `priority` still in `roadkeep.toml` beside a section that now holds the order is
|
|
2425
|
+
the third note: it is read (:func:`~roadkeep.queueing.declared` says the section wins),
|
|
2426
|
+
and a queue quietly coming from the other file is the failure RK325 is about.
|
|
2427
|
+
|
|
2428
|
+
A queue the **config** declares is resolved too, against `roadkeep.toml` and without a
|
|
2429
|
+
line: that is where the defect was measured, and a project that has not written the
|
|
2430
|
+
section is exactly the one whose queue nothing else reads.
|
|
2431
|
+
"""
|
|
2432
|
+
roadmap = documents.get("roadmap")
|
|
2433
|
+
if roadmap is None:
|
|
2434
|
+
return [], []
|
|
2435
|
+
backlog = Backlog.during(
|
|
2436
|
+
config,
|
|
2437
|
+
roadmap=roadmap,
|
|
2438
|
+
ledger=documents.get("changelog"),
|
|
2439
|
+
store=documents.get("deferred"),
|
|
2440
|
+
)
|
|
2441
|
+
file = config.relative(config.path("roadmap"))
|
|
2442
|
+
found = queueing.read(roadmap, config)
|
|
2443
|
+
|
|
2444
|
+
out: list[Finding] = []
|
|
2445
|
+
notes: list[Note] = []
|
|
2446
|
+
# A line the task grammar already read is that reader's (RK1357), which is the decision
|
|
2447
|
+
# RK1355 recorded and the queue's own verbs already keep: `priority list` prints such a
|
|
2448
|
+
# line as `unread` rather than as an entry, and `priority drop` pointed at it refuses.
|
|
2449
|
+
# Only the finding claimed it — *a malformed entry of mine* — beside the `block.missing`
|
|
2450
|
+
# that says what actually happened, so the gate and the read disagreed about one line.
|
|
2451
|
+
#
|
|
2452
|
+
# Filtered here and never in `queueing.read`: the reject is what makes the `unread` row,
|
|
2453
|
+
# and a queue holding a line it cannot read is worth saying. What is dropped is the claim
|
|
2454
|
+
# that the line is a defective entry, not the report that it is sitting there.
|
|
2455
|
+
claimed = {entry.lineno for entry in roadmap.entries}
|
|
2456
|
+
for lineno, raw in found.rejects:
|
|
2457
|
+
if lineno in claimed:
|
|
2458
|
+
continue
|
|
2459
|
+
out.append(
|
|
2460
|
+
Finding(
|
|
2461
|
+
"priority.shape",
|
|
2462
|
+
file,
|
|
2463
|
+
f"a queue entry is `- <id>` or `- Block X` and nothing else, so this "
|
|
2464
|
+
f"bullet addresses no work: {raw.strip()[:60]!r}",
|
|
2465
|
+
lineno,
|
|
2466
|
+
)
|
|
2467
|
+
)
|
|
2468
|
+
|
|
2469
|
+
if found.declared_in:
|
|
2470
|
+
if config.priority:
|
|
2471
|
+
notes.append(
|
|
2472
|
+
Note(
|
|
2473
|
+
"priority.config",
|
|
2474
|
+
_configured(config),
|
|
2475
|
+
f"declares priority = {list(config.priority)} while "
|
|
2476
|
+
f"{file} holds the queue: the section wins, so the config's order is "
|
|
2477
|
+
f"read by nothing and `priority drop` cannot reach it",
|
|
2478
|
+
)
|
|
2479
|
+
)
|
|
2480
|
+
places = [
|
|
2481
|
+
(entry.token, entry.lineno, entry.raw.index(entry.token) + 1)
|
|
2482
|
+
for entry in queueing.entries(roadmap, config)
|
|
2483
|
+
]
|
|
2484
|
+
else:
|
|
2485
|
+
file = _configured(config)
|
|
2486
|
+
places = [(token, None, None) for token in config.priority]
|
|
2487
|
+
|
|
2488
|
+
seen: dict[str, int | None] = {}
|
|
2489
|
+
for token, lineno, column in places:
|
|
2490
|
+
if token in seen:
|
|
2491
|
+
first = f" on line {seen[token]}" if seen[token] else ""
|
|
2492
|
+
out.append(
|
|
2493
|
+
Finding(
|
|
2494
|
+
"priority.duplicate",
|
|
2495
|
+
file,
|
|
2496
|
+
f"{token} is already queued{first}: an entry is an address, so a "
|
|
2497
|
+
f"second one is two answers about where the same work sits",
|
|
2498
|
+
lineno,
|
|
2499
|
+
subject=token,
|
|
2500
|
+
column=column,
|
|
2501
|
+
)
|
|
2502
|
+
)
|
|
2503
|
+
continue
|
|
2504
|
+
seen[token] = lineno
|
|
2505
|
+
finding = _dead(config, backlog, token, file, lineno, column)
|
|
2506
|
+
if isinstance(finding, Note):
|
|
2507
|
+
notes.append(finding)
|
|
2508
|
+
elif finding is not None:
|
|
2509
|
+
out.append(finding)
|
|
2510
|
+
return out, notes
|
|
2511
|
+
|
|
2512
|
+
|
|
2513
|
+
def _dead(
|
|
2514
|
+
config: Config,
|
|
2515
|
+
backlog: Backlog,
|
|
2516
|
+
token: str,
|
|
2517
|
+
file: str,
|
|
2518
|
+
lineno: int | None,
|
|
2519
|
+
column: int | None,
|
|
2520
|
+
) -> Finding | Note | None:
|
|
2521
|
+
"""How this one entry is dead, or nothing where the tier can still fire.
|
|
2522
|
+
|
|
2523
|
+
One resolution, from the code that resolves a dep, so a token cannot mean one thing in
|
|
2524
|
+
an annotation and another in the order (RK11's rule, and :func:`~roadkeep.queueing.typed`
|
|
2525
|
+
at the other end).
|
|
2526
|
+
|
|
2527
|
+
The block half opens no file of its own since RK434: the states it used to read out of
|
|
2528
|
+
the ledger are :class:`~roadkeep.backlog.Stage`'s, read off the same backlog this
|
|
2529
|
+
resolution came from — which was already built from those documents.
|
|
2530
|
+
"""
|
|
2531
|
+
resolution = backlog.resolve_dep(Dep(token))
|
|
2532
|
+
if resolution.kind is DepKind.BLOCK:
|
|
2533
|
+
return _dead_block(config, backlog, token, file, lineno, column, resolution.detail)
|
|
2534
|
+
if resolution.status is DepStatus.SHIPPED:
|
|
2535
|
+
return Finding(
|
|
2536
|
+
"priority.shipped",
|
|
2537
|
+
file,
|
|
2538
|
+
f"queues {token}, which is {resolution.detail}: work that left the roadmap "
|
|
2539
|
+
f"cannot be first, and the queue is the one list its departure did not reach",
|
|
2540
|
+
lineno,
|
|
2541
|
+
column=column,
|
|
2542
|
+
subject=token,
|
|
2543
|
+
)
|
|
2544
|
+
if resolution.status is DepStatus.DEFERRED:
|
|
2545
|
+
return Finding(
|
|
2546
|
+
"priority.deferred",
|
|
2547
|
+
file,
|
|
2548
|
+
f"queues {token}, which is {resolution.detail}: `pick` never offers a paused "
|
|
2549
|
+
f"line, so the order is over work nothing can start",
|
|
2550
|
+
lineno,
|
|
2551
|
+
column=column,
|
|
2552
|
+
subject=token,
|
|
2553
|
+
)
|
|
2554
|
+
if resolution.status is DepStatus.UNKNOWN:
|
|
2555
|
+
return Finding(
|
|
2556
|
+
"priority.unknown",
|
|
2557
|
+
file,
|
|
2558
|
+
f"queues {token}, which is {resolution.detail}: nothing can be first because "
|
|
2559
|
+
f"of an id no file carries",
|
|
2560
|
+
lineno,
|
|
2561
|
+
column=column,
|
|
2562
|
+
subject=token,
|
|
2563
|
+
)
|
|
2564
|
+
if resolution.status is DepStatus.UNRESOLVABLE:
|
|
2565
|
+
return Finding(
|
|
2566
|
+
"priority.retired",
|
|
2567
|
+
file,
|
|
2568
|
+
f"queues {token}, which is {resolution.detail}",
|
|
2569
|
+
lineno,
|
|
2570
|
+
column=column,
|
|
2571
|
+
subject=token,
|
|
2572
|
+
)
|
|
2573
|
+
# OPEN, which includes blocked: a queue naming work that is waiting is a queue doing
|
|
2574
|
+
# its job, and the tier fires the moment the blocker ships.
|
|
2575
|
+
return None
|
|
2576
|
+
|
|
2577
|
+
|
|
2578
|
+
def _dead_block(
|
|
2579
|
+
config: Config,
|
|
2580
|
+
backlog: Backlog,
|
|
2581
|
+
token: str,
|
|
2582
|
+
file: str,
|
|
2583
|
+
lineno: int | None,
|
|
2584
|
+
column: int | None,
|
|
2585
|
+
detail: str,
|
|
2586
|
+
) -> Finding | Note | None:
|
|
2587
|
+
"""The half of :func:`_dead` about a `Block X` entry, and what each state costs a queue.
|
|
2588
|
+
|
|
2589
|
+
The states are :class:`~roadkeep.backlog.Stage`'s and not this function's (RK434). They
|
|
2590
|
+
were worked out here first — a heading the ledger files entries under is a block that
|
|
2591
|
+
emptied, one with neither is a heading written before its lines — and RK429 wrote the
|
|
2592
|
+
same walk as :meth:`~roadkeep.backlog.Backlog.standing`, because `brief`, `pick` and
|
|
2593
|
+
`list` needed it too. The copy that goes is this one, and not for being second: it read
|
|
2594
|
+
the roadmap and the ledger and never the store, though `lint` already loads all three,
|
|
2595
|
+
so a block whose lines were set aside was reported as one nothing had been filed under
|
|
2596
|
+
yet — a finding arguing from the opposite of what the file says.
|
|
2597
|
+
|
|
2598
|
+
What stays is the **codes and the tier**, which are the gate's and not a property of a
|
|
2599
|
+
block. `empty` is a note because `block add` writes the heading before the lines, which
|
|
2600
|
+
is the order this tool prescribes and so is a plan rather than a defect; the other
|
|
2601
|
+
three fail a build, `paused` for the reason a queued id in the store does
|
|
2602
|
+
(`priority.deferred`) — the same fact must not change tier by whether it was written as
|
|
2603
|
+
an id or as the label above it. `live` is the one state with nothing to say, so it is
|
|
2604
|
+
the fall-through: a stage this does not name yet is a silence, and a code naming a
|
|
2605
|
+
state the file is not in is worse than no code.
|
|
2606
|
+
|
|
2607
|
+
``detail`` is the resolver's sentence for the same label, which since RK432 *is*
|
|
2608
|
+
:attr:`Standing.sentence` — one oracle reached two ways, and it is taken as an argument
|
|
2609
|
+
rather than re-read so that a message and the dep report quoting it cannot drift.
|
|
2610
|
+
"""
|
|
2611
|
+
label = config.schema.block_of_dep(Dep(token))
|
|
2612
|
+
# Never None here: `_dead` calls this only where `classify_dep` answered `BLOCK`, which
|
|
2613
|
+
# is the same pattern `block_of_dep` matches.
|
|
2614
|
+
standing = backlog.standing(label)
|
|
2615
|
+
if standing.stage is Stage.UNKNOWN:
|
|
2616
|
+
return Finding(
|
|
2617
|
+
"priority.block",
|
|
2618
|
+
file,
|
|
2619
|
+
f"queues {token} and {detail}",
|
|
2620
|
+
lineno,
|
|
2621
|
+
column=column,
|
|
2622
|
+
subject=token,
|
|
2623
|
+
)
|
|
2624
|
+
if standing.stage is Stage.PAUSED:
|
|
2625
|
+
return Finding(
|
|
2626
|
+
"priority.block-paused",
|
|
2627
|
+
file,
|
|
2628
|
+
f"queues {token}, which has nothing open and {standing.paused} set aside: "
|
|
2629
|
+
f"`pick` never offers a paused line, so the order is over work nothing can "
|
|
2630
|
+
f"start",
|
|
2631
|
+
lineno,
|
|
2632
|
+
column=column,
|
|
2633
|
+
subject=token,
|
|
2634
|
+
)
|
|
2635
|
+
if standing.stage is Stage.CURRENT:
|
|
2636
|
+
# Silent (RK1180): a tier over a standing category is an order waiting for the next
|
|
2637
|
+
# finding, which is what that kind of block is for — the finding below is about a tier
|
|
2638
|
+
# that fires on nothing *from now on*, and this one will fire again.
|
|
2639
|
+
return None
|
|
2640
|
+
if standing.stage is Stage.FINISHED:
|
|
2641
|
+
return Finding(
|
|
2642
|
+
"priority.block-empty",
|
|
2643
|
+
file,
|
|
2644
|
+
f"queues {token}, whose every line has shipped or left: a tier that fires on "
|
|
2645
|
+
f"nothing is an order the author believes is in force",
|
|
2646
|
+
lineno,
|
|
2647
|
+
column=column,
|
|
2648
|
+
subject=token,
|
|
2649
|
+
)
|
|
2650
|
+
if standing.stage is Stage.EMPTY:
|
|
2651
|
+
return Note(
|
|
2652
|
+
"priority.block-unstarted",
|
|
2653
|
+
file,
|
|
2654
|
+
f"queues {token}, which no line is filed under yet: the tier fires on nothing "
|
|
2655
|
+
f"until one is",
|
|
2656
|
+
lineno,
|
|
2657
|
+
subject=token,
|
|
2658
|
+
)
|
|
2659
|
+
return None
|
|
2660
|
+
|
|
2661
|
+
|
|
2662
|
+
def _across(config: Config, documents: dict[str, Document]) -> list[Finding]:
|
|
2663
|
+
"""What needs both files: one id in two of them, a block only one declares, and every
|
|
2664
|
+
dep resolved."""
|
|
2665
|
+
roadmap = documents.get("roadmap")
|
|
2666
|
+
if roadmap is None:
|
|
2667
|
+
return []
|
|
2668
|
+
ledger = documents.get("changelog")
|
|
2669
|
+
backlog = Backlog.during(
|
|
2670
|
+
config, roadmap=roadmap, ledger=ledger, store=documents.get("deferred")
|
|
2671
|
+
)
|
|
2672
|
+
file = config.relative(config.path("roadmap"))
|
|
2673
|
+
out: list[Finding] = []
|
|
2674
|
+
|
|
2675
|
+
if ledger is not None:
|
|
2676
|
+
out.extend(_undeclared_blocks(config, roadmap, ledger, file))
|
|
2677
|
+
out.extend(_carried(config, backlog))
|
|
2678
|
+
|
|
2679
|
+
for entry in roadmap.entries:
|
|
2680
|
+
out.extend(_deps(backlog, entry.task, file, entry.lineno))
|
|
2681
|
+
derived = derive(backlog, entry.task)
|
|
2682
|
+
if derived.deps != entry.task.deps:
|
|
2683
|
+
out.append(
|
|
2684
|
+
Finding(
|
|
2685
|
+
"deps.stale",
|
|
2686
|
+
file,
|
|
2687
|
+
f"the annotation caches another line's status and this one is out "
|
|
2688
|
+
f"of date: derived, it reads "
|
|
2689
|
+
f"({', '.join(d.render() for d in derived.deps)})",
|
|
2690
|
+
entry.lineno,
|
|
2691
|
+
entry.task.id,
|
|
2692
|
+
)
|
|
2693
|
+
)
|
|
2694
|
+
|
|
2695
|
+
out.extend(_cycles(backlog, file))
|
|
2696
|
+
return out
|
|
2697
|
+
|
|
2698
|
+
|
|
2699
|
+
def _disagreeing(config: Config, tree: Tree) -> list[Note]:
|
|
2700
|
+
"""The pen and the judge, where they are two versions of this tool (RK415).
|
|
2701
|
+
|
|
2702
|
+
An adopting project runs three copies — the plugin its hook and skill run, the action its
|
|
2703
|
+
workflow gates on, and whatever `roadkeep` the caller invokes. Measured live: a checkout
|
|
2704
|
+
at 0.1.418 doing every write while the plugin at 0.1.285 denied the hand edits, 133
|
|
2705
|
+
versions apart, in a project whose backlog reasoned about *the plugin this repository
|
|
2706
|
+
runs* while a newer copy held the pen. Nothing said so, and the facts were local the
|
|
2707
|
+
whole time.
|
|
2708
|
+
|
|
2709
|
+
Here because this is the gate, and once per commit is the right frequency: the same
|
|
2710
|
+
sentence on every `add` is noise the author learns to skip, and `engines` is the verb for
|
|
2711
|
+
asking on purpose. A **note**, so the exit code does not move — a cache lagging a
|
|
2712
|
+
checkout is allowed, and what is not survivable is not being told (RK79).
|
|
2713
|
+
|
|
2714
|
+
Never over a **revision** (`--baseline`, `--at`): those runs judge the files as they were
|
|
2715
|
+
and the engines are a fact about right now, so the same note subtracted from itself would
|
|
2716
|
+
be reported as resolved debt the moment the versions agreed again.
|
|
2717
|
+
"""
|
|
2718
|
+
if tree.rev is not None:
|
|
2719
|
+
return []
|
|
2720
|
+
from roadkeep.installing import engines # noqa: PLC0415
|
|
2721
|
+
|
|
2722
|
+
found = engines(config.root)
|
|
2723
|
+
if found.agree or found.plugin is None:
|
|
2724
|
+
return []
|
|
2725
|
+
return [
|
|
2726
|
+
Note(
|
|
2727
|
+
"engine.disagreement",
|
|
2728
|
+
config.relative(config.root),
|
|
2729
|
+
f"this gate is {found.running.version} and the plugin wired to this project is "
|
|
2730
|
+
f"{found.plugin.version}: a hook's refusal is that copy's rule — `engines` "
|
|
2731
|
+
f"reads all three, and `/plugin update` moves the judge",
|
|
2732
|
+
)
|
|
2733
|
+
]
|
|
2734
|
+
|
|
2735
|
+
|
|
2736
|
+
def _repeated(config: Config, files: dict[str, Document]) -> list[Finding]:
|
|
2737
|
+
"""One label declared by two headings in one file — the gate's half of RK391.
|
|
2738
|
+
|
|
2739
|
+
RK390 made `init` refuse it, which closed one of four doors: a hand edit, an `adopt`, and
|
|
2740
|
+
a merge of two branches all reach the same file, and there `lint` said *clean* while
|
|
2741
|
+
`add --block A` filed under the last of the two. That is L1 read the wrong way round —
|
|
2742
|
+
the law is that the schema is enforced where the text is created *and* the gate is the
|
|
2743
|
+
backstop, not that the write path is the only way in. Every other rule here has both
|
|
2744
|
+
ends; this one had the first alone.
|
|
2745
|
+
|
|
2746
|
+
A **finding**, not a note, and the exit code is the argument: a file no verb can address
|
|
2747
|
+
is not a stylistic drift, and `add`, `ship` and `record add` now all refuse over it
|
|
2748
|
+
(:class:`~roadkeep.kernel.document.RepeatedHeading`) — a gate that stayed quiet would be the
|
|
2749
|
+
only thing in this tool that saw the state and let it stand. A project mid-adoption that
|
|
2750
|
+
has not reached its duplicate yet is what `--baseline` answers (RK84), which is the
|
|
2751
|
+
general answer to standing debt and not a reason to weaken one rule.
|
|
2752
|
+
|
|
2753
|
+
Every governed file with headings, prose included: the rationale file is filed under the
|
|
2754
|
+
same block headings, and `section add` resolves a block there the same way.
|
|
2755
|
+
|
|
2756
|
+
Reported once per label, at the **second** heading and naming the first. The second is
|
|
2757
|
+
the one that was added, and the message needs both addresses because the fix is an
|
|
2758
|
+
editorial merge of two regions that nothing but their line numbers locates.
|
|
2759
|
+
|
|
2760
|
+
**And it names the verb where the verb works** (RK417). One of two headings often stands
|
|
2761
|
+
over nothing — measured on a real corpus — and `block drop <label>` takes exactly that
|
|
2762
|
+
one out, in one command and with no editorial judgement at all; a report that stopped at
|
|
2763
|
+
the diagnosis left the author to research it. The clause is conditional, because that
|
|
2764
|
+
removal is all-or-nothing across the governed set: a file where nothing is removable
|
|
2765
|
+
refuses the whole run, so the condition is asked of every file that declares the label
|
|
2766
|
+
and :func:`~roadkeep.blocking.removable` is the one expression both sides read. If the
|
|
2767
|
+
repair is `block merge` (RK403), the message references the first heading because the
|
|
2768
|
+
merge keeps that first heading and folds the later region into it. Where both regions
|
|
2769
|
+
hold work there is no command to name, and saying so is still the useful half — it
|
|
2770
|
+
tells the reader which of the two cases they are in.
|
|
2771
|
+
|
|
2772
|
+
"""
|
|
2773
|
+
word = config.schema.heading_word
|
|
2774
|
+
out: list[Finding] = []
|
|
2775
|
+
for role, document in files.items():
|
|
2776
|
+
where = config.relative(config.path(role))
|
|
2777
|
+
for label in dict.fromkeys(h.label for h in document.headings if h.label):
|
|
2778
|
+
declared = document.declaring(label)
|
|
2779
|
+
if len(declared) < 2:
|
|
2780
|
+
continue
|
|
2781
|
+
first, *rest = declared
|
|
2782
|
+
remedy = (
|
|
2783
|
+
f"`block drop {label}` takes the empty one out"
|
|
2784
|
+
if closes_by_drop(document, rest[0], files, label)
|
|
2785
|
+
# `block merge` is that command, and this clause read "a merge by hand"
|
|
2786
|
+
# until RK425 — prose left behind when RK403 shipped the verb. It named an
|
|
2787
|
+
# edit the guard denies, and the obvious reading of it is a *rename*, which
|
|
2788
|
+
# detaches every entry beneath the second heading: measured, renaming five
|
|
2789
|
+
# produced 83 findings and had to be reverted. So the sentence says what the
|
|
2790
|
+
# command does, because the caller's next question is whether their lines
|
|
2791
|
+
# survive it.
|
|
2792
|
+
else f"`block merge {label}` folds the later region into the first"
|
|
2793
|
+
)
|
|
2794
|
+
for later in rest:
|
|
2795
|
+
out.append(
|
|
2796
|
+
Finding(
|
|
2797
|
+
"block.repeated",
|
|
2798
|
+
where,
|
|
2799
|
+
f"{word} {label} is already declared on line {first.lineno}: one "
|
|
2800
|
+
f"label is one region, neither of these is inside the other, and a "
|
|
2801
|
+
f"write files under the first by position alone — {remedy}"
|
|
2802
|
+
+ _moving(document, later, files, label),
|
|
2803
|
+
later.lineno,
|
|
2804
|
+
# The label rather than a task id: this finding is about a heading,
|
|
2805
|
+
# and it is what `block merge` takes (RK420).
|
|
2806
|
+
subject=label,
|
|
2807
|
+
)
|
|
2808
|
+
)
|
|
2809
|
+
return out
|
|
2810
|
+
|
|
2811
|
+
|
|
2812
|
+
def _moving(
|
|
2813
|
+
document: Document, later: Heading, files: dict[str, Document], label: str
|
|
2814
|
+
) -> str:
|
|
2815
|
+
"""What the merge would move, where there is a merge to make (RK425).
|
|
2816
|
+
|
|
2817
|
+
Said only on the branch that names `block merge`: the drop branch removes a region that
|
|
2818
|
+
holds nothing, so a count of zero beside it is a sentence about the absence of a fact.
|
|
2819
|
+
"""
|
|
2820
|
+
if closes_by_drop(document, later, files, label):
|
|
2821
|
+
return ""
|
|
2822
|
+
held = _under(document, later)
|
|
2823
|
+
return f", moving the {held} line(s) under it and keeping the file's order"
|
|
2824
|
+
|
|
2825
|
+
|
|
2826
|
+
def _under(document: Document, heading: Heading) -> int:
|
|
2827
|
+
"""How many entries sit in **this heading's region** — the lines a merge would move.
|
|
2828
|
+
|
|
2829
|
+
Printed because it is the caller's next question, and the one the report could answer
|
|
2830
|
+
all along: `block merge` moves exactly these, and a number beside the verb is the
|
|
2831
|
+
difference between running it and reading the source first.
|
|
2832
|
+
|
|
2833
|
+
The region ends at the next heading of **any level**, which is the second fact RK425 is
|
|
2834
|
+
about: a `###` cannot group entries inside a block, so a subheading between two regions
|
|
2835
|
+
ends the first one — and a count that ignored the level would promise to move lines the
|
|
2836
|
+
merge leaves where they are.
|
|
2837
|
+
"""
|
|
2838
|
+
after = [one.lineno for one in document.headings if one.lineno > heading.lineno]
|
|
2839
|
+
end = min(after) if after else len(document.lines) + 1
|
|
2840
|
+
return sum(1 for e in document.entries if heading.lineno < e.lineno < end)
|
|
2841
|
+
|
|
2842
|
+
|
|
2843
|
+
def closes_by_drop(
|
|
2844
|
+
document: Document, later: Heading, files: dict[str, Document], label: str
|
|
2845
|
+
) -> bool:
|
|
2846
|
+
"""Whether `block drop` would **close this finding** rather than merely run (RK468).
|
|
2847
|
+
|
|
2848
|
+
Two questions and the conjunction, where `_droppable` alone was read as both. That one
|
|
2849
|
+
asks whether the verb will refuse — it is all-or-nothing across files, so a label with
|
|
2850
|
+
work under it anywhere stops the run — and it says nothing about *which* heading comes
|
|
2851
|
+
out. Measured: a repeat in the ledger beside an empty `## Block A` in the roadmap
|
|
2852
|
+
answered droppable, and `block drop` then withdrew the roadmap's heading and left the
|
|
2853
|
+
finding standing, correctly reporting `block merge` on the next run.
|
|
2854
|
+
|
|
2855
|
+
So the region this finding is about has to be the empty one too. `_under` is that
|
|
2856
|
+
question, per heading and per file, and it is the same count `_moving` prints — which is
|
|
2857
|
+
what keeps the sentence, the remedy and the number one answer instead of three.
|
|
2858
|
+
|
|
2859
|
+
Public because `remedying` asks it (RK468): the finding's message branched here and its
|
|
2860
|
+
remedy came from a table that could not, so on a droppable one the two named different
|
|
2861
|
+
commands and `repair` ran the one the sentence did not.
|
|
2862
|
+
"""
|
|
2863
|
+
return _under(document, later) == 0 and _droppable(files, label)
|
|
2864
|
+
|
|
2865
|
+
|
|
2866
|
+
def _droppable(files: dict[str, Document], label: str) -> bool:
|
|
2867
|
+
"""Whether `block drop <label>` would remove a heading rather than refuse (RK417).
|
|
2868
|
+
|
|
2869
|
+
Asked of every file that declares the label, because that verb is all-or-nothing: one
|
|
2870
|
+
file where nothing is removable refuses the run, including the files whose heading *was*
|
|
2871
|
+
removable. The ledger is the exception it is at the door — its headings hold history and
|
|
2872
|
+
are skipped rather than refused over — so a ledger with nothing removable is not what
|
|
2873
|
+
stops the rest.
|
|
2874
|
+
"""
|
|
2875
|
+
declaring = {
|
|
2876
|
+
role: document for role, document in files.items() if document.declaring(label)
|
|
2877
|
+
}
|
|
2878
|
+
if not declaring:
|
|
2879
|
+
return False
|
|
2880
|
+
return any(
|
|
2881
|
+
removable(document, label) is not None for document in declaring.values()
|
|
2882
|
+
) and all(
|
|
2883
|
+
role == "changelog" or removable(document, label) is not None
|
|
2884
|
+
for role, document in declaring.items()
|
|
2885
|
+
)
|
|
2886
|
+
|
|
2887
|
+
|
|
2888
|
+
def _undeclared_blocks(
|
|
2889
|
+
config: Config, roadmap: Document, ledger: Document, file: str
|
|
2890
|
+
) -> list[Finding]:
|
|
2891
|
+
"""A block planning work the ledger cannot receive it into (RK380).
|
|
2892
|
+
|
|
2893
|
+
Measured in Turing: `## Block BV` carried eight open lines for months and `CHANGELOG.md`
|
|
2894
|
+
declared no such heading. Nothing said so — every one of those lines is valid, its deps
|
|
2895
|
+
resolve, its pointer resolves — and the fact surfaced at the first `ship`, which is the
|
|
2896
|
+
end of a task rather than the start. :func:`~roadkeep.authoring.declaring` closes the
|
|
2897
|
+
door for lines written from here on; this is the state a project already in it is in, and
|
|
2898
|
+
reporting it costs one pass rather than one ship.
|
|
2899
|
+
|
|
2900
|
+
**Only where the block has open lines**, which is what makes it a defect rather than an
|
|
2901
|
+
observation. A roadmap heading over nothing is a block being drafted, and one whose lines
|
|
2902
|
+
have all shipped or left keeps a ledger heading anyway — so the finding fires exactly
|
|
2903
|
+
when there is work that cannot be delivered.
|
|
2904
|
+
|
|
2905
|
+
Reported at the roadmap's heading and not at each line under it: one heading is missing,
|
|
2906
|
+
one command adds it, and a finding per open line would report an eight-line block eight
|
|
2907
|
+
times for a single omission.
|
|
2908
|
+
|
|
2909
|
+
A ledger organised by **nothing** is one finding and not one per block (RK403, RK411).
|
|
2910
|
+
It was silent for a week, because `block add` did not start organising such a file and
|
|
2911
|
+
the sentence would have named a verb that refuses; `--organise <role>` is that remedy now
|
|
2912
|
+
(RK405), and what is restored is deliberately not the per-block shape. There is one thing
|
|
2913
|
+
wrong with that project — its ledger has no headings — and saying it once per roadmap
|
|
2914
|
+
heading is the same omission reported as many defects. So the finding is about the
|
|
2915
|
+
**file**, reported against the ledger and at no line, which is where `file.missing`
|
|
2916
|
+
already reports a whole-file fact. It names one label, because `--organise` is needed for
|
|
2917
|
+
the first heading and never for the second.
|
|
2918
|
+
"""
|
|
2919
|
+
out: list[Finding] = []
|
|
2920
|
+
word = config.schema.heading_word
|
|
2921
|
+
if not any(heading.label for heading in ledger.headings):
|
|
2922
|
+
return _unorganised(config, roadmap, word)
|
|
2923
|
+
for heading in roadmap.headings:
|
|
2924
|
+
if heading.label is None or ledger.heading(heading.label) is not None:
|
|
2925
|
+
continue
|
|
2926
|
+
open_lines = roadmap.block(heading.label)
|
|
2927
|
+
if not open_lines:
|
|
2928
|
+
continue
|
|
2929
|
+
out.append(
|
|
2930
|
+
Finding(
|
|
2931
|
+
"block.unrecorded",
|
|
2932
|
+
file,
|
|
2933
|
+
f"{word} {heading.label} plans {len(open_lines)} open line(s) and "
|
|
2934
|
+
f"{config.relative(config.path('changelog'))} declares no heading for it: "
|
|
2935
|
+
f"the first ship in this block refuses — "
|
|
2936
|
+
f'`block add {heading.label} --title "<its title>"`',
|
|
2937
|
+
heading.lineno,
|
|
2938
|
+
subject=heading.label,
|
|
2939
|
+
)
|
|
2940
|
+
)
|
|
2941
|
+
return out
|
|
2942
|
+
|
|
2943
|
+
|
|
2944
|
+
def _unorganised(config: Config, roadmap: Document, word: str) -> list[Finding]:
|
|
2945
|
+
"""The whole-file half of :func:`_undeclared_blocks`: a ledger with no heading at all.
|
|
2946
|
+
|
|
2947
|
+
Every `ship` in this project refuses, and one command ends it — so the count that matters
|
|
2948
|
+
is how much work is waiting rather than which block is first, and the label named is only
|
|
2949
|
+
there to make the remedy copyable. Silent where nothing is open: a ledger organised by
|
|
2950
|
+
nothing is how every project starts, and it is a defect only once there is work it cannot
|
|
2951
|
+
receive.
|
|
2952
|
+
"""
|
|
2953
|
+
planned = [
|
|
2954
|
+
(heading.label, roadmap.block(heading.label))
|
|
2955
|
+
for heading in roadmap.headings
|
|
2956
|
+
if heading.label
|
|
2957
|
+
]
|
|
2958
|
+
waiting = [(label, lines) for label, lines in planned if lines]
|
|
2959
|
+
if not waiting:
|
|
2960
|
+
return []
|
|
2961
|
+
label = waiting[0][0]
|
|
2962
|
+
lines = sum(len(entries) for _, entries in waiting)
|
|
2963
|
+
return [
|
|
2964
|
+
Finding(
|
|
2965
|
+
"block.unorganised",
|
|
2966
|
+
config.relative(config.path("changelog")),
|
|
2967
|
+
f"declares no {word.lower()} heading at all, and "
|
|
2968
|
+
f"{config.relative(config.path('roadmap'))} plans {lines} open line(s) under "
|
|
2969
|
+
f"{len(waiting)} of them: every ship here refuses until one exists — "
|
|
2970
|
+
f'`block add {label} --title "<its title>" --organise changelog`',
|
|
2971
|
+
None,
|
|
2972
|
+
subject=label,
|
|
2973
|
+
)
|
|
2974
|
+
]
|
|
2975
|
+
|
|
2976
|
+
|
|
2977
|
+
def _carried(config: Config, backlog: Backlog) -> list[Finding]:
|
|
2978
|
+
"""Every pair of governed files holding a line for one id (RK1082).
|
|
2979
|
+
|
|
2980
|
+
One loop over `referring.PAIRS` rather than a rule per pair. Three files can hold a line
|
|
2981
|
+
— RK96 added the third — and the gate read two of the three pairs, each by its own copy
|
|
2982
|
+
of this loop: RK1081 wrote the second by copying the first, which is the arrangement
|
|
2983
|
+
RK1077 was filed about one layer up. The pairs are a cross product over
|
|
2984
|
+
:data:`~roadkeep.ids.CARRIERS`, so a fourth role that can hold a line is covered by
|
|
2985
|
+
arithmetic instead of by somebody remembering.
|
|
2986
|
+
|
|
2987
|
+
The **wording** stays per pair, which is the line RK1081 drew: open-and-gone is not the
|
|
2988
|
+
sentence open-and-paused is, and the doors differ too. What is shared is which pairs
|
|
2989
|
+
exist and the walk over them; a pair the declaration carries with no code is one nobody
|
|
2990
|
+
has walked into, and it is skipped here and named there.
|
|
2991
|
+
|
|
2992
|
+
`in_halves` is the one tolerated shape (RK121, RK1080) and belongs to the **ledger's own
|
|
2993
|
+
entry**: an entry naming a half is the file saying work arrived in halves, and whatever
|
|
2994
|
+
sits beside it agrees rather than disagrees. No other file can say so, which is why the
|
|
2995
|
+
roadmap–store pair has no tolerance at all.
|
|
2996
|
+
|
|
2997
|
+
Read off whichever side *is* the changelog and no longer off `second` (RK1215). Two of
|
|
2998
|
+
the three pairs put the ledger second and the third puts it first, so the qualifier was
|
|
2999
|
+
being looked for on the store's line — where it never appears — and `id.paused-and-gone`
|
|
3000
|
+
fired on a half-shipped line the store legitimately holds. A tolerance applied to a
|
|
3001
|
+
position rather than to the file that carries the fact is one that works by coincidence.
|
|
3002
|
+
"""
|
|
3003
|
+
# Off the `Backlog` the run already holds (RK1085), which is the reader that opens all
|
|
3004
|
+
# three carriers once — the shape `_deps` and `_queued` are handed. Reaching for
|
|
3005
|
+
# `config.document` per pair was one extra parse today and one per pair as carriers are
|
|
3006
|
+
# added, on a check whose caller had the documents in scope the whole time.
|
|
3007
|
+
carriers = {
|
|
3008
|
+
"roadmap": backlog.roadmap,
|
|
3009
|
+
"changelog": backlog.ledger,
|
|
3010
|
+
"deferred": backlog.store,
|
|
3011
|
+
}
|
|
3012
|
+
out: list[Finding] = []
|
|
3013
|
+
for pair in PAIRS:
|
|
3014
|
+
first, second = carriers.get(pair.first), carriers.get(pair.second)
|
|
3015
|
+
if not pair.code or first is None or second is None:
|
|
3016
|
+
continue
|
|
3017
|
+
elsewhere = second.by_id()
|
|
3018
|
+
where = config.relative(config.path(pair.second))
|
|
3019
|
+
filed = config.relative(config.path(pair.first))
|
|
3020
|
+
for task_id, entry in first.by_id().items():
|
|
3021
|
+
held = elsewhere.get(task_id)
|
|
3022
|
+
if held is None:
|
|
3023
|
+
continue
|
|
3024
|
+
recorded = (
|
|
3025
|
+
entry if pair.first == "changelog"
|
|
3026
|
+
else held if pair.second == "changelog"
|
|
3027
|
+
else None
|
|
3028
|
+
)
|
|
3029
|
+
if recorded is not None and recorded.task.in_halves:
|
|
3030
|
+
continue
|
|
3031
|
+
out.append(
|
|
3032
|
+
Finding(
|
|
3033
|
+
pair.code,
|
|
3034
|
+
# The pair's own first file and not the roadmap's (RK1084): the third
|
|
3035
|
+
# pair is filed against the changelog, which is where its line is.
|
|
3036
|
+
filed,
|
|
3037
|
+
f"also on line {held.lineno} of {where}: {pair.says}",
|
|
3038
|
+
entry.lineno,
|
|
3039
|
+
task_id,
|
|
3040
|
+
)
|
|
3041
|
+
)
|
|
3042
|
+
return out
|
|
3043
|
+
|
|
3044
|
+
|
|
3045
|
+
def _deps(backlog: Backlog, task: Task, file: str, lineno: int) -> list[Finding]:
|
|
3046
|
+
"""Deps nothing will ever satisfy — three of the four kinds, for three reasons."""
|
|
3047
|
+
out: list[Finding] = []
|
|
3048
|
+
for resolution in backlog.resolve(task):
|
|
3049
|
+
kind, dep = resolution.kind, resolution.dep
|
|
3050
|
+
if resolution.status is DepStatus.UNKNOWN:
|
|
3051
|
+
out.append(
|
|
3052
|
+
Finding(
|
|
3053
|
+
"deps.unknown",
|
|
3054
|
+
file,
|
|
3055
|
+
f"waits on {dep.id}, which is in neither the roadmap nor the "
|
|
3056
|
+
f"changelog: nothing can say whether it is done",
|
|
3057
|
+
lineno,
|
|
3058
|
+
task.id,
|
|
3059
|
+
)
|
|
3060
|
+
)
|
|
3061
|
+
elif resolution.status is not DepStatus.UNRESOLVABLE:
|
|
3062
|
+
continue
|
|
3063
|
+
elif kind is DepKind.TASK:
|
|
3064
|
+
out.append(
|
|
3065
|
+
Finding(
|
|
3066
|
+
"deps.retired",
|
|
3067
|
+
file,
|
|
3068
|
+
f"waits on {dep.id}, which left without shipping: "
|
|
3069
|
+
f"{resolution.detail}",
|
|
3070
|
+
lineno,
|
|
3071
|
+
task.id,
|
|
3072
|
+
)
|
|
3073
|
+
)
|
|
3074
|
+
elif kind is DepKind.BLOCK:
|
|
3075
|
+
out.append(
|
|
3076
|
+
Finding(
|
|
3077
|
+
"deps.block",
|
|
3078
|
+
file,
|
|
3079
|
+
f"waits on {dep.id} and {resolution.detail}",
|
|
3080
|
+
lineno,
|
|
3081
|
+
task.id,
|
|
3082
|
+
)
|
|
3083
|
+
)
|
|
3084
|
+
# An external dep falls through on purpose: waiting on work this backlog does
|
|
3085
|
+
# not track is a fact about the work, and reporting it would fail every file
|
|
3086
|
+
# that states one honestly. A deferred one falls through for the same reason
|
|
3087
|
+
# (RK92) — it is recorded, findable and revivable, and the gate reported it as a
|
|
3088
|
+
# missing id for as long as the resolver had no fifth answer to give.
|
|
3089
|
+
return out
|
|
3090
|
+
|
|
3091
|
+
|
|
3092
|
+
def _pointers(
|
|
3093
|
+
config: Config,
|
|
3094
|
+
documents: dict[str, Document],
|
|
3095
|
+
anchors: dict[str, tuple[Section, ...]],
|
|
3096
|
+
) -> list[Finding]:
|
|
3097
|
+
"""Every `→ §<anchor>` on a line that still has a design, resolved against **every**
|
|
3098
|
+
governed prose file (RK15, widened by RK172) — open, or set aside and still pointing at
|
|
3099
|
+
the rationale a resume needs (RK96).
|
|
3100
|
+
|
|
3101
|
+
Read from the parsed ``ref`` and never from the line's text, which is the whole
|
|
3102
|
+
subtlety: §RK15's own sentence quotes a pointer as an example of one, and a scan
|
|
3103
|
+
over the raw line reports that quotation as a design that does not exist.
|
|
3104
|
+
|
|
3105
|
+
Measured adopting Turing: six open GEO lines carry `→ §X.3` and `→ §X.4`, which
|
|
3106
|
+
`docs/STRATEGY.md` declares and this resolved against the improvements file alone — so
|
|
3107
|
+
the gate called six correct pointers unresolved, and the only ways to satisfy it were to
|
|
3108
|
+
repoint a line at an unrelated section or to move positioning prose out of the file the
|
|
3109
|
+
config declares for it. Where **two** roles declare one anchor the answer is neither
|
|
3110
|
+
file: `ref.ambiguous` names both, because reading the first is what billed T354's `§X.1`
|
|
3111
|
+
365 words of somebody else's subtree without saying so.
|
|
3112
|
+
"""
|
|
3113
|
+
declared = _declared(anchors)
|
|
3114
|
+
where = " or ".join(config.relative(config.path(role)) for role in anchors)
|
|
3115
|
+
out: list[Finding] = []
|
|
3116
|
+
for role in LIVE_ROLES:
|
|
3117
|
+
if role not in documents:
|
|
3118
|
+
continue
|
|
3119
|
+
file = config.relative(config.path(role))
|
|
3120
|
+
for entry in documents[role].entries:
|
|
3121
|
+
ref = entry.task.ref
|
|
3122
|
+
if not ref:
|
|
3123
|
+
continue
|
|
3124
|
+
found = declared.get(ref, ())
|
|
3125
|
+
if not found:
|
|
3126
|
+
out.append(
|
|
3127
|
+
Finding(
|
|
3128
|
+
"ref.unresolved",
|
|
3129
|
+
file,
|
|
3130
|
+
f"points at §{ref}, which is not in {where}: a pointer to a "
|
|
3131
|
+
f"section that does not exist reads as a design that does",
|
|
3132
|
+
entry.lineno,
|
|
3133
|
+
entry.task.id,
|
|
3134
|
+
# The remedy is about the **anchor** and the report is about the line
|
|
3135
|
+
# (RK1206). Under `ref_scheme = "id"` the two are the same string, so
|
|
3136
|
+
# composing the door from the id was right here and wrong everywhere
|
|
3137
|
+
# else: on an outline, `TT1` points at `§I.1`, and `section add TT1`
|
|
3138
|
+
# writes a section the line does not point at — leaving the finding
|
|
3139
|
+
# standing with a second orphan beside it. `subject` is the field
|
|
3140
|
+
# RK420 added for exactly this split, so the prefix stays the id a
|
|
3141
|
+
# reader clicks and the substitution becomes the address that failed.
|
|
3142
|
+
subject=ref,
|
|
3143
|
+
)
|
|
3144
|
+
)
|
|
3145
|
+
elif len(found) > 1:
|
|
3146
|
+
named = " and ".join(
|
|
3147
|
+
config.relative(config.path(other)) for other in found
|
|
3148
|
+
)
|
|
3149
|
+
out.append(
|
|
3150
|
+
Finding(
|
|
3151
|
+
"ref.ambiguous",
|
|
3152
|
+
file,
|
|
3153
|
+
f"points at §{ref}, which {named} both declare: one anchor names "
|
|
3154
|
+
f"one section, and a pointer resolving to two resolves to neither"
|
|
3155
|
+
f"{_namespace_remedy(config)}",
|
|
3156
|
+
entry.lineno,
|
|
3157
|
+
entry.task.id,
|
|
3158
|
+
)
|
|
3159
|
+
)
|
|
3160
|
+
return out
|
|
3161
|
+
|
|
3162
|
+
|
|
3163
|
+
def _citations(
|
|
3164
|
+
config: Config,
|
|
3165
|
+
prose: dict[str, Document],
|
|
3166
|
+
anchors: dict[str, tuple[Section, ...]],
|
|
3167
|
+
) -> list[Finding]:
|
|
3168
|
+
"""Every `§<anchor>` a section's **prose** makes, resolved like a pointer (RK1106).
|
|
3169
|
+
|
|
3170
|
+
The fourth relation, and the gap the other three left between them. `_pointers` reads the
|
|
3171
|
+
ref a task line carries and `_orphans` reads what points at a section; a citation inside a
|
|
3172
|
+
paragraph is neither, so `ship` deletes a design another design argues from and the gate
|
|
3173
|
+
reports clean. Measured on Shio: four citations of retired addresses — `§II.1`, `§II.7`,
|
|
3174
|
+
`§III.1`, `§III.10` — over 641 lines the gate called clean.
|
|
3175
|
+
|
|
3176
|
+
Not a duplicate of what the writers already say. `ship` and `section drop` name the
|
|
3177
|
+
sections citing what *they* are deleting, in the transaction that creates the dangling
|
|
3178
|
+
reference, which is the L1 door and the cheaper moment. This is the backstop for the
|
|
3179
|
+
caller who was told and did not act, and for the hand edit and the merge — and it reads
|
|
3180
|
+
:func:`~roadkeep.sections.references`, the same scan those two select from, so a project
|
|
3181
|
+
never gets two counts of its own dead citations.
|
|
3182
|
+
|
|
3183
|
+
**Resolved against every prose file, exactly as a pointer is**, which is why `declared` is
|
|
3184
|
+
the index and not one document's anchors: a citation of `§S:I.2` from the improvements
|
|
3185
|
+
file is a reference into the strategy file, and asking one document would report the
|
|
3186
|
+
correct half of a project's prose as dangling.
|
|
3187
|
+
"""
|
|
3188
|
+
if not prose:
|
|
3189
|
+
return []
|
|
3190
|
+
declared = _declared(anchors)
|
|
3191
|
+
where = " or ".join(config.relative(config.path(role)) for role in anchors)
|
|
3192
|
+
out: list[Finding] = []
|
|
3193
|
+
for role, document in prose.items():
|
|
3194
|
+
file = config.relative(config.path(role))
|
|
3195
|
+
for cited in references(document):
|
|
3196
|
+
if cited.anchor in declared:
|
|
3197
|
+
continue
|
|
3198
|
+
out.append(
|
|
3199
|
+
Finding(
|
|
3200
|
+
"ref.dangling",
|
|
3201
|
+
file,
|
|
3202
|
+
f"§{cited.by} cites §{cited.anchor}, which is not in {where}: prose "
|
|
3203
|
+
f"arguing from a section that is gone reads exactly like a typo, and "
|
|
3204
|
+
f"from the next command on nothing can tell the two apart",
|
|
3205
|
+
cited.lineno,
|
|
3206
|
+
# The **citing** section and not the cited one, which is the subject every
|
|
3207
|
+
# other reference code carries: `ref.unresolved` names the task holding the
|
|
3208
|
+
# pointer, not the heading nothing answers. The edit is here too.
|
|
3209
|
+
subject=cited.by,
|
|
3210
|
+
)
|
|
3211
|
+
)
|
|
3212
|
+
return out
|
|
3213
|
+
|
|
3214
|
+
|
|
3215
|
+
#: A law as a sentence cites one, and the two shapes that are not citations. `#L35` is a line
|
|
3216
|
+
#: anchor inside a URL fragment — the ledger carries one — and `L` followed by a letter is a
|
|
3217
|
+
#: word. A check opening with a false finding on a corpus that has none is how a gate comes to
|
|
3218
|
+
#: be switched off (RK1380), so the exclusions are in the pattern rather than in a filter after.
|
|
3219
|
+
_CITED_LAW = re.compile(r"(?<![#\w])(L[1-9][0-9]*)(?![\w])")
|
|
3220
|
+
|
|
3221
|
+
#: How the authoritative table states one: a leading cell holding the law's own name. Read
|
|
3222
|
+
#: rather than declared, because the table *is* the declaration — `agents.md` carries a
|
|
3223
|
+
#: compressed copy and says this one governs, and a second list in `roadkeep.toml` would be the
|
|
3224
|
+
#: thing the table exists not to be. A project with no such table declares no laws, and then
|
|
3225
|
+
#: this reports **nothing**: an empty declaration means there is nothing to resolve against,
|
|
3226
|
+
#: never that every citation is unknown — which is the direction a gate may not fail in.
|
|
3227
|
+
_DECLARES_LAW = re.compile(r"^\|\s*(L[1-9][0-9]*)\s*\|", flags=re.MULTILINE)
|
|
3228
|
+
|
|
3229
|
+
|
|
3230
|
+
def _laws(
|
|
3231
|
+
config: Config, documents: dict[str, Document], prose: dict[str, Document]
|
|
3232
|
+
) -> list[Finding]:
|
|
3233
|
+
"""A law a governed sentence cites that no prose file declares (RK1380).
|
|
3234
|
+
|
|
3235
|
+
The fourth kind of citation this prose carries and the only one nothing resolved. An anchor
|
|
3236
|
+
is `ref.dangling`, a path is `path.missing`, an id is a dep the parser types — and a law
|
|
3237
|
+
read back as true whatever it said, so an `L7` was a law this project appeared to hold and
|
|
3238
|
+
was a number somebody typed.
|
|
3239
|
+
|
|
3240
|
+
Silent on a project that declares none, which is every adopter: the laws are one project's
|
|
3241
|
+
and the table stating them is what makes the set closed, so where there is no table there is
|
|
3242
|
+
no population and no finding. That is the whole safety of doing this by reading rather than
|
|
3243
|
+
by configuration — an absent declaration reports nothing rather than everything.
|
|
3244
|
+
"""
|
|
3245
|
+
declared = {
|
|
3246
|
+
law
|
|
3247
|
+
for document in prose.values()
|
|
3248
|
+
for law in _DECLARES_LAW.findall(document.render())
|
|
3249
|
+
}
|
|
3250
|
+
if not declared:
|
|
3251
|
+
return []
|
|
3252
|
+
where = " or ".join(config.relative(config.path(role)) for role in prose)
|
|
3253
|
+
out: list[Finding] = []
|
|
3254
|
+
# Both sets, because `_Scan` keeps them apart: `documents` is the files organised by lines
|
|
3255
|
+
# and `prose` the ones organised by sections, and a law is cited from a design as readily
|
|
3256
|
+
# as from a ledger sentence — which is the whole population this is about.
|
|
3257
|
+
for role, document in {**documents, **prose}.items():
|
|
3258
|
+
file = config.relative(config.path(role))
|
|
3259
|
+
owner = _owners(document)
|
|
3260
|
+
for lineno, line in enumerate(document.lines, start=1):
|
|
3261
|
+
for found in _CITED_LAW.finditer(line):
|
|
3262
|
+
if found.group(1) in declared:
|
|
3263
|
+
continue
|
|
3264
|
+
out.append(
|
|
3265
|
+
Finding(
|
|
3266
|
+
"law.unknown",
|
|
3267
|
+
file,
|
|
3268
|
+
f"cites {found.group(1)}, which {where} does not declare: the laws "
|
|
3269
|
+
f"are a closed table and a citation of one outside it reads as a rule "
|
|
3270
|
+
f"this project holds, which is the one thing prose may not invent",
|
|
3271
|
+
lineno,
|
|
3272
|
+
# The id or anchor whose prose carries the sentence, so the door is one
|
|
3273
|
+
# command and not a shape to fill (RK420) — every other finding here
|
|
3274
|
+
# names the thing its remedy addresses, and a citation's is whatever
|
|
3275
|
+
# owns the line it sits on.
|
|
3276
|
+
owner.get(lineno, ""),
|
|
3277
|
+
# And the offset by name, which is what makes one `L` among a
|
|
3278
|
+
# paragraph's words findable by eye (RK34).
|
|
3279
|
+
column=found.start(1) + 1,
|
|
3280
|
+
)
|
|
3281
|
+
)
|
|
3282
|
+
return out
|
|
3283
|
+
|
|
3284
|
+
|
|
3285
|
+
def _owners(document: Document) -> dict[int, str]:
|
|
3286
|
+
"""Which id or anchor owns each line of one governed file (RK1380).
|
|
3287
|
+
|
|
3288
|
+
A citation is corrected through the verb that owns the prose it sits in, and every one of
|
|
3289
|
+
those takes an address: `amend` a line's id, `section amend` an anchor, `record amend` an
|
|
3290
|
+
entry's id. So a finding about a *line* has to resolve it, or its door is a shape rather
|
|
3291
|
+
than a command.
|
|
3292
|
+
|
|
3293
|
+
Both organisations, read through the two readers that already answer this: an entry knows
|
|
3294
|
+
the span it owns because a ledger bullet may wrap (RK157), and a section knows its own from
|
|
3295
|
+
`first` to `last`. A line owned by neither — a heading, a blank, prose above the first
|
|
3296
|
+
section — answers `""`, which is the honest state and the one the remedy's blank is for.
|
|
3297
|
+
"""
|
|
3298
|
+
from roadkeep.sections import anchored # noqa: PLC0415 - RK260
|
|
3299
|
+
|
|
3300
|
+
out: dict[int, str] = {}
|
|
3301
|
+
for entry in document.entries:
|
|
3302
|
+
for lineno in range(entry.lineno, max(entry.stop, entry.lineno) + 1):
|
|
3303
|
+
out[lineno] = entry.task.id
|
|
3304
|
+
for section in anchored(document):
|
|
3305
|
+
for lineno in range(section.first, section.last + 1):
|
|
3306
|
+
out.setdefault(lineno, section.anchor)
|
|
3307
|
+
return out
|
|
3308
|
+
|
|
3309
|
+
|
|
3310
|
+
def _namespace_remedy(config: Config) -> str:
|
|
3311
|
+
"""The configuration that makes two colliding addresses two addresses (RK340).
|
|
3312
|
+
|
|
3313
|
+
Named at the finding and not only in the docs, because the state it reports is one a
|
|
3314
|
+
project cannot edit its way out of: both files number their own outline from `I`, so
|
|
3315
|
+
"rename one of them" is a renumbering of somebody's whole document. Silent where the
|
|
3316
|
+
project already declares a namespace for both — there the collision is inside one of
|
|
3317
|
+
them, and `[refs]` has nothing left to say about it.
|
|
3318
|
+
"""
|
|
3319
|
+
if all(role in config.refs for role in PROSE_ROLES if config.has(role)):
|
|
3320
|
+
return ""
|
|
3321
|
+
return (
|
|
3322
|
+
" — `[refs] <role> = \"<prefix>\"` in roadkeep.toml gives one of the two files its "
|
|
3323
|
+
"own namespace, so its addresses are written §<prefix>:<x.y>"
|
|
3324
|
+
)
|
|
3325
|
+
|
|
3326
|
+
|
|
3327
|
+
def _crossing(
|
|
3328
|
+
config: Config,
|
|
3329
|
+
prose: dict[str, Document],
|
|
3330
|
+
anchors: dict[str, tuple[Section, ...]],
|
|
3331
|
+
) -> list[Finding]:
|
|
3332
|
+
"""A citation that resolves into the **other** prose file while a local one exists (RK1168).
|
|
3333
|
+
|
|
3334
|
+
Declaring `[refs]` re-addresses every heading in a file at once — 48 of them in the run this
|
|
3335
|
+
was measured on — and carries none of that file's own citations. Seven became `ref.dangling`,
|
|
3336
|
+
which the gate reports; **twenty-one kept resolving**, into the other file's section of the
|
|
3337
|
+
same address, because both files declared it — which is why they collided at all and why the
|
|
3338
|
+
key was declared in the first place. Nothing said a word about those.
|
|
3339
|
+
|
|
3340
|
+
That is worse than a dead reference: a dangling citation stops a reader, and this one hands
|
|
3341
|
+
them somebody else's design under the address they meant. So the shape reported is exactly
|
|
3342
|
+
that state — the citing file gives its own headings a namespace, the citation is written bare,
|
|
3343
|
+
and the namespaced address it would have meant is a section that exists here.
|
|
3344
|
+
|
|
3345
|
+
Not every bare citation into another file. A project's prose argues from the other file all
|
|
3346
|
+
the time and `§S:I.2` is how it says so; what makes this a finding is that the same address
|
|
3347
|
+
resolves **both** ways and the local one is the file the sentence is in.
|
|
3348
|
+
"""
|
|
3349
|
+
declared = _declared(anchors)
|
|
3350
|
+
out: list[Finding] = []
|
|
3351
|
+
for role, document in prose.items():
|
|
3352
|
+
namespace = document.schema.ref_prefix
|
|
3353
|
+
if not namespace:
|
|
3354
|
+
continue
|
|
3355
|
+
file = config.relative(config.path(role))
|
|
3356
|
+
for cited in references(document):
|
|
3357
|
+
local = f"{namespace}:{cited.anchor}"
|
|
3358
|
+
if local not in declared or role in declared.get(cited.anchor, ()):
|
|
3359
|
+
continue
|
|
3360
|
+
elsewhere = declared.get(cited.anchor, ())
|
|
3361
|
+
if not elsewhere:
|
|
3362
|
+
continue # `ref.dangling` is that finding, and one state is one code
|
|
3363
|
+
named = " and ".join(config.relative(config.path(one)) for one in elsewhere)
|
|
3364
|
+
out.append(
|
|
3365
|
+
Finding(
|
|
3366
|
+
"ref.crossed",
|
|
3367
|
+
file,
|
|
3368
|
+
f"§{cited.by} cites §{cited.anchor}, which resolves into {named} while "
|
|
3369
|
+
f"§{local} is this file's own: a namespace re-addressed the headings and "
|
|
3370
|
+
f"not the prose citing them, so the reference reads as correct and answers "
|
|
3371
|
+
f"with somebody else's design",
|
|
3372
|
+
cited.lineno,
|
|
3373
|
+
subject=cited.by,
|
|
3374
|
+
)
|
|
3375
|
+
)
|
|
3376
|
+
return out
|
|
3377
|
+
|
|
3378
|
+
|
|
3379
|
+
def _declared(anchors: dict[str, tuple[Section, ...]]) -> dict[str, tuple[str, ...]]:
|
|
3380
|
+
"""Which prose roles declare which anchor — one index, read by resolution and by budget.
|
|
3381
|
+
|
|
3382
|
+
A role that declares an anchor twice says so once here: `section.duplicate` is that
|
|
3383
|
+
file's own finding, and counting it again would make one file's mistake read as two
|
|
3384
|
+
files disagreeing.
|
|
3385
|
+
"""
|
|
3386
|
+
out: dict[str, list[str]] = {}
|
|
3387
|
+
for role, found in anchors.items():
|
|
3388
|
+
for anchor in dict.fromkeys(section.anchor for section in found):
|
|
3389
|
+
out.setdefault(anchor, []).append(role)
|
|
3390
|
+
return {anchor: tuple(roles) for anchor, roles in out.items()}
|
|
3391
|
+
|
|
3392
|
+
|
|
3393
|
+
def _orphans(
|
|
3394
|
+
config: Config,
|
|
3395
|
+
documents: dict[str, Document],
|
|
3396
|
+
prose: Document,
|
|
3397
|
+
anchors: dict[str, tuple[Section, ...]],
|
|
3398
|
+
*,
|
|
3399
|
+
role: str,
|
|
3400
|
+
) -> list[Finding]:
|
|
3401
|
+
"""One prose file read from its own side: a section, and what points at it.
|
|
3402
|
+
|
|
3403
|
+
A pointer resolves one way only, so nothing in `_pointers` can see a section that
|
|
3404
|
+
survived its task. Three ways that happens and one budget, all at the anchor's line.
|
|
3405
|
+
|
|
3406
|
+
Called **per governed prose role** (RK172), because a strategy file is a prose file: its
|
|
3407
|
+
sections are pointed at, budgeted and orphaned by the same rules, and a gate that read
|
|
3408
|
+
one of the two would leave the other ungoverned in exactly the way the roadmap is not.
|
|
3409
|
+
|
|
3410
|
+
The budget is charged against **what a pointer hands a reader**, which is the one
|
|
3411
|
+
reading that keeps RK9's rule and this repository's own file both true: a section a
|
|
3412
|
+
line points at is measured with its subsections (`show` prints them, so a rationale
|
|
3413
|
+
that doubled by growing a `§RK34.1` is caught), and one nothing points at is measured
|
|
3414
|
+
on its own prose (`§0` is a container whose three anchored children are each inside
|
|
3415
|
+
the budget, and charging it 461 words would fail a file with no long paragraph in it).
|
|
3416
|
+
An anchor **two** files declare is charged as pointed at by nobody: which of the two a
|
|
3417
|
+
line meant is what `ref.ambiguous` asks the author, and billing one of them 365 words of
|
|
3418
|
+
the other's subtree in the meantime is the silent half of that defect.
|
|
3419
|
+
|
|
3420
|
+
Which is also reported **here**, at the heading, and that is RK239: `ref.ambiguous`
|
|
3421
|
+
fires from the pointer end, so the state is named only where a task line happens to
|
|
3422
|
+
reach it. Turing at `f08304fcb1` declares thirteen anchors in both prose files, one is
|
|
3423
|
+
pointed at, and the other twelve were reported by nothing — while `show`, `brief`,
|
|
3424
|
+
`ship` and `defer` all already refuse to resolve them (RK186/RK196/RK229) and
|
|
3425
|
+
`_budget` above charges them as unreachable. `section.ambiguous` is the same word from
|
|
3426
|
+
the file that made the claim, once per heading, because the remedy is an edit at each
|
|
3427
|
+
of the two and `id.duplicate` is the shape an editor can act on twice. Not `--fix`'s:
|
|
3428
|
+
which of the two is the design is editorial (RK16).
|
|
3429
|
+
"""
|
|
3430
|
+
file = config.relative(config.path(role))
|
|
3431
|
+
sections = anchors[role]
|
|
3432
|
+
declared = _declared(anchors)
|
|
3433
|
+
# A deferred task's section is carried, not deleted (RK96), so the line that owns it is
|
|
3434
|
+
# in the store rather than the roadmap — and reporting it orphaned would make the gate
|
|
3435
|
+
# demand the deletion of exactly what a resume restores.
|
|
3436
|
+
# And the decisions file owns its own prose (RK1361): a body there belongs to the record
|
|
3437
|
+
# one bullet up, not to a roadmap line — so the ledger is not what decides it left. Read
|
|
3438
|
+
# off the file being judged, because that is the whole difference between the two kinds of
|
|
3439
|
+
# body: a design is deleted by the ship that files the decision, and the decision's body
|
|
3440
|
+
# is what survives it. Superseded entries included, both halves of a `supersede` keeping
|
|
3441
|
+
# theirs — the record of what a replacement was needed against is the body it replaced.
|
|
3442
|
+
owning = ("decisions",) if role == "decisions" else LIVE_ROLES
|
|
3443
|
+
lines = {
|
|
3444
|
+
task_id: entry
|
|
3445
|
+
for one in owning
|
|
3446
|
+
if one in documents
|
|
3447
|
+
for task_id, entry in documents[one].by_id().items()
|
|
3448
|
+
}
|
|
3449
|
+
kept = set(lines)
|
|
3450
|
+
gone = (
|
|
3451
|
+
{}
|
|
3452
|
+
if role == "decisions"
|
|
3453
|
+
else (documents["changelog"].by_id() if "changelog" in documents else {})
|
|
3454
|
+
)
|
|
3455
|
+
pointed = {
|
|
3456
|
+
entry.task.ref
|
|
3457
|
+
for document in documents.values()
|
|
3458
|
+
for entry in document.entries
|
|
3459
|
+
if entry.task.ref and len(declared.get(entry.task.ref, ())) == 1
|
|
3460
|
+
}
|
|
3461
|
+
claimed = _claimed(documents)
|
|
3462
|
+
ids = config.schema.id_pattern()
|
|
3463
|
+
seen: dict[str, int] = {}
|
|
3464
|
+
out: list[Finding] = []
|
|
3465
|
+
|
|
3466
|
+
for section in sections:
|
|
3467
|
+
anchor = section.anchor
|
|
3468
|
+
first = seen.get(anchor)
|
|
3469
|
+
if first is not None:
|
|
3470
|
+
out.append(
|
|
3471
|
+
Finding(
|
|
3472
|
+
"section.duplicate",
|
|
3473
|
+
file,
|
|
3474
|
+
f"§{anchor} is already at line {first}: an anchor names one "
|
|
3475
|
+
f"section, and a pointer that resolves to two resolves to neither",
|
|
3476
|
+
section.first,
|
|
3477
|
+
anchor,
|
|
3478
|
+
)
|
|
3479
|
+
)
|
|
3480
|
+
elif len(declared.get(anchor, ())) > 1:
|
|
3481
|
+
# Once per file and never per copy, for the reason `_declared` dedupes a role:
|
|
3482
|
+
# a file that declares the anchor twice already carries the finding above, and
|
|
3483
|
+
# counting it again here would read as three files disagreeing.
|
|
3484
|
+
elsewhere = " and ".join(
|
|
3485
|
+
config.relative(config.path(other))
|
|
3486
|
+
for other in declared[anchor]
|
|
3487
|
+
if other != role
|
|
3488
|
+
)
|
|
3489
|
+
out.append(
|
|
3490
|
+
Finding(
|
|
3491
|
+
"section.ambiguous",
|
|
3492
|
+
file,
|
|
3493
|
+
f"§{anchor} is declared in {elsewhere} as well: one anchor names one "
|
|
3494
|
+
f"section, so no pointer here resolves and every verb that reads one "
|
|
3495
|
+
f"refuses{_namespace_remedy(config)}",
|
|
3496
|
+
section.first,
|
|
3497
|
+
anchor,
|
|
3498
|
+
# The fact these findings **share** (RK469): the pair of files, not the
|
|
3499
|
+
# address. Measured on Turing, 27 of them filled 80% of the report with
|
|
3500
|
+
# one sentence and one remedy repeated, and a single `[refs]` line closes
|
|
3501
|
+
# every one — so the reader is told the pair once and the addresses under
|
|
3502
|
+
# it. The findings stay one per address, because the addresses are the
|
|
3503
|
+
# evidence an author picking which file takes the namespace reads.
|
|
3504
|
+
shared=f"declared in {elsewhere} as well",
|
|
3505
|
+
)
|
|
3506
|
+
)
|
|
3507
|
+
seen.setdefault(anchor, section.first)
|
|
3508
|
+
out.extend(_budget(prose, section, pointed=anchor in pointed, file=file))
|
|
3509
|
+
out.extend(_query(config, section, file))
|
|
3510
|
+
out.extend(_hollow(prose, section, file, pointed=anchor in pointed))
|
|
3511
|
+
out.extend(_promise(config, section, file))
|
|
3512
|
+
owners = section_owners(section, ids)
|
|
3513
|
+
# Prose that belongs to no task is nobody's orphan — `§0.1` under the id scheme, and
|
|
3514
|
+
# any outline heading that names no id — the same rule `section add` applies (RK9).
|
|
3515
|
+
if not owners:
|
|
3516
|
+
continue
|
|
3517
|
+
if any(owner in kept for owner in owners):
|
|
3518
|
+
finding = _unreachable(section, file, owners=owners, lines=lines, claimed=claimed)
|
|
3519
|
+
else:
|
|
3520
|
+
finding = _unowned(
|
|
3521
|
+
section,
|
|
3522
|
+
file,
|
|
3523
|
+
shipped=any(owner in gone for owner in owners),
|
|
3524
|
+
owners=owners,
|
|
3525
|
+
claimants=tuple(claimed.get(anchor, ())),
|
|
3526
|
+
)
|
|
3527
|
+
if finding is not None:
|
|
3528
|
+
out.append(finding)
|
|
3529
|
+
return out
|
|
3530
|
+
|
|
3531
|
+
|
|
3532
|
+
def _claimed(documents: dict[str, Document]) -> dict[str, list[str]]:
|
|
3533
|
+
"""Which open lines point at which anchor — :func:`~roadkeep.sections.pointers`' index.
|
|
3534
|
+
|
|
3535
|
+
Rebuilt from the documents this run already read rather than from disk, because a
|
|
3536
|
+
baseline run judges a revision and the gate has to ask its questions of that tree.
|
|
3537
|
+
|
|
3538
|
+
And the decisions file's own records, which claim by pointer under an outline (RK1363).
|
|
3539
|
+
The same index `sections.pointers` builds, so the gate and the writer cannot disagree —
|
|
3540
|
+
which is the disagreement `_pointed_at` exists to prevent, found here as a
|
|
3541
|
+
`section.unreachable` on a body the ship had just addressed correctly. Not in
|
|
3542
|
+
:data:`LIVE_ROLES`: those are the roles whose *lines* are still open work, and a decision
|
|
3543
|
+
is not open work — it is a record that never leaves, which is why its claim never lapses.
|
|
3544
|
+
"""
|
|
3545
|
+
out: dict[str, list[str]] = {}
|
|
3546
|
+
for role in (*LIVE_ROLES, "decisions"):
|
|
3547
|
+
for entry in documents[role].entries if role in documents else ():
|
|
3548
|
+
if entry.task.ref:
|
|
3549
|
+
out.setdefault(entry.task.ref, []).append(entry.task.id)
|
|
3550
|
+
return out
|
|
3551
|
+
|
|
3552
|
+
|
|
3553
|
+
def _unreachable(
|
|
3554
|
+
section: Section,
|
|
3555
|
+
file: str,
|
|
3556
|
+
*,
|
|
3557
|
+
owners: tuple[str, ...],
|
|
3558
|
+
lines: dict[str, Entry],
|
|
3559
|
+
claimed: dict[str, list[str]],
|
|
3560
|
+
) -> Finding | None:
|
|
3561
|
+
"""A section whose task is alive and points somewhere else (RK135).
|
|
3562
|
+
|
|
3563
|
+
The gap the three neighbouring checks leave between them, measured on Shio: `XV.21` and
|
|
3564
|
+
`XV.22` carried the same title — one an earlier draft of the other — and SH265 points at
|
|
3565
|
+
`XV.22`. `section.orphan` did not fire, the id in the title being an open line;
|
|
3566
|
+
`section.duplicate` did not fire, the anchors differing; `ref.unresolved` did not fire,
|
|
3567
|
+
the pointer resolving somewhere. Twenty-three lines of superseded design lint clean, and
|
|
3568
|
+
the only reason it was found is that a reader compared two adjacent headings.
|
|
3569
|
+
|
|
3570
|
+
Reachability is the pointer index and never the title, so the two readers RK134 split
|
|
3571
|
+
apart stay one: a section **any** open line points at is reached, and so is one under an
|
|
3572
|
+
anchor a pointer names — `§RK34.1` is handed to a reader by the `§RK34` its parent's
|
|
3573
|
+
pointer resolves to, which is the same subtree `show` prints and `_budget` measures.
|
|
3574
|
+
|
|
3575
|
+
Not an orphan, and the remedy is not a drop: the task is alive, one of the two sections
|
|
3576
|
+
is its design and the other is history, and which is which is a reading.
|
|
3577
|
+
"""
|
|
3578
|
+
if _reached(section.anchor, claimed):
|
|
3579
|
+
return None
|
|
3580
|
+
elsewhere = [
|
|
3581
|
+
(owner, lines[owner].task.ref)
|
|
3582
|
+
for owner in owners
|
|
3583
|
+
if owner in lines and lines[owner].task.ref
|
|
3584
|
+
]
|
|
3585
|
+
if not elsewhere:
|
|
3586
|
+
return None
|
|
3587
|
+
named = ", ".join(f"{owner} points at §{ref}" for owner, ref in elsewhere)
|
|
3588
|
+
return Finding(
|
|
3589
|
+
"section.unreachable",
|
|
3590
|
+
file,
|
|
3591
|
+
f"{named}, so no pointer resolves here: the task is alive and its design is "
|
|
3592
|
+
f"somewhere else, which makes one of the two history rather than a deletion",
|
|
3593
|
+
section.first,
|
|
3594
|
+
section.anchor,
|
|
3595
|
+
)
|
|
3596
|
+
|
|
3597
|
+
|
|
3598
|
+
def _reached(anchor: str, claimed: dict[str, list[str]]) -> bool:
|
|
3599
|
+
"""Does an open line's pointer hand a reader this section — directly or by its parent?
|
|
3600
|
+
|
|
3601
|
+
Segment by segment and never by string, the care :func:`~roadkeep.sections._extends`
|
|
3602
|
+
takes at the other end: `§0.1` is not under `§0.10`, and reading it as one would silence
|
|
3603
|
+
a check on a section nobody can reach.
|
|
3604
|
+
"""
|
|
3605
|
+
segments = anchor.split(".")
|
|
3606
|
+
return any(
|
|
3607
|
+
".".join(segments[:depth]) in claimed for depth in range(1, len(segments) + 1)
|
|
3608
|
+
)
|
|
3609
|
+
|
|
3610
|
+
|
|
3611
|
+
def _query(config: Config, section: Section, file: str) -> list[Finding]:
|
|
3612
|
+
"""The `roadkeep-remaining` block a design may declare, held to its grammar (RK492).
|
|
3613
|
+
|
|
3614
|
+
The backstop half of L1 for a fence: `remaining` refuses one it cannot read, but that verb
|
|
3615
|
+
is asked by whoever is continuing the migration, and a query nobody has run since it was
|
|
3616
|
+
typed is exactly the one that is wrong. So the gate reads it on every run, which costs one
|
|
3617
|
+
string scan per section and answers the only question the fence can be wrong about.
|
|
3618
|
+
|
|
3619
|
+
A section declaring none is silent, which is every section here: this reports a block that
|
|
3620
|
+
exists and does not parse, never the absence of one. The count itself is `remaining`'s and
|
|
3621
|
+
never a finding — sites left are work, and work is not a defect in a file.
|
|
3622
|
+
"""
|
|
3623
|
+
from roadkeep.remaining import ( # noqa: PLC0415 - RK260
|
|
3624
|
+
EVIDENCE,
|
|
3625
|
+
FENCE,
|
|
3626
|
+
QueryError,
|
|
3627
|
+
declared,
|
|
3628
|
+
)
|
|
3629
|
+
|
|
3630
|
+
# Both fences, and one rule (RK1184): the criterion is the same grammar with the sign
|
|
3631
|
+
# flipped, so a block it cannot read is the same finding — and reporting one kind and
|
|
3632
|
+
# not the other would be the gate holding half of what the parser accepts.
|
|
3633
|
+
found: list[Finding] = []
|
|
3634
|
+
for tag in (FENCE, EVIDENCE):
|
|
3635
|
+
if tag not in section.body:
|
|
3636
|
+
continue
|
|
3637
|
+
try:
|
|
3638
|
+
declared(section.body, tag)
|
|
3639
|
+
except QueryError as error:
|
|
3640
|
+
found.append(
|
|
3641
|
+
Finding(
|
|
3642
|
+
"remaining.format",
|
|
3643
|
+
file,
|
|
3644
|
+
f"§{section.anchor} declares a `{tag}` block this grammar cannot "
|
|
3645
|
+
f"read: {error}",
|
|
3646
|
+
section.first,
|
|
3647
|
+
section.anchor,
|
|
3648
|
+
)
|
|
3649
|
+
)
|
|
3650
|
+
continue
|
|
3651
|
+
found += _directoried(config, section, file, tag)
|
|
3652
|
+
return found
|
|
3653
|
+
|
|
3654
|
+
|
|
3655
|
+
#: What makes a pathspec a **pattern** rather than a name (RK1222). `Path.glob`'s own three,
|
|
3656
|
+
#: and the whole of the narrowing below: a spec carrying one of these is a query the author
|
|
3657
|
+
#: wrote as a query, and a migration whose sites were deleted rather than rewritten ends with
|
|
3658
|
+
#: exactly such a spec matching nothing — which is the query working.
|
|
3659
|
+
_GLOBBED = ("*", "?", "[")
|
|
3660
|
+
|
|
3661
|
+
|
|
3662
|
+
def _directoried(
|
|
3663
|
+
config: Config, section: Section, file: str, tag: str
|
|
3664
|
+
) -> list[Finding]:
|
|
3665
|
+
"""A pathspec that is a directory where a pattern was meant (RK1222).
|
|
3666
|
+
|
|
3667
|
+
RK1216 gave the *read* the words — `remaining` names a pathspec that reached no file, on
|
|
3668
|
+
the headline and beside its own clause — and left the gate to this task, because the typo
|
|
3669
|
+
is in a governed file and a claim nothing can answer is what `lint` refuses for a pointer,
|
|
3670
|
+
a dead queue entry and an unreadable fence.
|
|
3671
|
+
|
|
3672
|
+
**The false positive is real and this is the narrowing that avoids it.** A migration whose
|
|
3673
|
+
sites are *deleted* rather than rewritten ends with its pathspec matching nothing, and that
|
|
3674
|
+
is the query working — the same zero, arrived at honestly. A finding on that would fire on
|
|
3675
|
+
the finished migration it was meant to tell apart from the typo, which is RK1216's own
|
|
3676
|
+
confusion with the sign flipped.
|
|
3677
|
+
|
|
3678
|
+
So this fires on one shape only, and it is the shape both measured cases had: a spec with
|
|
3679
|
+
**no glob metacharacter** that names an **extant directory**. `lib/src :: <regex>` reads as
|
|
3680
|
+
a directory, which `Path.glob` matches as one entry that is not a file, so the whole query
|
|
3681
|
+
answered `0 site(s) left in 0 file(s)` over trees holding 14 and 420. Corrected to
|
|
3682
|
+
`lib/src/**/*.c` the tool agrees exactly; nothing was wrong but the glob.
|
|
3683
|
+
|
|
3684
|
+
A spec that carries a metacharacter is the author's query and is left alone, whatever it
|
|
3685
|
+
matches. A spec naming a directory that is *gone* is left alone too — that is the deleted
|
|
3686
|
+
migration, and the read already says so in words.
|
|
3687
|
+
"""
|
|
3688
|
+
from roadkeep.remaining import declared # noqa: PLC0415 - RK260
|
|
3689
|
+
|
|
3690
|
+
out: list[Finding] = []
|
|
3691
|
+
for clause in declared(section.body, tag):
|
|
3692
|
+
spec = clause.pathspec
|
|
3693
|
+
if any(one in spec for one in _GLOBBED):
|
|
3694
|
+
continue
|
|
3695
|
+
if not (config.root / spec).is_dir():
|
|
3696
|
+
continue
|
|
3697
|
+
out.append(
|
|
3698
|
+
Finding(
|
|
3699
|
+
"remaining.unmatched",
|
|
3700
|
+
file,
|
|
3701
|
+
f"§{section.anchor} queries `{spec}`, which is a directory: `Path.glob` "
|
|
3702
|
+
f"matches it as one entry that is not a file, so this clause reads every "
|
|
3703
|
+
f"file in it and finds none — `{spec}/**/*` is the pattern it was meant as",
|
|
3704
|
+
section.first,
|
|
3705
|
+
section.anchor,
|
|
3706
|
+
)
|
|
3707
|
+
)
|
|
3708
|
+
return out
|
|
3709
|
+
|
|
3710
|
+
|
|
3711
|
+
def _promise(config: Config, section: Section, file: str) -> list[Finding]:
|
|
3712
|
+
"""A design naming an id no line carries, once a file already holds one (RK1003).
|
|
3713
|
+
|
|
3714
|
+
The backstop half of L1 for the rule RK1002 put at the door, and :func:`_query`'s shape
|
|
3715
|
+
exactly: `section add` refuses the body, and this reads what is already on disk. The
|
|
3716
|
+
three ways one gets there without passing a door are the three the backstop exists for —
|
|
3717
|
+
an adopted backlog, a hand edit and a textual merge.
|
|
3718
|
+
|
|
3719
|
+
Reproduced the hour RK1002 shipped: a design edited to name an unclaimed id left `lint`
|
|
3720
|
+
clean while `next-id` warned about it inside another command's output, hedged, with
|
|
3721
|
+
nothing that had to act on the warning.
|
|
3722
|
+
|
|
3723
|
+
**Not repairable, and it says so through its remedy rather than through `--fix`**: which
|
|
3724
|
+
of two ids an author meant is a judgement about a sentence, and the tool has no model of
|
|
3725
|
+
one (L4). The finding names the same two ways out the refusal does.
|
|
3726
|
+
|
|
3727
|
+
Under the same code the door raises, which is what :class:`Finding` promises about every
|
|
3728
|
+
rule the two surfaces share: a caller filtering on `body.promise` filters one rule.
|
|
3729
|
+
"""
|
|
3730
|
+
# Deferred beside `_query`'s, and one-way for the same reason (RK260).
|
|
3731
|
+
from roadkeep.sections import known, promised # noqa: PLC0415 - RK1003
|
|
3732
|
+
|
|
3733
|
+
return [
|
|
3734
|
+
Finding("body.promise", file, f"§{section.anchor} {one.message}", section.first, section.anchor)
|
|
3735
|
+
for one in promised(config.schema_for("roadmap"), section.body, known(config, section.anchor, None))
|
|
3736
|
+
]
|
|
3737
|
+
|
|
3738
|
+
|
|
3739
|
+
def _hollow(prose: Document, section: Section, file: str, *, pointed: bool) -> list[Finding]:
|
|
3740
|
+
"""A section a pointer resolves to that gives the reader nothing (RK1012).
|
|
3741
|
+
|
|
3742
|
+
The two states RK1004's register measured as reachable and reported by nothing: a heading
|
|
3743
|
+
with no prose under it, and one addressed with no title. `section add` refuses both — the
|
|
3744
|
+
door's own words are *a section with no prose is a heading* and *a section is named by its
|
|
3745
|
+
heading* — and a file carrying either lints clean.
|
|
3746
|
+
|
|
3747
|
+
Neither is cosmetic, and the pointer is why. A line renders `→ §<id>` and the gate holds
|
|
3748
|
+
that the address resolves, so a heading with nothing under it satisfies that check while
|
|
3749
|
+
giving the reader none of what the pointer promised: `show` prints it and `brief` hands it
|
|
3750
|
+
to whoever starts the task, both answering with a title and a blank.
|
|
3751
|
+
|
|
3752
|
+
The five rows beside them in that register stay silent and are a different answer: a
|
|
3753
|
+
heading is one line, so a newline in a title is about an argument, and an address this
|
|
3754
|
+
scheme cannot read is not parsed as a section at all — the heading is prose, and prose in
|
|
3755
|
+
a prose file is allowed.
|
|
3756
|
+
|
|
3757
|
+
Not repairable, which is why both are `compose`: what the paragraph should say and what
|
|
3758
|
+
the heading should be called are the author's, and the tool writes neither (L4).
|
|
3759
|
+
|
|
3760
|
+
**Only a section a line points at**, which is the symptom's own wording and the thing that
|
|
3761
|
+
makes it decidable. A heading nothing addresses is prose under a heading — this file's own
|
|
3762
|
+
`§0` is one, a container whose children are the rationale — and `section.orphan` is what
|
|
3763
|
+
names one of those. The subtree is read for the same reason `_budget` reads it: the walk
|
|
3764
|
+
hands over a section's own paragraph, and a parent's argument is its children.
|
|
3765
|
+
"""
|
|
3766
|
+
if not pointed:
|
|
3767
|
+
return []
|
|
3768
|
+
whole = find(prose, section.anchor) or section
|
|
3769
|
+
out: list[Finding] = []
|
|
3770
|
+
if not section.title.strip():
|
|
3771
|
+
out.append(
|
|
3772
|
+
Finding(
|
|
3773
|
+
"title.empty",
|
|
3774
|
+
file,
|
|
3775
|
+
f"§{section.anchor} is addressed and unnamed: a section is named by its "
|
|
3776
|
+
f"heading, and a pointer resolving here reaches an address and no subject",
|
|
3777
|
+
section.first,
|
|
3778
|
+
section.anchor,
|
|
3779
|
+
)
|
|
3780
|
+
)
|
|
3781
|
+
if not whole.body.strip():
|
|
3782
|
+
out.append(
|
|
3783
|
+
Finding(
|
|
3784
|
+
"body.empty",
|
|
3785
|
+
file,
|
|
3786
|
+
f"§{section.anchor} has a heading and no prose: the line pointing here "
|
|
3787
|
+
f"promised a rationale, and `show` answers with a title and a blank",
|
|
3788
|
+
section.first,
|
|
3789
|
+
section.anchor,
|
|
3790
|
+
)
|
|
3791
|
+
)
|
|
3792
|
+
return out
|
|
3793
|
+
|
|
3794
|
+
|
|
3795
|
+
def _budget(
|
|
3796
|
+
prose: Document, section: Section, *, pointed: bool, file: str
|
|
3797
|
+
) -> list[Finding]:
|
|
3798
|
+
handed = (find(prose, section.anchor) if pointed else None) or section
|
|
3799
|
+
# The prose file's own budget where it declares one (RK50): `[limits.improvements]` is
|
|
3800
|
+
# the same declaration `[limits.changelog]` is, and this is the file it governs.
|
|
3801
|
+
limit = prose.schema.section_max
|
|
3802
|
+
if handed.words <= limit:
|
|
3803
|
+
return []
|
|
3804
|
+
return [
|
|
3805
|
+
Finding(
|
|
3806
|
+
"section.too-long",
|
|
3807
|
+
file,
|
|
3808
|
+
f"{over_by(handed.words, limit, unit='word')}; a section this long is "
|
|
3809
|
+
f"two sections, or a paragraph that belongs in the commit",
|
|
3810
|
+
section.first,
|
|
3811
|
+
section.anchor,
|
|
3812
|
+
)
|
|
3813
|
+
]
|
|
3814
|
+
|
|
3815
|
+
|
|
3816
|
+
def _unowned(
|
|
3817
|
+
section: Section,
|
|
3818
|
+
file: str,
|
|
3819
|
+
*,
|
|
3820
|
+
shipped: bool,
|
|
3821
|
+
owners: tuple[str, ...],
|
|
3822
|
+
claimants: tuple[str, ...] = (),
|
|
3823
|
+
) -> Finding | None:
|
|
3824
|
+
"""A section whose task no open line carries — gone, or never there.
|
|
3825
|
+
|
|
3826
|
+
`owners` is what the section says it belongs to, which is the anchor under the id scheme
|
|
3827
|
+
and the ids in the heading under an outline (RK61). Named in the message, because
|
|
3828
|
+
`§XVI.12` alone tells a reader nothing about which task left.
|
|
3829
|
+
|
|
3830
|
+
`claimants` is the other reader of the same fact, and until RK134 the two disagreed:
|
|
3831
|
+
this check decided from the ids in the heading while `section drop` decides from the
|
|
3832
|
+
pointers that resolve, so a section **still pointed at by** four open lines was reported
|
|
3833
|
+
stale and the only remedy the finding named was the one the tool refuses. RK64 already
|
|
3834
|
+
settled it for `ship` — a section another open line points at is kept, and the reason is
|
|
3835
|
+
reported — so the state this reports is the one `ship` itself writes. Shio's `VI.1` is
|
|
3836
|
+
the live case: SH22 shipped, SH44-SH47 are open against the same design, and the only
|
|
3837
|
+
way out was to retitle the heading by hand. A finding whose remedy the tool refuses is
|
|
3838
|
+
worse than no finding, which is the split RK16 exists to keep.
|
|
3839
|
+
"""
|
|
3840
|
+
if claimants:
|
|
3841
|
+
return None
|
|
3842
|
+
named = ", ".join(owners)
|
|
3843
|
+
if shipped:
|
|
3844
|
+
return Finding(
|
|
3845
|
+
"section.stale",
|
|
3846
|
+
file,
|
|
3847
|
+
f"{named} is in the changelog and this rationale is still here: "
|
|
3848
|
+
f"`ship` deletes the section, so this survived a hand edit",
|
|
3849
|
+
section.first,
|
|
3850
|
+
section.anchor,
|
|
3851
|
+
)
|
|
3852
|
+
return Finding(
|
|
3853
|
+
"section.orphan",
|
|
3854
|
+
file,
|
|
3855
|
+
f"no line in any governed file carries {named}, so nothing can ever point "
|
|
3856
|
+
f"at this section",
|
|
3857
|
+
section.first,
|
|
3858
|
+
section.anchor,
|
|
3859
|
+
)
|
|
3860
|
+
|
|
3861
|
+
|
|
3862
|
+
def _paths(config: Config, documents: dict[str, Document], tree: Tree) -> list[Finding]:
|
|
3863
|
+
"""Paths a *shipped* line claims, resolved against disk (RK15, narrowed by RK46).
|
|
3864
|
+
|
|
3865
|
+
Two exemptions, and both turn on which file is being read rather than on the token.
|
|
3866
|
+
|
|
3867
|
+
Lines only: an unshipped design's whole job is to describe a file that does not exist
|
|
3868
|
+
yet — §RK26 names `.claude-plugin/marketplace.json` and is right to — so resolving a
|
|
3869
|
+
section's prose would fail every honest forward reference.
|
|
3870
|
+
|
|
3871
|
+
And the ledger only, which is the same reasoning applied one file up. A roadmap
|
|
3872
|
+
describes work that has **not happened**, so the paths in it are disproportionately
|
|
3873
|
+
the artefacts its tasks exist to write; naming one is what a task line is for. Shio
|
|
3874
|
+
had eight such findings and all eight were false. A shipped line is the opposite
|
|
3875
|
+
claim — the work is done, so a path it names and the repository lacks is a real
|
|
3876
|
+
defect, and the only one here worth exit 1.
|
|
3877
|
+
|
|
3878
|
+
The one place a baseline run resolves against the *revision* rather than the working
|
|
3879
|
+
tree (RK84). It has to: this finding is the only one whose subject is outside the
|
|
3880
|
+
governed files, so an artefact deleted since the ref would otherwise be missing in both
|
|
3881
|
+
runs and forgiven — and a rename the ledger did not follow is precisely the true finding
|
|
3882
|
+
this check produced on the corpus that motivated it.
|
|
3883
|
+
|
|
3884
|
+
**And the working tree is then not a reader at all** (RK218). Half of that resolution
|
|
3885
|
+
moved and half did not: `carries` and `anywhere` asked git at the ref while
|
|
3886
|
+
`referenced.exists` still asked this disk, so a file created since the ref — untracked,
|
|
3887
|
+
never committed, invisible to git — silenced a finding the revision genuinely had. The
|
|
3888
|
+
same commit answered two ways depending on somebody's scratch file. So at a revision the
|
|
3889
|
+
filesystem is skipped outright rather than corrected: `exists` is a fact about now, and
|
|
3890
|
+
a run that names a revision is not asking about now.
|
|
3891
|
+
"""
|
|
3892
|
+
document = documents.get("changelog")
|
|
3893
|
+
if document is None:
|
|
3894
|
+
return []
|
|
3895
|
+
file = config.relative(config.path("changelog"))
|
|
3896
|
+
near = config.path("changelog").parent
|
|
3897
|
+
# One pass, keeping what it found (RK223). The candidates have to be gathered before
|
|
3898
|
+
# `.gitignore` is asked, because one call for all of them is what keeps that question
|
|
3899
|
+
# cheap (RK213) — and gathering them with a comprehension of its own made the findings
|
|
3900
|
+
# comprehension repeat the whole scan: 1602 entries into `paths_in` for 801 entries,
|
|
3901
|
+
# and 2.9 s of a `lint` that a pre-commit hook waits for (RK17).
|
|
3902
|
+
unresolved = [
|
|
3903
|
+
(entry, token)
|
|
3904
|
+
for entry in document.entries
|
|
3905
|
+
for token in _candidates(tree, entry.raw, near)
|
|
3906
|
+
]
|
|
3907
|
+
untracked = tree.declared_untracked([(token, near) for _, token in unresolved])
|
|
3908
|
+
left = _left_the_repository(config, tree, [token for _, token in unresolved])
|
|
3909
|
+
return [
|
|
3910
|
+
Finding(
|
|
3911
|
+
"path.missing",
|
|
3912
|
+
file,
|
|
3913
|
+
f"names {token}, which is not in the repository",
|
|
3914
|
+
entry.lineno,
|
|
3915
|
+
entry.task.id,
|
|
3916
|
+
)
|
|
3917
|
+
for entry, token in unresolved
|
|
3918
|
+
# Not a path this repository has declared it will never track (RK213): a build
|
|
3919
|
+
# output is absent from a bare checkout and present for whoever just compiled, so
|
|
3920
|
+
# a gate that read the filesystem alone answered by machine.
|
|
3921
|
+
if token not in untracked
|
|
3922
|
+
# And not one it *had* when the entry was written (RK1217): a shipped sentence is a
|
|
3923
|
+
# claim about the tree that shipped it, and a file later extracted into its own
|
|
3924
|
+
# repository makes history a finding on every run for ever.
|
|
3925
|
+
and token not in left
|
|
3926
|
+
]
|
|
3927
|
+
|
|
3928
|
+
|
|
3929
|
+
def _left_the_repository(
|
|
3930
|
+
config: Config, tree: Tree, tokens: Sequence[str]
|
|
3931
|
+
) -> frozenset[str]:
|
|
3932
|
+
"""Which of these paths this repository once held and no longer does (RK1217).
|
|
3933
|
+
|
|
3934
|
+
Asked **last and only of what already failed**, which is the whole of its cost: `exists`,
|
|
3935
|
+
`anywhere` and `check-ignore` have each answered before a token reaches here, so a healthy
|
|
3936
|
+
repository asks git nothing and a corpus with stale entries pays one call per token — six
|
|
3937
|
+
on the ledger that motivated this, against 801 entries.
|
|
3938
|
+
|
|
3939
|
+
Skipped at a revision, where the question is already being asked of history: a run naming a
|
|
3940
|
+
`--baseline` resolves the tree at that ref (RK218), and reaching past it to *every* ref
|
|
3941
|
+
would forgive a path the baseline's own tree never had.
|
|
3942
|
+
"""
|
|
3943
|
+
if tree.rev is not None or not tokens:
|
|
3944
|
+
return frozenset()
|
|
3945
|
+
from roadkeep.history import left_the_repository # noqa: PLC0415 - RK260
|
|
3946
|
+
|
|
3947
|
+
return frozenset(
|
|
3948
|
+
token
|
|
3949
|
+
for token in dict.fromkeys(tokens)
|
|
3950
|
+
if left_the_repository(config.root, token)
|
|
3951
|
+
)
|
|
3952
|
+
|
|
3953
|
+
|
|
3954
|
+
def _candidates(tree: Tree, text: str, near: Path) -> tuple[str, ...]:
|
|
3955
|
+
"""Every path one sentence names that this tree does not have, before `.gitignore`.
|
|
3956
|
+
|
|
3957
|
+
The half :func:`_paths` and :func:`unresolved` share, so the gate and the write path
|
|
3958
|
+
cannot come to disagree about what counts as missing — which they would, being written
|
|
3959
|
+
weeks apart against the same six rules (RK55, RK173, RK213, RK217, RK218).
|
|
3960
|
+
|
|
3961
|
+
``known`` is the bound method and not its answer (RK222): it caches, so passing it makes
|
|
3962
|
+
the listing lazy for free, and a sentence whose every path resolves asks git nothing.
|
|
3963
|
+
"""
|
|
3964
|
+
return tuple(
|
|
3965
|
+
referenced.path
|
|
3966
|
+
for referenced in paths_in(
|
|
3967
|
+
text,
|
|
3968
|
+
tree.config.root,
|
|
3969
|
+
near=near,
|
|
3970
|
+
known=tree.directories,
|
|
3971
|
+
has=lambda token: tree.holds(token, near),
|
|
3972
|
+
)
|
|
3973
|
+
if not referenced.exists and not tree.anywhere(referenced.path)
|
|
3974
|
+
)
|
|
3975
|
+
|
|
3976
|
+
|
|
3977
|
+
def unresolved(config: Config, text: str) -> tuple[str, ...]:
|
|
3978
|
+
"""The paths a sentence about *shipped* work names that this repository lacks (RK497).
|
|
3979
|
+
|
|
3980
|
+
The gate's own `path.missing` rule, asked before the prose exists rather than after it
|
|
3981
|
+
lands — which is L1, and the reason this is here rather than a second reading in
|
|
3982
|
+
:mod:`roadkeep.shipping`: one definition of missing, called from both ends.
|
|
3983
|
+
|
|
3984
|
+
Measured cost, and why a write can afford it: `paths_in` asks the filesystem per token
|
|
3985
|
+
and asks git only for a token that fails (RK222), and `check-ignore` runs only for what
|
|
3986
|
+
survives that (RK213). A sentence whose paths resolve — every sentence anybody means to
|
|
3987
|
+
write — costs one `stat` each and no subprocess at all.
|
|
3988
|
+
|
|
3989
|
+
Resolved against the **working tree**, never a revision: the caller is writing the entry
|
|
3990
|
+
now, so "now" is the only tree the question can be about.
|
|
3991
|
+
"""
|
|
3992
|
+
near = config.path("changelog").parent
|
|
3993
|
+
tree = Tree(config)
|
|
3994
|
+
found = _candidates(tree, text, near)
|
|
3995
|
+
untracked = tree.declared_untracked([(token, near) for token in found])
|
|
3996
|
+
return tuple(token for token in found if token not in untracked)
|
|
3997
|
+
|
|
3998
|
+
|
|
3999
|
+
def _declared_untracked(
|
|
4000
|
+
config: Config, tokens: Sequence[tuple[str, Path]]
|
|
4001
|
+
) -> frozenset[str]:
|
|
4002
|
+
"""The tokens `check-ignore` says this repository will never track (RK213).
|
|
4003
|
+
|
|
4004
|
+
Both spellings per token — under the ledger's own directory and under the root (RK51) —
|
|
4005
|
+
so a `bin/…` written from `docs/` is asked about as the repository spells it. The answer
|
|
4006
|
+
is mapped back to the token, because that is what the finding names.
|
|
4007
|
+
"""
|
|
4008
|
+
if not tokens:
|
|
4009
|
+
return frozenset()
|
|
4010
|
+
asked: dict[str, str] = {}
|
|
4011
|
+
for token, near in tokens:
|
|
4012
|
+
for base in (near, config.root):
|
|
4013
|
+
spelling = _spelled(os.path.normpath(str(config.root)), str(base), token)
|
|
4014
|
+
# None is a path above the root, which is nothing this repository's
|
|
4015
|
+
# `.gitignore` could have declared — and git refuses the **whole**
|
|
4016
|
+
# invocation over one of them (RK220), through the same door as "there is
|
|
4017
|
+
# no git here", where nothing is withheld. The *spelling* is dropped and
|
|
4018
|
+
# not the token, because the other base may still be inside.
|
|
4019
|
+
if spelling is not None:
|
|
4020
|
+
asked.setdefault(spelling, token)
|
|
4021
|
+
if not asked:
|
|
4022
|
+
return frozenset()
|
|
4023
|
+
try:
|
|
4024
|
+
answered = check_ignore(config.root, tuple(asked))
|
|
4025
|
+
except HistoryUnavailable:
|
|
4026
|
+
# The question could not be asked, so nothing is withheld: silence here would read
|
|
4027
|
+
# as "this repository declared it untracked", which is the one thing it did not.
|
|
4028
|
+
return frozenset()
|
|
4029
|
+
return frozenset(asked[name] for name in answered if name in asked)
|
|
4030
|
+
|
|
4031
|
+
|
|
4032
|
+
def _spelled(root: str, base: str, token: str) -> str | None:
|
|
4033
|
+
"""How git would spell this token from this base — decided **lexically** (RK225).
|
|
4034
|
+
|
|
4035
|
+
`Config.relative` resolves the path, which is right where a junction has to be followed
|
|
4036
|
+
and ruinous where a check asks it per token: 34326 `realpath` calls at Turing's pin,
|
|
4037
|
+
7.4 s of an 11.5 s run. Every path compared against git's listing here is built from the
|
|
4038
|
+
config's own root, so the prefix already agrees and normalising the `..` segments
|
|
4039
|
+
textually gives the answer that listing holds — without touching the filesystem, which
|
|
4040
|
+
is the whole point of judging a revision.
|
|
4041
|
+
|
|
4042
|
+
None where the spelling climbs out of the repository: git has nothing to say about a
|
|
4043
|
+
path above the root, and one of them refuses a whole `check-ignore` batch (RK220).
|
|
4044
|
+
"""
|
|
4045
|
+
joined = os.path.normpath(os.path.join(base, token))
|
|
4046
|
+
if joined == root:
|
|
4047
|
+
return "."
|
|
4048
|
+
if not joined.startswith(root + os.sep):
|
|
4049
|
+
# Above the root, or on another mount: either way not a path git can be asked
|
|
4050
|
+
# about. A prefix test rather than `os.path.relpath`, which normcases and splits
|
|
4051
|
+
# both ends per call — 342330 `normcase` calls under 34133 of them (RK228) — and
|
|
4052
|
+
# cannot say more here, because both sides are built from the same config root.
|
|
4053
|
+
return None
|
|
4054
|
+
return joined[len(root) + 1 :].replace(os.sep, "/")
|
|
4055
|
+
|
|
4056
|
+
|
|
4057
|
+
@dataclass(frozen=True, slots=True)
|
|
4058
|
+
class Target:
|
|
4059
|
+
"""A file carrying a projection of the backlog, as this tree holds it (RK104)."""
|
|
4060
|
+
|
|
4061
|
+
#: The `export` flag that writes it, which is what the repair is named by.
|
|
4062
|
+
flag: str
|
|
4063
|
+
#: The path as the project spells it.
|
|
4064
|
+
where: str
|
|
4065
|
+
#: Which of the two shapes belongs between its markers.
|
|
4066
|
+
shape: str
|
|
4067
|
+
text: str
|
|
4068
|
+
|
|
4069
|
+
|
|
4070
|
+
def _targets(config: Config, tree: Tree) -> tuple[Target, ...]:
|
|
4071
|
+
"""Every file `export` writes that has been given somewhere to write (RK104).
|
|
4072
|
+
|
|
4073
|
+
**The markers are the declaration**, so a file carrying none is not a target and is not
|
|
4074
|
+
read again (RK37): a README restating nothing cannot restate it wrongly, and demanding the
|
|
4075
|
+
container would be a gate inventing what only the author may put there — which is why
|
|
4076
|
+
`docs/index.html` here, a pitch with no strip in it, is not one.
|
|
4077
|
+
"""
|
|
4078
|
+
out: list[Target] = []
|
|
4079
|
+
for flag, kind in DEFAULTS.items():
|
|
4080
|
+
# Through the resolver the write uses (RK1110), never a path spelled again here: a
|
|
4081
|
+
# target is a literal name or a governed role, and a gate that decided that for itself
|
|
4082
|
+
# would be a gate over a file nothing writes — which passes for the same reason the
|
|
4083
|
+
# drift got in.
|
|
4084
|
+
path = target_of(config, flag)
|
|
4085
|
+
raw = None if path is None else tree.blob(path)
|
|
4086
|
+
if raw is None:
|
|
4087
|
+
continue
|
|
4088
|
+
text = raw.decode("utf-8", errors="replace")
|
|
4089
|
+
if BEGIN in text:
|
|
4090
|
+
out.append(Target(flag, config.relative(path), kind.shape, text))
|
|
4091
|
+
return tuple(out)
|
|
4092
|
+
|
|
4093
|
+
|
|
4094
|
+
def _projections(
|
|
4095
|
+
config: Config, documents: dict[str, Document], targets: tuple[Target, ...]
|
|
4096
|
+
) -> list[Finding]:
|
|
4097
|
+
"""The derived block in a file this tool does not own, checked where it was written (RK104).
|
|
4098
|
+
|
|
4099
|
+
RK39 made the README's status table derived rather than restated, on the argument that a
|
|
4100
|
+
file repeating a backlog it cannot re-read is stale from the first ship. The derivation
|
|
4101
|
+
shipped and the gate over it did not, so a commit that ships a task and forgets `export`
|
|
4102
|
+
leaves a table contradicting the ledger — and what caught that here was a pytest fixture,
|
|
4103
|
+
which an adopting project does not install with the plugin.
|
|
4104
|
+
|
|
4105
|
+
Two decisions, and each is the same one made elsewhere in this module:
|
|
4106
|
+
|
|
4107
|
+
* **The block is compared, never repaired.** Every character of it is derived, so the
|
|
4108
|
+
repair is one command and the finding names it; writing it from here would make the
|
|
4109
|
+
linter a writer (L4), and `--fix` is where a derived field is normalised (RK16).
|
|
4110
|
+
* **The finding lands on the begin marker.** It is a defect about that block and the block
|
|
4111
|
+
has a place, the same reading RK34 makes of a column — so the report is usable, and the
|
|
4112
|
+
`Stop` hook's own narrowing (RK60) leaves a turn that merely moved a marker alone. What
|
|
4113
|
+
a projection goes stale against is a commit, and the commit is where this bites.
|
|
4114
|
+
|
|
4115
|
+
The block is derived from the tree's own documents, so a baseline run compares a revision's
|
|
4116
|
+
README against the counts *that* revision's files render: a stale block is standing debt to
|
|
4117
|
+
be named and forgiven (RK84), not something every commit after it is charged for.
|
|
4118
|
+
"""
|
|
4119
|
+
if not targets or "roadmap" not in documents:
|
|
4120
|
+
return []
|
|
4121
|
+
projection = project(config, documents)
|
|
4122
|
+
out: list[Finding] = []
|
|
4123
|
+
for target in targets:
|
|
4124
|
+
try:
|
|
4125
|
+
rendered = projection.body(target.shape, omit=enclosing(target.text))
|
|
4126
|
+
if splice(target.text, rendered, target.where) == target.text:
|
|
4127
|
+
continue
|
|
4128
|
+
except NoMarkers as error:
|
|
4129
|
+
# A begin with no end, or the two in the wrong order: the block has no extent, so
|
|
4130
|
+
# there is nothing to compare and `export` refuses the same file for the same
|
|
4131
|
+
# reason. Reported with the message that names the two lines to paste.
|
|
4132
|
+
out.append(
|
|
4133
|
+
Finding(
|
|
4134
|
+
"export.unmarked",
|
|
4135
|
+
target.where,
|
|
4136
|
+
str(error),
|
|
4137
|
+
_marked(target.text),
|
|
4138
|
+
# The flag, so the door under the message names the same projection the
|
|
4139
|
+
# message does (RK1110) — with a third target a literal `--readme` in the
|
|
4140
|
+
# remedy contradicted it, which is the half a reader trusts.
|
|
4141
|
+
subject=target.flag,
|
|
4142
|
+
)
|
|
4143
|
+
)
|
|
4144
|
+
continue
|
|
4145
|
+
out.append(
|
|
4146
|
+
Finding(
|
|
4147
|
+
"export.stale",
|
|
4148
|
+
target.where,
|
|
4149
|
+
f"the block between the roadkeep markers is not what the governed files "
|
|
4150
|
+
f"render: `{invocation()} export --{target.flag}` rewrites it, and every "
|
|
4151
|
+
f"character of it is derived",
|
|
4152
|
+
_marked(target.text),
|
|
4153
|
+
subject=target.flag,
|
|
4154
|
+
)
|
|
4155
|
+
)
|
|
4156
|
+
return out
|
|
4157
|
+
|
|
4158
|
+
|
|
4159
|
+
def _marked(text: str) -> int | None:
|
|
4160
|
+
"""Where the block starts, as an editor counts — the line the report sends a reader to."""
|
|
4161
|
+
for number, line in enumerate(text.split("\n"), start=1):
|
|
4162
|
+
if line.strip() == BEGIN:
|
|
4163
|
+
return number
|
|
4164
|
+
return None
|
|
4165
|
+
|
|
4166
|
+
|
|
4167
|
+
def _cycles(backlog: Backlog, file: str) -> list[Finding]:
|
|
4168
|
+
"""A group of tasks that wait on each other, anchored on its lowest id."""
|
|
4169
|
+
out: list[Finding] = []
|
|
4170
|
+
schema = backlog.config.schema
|
|
4171
|
+
for group in Graph.of(backlog).cycles():
|
|
4172
|
+
anchor = min(group, key=lambda i: id_order(i, schema))
|
|
4173
|
+
entry = backlog.entry(anchor)
|
|
4174
|
+
# A group of one is the same defect through a `Block X` dep the task is itself a
|
|
4175
|
+
# member of: the block cannot empty until this line ships, so the line waits on
|
|
4176
|
+
# itself. Worth its own sentence — "wait on each other" reads as a tool bug.
|
|
4177
|
+
message = (
|
|
4178
|
+
f"{' ↔ '.join(group)} wait on each other, so nothing in the group can be "
|
|
4179
|
+
f"started"
|
|
4180
|
+
if len(group) > 1
|
|
4181
|
+
else f"{anchor} is in its own blocker set, so no amount of shipping "
|
|
4182
|
+
f"anything else makes it ready"
|
|
4183
|
+
)
|
|
4184
|
+
out.append(
|
|
4185
|
+
Finding(
|
|
4186
|
+
"deps.cycle",
|
|
4187
|
+
file,
|
|
4188
|
+
message,
|
|
4189
|
+
None if entry is None else entry.lineno,
|
|
4190
|
+
anchor,
|
|
4191
|
+
)
|
|
4192
|
+
)
|
|
4193
|
+
return out
|
|
4194
|
+
|
|
4195
|
+
|
|
4196
|
+
# -- the gate's own two readings (RK1170) -------------------------------------
|
|
4197
|
+
#
|
|
4198
|
+
# Here and no longer in `rendering`, which is where they were cut to when that module was made
|
|
4199
|
+
# out of an 8,489-line `cli.py`: theirs was the cut with no import cycle, which is a fix for a
|
|
4200
|
+
# file's size and not for where a verb's answer lives. `Report` is what both are about, so both
|
|
4201
|
+
# are on it — and the finding-level helpers below are private to them.
|
|
4202
|
+
|
|
4203
|
+
|
|
4204
|
+
def _report_rows(config: Config, report: Report, applied: Fix, root: str, quiet: bool) -> None:
|
|
4205
|
+
from roadkeep.rendering import _print, _tree # noqa: PLC0415 - RK260
|
|
4206
|
+
|
|
4207
|
+
if not quiet:
|
|
4208
|
+
_print(applied.stated())
|
|
4209
|
+
# Notes before the findings and the summary: a note is what the gate says about a
|
|
4210
|
+
# file it is passing, and after an exit-1 report nobody would read it (RK35).
|
|
4211
|
+
for note in report.notes:
|
|
4212
|
+
print(str(note))
|
|
4213
|
+
for line in applied.refusals():
|
|
4214
|
+
print(line, file=sys.stderr)
|
|
4215
|
+
if report.clean:
|
|
4216
|
+
# The files are named on the way out even when there is nothing to say: a gate
|
|
4217
|
+
# that passed by reading nothing looks exactly like a gate that passed.
|
|
4218
|
+
print(
|
|
4219
|
+
f"{', '.join(report.checked) or 'nothing'}: {_measured(report)}, clean"
|
|
4220
|
+
f"{_standing_line(report)}{_tree(root)}"
|
|
4221
|
+
)
|
|
4222
|
+
return
|
|
4223
|
+
mechanical = 0
|
|
4224
|
+
if not quiet:
|
|
4225
|
+
mechanical = _print_findings(config, report)
|
|
4226
|
+
added = "new " if report.baseline is not None else ""
|
|
4227
|
+
print(
|
|
4228
|
+
f"{report.problems} {added}problem(s) in {_measured(report)} across "
|
|
4229
|
+
f"{len(report.checked)} file(s): {_codes_line(report)}{_standing_line(report)}{_tree(root)}"
|
|
4230
|
+
)
|
|
4231
|
+
if mechanical:
|
|
4232
|
+
# Said once and never per line (RK420): the mechanical class is the one remedy that
|
|
4233
|
+
# is identical on every finding it answers, so repeating it under each of them would
|
|
4234
|
+
# spend the report's length on the findings that cost the reader nothing.
|
|
4235
|
+
print(f"{mechanical} of them need no decision: {invocation()} lint --fix")
|
|
4236
|
+
|
|
4237
|
+
|
|
4238
|
+
def _print_findings(config: Config, report: Report) -> int:
|
|
4239
|
+
"""Every finding, with a group that is one fact said once (RK469).
|
|
4240
|
+
|
|
4241
|
+
A finding is per line and stays per line — the addresses are the evidence. What is said
|
|
4242
|
+
once is the *sentence and the remedy* where a whole run of them shares both: measured on
|
|
4243
|
+
Turing, 27 `section.ambiguous` findings and their 26 remedies were 80% of a 15,894-char
|
|
4244
|
+
report, two distinct messages once the anchor was taken off, and one `[refs]` line in
|
|
4245
|
+
`roadkeep.toml` closes every one.
|
|
4246
|
+
|
|
4247
|
+
The same argument RK420 already makes one line down, where the mechanical remedy is
|
|
4248
|
+
counted rather than repeated under each finding, and the same one RK451 made about a file
|
|
4249
|
+
a crash left NUL: one finding because the loss is one. A report whose bulk is one sentence
|
|
4250
|
+
repeated is one a reader learns to skip (RK146), and it buries the four findings here that
|
|
4251
|
+
are each about a different line.
|
|
4252
|
+
|
|
4253
|
+
Grouped by what the **emitter** declared they share, and only for runs of two or more: a
|
|
4254
|
+
single member is its own sentence, and a group of one printed as a group would be a
|
|
4255
|
+
heading over nothing.
|
|
4256
|
+
"""
|
|
4257
|
+
mechanical = 0
|
|
4258
|
+
# By the key and not by adjacency: a report interleaves files, so the members of one
|
|
4259
|
+
# group are rarely consecutive — and a grouping that only folded runs would fold Turing's
|
|
4260
|
+
# and leave a fixture's alone, which is the shape that passes a test and misses the case.
|
|
4261
|
+
# Printed at the first member's place, so the report's order is otherwise the one it had.
|
|
4262
|
+
groups: dict[tuple[str, str, str], list[Finding]] = {}
|
|
4263
|
+
for finding in report.findings:
|
|
4264
|
+
if finding.shared:
|
|
4265
|
+
groups.setdefault((finding.code, finding.file, finding.shared), []).append(finding)
|
|
4266
|
+
printed: set[tuple[str, str, str]] = set()
|
|
4267
|
+
for finding in report.findings:
|
|
4268
|
+
key = (finding.code, finding.file, finding.shared)
|
|
4269
|
+
run = groups.get(key, []) if finding.shared else []
|
|
4270
|
+
if len(run) < 2:
|
|
4271
|
+
print(str(finding))
|
|
4272
|
+
mechanical += _print_remedy(finding, config)
|
|
4273
|
+
continue
|
|
4274
|
+
if key in printed:
|
|
4275
|
+
continue
|
|
4276
|
+
printed.add(key)
|
|
4277
|
+
first = finding
|
|
4278
|
+
# The pair once, the addresses under it: `file:line` each, which is what an editor
|
|
4279
|
+
# opens and what an author choosing which file takes the namespace counts.
|
|
4280
|
+
print(f"{first.file} {first.code} {len(run)} addresses {first.shared}")
|
|
4281
|
+
print(f" {' '.join(f'{one.token}:{one.lineno}' for one in run)}")
|
|
4282
|
+
mechanical += _print_remedy(first, config)
|
|
4283
|
+
return mechanical
|
|
4284
|
+
|
|
4285
|
+
|
|
4286
|
+
def _print_remedy(finding: Finding, config: Config) -> int:
|
|
4287
|
+
"""Print what closes this finding, and return 1 where that was `--fix`'s (RK420).
|
|
4288
|
+
|
|
4289
|
+
Printed by default rather than behind a flag. The defect being answered is a caller
|
|
4290
|
+
spending a *turn* to learn the command, so a report that carries it only on request has
|
|
4291
|
+
the cost exactly where it was: the second call is the thing being removed.
|
|
4292
|
+
|
|
4293
|
+
The mechanical class is counted instead of printed, and every other kind gets its line —
|
|
4294
|
+
including `decide`, whose whole content is the two doors and what separates them, since
|
|
4295
|
+
a decision printed as one word is a decision made by running one and reading its refusal.
|
|
4296
|
+
"""
|
|
4297
|
+
from roadkeep.remedying import remedy # noqa: PLC0415 - RK260
|
|
4298
|
+
|
|
4299
|
+
found = remedy(finding, config)
|
|
4300
|
+
if found is None or found.kind == "fix":
|
|
4301
|
+
return 1 if found is not None else 0
|
|
4302
|
+
for line in str(found).splitlines():
|
|
4303
|
+
print(f" {line}" if not line.startswith(" ") else line)
|
|
4304
|
+
return 0
|
|
4305
|
+
|
|
4306
|
+
|
|
4307
|
+
def _lint_json(config: Config, report: Report, applied: Fix, root: str) -> dict[str, object]:
|
|
4308
|
+
baseline = report.baseline
|
|
4309
|
+
return {
|
|
4310
|
+
# First, because every path below is relative to it and a payload a second tool files
|
|
4311
|
+
# against the wrong project is worse than one it cannot file at all (RK299). The same
|
|
4312
|
+
# key `install --json` already uses, spelled the same way.
|
|
4313
|
+
"root": root,
|
|
4314
|
+
"clean": report.clean and not applied.refused,
|
|
4315
|
+
# Absent without `--baseline`, so a caller reading `problems` cannot mistake a
|
|
4316
|
+
# difference for a total: with it, `findings` holds only what this tree added.
|
|
4317
|
+
**(
|
|
4318
|
+
{}
|
|
4319
|
+
if baseline is None
|
|
4320
|
+
else {
|
|
4321
|
+
"baseline": {
|
|
4322
|
+
"rev": baseline.rev,
|
|
4323
|
+
"standing": baseline.standing,
|
|
4324
|
+
"forgiven": [_finding_json(f, config) for f in baseline.forgiven],
|
|
4325
|
+
"resolved": [_finding_json(f, config) for f in baseline.resolved],
|
|
4326
|
+
}
|
|
4327
|
+
}
|
|
4328
|
+
),
|
|
4329
|
+
"fixed": [
|
|
4330
|
+
{
|
|
4331
|
+
"file": repair.file,
|
|
4332
|
+
"line": repair.lineno,
|
|
4333
|
+
"id": repair.id,
|
|
4334
|
+
"reasons": list(repair.reasons),
|
|
4335
|
+
"before": repair.before,
|
|
4336
|
+
"after": repair.after,
|
|
4337
|
+
# A key on the same list rather than a `removed` list beside `fixed` (RK357):
|
|
4338
|
+
# `line` means the pre-pass position here, and a consumer resolving addresses
|
|
4339
|
+
# has to know that from the payload rather than from an empty `after`.
|
|
4340
|
+
"removed": repair.removed,
|
|
4341
|
+
}
|
|
4342
|
+
for repair in applied.repairs
|
|
4343
|
+
],
|
|
4344
|
+
"kept": [
|
|
4345
|
+
{"file": s.file, "line": s.lineno, "id": s.id, "reason": s.reason}
|
|
4346
|
+
for s in applied.skipped
|
|
4347
|
+
],
|
|
4348
|
+
"refused": list(applied.refused),
|
|
4349
|
+
"checked": list(report.checked),
|
|
4350
|
+
"lines": report.lines,
|
|
4351
|
+
"sections": report.sections,
|
|
4352
|
+
"budgets": report.budgets,
|
|
4353
|
+
"problems": report.problems,
|
|
4354
|
+
"codes": report.codes(),
|
|
4355
|
+
"findings": [_finding_json(f, config) for f in report.findings],
|
|
4356
|
+
"notes": [
|
|
4357
|
+
{
|
|
4358
|
+
"code": note.code,
|
|
4359
|
+
"file": note.file,
|
|
4360
|
+
"line": note.lineno,
|
|
4361
|
+
"id": note.id or None,
|
|
4362
|
+
"message": note.message,
|
|
4363
|
+
**_remedy_json(note, config),
|
|
4364
|
+
}
|
|
4365
|
+
for note in report.notes
|
|
4366
|
+
],
|
|
4367
|
+
}
|
|
4368
|
+
|
|
4369
|
+
|
|
4370
|
+
def _standing_line(report: Report) -> str:
|
|
4371
|
+
"""What the baseline forgave, and what left — said out loud, both of them (RK84).
|
|
4372
|
+
|
|
4373
|
+
Both, because either number alone is the misreading §RK84 was written about: the run
|
|
4374
|
+
that deleted 160 lines of rationale took the count *down* by eight, and the drop read as
|
|
4375
|
+
an improvement right up until the two findings it added were looked at individually.
|
|
4376
|
+
"""
|
|
4377
|
+
baseline = report.baseline
|
|
4378
|
+
if baseline is None:
|
|
4379
|
+
return ""
|
|
4380
|
+
counts = f"{baseline.standing} standing"
|
|
4381
|
+
if baseline.resolved:
|
|
4382
|
+
counts += f", {len(baseline.resolved)} resolved"
|
|
4383
|
+
return f" against {baseline.rev} ({counts})"
|
|
4384
|
+
|
|
4385
|
+
|
|
4386
|
+
def _measured(report: Report) -> str:
|
|
4387
|
+
"""What was read, in its own units: task lines, sections, and budgeted files."""
|
|
4388
|
+
scope = f"{report.lines} line(s), {report.sections} section(s)"
|
|
4389
|
+
return scope if not report.budgets else f"{scope}, {report.budgets} budget(s)"
|
|
4390
|
+
|
|
4391
|
+
|
|
4392
|
+
def _codes_line(report: Report) -> str:
|
|
4393
|
+
return " ".join(f"{code} {count}" for code, count in report.codes().items())
|
|
4394
|
+
|
|
4395
|
+
|
|
4396
|
+
def _finding_json(finding: Finding, config: Config) -> dict[str, object]:
|
|
4397
|
+
return {
|
|
4398
|
+
"code": finding.code,
|
|
4399
|
+
"file": finding.file,
|
|
4400
|
+
"line": finding.lineno,
|
|
4401
|
+
# Only a character finding has one (RK34), and it is what makes an invisible
|
|
4402
|
+
# codepoint findable: `file:line:column` is what an editor jumps to.
|
|
4403
|
+
"column": finding.column,
|
|
4404
|
+
"id": finding.id or None,
|
|
4405
|
+
"message": finding.message,
|
|
4406
|
+
**_remedy_json(finding, config),
|
|
4407
|
+
}
|
|
4408
|
+
|
|
4409
|
+
|
|
4410
|
+
def _remedy_json(finding: object, config: Config) -> dict[str, object]:
|
|
4411
|
+
"""The remedy, as a key that is absent rather than null when the table has none (RK420).
|
|
4412
|
+
|
|
4413
|
+
Absent and not `"remedy": null`, because a consumer that reads the key at all is one
|
|
4414
|
+
about to run what is in it, and a null is a shape it has to branch on before it can
|
|
4415
|
+
tell "no command exists" from "this build predates the field".
|
|
4416
|
+
"""
|
|
4417
|
+
from roadkeep.remedying import remedy # noqa: PLC0415 - RK260
|
|
4418
|
+
|
|
4419
|
+
found = remedy(finding, config)
|
|
4420
|
+
return {} if found is None else {"remedy": found.payload(_served(config))}
|