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/config.py
ADDED
|
@@ -0,0 +1,1832 @@
|
|
|
1
|
+
"""`roadkeep.toml` — the format's variability, declared per project (RK3, L6).
|
|
2
|
+
|
|
3
|
+
Three real projects, one format: Shio numbers `SH` and has no strategy file, Turing
|
|
4
|
+
numbers `T` and has one, Cursarei keeps its roadmap under `docs/roadmap/`. The moment
|
|
5
|
+
any of that is hardcoded the tool serves exactly one repository, so everything that
|
|
6
|
+
differs is a key here and everything that does not is in :mod:`roadkeep.kernel.schema`.
|
|
7
|
+
|
|
8
|
+
Two decisions that matter more than the file format:
|
|
9
|
+
|
|
10
|
+
* **An unknown key is refused, never ignored.** A mistyped `symptom_max` that silently
|
|
11
|
+
falls back to the default is a limit the author believes is in force and is not —
|
|
12
|
+
the same failure the whole tool exists to remove, one layer down. Refusals are
|
|
13
|
+
batched and name the allowed keys.
|
|
14
|
+
* **Config is found by walking up**, like git. A command run from a subdirectory has to
|
|
15
|
+
reach the same backlog as one run from the root, or the answer depends on the shell's
|
|
16
|
+
working directory.
|
|
17
|
+
|
|
18
|
+
Reading order: `roadkeep.toml` first, then `[tool.roadkeep]` in `pyproject.toml`. A
|
|
19
|
+
project that already has one config file does not need a second.
|
|
20
|
+
"""
|
|
21
|
+
|
|
22
|
+
from __future__ import annotations
|
|
23
|
+
|
|
24
|
+
import re
|
|
25
|
+
import tomllib
|
|
26
|
+
from collections.abc import Mapping, Sequence
|
|
27
|
+
from dataclasses import dataclass, field, replace
|
|
28
|
+
from pathlib import Path
|
|
29
|
+
from typing import TYPE_CHECKING
|
|
30
|
+
|
|
31
|
+
if TYPE_CHECKING: # a string annotation under `from __future__ import annotations` (RK261)
|
|
32
|
+
from roadkeep.kernel.document import Document
|
|
33
|
+
from roadkeep.kernel.schema import (
|
|
34
|
+
DEFAULT_GRAMMARS,
|
|
35
|
+
DEFAULT_HEADING_WORD,
|
|
36
|
+
DEFERRED,
|
|
37
|
+
DROPPABLE,
|
|
38
|
+
MARKER_NAMES,
|
|
39
|
+
OPEN_MARKERS,
|
|
40
|
+
REF_PREFIX_RE,
|
|
41
|
+
REF_SEPARATOR,
|
|
42
|
+
RETIRED,
|
|
43
|
+
SHIPPED,
|
|
44
|
+
UNDESIGNED,
|
|
45
|
+
Dep,
|
|
46
|
+
DepKind,
|
|
47
|
+
Grammar,
|
|
48
|
+
Schema,
|
|
49
|
+
)
|
|
50
|
+
|
|
51
|
+
CONFIG_NAME = "roadkeep.toml"
|
|
52
|
+
PYPROJECT = "pyproject.toml"
|
|
53
|
+
|
|
54
|
+
#: The governed files. A project declares the ones it has; the rest are absent,
|
|
55
|
+
#: not empty — `strategy` missing means Shio, not a Shio with an empty strategy. The
|
|
56
|
+
#: same is true of `deferred` (RK96), which is why it is not in :data:`DEFAULT_PATHS`:
|
|
57
|
+
#: a project that never pauses anything has no store, rather than an empty one.
|
|
58
|
+
#:
|
|
59
|
+
#: `decisions` is the sixth and the one adopters ask for by name (RK1269): read as this format
|
|
60
|
+
#: an ADR is the pair already written here — an id, a marker, one falsifiable claim and a
|
|
61
|
+
#: reason — and the only difference is the departure. A roadmap line leaves by three doors and
|
|
62
|
+
#: a decision leaves by one, being superseded, so nothing in that file is ever deleted and it
|
|
63
|
+
#: grows only by decisions somebody actually made. **A named role and not an open tuple**: a
|
|
64
|
+
#: role no machinery knows is a file with no schema, which is the convention this tool replaces.
|
|
65
|
+
ROLES = ("roadmap", "changelog", "improvements", "strategy", "deferred", "decisions")
|
|
66
|
+
|
|
67
|
+
#: The governed files a `→ §<anchor>` pointer may address (RK172). Both, because `[files]`
|
|
68
|
+
#: declares strategy as a governed role and a line pointing at it is already in the model.
|
|
69
|
+
#: Here rather than beside either reader, because the gate and `show` resolving against
|
|
70
|
+
#: different sets is exactly what RK186 was: one of them called a section the other found.
|
|
71
|
+
#: Order is where a design goes when there is none yet — improvements first.
|
|
72
|
+
#:
|
|
73
|
+
#: `decisions` is the third (RK1361), and it is the one file here that carries **both** —
|
|
74
|
+
#: the records and the prose about them. That is the difference between the two kinds of
|
|
75
|
+
#: body and not an exception to the shape: a design section says how the work was built and
|
|
76
|
+
#: is correctly deleted by the ship that finishes it, while a decision's body says what was
|
|
77
|
+
#: weighed and what it costs, which is the half no store keeps and the half no `ship`
|
|
78
|
+
#: deletes. Last in the order, because a design with nowhere to go still goes to
|
|
79
|
+
#: `improvements`: nothing derives this role, and every body in it is one a caller named.
|
|
80
|
+
PROSE_ROLES = ("improvements", "strategy", "decisions")
|
|
81
|
+
|
|
82
|
+
#: Where a **task's** design section may go — the subset of :data:`PROSE_ROLES` that answers
|
|
83
|
+
#: "this line has a rationale and it lives somewhere" (RK1361). Not the same question: a
|
|
84
|
+
#: pointer may address any prose file, and a design has two candidates. `decisions` is
|
|
85
|
+
#: deliberately absent, and that absence is the whole distinction the third prose role
|
|
86
|
+
#: introduced — a decision's body is written *about a decision*, so a `defer` that cannot
|
|
87
|
+
#: find a design file must not report a decisions file as somewhere the design could live.
|
|
88
|
+
DESIGN_ROLES = ("improvements", "strategy")
|
|
89
|
+
|
|
90
|
+
#: The roles whose records are **lines**, which the gate reads and `govern` measures a field
|
|
91
|
+
#: over (RK1279, RK1361). Stated, not derived: it was "a declared role that is not a prose
|
|
92
|
+
#: one" until `decisions` became both, and that derivation then failed the way it was written
|
|
93
|
+
#: to fail loudly and did not — reporting a widest over three files where four hold lines,
|
|
94
|
+
#: and accepting a limit the fourth already breaks. Two overlapping sets are what the format
|
|
95
|
+
#: has, so each is named.
|
|
96
|
+
LINE_ROLES = ("roadmap", "changelog", "deferred", "decisions")
|
|
97
|
+
|
|
98
|
+
DEFAULT_PATHS: Mapping[str, str] = {
|
|
99
|
+
"roadmap": "docs/ROADMAP.md",
|
|
100
|
+
"changelog": "docs/CHANGELOG.md",
|
|
101
|
+
"improvements": "docs/IMPROVEMENTS.md",
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
#: Where the strategy file goes when a scaffold is asked for one (RK1186). **Beside the table
|
|
105
|
+
#: and not in it**, and the difference is what that table is: it declares the layout a project
|
|
106
|
+
#: *has* when it declares none, so a `strategy` row made `Config.missing()` report an absent
|
|
107
|
+
#: strategy file on every unconfigured project — measured immediately, by the test that asserts
|
|
108
|
+
#: that layout. This says where `init --strategy` would put one, which is a scaffold's decision.
|
|
109
|
+
#:
|
|
110
|
+
#: Here rather than in `adopting`, because L6's own invariant says so: two modules may spell a
|
|
111
|
+
#: governed file's default name, and the one that scaffolds is not one of them.
|
|
112
|
+
STRATEGY_PATH = "docs/STRATEGY.md"
|
|
113
|
+
|
|
114
|
+
#: Where the deferred store goes when a scaffold is asked for one (RK1259). Beside the table
|
|
115
|
+
#: for :data:`STRATEGY_PATH`'s reason and for the one this file already gives above it: a
|
|
116
|
+
#: project that never pauses anything has no store rather than an empty one, so the layout it
|
|
117
|
+
#: *has* does not include this and the layout `init --deferred` writes does.
|
|
118
|
+
#:
|
|
119
|
+
#: The verb exists because the alternative is where the refusal lands. `defer` will not
|
|
120
|
+
#: scaffold on the way past — a store invented at the moment one is needed is a format decided
|
|
121
|
+
#: by a verb — so until this the remedy was a toml key and a skeleton no command offered to
|
|
122
|
+
#: write, read out at the moment a pause reason had just been composed.
|
|
123
|
+
DEFERRED_PATH = "docs/DEFERRED.md"
|
|
124
|
+
|
|
125
|
+
#: Where the decision record goes when one is asked for (RK1269). Beside the two above and for
|
|
126
|
+
#: their reason: a project that has recorded no decision has no file, and `declare decisions`
|
|
127
|
+
#: is what writes one — never a `ship --decides` on the way past, a store invented at the moment
|
|
128
|
+
#: one is needed being a format decided by a verb.
|
|
129
|
+
DECISIONS_PATH = "docs/DECISIONS.md"
|
|
130
|
+
|
|
131
|
+
_TOP_KEYS = frozenset(
|
|
132
|
+
{
|
|
133
|
+
"prefix",
|
|
134
|
+
"ids",
|
|
135
|
+
"ref_scheme",
|
|
136
|
+
"files",
|
|
137
|
+
"limits",
|
|
138
|
+
"markers",
|
|
139
|
+
"id_sources",
|
|
140
|
+
"reserved_ids",
|
|
141
|
+
"priority",
|
|
142
|
+
"budgets",
|
|
143
|
+
"ledger",
|
|
144
|
+
"rules",
|
|
145
|
+
"non_goals",
|
|
146
|
+
# RK1265. The positive twin of the list above, governed on its own declaration.
|
|
147
|
+
"criteria",
|
|
148
|
+
"headings",
|
|
149
|
+
"report",
|
|
150
|
+
"claims",
|
|
151
|
+
"refs",
|
|
152
|
+
"tools",
|
|
153
|
+
# RK1286. What the read that replaces reading the file may cost.
|
|
154
|
+
"reads",
|
|
155
|
+
"grammar",
|
|
156
|
+
# RK1180. Which labels are standing categories rather than projects.
|
|
157
|
+
"blocks",
|
|
158
|
+
# RK1192. Whether the wired surfaces are held where they are, deliberately.
|
|
159
|
+
"install",
|
|
160
|
+
# RK1297. What a line may say has to be *present* before it can be finished.
|
|
161
|
+
"requirements",
|
|
162
|
+
}
|
|
163
|
+
)
|
|
164
|
+
#: `[grammar.<role>]` — the shape of a role's records, which L6 declared everything about
|
|
165
|
+
#: except (RK1064). Three keys and no fourth: what a record starts from, which markers it
|
|
166
|
+
#: may carry, and which slots it does without. `states` is not among them — whether a file
|
|
167
|
+
#: *is* a status is a fact about the tool's own roles, so a project may reshape a line and
|
|
168
|
+
#: never invent a state for which no verb exists.
|
|
169
|
+
_GRAMMAR_KEYS = frozenset({"extends", "markers", "drop"})
|
|
170
|
+
#: `[tools]` — what one served tool may cost a session (RK1059). Its own table and not a
|
|
171
|
+
#: `[budgets]` entry, because every key there is a **path** and this cost is not a file: it
|
|
172
|
+
#: is composed per session from the parser, the config and the `TOOLS` table, so an entry
|
|
173
|
+
#: under a name no file has would break the one thing that table's refusals can say.
|
|
174
|
+
#:
|
|
175
|
+
#: Per tool and not per list, which is the decision RK464 deliberately left open. A ceiling
|
|
176
|
+
#: on the total fails on whichever tool is added last and names nothing; a per-tool one is
|
|
177
|
+
#: refused by the tool that grew, which is the tool whose description somebody just edited —
|
|
178
|
+
#: and `cost --tools` already ranks them, so the read that composes the fix exists.
|
|
179
|
+
_TOOLS_KEYS = frozenset({"characters", "session"})
|
|
180
|
+
#: `[reads] brief` — what the one read that replaces reading the file may cost (RK1286). Its
|
|
181
|
+
#: own table and not a `[budgets]` entry, for `[tools]`' reason exactly: every key there is a
|
|
182
|
+
#: **path**, and a brief is composed per call from the line, its design, the deps, the
|
|
183
|
+
#: non-goals and four allowances. Not `[limits]` either — that table is the widths of the
|
|
184
|
+
#: fields a line carries, and this is the size of an answer about one.
|
|
185
|
+
_READS_KEYS = frozenset({"brief"})
|
|
186
|
+
#: `[install]` — whether this project holds its wired launcher, hook and skill at the version
|
|
187
|
+
#: they are (RK1192). Its own table and not a `[rules]` entry, because every key there is a
|
|
188
|
+
#: prose rule one governed *file* is not held to, and this is about the harness around them.
|
|
189
|
+
_INSTALL_KEYS = frozenset({"pinned", "enforced"})
|
|
190
|
+
#: `[claims]` — how long a claim on a line reads as held (RK151). Its own table for the reason
|
|
191
|
+
#: `[headings]` has one: a bare `held` beside `prefix` would read as one of the limits, and it
|
|
192
|
+
#: is not a limit on any field — it is the one number in the claim mechanism that is a
|
|
193
|
+
#: judgement about how long work takes.
|
|
194
|
+
_CLAIMS_KEYS = frozenset({"held"})
|
|
195
|
+
#: `[requirements]` — the words a `(needs: …)` group may draw on (RK1297). Its own table for
|
|
196
|
+
#: `[markers]`' reason: the vocabulary is one part of a shape whose other parts are a caller's
|
|
197
|
+
#: (`pick --have`) and a line's, and a bare `requirements` beside `priority` would read as a
|
|
198
|
+
#: list this backlog is subject to rather than one its lines quote from.
|
|
199
|
+
_REQUIREMENTS_KEYS = frozenset({"declared"})
|
|
200
|
+
#: `[headings]` — the word a project files work under (RK75). Its own table and not a top
|
|
201
|
+
#: key, because the heading is a shape with more than one part and the next question about
|
|
202
|
+
#: it (a sub-block that carries no word at all) belongs under the same heading.
|
|
203
|
+
_HEADING_KEYS = frozenset({"word", "permanent"})
|
|
204
|
+
#: `[ids]` — the shape of an id, where a project already spells one the format refused
|
|
205
|
+
#: (RK106). Its own table for the reason `[headings]` is: the spelling has more than one
|
|
206
|
+
#: part, and a bare `pad` beside `prefix` would read as one of the limits.
|
|
207
|
+
_IDS_KEYS = frozenset({"pad", "suffix"})
|
|
208
|
+
#: `[non_goals]` — the two fields the roadmap's other bullet has (RK70). Opt-in for RK66's
|
|
209
|
+
#: reason: two live corpora wrote theirs as free prose, and a default that reported findings
|
|
210
|
+
#: on the first run is a gate that gets bypassed instead of adopted.
|
|
211
|
+
_SCOPE_KEYS = frozenset({"lead", "why"})
|
|
212
|
+
_BUDGET_KEYS = frozenset({"lines", "bytes"})
|
|
213
|
+
#: Which slots the ledger's lines carry (RK43, RK48). Its own table because the shape of a
|
|
214
|
+
#: file is one decision with two parts, and `markers.ledger` put half of it under a heading
|
|
215
|
+
#: that cannot name the other half: a symptom is not a marker.
|
|
216
|
+
_LEDGER_KEYS = frozenset({"marker", "symptom"})
|
|
217
|
+
#: The rules a role may switch off (`[rules.<role>]`, RK52). Not limits, because they
|
|
218
|
+
#: are not numbers, and not `[ledger]`, because that table says which *slots* a line has.
|
|
219
|
+
#: `ref` joins them for RK66's reason: whether a line must point at a rationale section is
|
|
220
|
+
#: a convention, not a fact about the format, and a project that documents the opposite one
|
|
221
|
+
#: gets a finding for obeying itself.
|
|
222
|
+
_RULE_KEYS = {
|
|
223
|
+
"one_sentence": "one_sentence",
|
|
224
|
+
"terminator": "terminator",
|
|
225
|
+
"ref": "ref_required",
|
|
226
|
+
}
|
|
227
|
+
_LIMIT_KEYS = {
|
|
228
|
+
"symptom": "symptom_max",
|
|
229
|
+
"why": "why_max",
|
|
230
|
+
# What a partial entry's qualifier may cost (RK121). Per project like every other
|
|
231
|
+
# limit (L6): `local half` and `the SH22 half` are one corpus's answer to "which part",
|
|
232
|
+
# and a project whose halves have longer names has not made the qualifier a summary.
|
|
233
|
+
"part": "part_max",
|
|
234
|
+
"line": "line_max",
|
|
235
|
+
# A section is prose, so its budget is words and its shape is a width (RK9).
|
|
236
|
+
"section": "section_max",
|
|
237
|
+
"prose": "prose_width",
|
|
238
|
+
}
|
|
239
|
+
_MARKER_KEYS = frozenset({"open", "shipped", "retired", "deferred", "undesigned"})
|
|
240
|
+
# The invisible ones. A marker carrying U+FE0F renders identically and compares
|
|
241
|
+
# unequal, so a config that declares one puts every line in the file permanently
|
|
242
|
+
# out of round-trip. Refuse it where it is typed.
|
|
243
|
+
_INVISIBLE = {"️": "U+FE0F", "": "U+200D", "": "U+200B"}
|
|
244
|
+
|
|
245
|
+
|
|
246
|
+
@dataclass(frozen=True, slots=True)
|
|
247
|
+
class Budget:
|
|
248
|
+
"""A file that is loaded every turn, and what it is allowed to cost (RK30).
|
|
249
|
+
|
|
250
|
+
Declared here rather than in the file's own prose, which is the arrangement that let
|
|
251
|
+
Shio's `agents.md` reach 186 KB while stating a 150-line rule at the bottom of itself:
|
|
252
|
+
a budget nothing reads is a budget nothing enforces. Both numbers are optional and at
|
|
253
|
+
least one is required — an entry that declares neither is refused, because it would
|
|
254
|
+
read as a budget and hold nobody to anything.
|
|
255
|
+
"""
|
|
256
|
+
|
|
257
|
+
path: Path
|
|
258
|
+
lines: int | None = None
|
|
259
|
+
#: Size on disk. Bytes and not tokens: the tool guesses at nothing, and 186 KB was the
|
|
260
|
+
#: measurement that started this — roughly 46k tokens, spent on every single turn.
|
|
261
|
+
bytes: int | None = None
|
|
262
|
+
|
|
263
|
+
|
|
264
|
+
def spent(raw: bytes) -> dict[str, int]:
|
|
265
|
+
"""What an always-loaded file costs, in the two units `[budgets]` declares (RK30).
|
|
266
|
+
|
|
267
|
+
Bytes and not text, for the reason the gate reads them that way: a budget is about what
|
|
268
|
+
a loader pays, and an instruction file is not a format this tool has any business
|
|
269
|
+
decoding (L4). Here rather than in either reader, because the gate that refuses the
|
|
270
|
+
overrun (RK30) and the read that reports the room before an edit (RK345) are two callers
|
|
271
|
+
of one measurement — and two spellings of it would be the disagreement RK50 removed.
|
|
272
|
+
|
|
273
|
+
**The terminator is normalised out and nothing else is** (RK1105). Counted raw, the byte
|
|
274
|
+
number is a fact about the *checkout*: one commit of claude-tray's `AGENTS.md` is 24310
|
|
275
|
+
bytes with CRLF and 23999 with LF under `core.autocrlf=input`, so a ceiling moves 311
|
|
276
|
+
bytes per machine while `git diff` shows nothing, and a commit one byte inside its budget
|
|
277
|
+
passes on the runner and is refused on the desk. A budget is a fact about the commit —
|
|
278
|
+
that is what a reviewer reads and what CI gates — so `\\r\\n` is counted as the `\\n` the
|
|
279
|
+
repository stores. What this checkout pays over that is real and is not dropped in
|
|
280
|
+
silence: :func:`translated` is the difference, which `lint` states as a note and
|
|
281
|
+
`budget` prints beside the number.
|
|
282
|
+
"""
|
|
283
|
+
counted = raw.replace(b"\r\n", b"\n")
|
|
284
|
+
return {"lines": counted.count(b"\n") + (0 if counted.endswith(b"\n") or not counted else 1),
|
|
285
|
+
"bytes": len(counted)}
|
|
286
|
+
|
|
287
|
+
|
|
288
|
+
def translated(raw: bytes) -> int:
|
|
289
|
+
"""How many bytes this checkout carries that :func:`spent` did not count (RK1105).
|
|
290
|
+
|
|
291
|
+
One per `\\r\\n`, which is the whole difference between the two measurements — a lone `\\r`
|
|
292
|
+
is a byte in its own right in both, and `char.mixed-endings` is what has something to say
|
|
293
|
+
about a file carrying two conventions.
|
|
294
|
+
"""
|
|
295
|
+
return raw.count(b"\r\n")
|
|
296
|
+
|
|
297
|
+
|
|
298
|
+
@dataclass(frozen=True, slots=True)
|
|
299
|
+
class Scope:
|
|
300
|
+
"""What a governed non-goal may say, when a project declares its list governed (RK70).
|
|
301
|
+
|
|
302
|
+
Two numbers and no marker, no id and no pointer: a non-goal has no lifecycle to state.
|
|
303
|
+
The list is eight lines that change once a year, and an id would buy them a retirement,
|
|
304
|
+
a rename and a second file to disagree with — so the lead *is* the address.
|
|
305
|
+
"""
|
|
306
|
+
|
|
307
|
+
#: The bolded head, which is what a `brief` prints and what a duplicate is judged on.
|
|
308
|
+
lead: int = 80
|
|
309
|
+
#: The rest of the bullet. Longer than a task's `why` and not one sentence: the corpus
|
|
310
|
+
#: argues these in two, and the file has no rationale section to send the second to.
|
|
311
|
+
why: int = 320
|
|
312
|
+
|
|
313
|
+
|
|
314
|
+
#: `[claims] held`, in **minutes** — how long a claim reads as held before a later caller
|
|
315
|
+
#: steps over it (RK119, RK151). An hour by default: long enough that a worker mid-task still
|
|
316
|
+
#: holds the line, short enough that a claim nobody released clears inside one session.
|
|
317
|
+
CLAIM_HELD = 60
|
|
318
|
+
#: The longest window this will accept. The reason there is an expiry rather than a lock is
|
|
319
|
+
#: that a killed worker must not take a line out of the backlog for ever, so a window nobody
|
|
320
|
+
#: would wait out is the defect coming back under a config key (RK151) — one working day is
|
|
321
|
+
#: where that starts, an abandoned claim past it surviving a night. It is also what turns the
|
|
322
|
+
#: unit into a refusal: `held = 3600`, meant as seconds, is refused rather than obeyed.
|
|
323
|
+
CLAIM_HELD_MAX = 480
|
|
324
|
+
|
|
325
|
+
|
|
326
|
+
class ConfigError(ValueError):
|
|
327
|
+
"""Every problem with the file, not the first one found.
|
|
328
|
+
|
|
329
|
+
An **unknown key adds a clause** (RK1150), and it is about this process rather than about the
|
|
330
|
+
file: `unknown key 'headings.permanent' (allowed: headings.word)` is every word true, and the
|
|
331
|
+
conclusion it invites — delete it, or fix a config that is already right — is wrong whenever
|
|
332
|
+
the key belongs to a *later* roadkeep than the one reading. Reached from Shio, where the
|
|
333
|
+
server resolves this package from the plugin cache and the project from a checkout.
|
|
334
|
+
|
|
335
|
+
A key nothing ever declared is a typo and a key this build predates is an upgrade; the file
|
|
336
|
+
cannot tell them apart, so both are named and the command that decides it is carried the way
|
|
337
|
+
every `lint` finding carries one (RK14/15). Once per refusal and not once per key: three
|
|
338
|
+
unknown keys are one skew, and the same sentence three times reads as three problems.
|
|
339
|
+
"""
|
|
340
|
+
|
|
341
|
+
def __init__(self, problems: tuple[str, ...], path: Path | None = None) -> None:
|
|
342
|
+
self.problems = tuple(problems)
|
|
343
|
+
self.path = path
|
|
344
|
+
where = f"{path}: " if path else ""
|
|
345
|
+
super().__init__(where + "; ".join(self.problems) + _skew(self.problems))
|
|
346
|
+
|
|
347
|
+
|
|
348
|
+
#: The three bytes a Windows editor writes ahead of a UTF-8 file, which `tomllib` refuses by
|
|
349
|
+
#: specification — and refuses at line 1, column 1, where the statement is correct.
|
|
350
|
+
_BOM = b"\xef\xbb\xbf"
|
|
351
|
+
|
|
352
|
+
|
|
353
|
+
def _marked(path: Path, broken: tomllib.TOMLDecodeError) -> Exception:
|
|
354
|
+
"""A TOML refusal, re-read as the byte that caused it where that is what it is (RK1030).
|
|
355
|
+
|
|
356
|
+
`Invalid statement (at line 1, column 1)` is `tomllib` answering about the first thing it
|
|
357
|
+
could parse, which is `prefix = "RK"` — correct, and pointing at a line with nothing wrong
|
|
358
|
+
with it. What is wrong is three bytes no editor shows, in the file a project writes before
|
|
359
|
+
it has run anything, and on Windows the default route writes them: PowerShell 5.1's
|
|
360
|
+
`Set-Content -Encoding utf8` and `Out-File` both add the mark.
|
|
361
|
+
|
|
362
|
+
**Named and not stripped**, which is the difference from :func:`roadkeep.verbs.reading`'s
|
|
363
|
+
answer to the same byte one file over. A prose field is a sentence somebody typed and the
|
|
364
|
+
mark is the encoder's; this file is the project's own declaration, and a tool that quietly
|
|
365
|
+
accepted one encoding variant of it would teach nothing — the author would meet the mark
|
|
366
|
+
again in `git diff`, in their editor's next save, and in whatever reads the file next.
|
|
367
|
+
|
|
368
|
+
Every other TOML error is handed back exactly as `tomllib` wrote it: this reads the bytes
|
|
369
|
+
only after a refusal, and only to answer the one question the refusal could not.
|
|
370
|
+
"""
|
|
371
|
+
try:
|
|
372
|
+
if not path.read_bytes().startswith(_BOM):
|
|
373
|
+
return broken
|
|
374
|
+
except OSError:
|
|
375
|
+
return broken
|
|
376
|
+
return ConfigError(
|
|
377
|
+
(
|
|
378
|
+
f"the file opens with a byte-order mark (U+FEFF), which TOML has no reading "
|
|
379
|
+
f"for — so the refusal below is about the first line it could parse and not "
|
|
380
|
+
f"about anything wrong with it ({broken}). Re-save it as UTF-8 without a BOM; "
|
|
381
|
+
f"in PowerShell, `Set-Content -Encoding utf8` and `Out-File` both write one",
|
|
382
|
+
),
|
|
383
|
+
path,
|
|
384
|
+
)
|
|
385
|
+
|
|
386
|
+
|
|
387
|
+
#: Every argument this CLI takes that carries a path, and which directory it is read from
|
|
388
|
+
#: (RK1103). RK1101 stated the rule for one verb and this is the reading that says where else
|
|
389
|
+
#: it applies — and the answer it produced is that there are **three** classes and not two.
|
|
390
|
+
#:
|
|
391
|
+
#: * ``project`` — names a file of the project, so a relative one is resolved against the root
|
|
392
|
+
#: by :meth:`Config.locate`. `-C` selects the project and never the working directory, and
|
|
393
|
+
#: over MCP the two are never the same tree.
|
|
394
|
+
#: * ``caller`` — names a file to *read from*, the way `cat` does. The caller's own, relative
|
|
395
|
+
#: to the caller. Resolving one against the root would be a rule about somebody else's shell.
|
|
396
|
+
#: * ``repo`` — repo-relative **text**, and never resolved at all. A claim's scope becomes a
|
|
397
|
+
#: `git add --` argument matched against what git reports, which is repo-relative already;
|
|
398
|
+
#: resolving it would make `src/` absolute and stop it covering `src/a.py` (RK495). git's
|
|
399
|
+
#: merge driver passes `%O`, `%A`, `%B` and `%P` under its own contract, which is this class
|
|
400
|
+
#: arrived at from the other side.
|
|
401
|
+
#:
|
|
402
|
+
#: Held by `tests/test_config.py` against the parser, so a key naming no argument is a failure
|
|
403
|
+
#: rather than a classification that quietly stopped applying — the rule `_DIVERGENT` has.
|
|
404
|
+
#: What that test **cannot** say is that the table is complete: no property of an argparse
|
|
405
|
+
#: argument marks it as carrying a path (`--with` is `alongside`, `install --source` reads as
|
|
406
|
+
#: neither), so the guard is a scan for the obvious spellings and the rest is this list. That
|
|
407
|
+
#: limit is stated rather than papered over: a new path argument spelled `--out-dir` is caught,
|
|
408
|
+
#: one spelled `--target` is not.
|
|
409
|
+
PATH_ARGUMENTS: Mapping[str, Mapping[str, str]] = {
|
|
410
|
+
# `-C` is the caller's, and it is the one row worth saying out loud: the flag that selects
|
|
411
|
+
# the project is itself read from the process's directory, because there is no project to
|
|
412
|
+
# be relative to until it has been answered. Every `project` row below is relative to what
|
|
413
|
+
# this one found.
|
|
414
|
+
"": {"directory": "caller"},
|
|
415
|
+
# Both capture paths are the caller's, exactly as `replay`'s is (RK1141, RK1142): the file
|
|
416
|
+
# lives under the project, and what is handed to the process is a path the process resolves
|
|
417
|
+
# — a `-C` elsewhere does not make somebody's argument project-relative.
|
|
418
|
+
"add": {"section_body_file": "caller", "capture": "caller"},
|
|
419
|
+
"capture filed": {"path": "caller"},
|
|
420
|
+
# A file *of the project* and resolved against its root (RK1264): this names where a
|
|
421
|
+
# governed file is to be created, which is the same class every `[files]` value is — and
|
|
422
|
+
# over MCP the caller's directory is not the tree `-C` selected, so the caller class would
|
|
423
|
+
# put a role's file wherever the harness happened to launch this process.
|
|
424
|
+
"declare": {"path": "project"},
|
|
425
|
+
"section add": {"body_file": "caller"},
|
|
426
|
+
"section amend": {"body_file": "caller"},
|
|
427
|
+
"merge": {
|
|
428
|
+
"base": "repo",
|
|
429
|
+
"ours": "repo",
|
|
430
|
+
"theirs": "repo",
|
|
431
|
+
"path": "repo",
|
|
432
|
+
},
|
|
433
|
+
"claim": {"path": "repo", "add_path": "repo"},
|
|
434
|
+
# Two classes on one verb, and the pair is what makes the distinction concrete (RK1190):
|
|
435
|
+
# `--file` names an every-turn file *of the project* and is resolved against the root,
|
|
436
|
+
# while `--body-file` is a draft the caller is holding and is read the way `cat` reads one.
|
|
437
|
+
"budget": {"file": "project", "body_file": "caller"},
|
|
438
|
+
# The same `--file` one verb over (RK1272), and the same class: a `[budgets]` entry is
|
|
439
|
+
# addressed by the path the config declares, which is project-relative by construction.
|
|
440
|
+
"govern": {"file": "project"},
|
|
441
|
+
"replay": {"path": "caller"},
|
|
442
|
+
"adopt": {"path": "project", "alongside": "project"},
|
|
443
|
+
"install": {"source": "caller"},
|
|
444
|
+
}
|
|
445
|
+
|
|
446
|
+
#: The dest spellings a scan can recognise as a path, which is the partial guard above.
|
|
447
|
+
PATH_SPELLINGS = ("path", "paths", "file", "files", "directory")
|
|
448
|
+
|
|
449
|
+
|
|
450
|
+
@dataclass(frozen=True, slots=True)
|
|
451
|
+
class Config:
|
|
452
|
+
"""Where the governed files are, and which format they are written in."""
|
|
453
|
+
|
|
454
|
+
root: Path
|
|
455
|
+
schema: Schema = field(default_factory=Schema)
|
|
456
|
+
paths: Mapping[str, Path] = field(default_factory=dict)
|
|
457
|
+
#: Files to scan for ids beyond the governed four (RK4). This repository keeps
|
|
458
|
+
#: task ids in `agents.md`, and an id the scan misses is an id that gets reused.
|
|
459
|
+
extra_id_sources: tuple[Path, ...] = ()
|
|
460
|
+
#: Ids this project has spoken for without writing them as a line (RK1031). Shio reserves
|
|
461
|
+
#: one per **epic** — `SH25`, `SH62` — each owning a sub-range whose sub-tasks ship under
|
|
462
|
+
#: their own numbers, so the epic id is never a task and never an entry; it exists so a
|
|
463
|
+
#: reader can name a body of work in one token.
|
|
464
|
+
#:
|
|
465
|
+
#: Declared and not inferred, because a reservation and a typo are the same string: the
|
|
466
|
+
#: deriver skips these because they **are** taken, the gate stops reporting them as spent,
|
|
467
|
+
#: and an id that is not on the list still fails exactly as it did.
|
|
468
|
+
reserved: tuple[str, ...] = ()
|
|
469
|
+
#: What jumps the queue, in order: an id or a `Block X`, and nothing else (RK11).
|
|
470
|
+
#: *Declared*, because the alternative is a "## Priority queue" section written in
|
|
471
|
+
#: prose — which Shio has, and which a tool that reads it would be interpreting
|
|
472
|
+
#: rather than validating (L4).
|
|
473
|
+
priority: tuple[str, ...] = ()
|
|
474
|
+
#: Always-loaded files and what each may cost (RK30). Not a governed role: the tool
|
|
475
|
+
#: writes none of these, it only refuses to let one grow unwatched.
|
|
476
|
+
budgets: tuple[Budget, ...] = ()
|
|
477
|
+
#: `[grammar.<role>]` — the shape of one role's records, where a project declares one
|
|
478
|
+
#: (RK1064), keyed by role and applied by :meth:`schema_for`. Empty is every project
|
|
479
|
+
#: that has not spoken about a shape, and then the grammars the tool ships are what
|
|
480
|
+
#: apply: a role nobody declared is not a role without one.
|
|
481
|
+
grammars: Mapping[str, Grammar] = field(default_factory=dict)
|
|
482
|
+
#: `[tools] characters` — what one served tool may cost the session that connects the
|
|
483
|
+
#: server (RK1059), or **None** where the project declares none, which is every project
|
|
484
|
+
#: that does not serve the surface and every one that has not looked at the number yet.
|
|
485
|
+
#: The same argument `budgets` makes about a resident file, about the schema: a cost
|
|
486
|
+
#: nobody counts is a cost that moves, and every flag added to a served verb spends it
|
|
487
|
+
#: in an edit whose diff shows one argument.
|
|
488
|
+
#: What one brief may cost a tool result, in UTF-16 code units (RK1286). `None` where the
|
|
489
|
+
#: project declared none, which is every project until it looks: the read exists to fit in
|
|
490
|
+
#: one tool result, and until this nothing said what that was — the same absence RK30 named
|
|
491
|
+
#: about a resident file and RK1059 about the served schema.
|
|
492
|
+
brief_read: int | None = None
|
|
493
|
+
tool_characters: int | None = None
|
|
494
|
+
#: `[tools] session` — what the whole served surface may cost at the handshake: every
|
|
495
|
+
#: tool plus the instructions, which is the figure `cost --session` prints (RK1097).
|
|
496
|
+
#: **None** where the project declares none, and separate from `characters` because they
|
|
497
|
+
#: refuse different edits — one description growing, against the list growing by one more
|
|
498
|
+
#: verb that is individually unremarkable. Measured across three projects before it was
|
|
499
|
+
#: offered: the count is 52 in all of them and the totals differ by 1.4%, so this is a
|
|
500
|
+
#: number about the package a project installs and not about the project.
|
|
501
|
+
tool_session: int | None = None
|
|
502
|
+
#: `[limits.<role>]` — the numbers one file is held to instead of the shared ones
|
|
503
|
+
#: (RK50), keyed by role and applied by :meth:`schema_for`. Empty is the common case:
|
|
504
|
+
#: a project declares one only where a file's economics differ, which in practice is a
|
|
505
|
+
#: ledger of history against a roadmap refused at insertion.
|
|
506
|
+
limits: Mapping[str, Mapping[str, int]] = field(default_factory=dict)
|
|
507
|
+
#: `[rules.<role>]` — a prose rule one file is not held to (RK52), applied by
|
|
508
|
+
#: :meth:`schema_for` alongside that file's limits.
|
|
509
|
+
rules: Mapping[str, Mapping[str, bool]] = field(default_factory=dict)
|
|
510
|
+
#: `[refs]` — the namespace a prose role's outline addresses live in (RK340), keyed by
|
|
511
|
+
#: role and applied by :meth:`schema_for`. Empty is every project that has not declared
|
|
512
|
+
#: one, and the behaviour is exactly what it was: one flat set of addresses across both
|
|
513
|
+
#: prose files, which is right for a project whose two files never collide and is the
|
|
514
|
+
#: `section.ambiguous` nothing could configure away for the one where they do.
|
|
515
|
+
refs: Mapping[str, str] = field(default_factory=dict)
|
|
516
|
+
#: `[non_goals]` — declared when this project's non-goals are governed too (RK70), and
|
|
517
|
+
#: **None** when they are prose, which is what every project's were before it opted in.
|
|
518
|
+
non_goals: Scope | None = None
|
|
519
|
+
#: `[criteria]` — the same two numbers about the **positive twin** (RK1265): what must be
|
|
520
|
+
#: true for a block to be finished, where a non-goal says what is not built. Opt-in for the
|
|
521
|
+
#: reason that one is, and separately: a project may govern one list and not the other, and
|
|
522
|
+
#: a criterion that inherited the non-goals' limits would be judged by numbers measured on
|
|
523
|
+
#: a different corpus.
|
|
524
|
+
criteria: Scope | None = None
|
|
525
|
+
#: `[report] upstream` — where a capture of a defect *in this tool* would be filed
|
|
526
|
+
#: (RK87), as `owner/repo`. Configuration and not a constant, so a fork reports to
|
|
527
|
+
#: itself (L6); **None** means `report --issue` refuses rather than guessing a
|
|
528
|
+
#: destination, since a wrong one is a private repository's contents in a stranger's
|
|
529
|
+
#: tracker. Nothing is ever sent from here — this only addresses the command a person
|
|
530
|
+
#: runs.
|
|
531
|
+
upstream: str | None = None
|
|
532
|
+
#: `[claims] held` — how many **minutes** a claim on a line reads as held (RK151). Per
|
|
533
|
+
#: project, because how long a task takes is the one thing about a claim that differs
|
|
534
|
+
#: between backlogs (L6), and bounded by :data:`CLAIM_HELD_MAX`, because a window nobody
|
|
535
|
+
#: would wait out is the lock this was designed not to be.
|
|
536
|
+
held: int = CLAIM_HELD
|
|
537
|
+
#: `[blocks] standing` — the labels that receive work forever and are empty only in the
|
|
538
|
+
#: sense that nobody has filed the next one yet (RK1180). A project block empties once and is
|
|
539
|
+
#: done; a standing category — *realignment of what already shipped*, a triage lane — empties
|
|
540
|
+
#: whenever it is caught up. Measured in one session on such a block: declared, emptied and
|
|
541
|
+
#: dropped **three times**, each drop followed within the hour by a finding that re-declared
|
|
542
|
+
#: it. Per label and not `[headings] permanent`, which is the same fact about a whole project:
|
|
543
|
+
#: a backlog can hold nine blocks that finish and one that never does.
|
|
544
|
+
standing: frozenset[str] = frozenset()
|
|
545
|
+
#: `[install] pinned` — whether this project holds its wired surfaces at the version they
|
|
546
|
+
#: are, deliberately (RK1192). Off by default, so nothing changes for a project that has
|
|
547
|
+
#: not said, and the gate reports a launcher, hook or skill behind the engine answering
|
|
548
|
+
#: here — which is the state that leaves a session with no door in, and which until now
|
|
549
|
+
#: only `install --check` reported, a command nobody thinks to run.
|
|
550
|
+
#:
|
|
551
|
+
#: Declared by a project that has chosen its version and is not the tool's to overrule.
|
|
552
|
+
#: The alternative to this key is a finding a reader learns to skip, which is how a gate
|
|
553
|
+
#: stops being read — the same argument `[headings] permanent` makes one table over.
|
|
554
|
+
#: It silences the *finding* and not the state: `install --check` and `engines` both
|
|
555
|
+
#: still answer, because what is pinned is a decision and not a fact about the files.
|
|
556
|
+
install_pinned: bool = False
|
|
557
|
+
#: `[install] enforced` — whether the engine writing here is held to the plugin the
|
|
558
|
+
#: harness registered (RK1240). A **different pair** from the one above: `pinned` is about
|
|
559
|
+
#: the surfaces vendored into this project against the engine answering, and this is about
|
|
560
|
+
#: that engine against the registered plugin. RK1235's write refusal and RK1238's gate
|
|
561
|
+
#: note read this one; borrowing `pinned` read a project that had quieted a finding as
|
|
562
|
+
#: having asked for a refusal on every write.
|
|
563
|
+
install_enforced: bool = False
|
|
564
|
+
#: `[headings] permanent` — whether this project's block headings outlive the work filed
|
|
565
|
+
#: under them (RK1121). Here and not on the schema: it shapes no line, it decides whether a
|
|
566
|
+
#: door is offered, which is `held`'s kind of fact rather than the grammar's.
|
|
567
|
+
permanent_headings: bool = False
|
|
568
|
+
source: Path | None = None
|
|
569
|
+
|
|
570
|
+
# -- construction ------------------------------------------------------
|
|
571
|
+
|
|
572
|
+
@classmethod
|
|
573
|
+
def default(cls, root: str | Path = ".") -> Config:
|
|
574
|
+
"""The layout of a project that has not declared one."""
|
|
575
|
+
base = Path(root).resolve()
|
|
576
|
+
return cls(
|
|
577
|
+
root=base,
|
|
578
|
+
paths={role: base / rel for role, rel in DEFAULT_PATHS.items()},
|
|
579
|
+
)
|
|
580
|
+
|
|
581
|
+
@classmethod
|
|
582
|
+
def discover(cls, start: str | Path = ".") -> Config:
|
|
583
|
+
"""Walk up for a config; fall back to the defaults at ``start``."""
|
|
584
|
+
found = find_config(start)
|
|
585
|
+
return cls.load(found) if found else cls.default(start)
|
|
586
|
+
|
|
587
|
+
@classmethod
|
|
588
|
+
def load(cls, path: str | Path) -> Config:
|
|
589
|
+
path = Path(path).resolve()
|
|
590
|
+
with path.open("rb") as handle:
|
|
591
|
+
try:
|
|
592
|
+
document = tomllib.load(handle)
|
|
593
|
+
except tomllib.TOMLDecodeError as broken:
|
|
594
|
+
raise _marked(path, broken) from None
|
|
595
|
+
if path.name == PYPROJECT:
|
|
596
|
+
document = document.get("tool", {}).get("roadkeep", {})
|
|
597
|
+
return cls.parse(document, root=path.parent, source=path)
|
|
598
|
+
|
|
599
|
+
@classmethod
|
|
600
|
+
def parse(
|
|
601
|
+
cls, data: Mapping[str, object], root: str | Path, source: Path | None = None
|
|
602
|
+
) -> Config:
|
|
603
|
+
base = Path(root).resolve()
|
|
604
|
+
problems: list[str] = []
|
|
605
|
+
_reject_unknown(data, _TOP_KEYS, "", problems)
|
|
606
|
+
|
|
607
|
+
prefixes = _prefixes(data.get("prefix"), problems)
|
|
608
|
+
ids = _ids(data.get("ids"), problems)
|
|
609
|
+
heading_word = _heading_word(data.get("headings"), problems)
|
|
610
|
+
ref_scheme = _string(data, "ref_scheme", "id", problems)
|
|
611
|
+
markers = _markers(data.get("markers"), problems)
|
|
612
|
+
ledger = _ledger(data.get("ledger"), problems)
|
|
613
|
+
limits = _limits(data.get("limits"), problems)
|
|
614
|
+
per_role = _by_role(data.get("limits"), problems)
|
|
615
|
+
rules = _rules(data.get("rules"), problems)
|
|
616
|
+
paths = _paths(data.get("files"), base, problems)
|
|
617
|
+
refs = _refs(data.get("refs"), ref_scheme, paths, problems)
|
|
618
|
+
extras = tuple(
|
|
619
|
+
base / name for name in _string_list(data.get("id_sources"), "id_sources", problems)
|
|
620
|
+
)
|
|
621
|
+
reserved = tuple(
|
|
622
|
+
dict.fromkeys(_string_list(data.get("reserved_ids"), "reserved_ids", problems))
|
|
623
|
+
)
|
|
624
|
+
priority = tuple(_string_list(data.get("priority"), "priority", problems))
|
|
625
|
+
budgets = _budgets(data.get("budgets"), base, problems)
|
|
626
|
+
tool_characters, tool_session = _tool_budget(data.get("tools"), problems)
|
|
627
|
+
brief_read = _read_budget(data.get("reads"), problems)
|
|
628
|
+
grammars = _grammars(data.get("grammar"), problems)
|
|
629
|
+
non_goals = _scope(data.get("non_goals"), problems)
|
|
630
|
+
criteria = _scope(data.get("criteria"), problems, "criteria")
|
|
631
|
+
upstream = _upstream(data.get("report"), problems)
|
|
632
|
+
held = _held(data.get("claims"), problems)
|
|
633
|
+
permanent = _permanent_headings(data.get("headings"), problems)
|
|
634
|
+
standing = _standing_blocks(data.get("blocks"), problems)
|
|
635
|
+
requirements = _requirements(data.get("requirements"), problems)
|
|
636
|
+
pinned = _pinned_surfaces(data.get("install"), problems)
|
|
637
|
+
enforced = _enforced_engine(data.get("install"), problems)
|
|
638
|
+
|
|
639
|
+
schema = None
|
|
640
|
+
if not problems:
|
|
641
|
+
try:
|
|
642
|
+
schema = Schema(
|
|
643
|
+
prefixes=prefixes,
|
|
644
|
+
**ids,
|
|
645
|
+
heading_word=heading_word,
|
|
646
|
+
ref_scheme=ref_scheme,
|
|
647
|
+
**markers,
|
|
648
|
+
**ledger,
|
|
649
|
+
**limits,
|
|
650
|
+
requirements=requirements,
|
|
651
|
+
# Where each of those numbers was written, so a refusal over one names
|
|
652
|
+
# the line somebody reviews rather than only the number (RK1067).
|
|
653
|
+
origins=_origins(source, _scalars(data.get("limits"))), # RK1067
|
|
654
|
+
)
|
|
655
|
+
except ValueError as error: # a valid TOML file can still be a wrong format
|
|
656
|
+
problems.append(str(error))
|
|
657
|
+
if schema is not None:
|
|
658
|
+
_check_priority(schema, priority, problems)
|
|
659
|
+
_check_reserved(schema, reserved, problems)
|
|
660
|
+
if problems:
|
|
661
|
+
raise ConfigError(tuple(problems), source)
|
|
662
|
+
|
|
663
|
+
assert schema is not None
|
|
664
|
+
return cls(
|
|
665
|
+
root=base,
|
|
666
|
+
schema=schema,
|
|
667
|
+
paths=paths,
|
|
668
|
+
extra_id_sources=extras,
|
|
669
|
+
reserved=reserved,
|
|
670
|
+
priority=priority,
|
|
671
|
+
budgets=budgets,
|
|
672
|
+
brief_read=brief_read,
|
|
673
|
+
tool_characters=tool_characters,
|
|
674
|
+
tool_session=tool_session,
|
|
675
|
+
grammars=grammars,
|
|
676
|
+
limits=per_role,
|
|
677
|
+
rules=rules,
|
|
678
|
+
refs=refs,
|
|
679
|
+
non_goals=non_goals,
|
|
680
|
+
criteria=criteria,
|
|
681
|
+
upstream=upstream,
|
|
682
|
+
held=held,
|
|
683
|
+
permanent_headings=permanent,
|
|
684
|
+
standing=standing,
|
|
685
|
+
install_pinned=pinned,
|
|
686
|
+
install_enforced=enforced,
|
|
687
|
+
source=source,
|
|
688
|
+
)
|
|
689
|
+
|
|
690
|
+
# -- using it ----------------------------------------------------------
|
|
691
|
+
|
|
692
|
+
def has(self, role: str) -> bool:
|
|
693
|
+
return role in self.paths
|
|
694
|
+
|
|
695
|
+
def path(self, role: str) -> Path:
|
|
696
|
+
try:
|
|
697
|
+
return self.paths[role]
|
|
698
|
+
except KeyError:
|
|
699
|
+
raise KeyError(
|
|
700
|
+
f"this project declares no {role!r} file (has: "
|
|
701
|
+
f"{', '.join(sorted(self.paths)) or 'none'})"
|
|
702
|
+
) from None
|
|
703
|
+
|
|
704
|
+
def schema_for(self, role: str) -> Schema:
|
|
705
|
+
"""The changelog is the same format in its ledger configuration, not another.
|
|
706
|
+
|
|
707
|
+
The deferred store (RK96) is the third such configuration and the same claim: one
|
|
708
|
+
format, one marker set per file, and the file a line sits in is what states its
|
|
709
|
+
status — never a second grammar.
|
|
710
|
+
|
|
711
|
+
Plus whatever `[limits.<role>]` says (RK50) — the same format again, held to this
|
|
712
|
+
file's own numbers, because a ledger of history and a roadmap line are refused at
|
|
713
|
+
opposite ends of the work.
|
|
714
|
+
|
|
715
|
+
The shape comes from a **declaration** since RK1064: the grammar this project wrote
|
|
716
|
+
for the role, or the one the tool ships for it, applied by `Schema.under` either
|
|
717
|
+
way. `as_ledger` and `as_deferred` are still the names those two grammars go by and
|
|
718
|
+
are what every other caller reaches for; what changed is that neither is where the
|
|
719
|
+
shape is stated, so a project overriding one is not overriding a method.
|
|
720
|
+
"""
|
|
721
|
+
declared = self.grammars.get(role) or DEFAULT_GRAMMARS.get(role)
|
|
722
|
+
schema = self.schema.under(declared) if declared else self.schema
|
|
723
|
+
own: dict[str, object] = {**self.limits.get(role, {}), **self.rules.get(role, {})}
|
|
724
|
+
if role in self.limits:
|
|
725
|
+
# The role's own citations layered over the shared ones (RK1067), so a `why`
|
|
726
|
+
# refused in the changelog names `[limits.changelog].why` and not the number
|
|
727
|
+
# the roadmap is held to — which is the whole reason RK50 exists, reaching the
|
|
728
|
+
# author at the moment they are standing over one of the two.
|
|
729
|
+
own["origins"] = tuple(
|
|
730
|
+
{**dict(schema.origins), **dict(_origins(self.source, self.limits[role], role))}
|
|
731
|
+
.items()
|
|
732
|
+
)
|
|
733
|
+
# The namespace this role's addresses live in (RK340), carried on the schema for the
|
|
734
|
+
# reason every other per-role difference is: the file travels with the rules it is
|
|
735
|
+
# read under, so nothing downstream has to be handed a role beside a document.
|
|
736
|
+
if role in self.refs:
|
|
737
|
+
own["ref_prefix"] = self.refs[role]
|
|
738
|
+
return replace(schema, **own) if own else schema
|
|
739
|
+
|
|
740
|
+
def document(self, role: str) -> Document:
|
|
741
|
+
"""Load a governed file under the right schema — the one seam every command uses.
|
|
742
|
+
|
|
743
|
+
The project travels with the file, which is what lets a save re-derive the blocks
|
|
744
|
+
projected from it (RK188): a document that arrived any other way has no project and
|
|
745
|
+
writes exactly itself.
|
|
746
|
+
|
|
747
|
+
`Document` is reached here and not at module level (RK261). This module is imported by
|
|
748
|
+
every command in the package, and the guard imports it to answer *where* a write was
|
|
749
|
+
going — it never opens the file, and paid 9 ms for the model that would. Measured, it is
|
|
750
|
+
not a cost moved: 22 of the 37 modules import `document` directly, `cli.py` among them,
|
|
751
|
+
so the commands that load a document already had it before this line runs.
|
|
752
|
+
"""
|
|
753
|
+
from roadkeep.kernel.document import Document # noqa: PLC0415 - RK261
|
|
754
|
+
|
|
755
|
+
return replace(
|
|
756
|
+
Document.load(self.path(role), self.schema_for(role)), config=self
|
|
757
|
+
)
|
|
758
|
+
|
|
759
|
+
def locate(self, path: str | Path) -> Path:
|
|
760
|
+
"""A path naming a file **of this project**, resolved against its root (RK1101).
|
|
761
|
+
|
|
762
|
+
`-C` selects the project and never the working directory, so a relative path had two
|
|
763
|
+
possible bases and the answer differed by argument: `budget --file agents.md` resolved
|
|
764
|
+
against the root and `adopt ROADMAP.md` against whatever directory the process happened
|
|
765
|
+
to be in. Two rules is worse than either, and this is the one the tool already kept for
|
|
766
|
+
the file arguments that name governed files.
|
|
767
|
+
|
|
768
|
+
The half that decided it is the served surface. Over MCP the process's directory is the
|
|
769
|
+
session's and the project is `-C`'s, so a relative path was read from a tree the caller
|
|
770
|
+
never named — loudly where the file is absent there, and **silently where it is not**:
|
|
771
|
+
a real measurement of somebody else's backlog, reported under this project's prefix,
|
|
772
|
+
markers and limits, with nothing in the output naming the tree it read.
|
|
773
|
+
|
|
774
|
+
Only for a path that names a file of the project. A body file (`add --section-body-file`,
|
|
775
|
+
`section amend --body-file`) is the caller's own and stays relative to the caller, the way
|
|
776
|
+
`cat` is: it names a file to *read from* and can be anywhere, and nothing in this tool
|
|
777
|
+
ever composes one.
|
|
778
|
+
|
|
779
|
+
**A capture is not one of those, and RK1101 put it there** (RK1396). It lives under this
|
|
780
|
+
project's own `.roadkeep/reports/`, `stats` counts it as this project's debt and `capture
|
|
781
|
+
filed` refuses a path that is not "a capture this project holds" — so it was a file of
|
|
782
|
+
the project by every reading except the one that resolved it. What made the cost visible
|
|
783
|
+
is RK1395: both readers now *print* a project-relative path for one, so the tool composed
|
|
784
|
+
a door and then refused it, with a message naming the very directory the file is in.
|
|
785
|
+
"""
|
|
786
|
+
given = Path(path)
|
|
787
|
+
return given if given.is_absolute() else self.root / given
|
|
788
|
+
|
|
789
|
+
def relative(self, path: Path) -> str:
|
|
790
|
+
"""A path as the project spells it — output has to be machine-independent."""
|
|
791
|
+
try:
|
|
792
|
+
return Path(path).resolve().relative_to(self.root).as_posix()
|
|
793
|
+
except ValueError:
|
|
794
|
+
return Path(path).as_posix()
|
|
795
|
+
|
|
796
|
+
def missing(self) -> tuple[str, ...]:
|
|
797
|
+
"""Declared roles with no file on disk — what `init` creates and `lint` reports."""
|
|
798
|
+
return tuple(role for role, path in self.paths.items() if not path.exists())
|
|
799
|
+
|
|
800
|
+
def id_sources(self) -> tuple[Path, ...]:
|
|
801
|
+
"""Every file that may carry an id, governed or not, in declaration order."""
|
|
802
|
+
seen: dict[Path, None] = {}
|
|
803
|
+
for role in ROLES:
|
|
804
|
+
if role in self.paths:
|
|
805
|
+
seen.setdefault(self.paths[role])
|
|
806
|
+
for extra in self.extra_id_sources:
|
|
807
|
+
seen.setdefault(extra)
|
|
808
|
+
return tuple(seen)
|
|
809
|
+
|
|
810
|
+
|
|
811
|
+
def find_config(start: str | Path = ".") -> Path | None:
|
|
812
|
+
"""The nearest `roadkeep.toml`, or a `pyproject.toml` that configures roadkeep."""
|
|
813
|
+
here = Path(start).resolve()
|
|
814
|
+
for directory in (here, *here.parents):
|
|
815
|
+
candidate = directory / CONFIG_NAME
|
|
816
|
+
if candidate.is_file():
|
|
817
|
+
return candidate
|
|
818
|
+
pyproject = directory / PYPROJECT
|
|
819
|
+
if pyproject.is_file() and _declares_roadkeep(pyproject):
|
|
820
|
+
return pyproject
|
|
821
|
+
return None
|
|
822
|
+
|
|
823
|
+
|
|
824
|
+
def _declares_roadkeep(path: Path) -> bool:
|
|
825
|
+
"""Whether this `pyproject.toml` configures roadkeep — a probe, and it may not refuse.
|
|
826
|
+
|
|
827
|
+
The mark is taken off **here and only here** (RK1030), because this decides whether a
|
|
828
|
+
file is the project's config at all: a marked `pyproject.toml` parsed as-is is a
|
|
829
|
+
`TOMLDecodeError`, which this swallows, so discovery walked past a file that declares
|
|
830
|
+
`[tool.roadkeep]` and every verb then ran on defaults — the encoding defect turning into
|
|
831
|
+
silence rather than a refusal, which is the one outcome worse than the refusal.
|
|
832
|
+
|
|
833
|
+
Found here, refused in :meth:`Config.load`, which reads the bytes as they are and says
|
|
834
|
+
what the mark is. The strip is a question about *which file* and never about its content.
|
|
835
|
+
"""
|
|
836
|
+
try:
|
|
837
|
+
raw = path.read_bytes()
|
|
838
|
+
except OSError:
|
|
839
|
+
return False
|
|
840
|
+
try:
|
|
841
|
+
data = tomllib.loads(raw.removeprefix(_BOM).decode("utf-8"))
|
|
842
|
+
except (UnicodeDecodeError, tomllib.TOMLDecodeError):
|
|
843
|
+
return False
|
|
844
|
+
return "roadkeep" in data.get("tool", {})
|
|
845
|
+
|
|
846
|
+
|
|
847
|
+
def _skew(problems: tuple[str, ...]) -> str:
|
|
848
|
+
"""The reading an unknown key cannot rule out, or `""` where none was reported (RK1150).
|
|
849
|
+
|
|
850
|
+
Keyed off the problem text this module writes, one function over — a code would be a second
|
|
851
|
+
vocabulary for the same set, and this file's problems are prose by construction (`lint` is
|
|
852
|
+
where findings carry codes). `engines` is the door because it is the one command that answers
|
|
853
|
+
*which copies answer here*: the build that writes, the plugin's own, and the gate's.
|
|
854
|
+
"""
|
|
855
|
+
if not any(one.startswith("unknown key") for one in problems):
|
|
856
|
+
return ""
|
|
857
|
+
from roadkeep.provenance import invocation # noqa: PLC0415 - RK260, the refusal path only
|
|
858
|
+
|
|
859
|
+
return (
|
|
860
|
+
" — unknown to this build: a typo if nothing declares it, an upgrade if a newer "
|
|
861
|
+
f"roadkeep does, and `{invocation()} engines` names the copies answering here"
|
|
862
|
+
)
|
|
863
|
+
|
|
864
|
+
|
|
865
|
+
# -- reading one key at a time, collecting what is wrong -------------------
|
|
866
|
+
|
|
867
|
+
|
|
868
|
+
def _reject_unknown(
|
|
869
|
+
data: Mapping[str, object], allowed: frozenset[str], where: str, problems: list[str]
|
|
870
|
+
) -> None:
|
|
871
|
+
"""Every key this schema does not declare, said as **two** readings and not one (RK1150).
|
|
872
|
+
|
|
873
|
+
The message used to name the key and the allowed set, which is the older schema presented as
|
|
874
|
+
though it were the schema: `unknown key 'headings.permanent' (allowed: headings.word)` was a
|
|
875
|
+
key a *later* roadkeep added, read by a build that predates it, and the cheapest action the
|
|
876
|
+
sentence suggested was deleting a key the project needs. Reached from Shio, where the server
|
|
877
|
+
resolves this package from the plugin cache and the project from a checkout.
|
|
878
|
+
|
|
879
|
+
A key no version ever declared is a typo and a key *this* build does not have is an upgrade,
|
|
880
|
+
and nothing in the file separates them — so both are named, and the clause carries the one
|
|
881
|
+
command that decides it (RK14/15's rule, on the refusal that reads a config rather than a
|
|
882
|
+
line). `engines` is that command: it prints the copy that writes beside the plugin's own.
|
|
883
|
+
"""
|
|
884
|
+
for key in data:
|
|
885
|
+
if key not in allowed:
|
|
886
|
+
problems.append(
|
|
887
|
+
f"unknown key '{where}{key}' (allowed: "
|
|
888
|
+
f"{', '.join(where + name for name in sorted(allowed))})"
|
|
889
|
+
)
|
|
890
|
+
|
|
891
|
+
|
|
892
|
+
def _string(
|
|
893
|
+
data: Mapping[str, object], key: str, default: str, problems: list[str]
|
|
894
|
+
) -> str:
|
|
895
|
+
value = data.get(key, default)
|
|
896
|
+
if not isinstance(value, str):
|
|
897
|
+
problems.append(f"{key} must be a string, got {type(value).__name__}")
|
|
898
|
+
return default
|
|
899
|
+
return value
|
|
900
|
+
|
|
901
|
+
|
|
902
|
+
def _prefixes(raw: object, problems: list[str]) -> tuple[str, ...]:
|
|
903
|
+
"""`prefix` — one family, or the list a backlog numbered by track needs (RK74).
|
|
904
|
+
|
|
905
|
+
A string stays a string in the file, because three of the four live corpora number one
|
|
906
|
+
family and `prefix = ["RK"]` would be a list nobody asked for. A list is read in
|
|
907
|
+
declaration order: the first is what `add` mints under when no family is named, and
|
|
908
|
+
the order is the author's, so a message that reprints it prints their list back.
|
|
909
|
+
"""
|
|
910
|
+
if raw is None:
|
|
911
|
+
return ("RK",)
|
|
912
|
+
if isinstance(raw, str):
|
|
913
|
+
return (raw,)
|
|
914
|
+
if isinstance(raw, list) and all(isinstance(item, str) for item in raw):
|
|
915
|
+
if not raw:
|
|
916
|
+
problems.append("prefix must name at least one family")
|
|
917
|
+
return ("RK",)
|
|
918
|
+
return tuple(raw)
|
|
919
|
+
problems.append(
|
|
920
|
+
"prefix must be a string, or a list of strings for a backlog that numbers "
|
|
921
|
+
"by track"
|
|
922
|
+
)
|
|
923
|
+
return ("RK",)
|
|
924
|
+
|
|
925
|
+
|
|
926
|
+
def _ids(raw: object, problems: list[str]) -> dict[str, object]:
|
|
927
|
+
"""`[ids]` — the width the number is padded to, and whether a sub-letter is legal (RK106).
|
|
928
|
+
|
|
929
|
+
Both default to the shape every project had before this table existed, so a config that
|
|
930
|
+
declares nothing reads exactly as it did. Two live corpora declare one: Dumont pads `D01`
|
|
931
|
+
through `D09` on every line, and Turing carries `T24b`, `T221a` and `T227a` from tasks
|
|
932
|
+
split after their numbers were cited in commits and issues.
|
|
933
|
+
|
|
934
|
+
What is being declared is a *spelling*, never a scheme — the non-goal is contiguity,
|
|
935
|
+
reuse and ordering, which are properties of real backlogs, and a project stating the
|
|
936
|
+
width it already writes is the opposite of a scheme imposed on it (L6).
|
|
937
|
+
"""
|
|
938
|
+
default: dict[str, object] = {"id_pad": 1, "id_suffix": False}
|
|
939
|
+
if raw is None:
|
|
940
|
+
return default
|
|
941
|
+
if not isinstance(raw, Mapping):
|
|
942
|
+
problems.append("ids must be a table with 'pad' and 'suffix'")
|
|
943
|
+
return default
|
|
944
|
+
_reject_unknown(raw, _IDS_KEYS, "ids.", problems)
|
|
945
|
+
pad = raw.get("pad", 1)
|
|
946
|
+
if not isinstance(pad, int) or isinstance(pad, bool) or pad < 1:
|
|
947
|
+
problems.append(
|
|
948
|
+
"ids.pad must be a positive integer: it is the width the number is "
|
|
949
|
+
"zero-filled to, and 1 is an unpadded id"
|
|
950
|
+
)
|
|
951
|
+
pad = 1
|
|
952
|
+
suffix = raw.get("suffix", False)
|
|
953
|
+
if not isinstance(suffix, bool):
|
|
954
|
+
problems.append("ids.suffix must be true or false")
|
|
955
|
+
suffix = False
|
|
956
|
+
return {"id_pad": pad, "id_suffix": suffix}
|
|
957
|
+
|
|
958
|
+
|
|
959
|
+
def _heading_word(raw: object, problems: list[str]) -> str:
|
|
960
|
+
"""`[headings] word` — what this project files work under (RK75).
|
|
961
|
+
|
|
962
|
+
Defaults to `Block`, so a project that never declares it is unchanged. Declared by the
|
|
963
|
+
three of four adopting corpora that chose otherwise: Dumont files under `## Track A`,
|
|
964
|
+
cursarei under `## Fase 0`, and each was getting a finding per line for its own word.
|
|
965
|
+
"""
|
|
966
|
+
if raw is None:
|
|
967
|
+
return DEFAULT_HEADING_WORD
|
|
968
|
+
if not isinstance(raw, Mapping):
|
|
969
|
+
problems.append("headings must be a table with 'word'")
|
|
970
|
+
return DEFAULT_HEADING_WORD
|
|
971
|
+
_reject_unknown(raw, _HEADING_KEYS, "headings.", problems)
|
|
972
|
+
word = raw.get("word", DEFAULT_HEADING_WORD)
|
|
973
|
+
if not isinstance(word, str):
|
|
974
|
+
problems.append("headings.word must be a string")
|
|
975
|
+
return DEFAULT_HEADING_WORD
|
|
976
|
+
return word
|
|
977
|
+
|
|
978
|
+
|
|
979
|
+
def _standing_blocks(raw: object, problems: list[str]) -> frozenset[str]:
|
|
980
|
+
"""`[blocks] standing` — the labels whose emptiness means *caught up* (RK1180).
|
|
981
|
+
|
|
982
|
+
Empty by default, so nothing changes for a project that has not said. A label listed here
|
|
983
|
+
empties the way a queue does rather than the way a project does, and three answers change
|
|
984
|
+
with it: `ship` says caught up instead of finished, the offer to drop the heading is not
|
|
985
|
+
made, and a queue token over it is no longer an order over nothing.
|
|
986
|
+
|
|
987
|
+
Labels and never a per-block table of properties: what a block *is* is one bit, and a table
|
|
988
|
+
would invite the second, which is a plan this tool would then be keeping.
|
|
989
|
+
"""
|
|
990
|
+
if not isinstance(raw, Mapping):
|
|
991
|
+
if raw is not None:
|
|
992
|
+
problems.append("blocks must be a table, e.g. [blocks] standing = [\"N\"]")
|
|
993
|
+
return frozenset()
|
|
994
|
+
value = raw.get("standing", ())
|
|
995
|
+
if isinstance(value, str) or not isinstance(value, Sequence):
|
|
996
|
+
problems.append('blocks.standing must be a list of labels, e.g. standing = ["N"]')
|
|
997
|
+
return frozenset()
|
|
998
|
+
labels = [one for one in value if isinstance(one, str) and one.strip()]
|
|
999
|
+
if len(labels) != len(list(value)):
|
|
1000
|
+
problems.append("blocks.standing takes block labels as strings")
|
|
1001
|
+
return frozenset(one.strip() for one in labels)
|
|
1002
|
+
|
|
1003
|
+
|
|
1004
|
+
def _permanent_headings(raw: object, problems: list[str]) -> bool:
|
|
1005
|
+
"""`[headings] permanent` — whether an emptied heading is one this project ever drops.
|
|
1006
|
+
|
|
1007
|
+
Off by default, so nothing changes for a project that has not said (RK1121). Declared by
|
|
1008
|
+
one whose headings are the structure of the backlog rather than a grouping of live work:
|
|
1009
|
+
measured here across a session, **nine ships, six offers to withdraw a heading — D, B, F,
|
|
1010
|
+
B, C, E — and no block ever dropped.** The offer's own clause said `where this project
|
|
1011
|
+
drops one`, which is the sentence knowing the answer it cannot read: whether a finished
|
|
1012
|
+
block is a heading to take out is a fact about the plan, and this is where the plan speaks.
|
|
1013
|
+
|
|
1014
|
+
It silences the *offer* and not the state: the ship still prints `finished`, and the gate's
|
|
1015
|
+
`block.emptied` note (RK269) still records the transition. What emptied is history and what
|
|
1016
|
+
to do about it is the project's — the split every configurable rule here keeps.
|
|
1017
|
+
"""
|
|
1018
|
+
if not isinstance(raw, Mapping):
|
|
1019
|
+
# Not a second refusal: `_heading_word` reads the same table and reports the shape.
|
|
1020
|
+
return False
|
|
1021
|
+
value = raw.get("permanent", False)
|
|
1022
|
+
if not isinstance(value, bool):
|
|
1023
|
+
problems.append("headings.permanent must be true or false")
|
|
1024
|
+
return False
|
|
1025
|
+
return value
|
|
1026
|
+
|
|
1027
|
+
|
|
1028
|
+
def _pinned_surfaces(raw: object, problems: list[str]) -> bool:
|
|
1029
|
+
"""`[install] pinned` — whether this project holds its wired surfaces where they are.
|
|
1030
|
+
|
|
1031
|
+
The half RK1192 could not ship without. The gate now reports a launcher, hook or skill
|
|
1032
|
+
behind the engine answering here, and it fires every turn through the `Stop` hook — so a
|
|
1033
|
+
project that has *decided* to sit on an older surface would be told about that decision
|
|
1034
|
+
on every turn for as long as it holds. A finding a reader learns to skip is how a gate
|
|
1035
|
+
stops being read, which costs more than the check is worth.
|
|
1036
|
+
|
|
1037
|
+
Off by default, exactly as `[headings] permanent` is and for its reason: nothing changes
|
|
1038
|
+
for a project that has not spoken, and the key exists so the project can. And it silences
|
|
1039
|
+
the *finding* and never the state — `install --check` still reports the drift on demand
|
|
1040
|
+
and `engines` still adjudicates the three copies, because what is declared here is a
|
|
1041
|
+
decision about which version to run and not a claim that the files agree.
|
|
1042
|
+
"""
|
|
1043
|
+
if not isinstance(raw, Mapping):
|
|
1044
|
+
return False
|
|
1045
|
+
_reject_unknown(raw, _INSTALL_KEYS, "install.", problems)
|
|
1046
|
+
return _install_flag(raw, "pinned", problems)
|
|
1047
|
+
|
|
1048
|
+
|
|
1049
|
+
def _enforced_engine(raw: object, problems: list[str]) -> bool:
|
|
1050
|
+
"""`[install] enforced` — whether the engine writing here is held to the registered one.
|
|
1051
|
+
|
|
1052
|
+
Split from `pinned` (RK1240), and the reason is that the two are about **different pairs
|
|
1053
|
+
of copies**. `pinned` is a decision about the surfaces vendored into this project against
|
|
1054
|
+
the engine answering here — RK1192's subject, and what its docstring declares. RK1235's
|
|
1055
|
+
write refusal and RK1238's gate note are about the engine answering here against the
|
|
1056
|
+
plugin the harness registered, which is a comparison that key never mentioned.
|
|
1057
|
+
|
|
1058
|
+
Borrowing it read a project that had quieted one finding as having asked for a refusal on
|
|
1059
|
+
every write, and in the direction that costs most: :attr:`~roadkeep.installing.Engines.
|
|
1060
|
+
verdict` calls **any** version difference `behind`, so a project deliberately sitting on
|
|
1061
|
+
an older vendored copy whose plugin cache moved forward was refused and sent to the copy
|
|
1062
|
+
it had chosen against.
|
|
1063
|
+
|
|
1064
|
+
Its own key removes both. Declaring this is a project saying *the registered plugin is the
|
|
1065
|
+
copy that should write here*, which is exactly the standing a refusal that names
|
|
1066
|
+
`engines --invoke` needs — and off by default, so nothing fires for a project that has
|
|
1067
|
+
not said so.
|
|
1068
|
+
"""
|
|
1069
|
+
if not isinstance(raw, Mapping):
|
|
1070
|
+
return False
|
|
1071
|
+
return _install_flag(raw, "enforced", problems)
|
|
1072
|
+
|
|
1073
|
+
|
|
1074
|
+
def _install_flag(raw: Mapping[str, object], key: str, problems: list[str]) -> bool:
|
|
1075
|
+
"""One boolean under `[install]`, refused the same way for both (RK1240)."""
|
|
1076
|
+
value = raw.get(key, False)
|
|
1077
|
+
if not isinstance(value, bool):
|
|
1078
|
+
problems.append(f"install.{key} must be true or false")
|
|
1079
|
+
return False
|
|
1080
|
+
return value
|
|
1081
|
+
|
|
1082
|
+
|
|
1083
|
+
def _markers(raw: object, problems: list[str]) -> dict[str, object]:
|
|
1084
|
+
"""The `[markers]` table as :class:`Schema` keywords — the four the format varies by."""
|
|
1085
|
+
default: dict[str, object] = {
|
|
1086
|
+
"markers": OPEN_MARKERS,
|
|
1087
|
+
"shipped_marker": SHIPPED,
|
|
1088
|
+
"retired_marker": RETIRED,
|
|
1089
|
+
"deferred_marker": DEFERRED,
|
|
1090
|
+
"undesigned": UNDESIGNED,
|
|
1091
|
+
}
|
|
1092
|
+
if raw is None:
|
|
1093
|
+
return default
|
|
1094
|
+
if not isinstance(raw, Mapping):
|
|
1095
|
+
problems.append(
|
|
1096
|
+
"markers must be a table with 'open', 'shipped', 'retired' and 'deferred'"
|
|
1097
|
+
)
|
|
1098
|
+
return default
|
|
1099
|
+
_reject_unknown(raw, _MARKER_KEYS, "markers.", problems)
|
|
1100
|
+
open_markers = tuple(_string_list(raw.get("open"), "markers.open", problems))
|
|
1101
|
+
shipped = _one_marker(raw, "shipped", SHIPPED, problems)
|
|
1102
|
+
retired = _one_marker(raw, "retired", RETIRED, problems)
|
|
1103
|
+
deferred = _one_marker(raw, "deferred", DEFERRED, problems)
|
|
1104
|
+
if shipped == retired:
|
|
1105
|
+
problems.append(
|
|
1106
|
+
"markers.shipped and markers.retired must differ: a ledger where both "
|
|
1107
|
+
"read the same cannot say whether the work was done"
|
|
1108
|
+
)
|
|
1109
|
+
if deferred in (shipped, retired):
|
|
1110
|
+
# Checked here rather than in the schema, where the open-set clash is: this pair
|
|
1111
|
+
# only meets inside `as_ledger`, so a project that spelled them the same would get
|
|
1112
|
+
# its refusal from a method call instead of from the file it typed them in.
|
|
1113
|
+
problems.append(
|
|
1114
|
+
"markers.deferred must differ from shipped and retired: a paused task that "
|
|
1115
|
+
"reads as a departure is the one distinction the state exists to make"
|
|
1116
|
+
)
|
|
1117
|
+
undesigned = _undesigned(raw, open_markers or OPEN_MARKERS, problems)
|
|
1118
|
+
for marker in (*open_markers, shipped, retired, deferred):
|
|
1119
|
+
_reject_invisible(marker, problems)
|
|
1120
|
+
if "ledger" in raw:
|
|
1121
|
+
# Moved to its own table by RK48, and refused rather than aliased: two spellings of
|
|
1122
|
+
# one flag are two spellings that can disagree, and a config error that names its
|
|
1123
|
+
# replacement costs one edit against a setting that silently stops being read.
|
|
1124
|
+
problems.append(
|
|
1125
|
+
"markers.ledger moved to [ledger] marker (RK48): the ledger's shape is one "
|
|
1126
|
+
"table, since [ledger] symptom cannot live under markers"
|
|
1127
|
+
)
|
|
1128
|
+
return {
|
|
1129
|
+
"markers": open_markers or OPEN_MARKERS,
|
|
1130
|
+
"shipped_marker": shipped,
|
|
1131
|
+
"retired_marker": retired,
|
|
1132
|
+
"deferred_marker": deferred,
|
|
1133
|
+
"undesigned": undesigned,
|
|
1134
|
+
}
|
|
1135
|
+
|
|
1136
|
+
|
|
1137
|
+
def _ledger(raw: object, problems: list[str]) -> dict[str, object]:
|
|
1138
|
+
"""Which slots the ledger's own lines carry — the marker (RK43) and the symptom (RK48).
|
|
1139
|
+
|
|
1140
|
+
Both default to *present*, so a project that declares nothing keeps the format this
|
|
1141
|
+
repository's own ledger is written in, and a ledger written before the tool declares
|
|
1142
|
+
the two absences it already has.
|
|
1143
|
+
"""
|
|
1144
|
+
default = {"ledger_marker": True, "ledger_symptom": True}
|
|
1145
|
+
if raw is None:
|
|
1146
|
+
return default
|
|
1147
|
+
if not isinstance(raw, Mapping):
|
|
1148
|
+
problems.append("ledger must be a table with 'marker' and 'symptom'")
|
|
1149
|
+
return default
|
|
1150
|
+
_reject_unknown(raw, _LEDGER_KEYS, "ledger.", problems)
|
|
1151
|
+
return {
|
|
1152
|
+
"ledger_marker": _flag(raw, "marker", True, problems),
|
|
1153
|
+
"ledger_symptom": _flag(raw, "symptom", True, problems),
|
|
1154
|
+
}
|
|
1155
|
+
|
|
1156
|
+
|
|
1157
|
+
def _flag(
|
|
1158
|
+
raw: Mapping[str, object], key: str, default: bool, problems: list[str]
|
|
1159
|
+
) -> bool:
|
|
1160
|
+
value = raw.get(key, default)
|
|
1161
|
+
if not isinstance(value, bool):
|
|
1162
|
+
problems.append(f"ledger.{key} must be true or false")
|
|
1163
|
+
return default
|
|
1164
|
+
return value
|
|
1165
|
+
|
|
1166
|
+
|
|
1167
|
+
def _undesigned(
|
|
1168
|
+
raw: Mapping[str, object], open_markers: tuple[str, ...], problems: list[str]
|
|
1169
|
+
) -> tuple[str, ...]:
|
|
1170
|
+
"""Which open markers mean the design is still to be written (RK83).
|
|
1171
|
+
|
|
1172
|
+
Undeclared, it is the built-in list narrowed to what this project actually opens with,
|
|
1173
|
+
so a backlog whose marker set never spells 💭 gets an empty one instead of a default
|
|
1174
|
+
naming a codepoint it does not use. Declared, every entry has to be an open marker:
|
|
1175
|
+
a marker `pick` sets aside and no line can carry is a `--designed` that silently does
|
|
1176
|
+
nothing, and this is the file it was typed in.
|
|
1177
|
+
"""
|
|
1178
|
+
if "undesigned" not in raw:
|
|
1179
|
+
return tuple(m for m in UNDESIGNED if m in open_markers)
|
|
1180
|
+
declared = tuple(_string_list(raw.get("undesigned"), "markers.undesigned", problems))
|
|
1181
|
+
stray = [m for m in declared if m not in open_markers]
|
|
1182
|
+
if stray:
|
|
1183
|
+
problems.append(
|
|
1184
|
+
f"markers.undesigned names {' '.join(stray)}, which markers.open does not: "
|
|
1185
|
+
"a marker no line may carry is a distinction `pick` can never act on"
|
|
1186
|
+
)
|
|
1187
|
+
return tuple(m for m in declared if m in open_markers)
|
|
1188
|
+
|
|
1189
|
+
|
|
1190
|
+
def _one_marker(
|
|
1191
|
+
raw: Mapping[str, object], key: str, default: str, problems: list[str]
|
|
1192
|
+
) -> str:
|
|
1193
|
+
value = raw.get(key, default)
|
|
1194
|
+
if not isinstance(value, str):
|
|
1195
|
+
problems.append(f"markers.{key} must be a string")
|
|
1196
|
+
return default
|
|
1197
|
+
return value
|
|
1198
|
+
|
|
1199
|
+
|
|
1200
|
+
def _reject_invisible(marker: str, problems: list[str]) -> None:
|
|
1201
|
+
for char, name in _INVISIBLE.items():
|
|
1202
|
+
if char in marker:
|
|
1203
|
+
problems.append(
|
|
1204
|
+
f"marker {marker.replace(char, '')!r} carries {name}, which is "
|
|
1205
|
+
f"invisible in an editor and unequal to the bare character: every "
|
|
1206
|
+
f"line would be permanently out of round-trip"
|
|
1207
|
+
)
|
|
1208
|
+
|
|
1209
|
+
|
|
1210
|
+
def _check_priority(
|
|
1211
|
+
schema: Schema, priority: tuple[str, ...], problems: list[str]
|
|
1212
|
+
) -> None:
|
|
1213
|
+
"""A priority entry names a task or a block, and is typed by the same code deps are.
|
|
1214
|
+
|
|
1215
|
+
Refused rather than ignored, like every other key here: an entry `pick` cannot
|
|
1216
|
+
resolve is a queue the author believes is in force and is not, and a *silent* one is
|
|
1217
|
+
worse than none — the tool would then answer "lowest ready id" while looking like it
|
|
1218
|
+
had applied a declaration.
|
|
1219
|
+
"""
|
|
1220
|
+
for token in priority:
|
|
1221
|
+
kind = schema.classify_dep(Dep(token))
|
|
1222
|
+
if kind is DepKind.TASK and not schema.id_pattern().match(token):
|
|
1223
|
+
problems.append(f"priority: not an id of this project: {token!r}")
|
|
1224
|
+
elif kind in (DepKind.RANGE, DepKind.EXTERNAL):
|
|
1225
|
+
problems.append(
|
|
1226
|
+
f"priority: {token!r} is neither an id nor 'Block X': a queue is an "
|
|
1227
|
+
f"order over work this backlog holds, so nothing else can be first"
|
|
1228
|
+
)
|
|
1229
|
+
|
|
1230
|
+
|
|
1231
|
+
def _check_reserved(
|
|
1232
|
+
schema: Schema, reserved: tuple[str, ...], problems: list[str]
|
|
1233
|
+
) -> None:
|
|
1234
|
+
"""A reserved id is an id of this project, and refused where it is not (RK1031).
|
|
1235
|
+
|
|
1236
|
+
The whole value of the list is that a token on it is *taken* and a token off it is a
|
|
1237
|
+
hazard, and both readings are worthless if the list can hold something the deriver
|
|
1238
|
+
cannot compare against a number. A word that is not an id would sit there looking like a
|
|
1239
|
+
reservation and reserve nothing — which is the silent state this declaration exists to
|
|
1240
|
+
replace, wearing the declaration's own name.
|
|
1241
|
+
"""
|
|
1242
|
+
for token in reserved:
|
|
1243
|
+
if not schema.id_pattern().match(token):
|
|
1244
|
+
problems.append(
|
|
1245
|
+
f"reserved_ids: not an id of this project: {token!r} — a reservation is an "
|
|
1246
|
+
f"address the deriver skips, so it has to be one the deriver can read"
|
|
1247
|
+
)
|
|
1248
|
+
|
|
1249
|
+
|
|
1250
|
+
def _scalars(raw: object) -> dict[str, object]:
|
|
1251
|
+
"""The keys a table sets directly, less its sub-tables — `[limits]` without a role's."""
|
|
1252
|
+
if not isinstance(raw, Mapping):
|
|
1253
|
+
return {}
|
|
1254
|
+
return {key: value for key, value in raw.items() if not isinstance(value, Mapping)}
|
|
1255
|
+
|
|
1256
|
+
|
|
1257
|
+
def _limits(raw: object, problems: list[str]) -> dict[str, int]:
|
|
1258
|
+
"""`[limits]` — the numbers every governed file is held to, before any role says less.
|
|
1259
|
+
|
|
1260
|
+
A sub-table is a role's own (`[limits.changelog]`, RK50) and is read by :func:`_by_role`;
|
|
1261
|
+
it is skipped here rather than rejected, so one table can carry both.
|
|
1262
|
+
"""
|
|
1263
|
+
if raw is None:
|
|
1264
|
+
return {}
|
|
1265
|
+
if not isinstance(raw, Mapping):
|
|
1266
|
+
problems.append("limits must be a table")
|
|
1267
|
+
return {}
|
|
1268
|
+
scalars = {key: value for key, value in raw.items() if not isinstance(value, Mapping)}
|
|
1269
|
+
_reject_unknown(scalars, frozenset(_LIMIT_KEYS), "limits.", problems)
|
|
1270
|
+
return _read_limits(scalars, "limits", problems)
|
|
1271
|
+
|
|
1272
|
+
|
|
1273
|
+
def _by_role(raw: object, problems: list[str]) -> dict[str, dict[str, int]]:
|
|
1274
|
+
"""`[limits.<role>]` — where one file is held to a different number (RK50).
|
|
1275
|
+
|
|
1276
|
+
A roadmap line is refused at insertion, where the refusal costs a retry; a ledger line
|
|
1277
|
+
is history, and Turing's reads 938 characters at the median against a `line` of 320.
|
|
1278
|
+
Judging the second by the first is a report about work nobody will redo, so the number
|
|
1279
|
+
is per role — and per *role*, not per path, because the role is what the format knows.
|
|
1280
|
+
"""
|
|
1281
|
+
if not isinstance(raw, Mapping):
|
|
1282
|
+
return {}
|
|
1283
|
+
out: dict[str, dict[str, int]] = {}
|
|
1284
|
+
for role, value in raw.items():
|
|
1285
|
+
if not isinstance(value, Mapping):
|
|
1286
|
+
continue
|
|
1287
|
+
where = f"limits.{role}"
|
|
1288
|
+
if role not in ROLES:
|
|
1289
|
+
problems.append(
|
|
1290
|
+
f"{where}: not a governed role ({', '.join(sorted(ROLES))}): a limit "
|
|
1291
|
+
f"for a file the format does not know is a limit nothing reads"
|
|
1292
|
+
)
|
|
1293
|
+
continue
|
|
1294
|
+
_reject_unknown(value, frozenset(_LIMIT_KEYS), f"{where}.", problems)
|
|
1295
|
+
found = _read_limits(value, where, problems)
|
|
1296
|
+
if found:
|
|
1297
|
+
out[role] = found
|
|
1298
|
+
return out
|
|
1299
|
+
|
|
1300
|
+
|
|
1301
|
+
def _rules(raw: object, problems: list[str]) -> dict[str, dict[str, bool]]:
|
|
1302
|
+
"""`[rules.<role>]` — a rule one file is not held to (RK52, RK66).
|
|
1303
|
+
|
|
1304
|
+
Only per role: `why` is one sentence ending in a stop *because* the remainder belongs in
|
|
1305
|
+
the section the line points at. That reasoning is a roadmap's. A ledger adopted with
|
|
1306
|
+
history in it holds 233 paragraphs that were written before the rule existed, and no edit
|
|
1307
|
+
available to their author makes them one sentence — so the project declares the file
|
|
1308
|
+
exempt, rather than the tool deciding the rule never mattered there. The write path reads
|
|
1309
|
+
the same declaration, so what a project exempts it may also record.
|
|
1310
|
+
|
|
1311
|
+
`ref = false` is the third, and it is the same shape of decision: Shio's process guide
|
|
1312
|
+
says a task with no rationale section carries no pointer, and three of its lines are a
|
|
1313
|
+
finding for obeying it. Both positions are defensible, which is what makes this
|
|
1314
|
+
configuration rather than a default to argue about (L6). It defaults to *required*, so
|
|
1315
|
+
nothing changes for a project that never declares it — and only the demand is
|
|
1316
|
+
negotiable, never the resolution: a pointer that is written must still point at
|
|
1317
|
+
something, which :mod:`roadkeep.linting` checks whatever this says.
|
|
1318
|
+
"""
|
|
1319
|
+
if not isinstance(raw, Mapping):
|
|
1320
|
+
if raw is not None:
|
|
1321
|
+
problems.append("rules must be a table of per-role tables")
|
|
1322
|
+
return {}
|
|
1323
|
+
out: dict[str, dict[str, bool]] = {}
|
|
1324
|
+
for role, value in raw.items():
|
|
1325
|
+
where = f"rules.{role}"
|
|
1326
|
+
if role not in ROLES:
|
|
1327
|
+
problems.append(
|
|
1328
|
+
f"{where}: not a governed role ({', '.join(sorted(ROLES))}): a rule for a "
|
|
1329
|
+
f"file the format does not know is a rule nothing reads"
|
|
1330
|
+
)
|
|
1331
|
+
continue
|
|
1332
|
+
if not isinstance(value, Mapping):
|
|
1333
|
+
problems.append(f"{where} must be a table of rule = true|false")
|
|
1334
|
+
continue
|
|
1335
|
+
_reject_unknown(value, frozenset(_RULE_KEYS), f"{where}.", problems)
|
|
1336
|
+
if role == "changelog" and "ref" in value:
|
|
1337
|
+
# The ledger has no pointer to demand or to waive: `ship` deletes §<id> in the
|
|
1338
|
+
# same transaction that writes the entry, so `ref = true` here would put every
|
|
1339
|
+
# line that ever ships permanently in violation, and `ref = false` states what
|
|
1340
|
+
# `as_ledger` already guarantees. Refused rather than ignored, like every other
|
|
1341
|
+
# key in this file.
|
|
1342
|
+
problems.append(
|
|
1343
|
+
f"{where}.ref: the ledger carries no pointer at all — the rationale "
|
|
1344
|
+
f"section is deleted when the task ships, so there is none to require"
|
|
1345
|
+
)
|
|
1346
|
+
continue
|
|
1347
|
+
found = {
|
|
1348
|
+
field: _flag(value, key, True, problems)
|
|
1349
|
+
for key, field in _RULE_KEYS.items()
|
|
1350
|
+
if key in value
|
|
1351
|
+
}
|
|
1352
|
+
if found:
|
|
1353
|
+
out[role] = found
|
|
1354
|
+
return out
|
|
1355
|
+
|
|
1356
|
+
|
|
1357
|
+
def _refs(
|
|
1358
|
+
raw: object, ref_scheme: str, declared: Mapping[str, Path], problems: list[str]
|
|
1359
|
+
) -> dict[str, str]:
|
|
1360
|
+
"""`[refs]` — which namespace a prose role's outline addresses live in (RK340).
|
|
1361
|
+
|
|
1362
|
+
Its own table and not a fourth key under `[rules.<role>]`, which says which rules a file
|
|
1363
|
+
is *not held to* and whose every value is a flag: a namespace is a name, and a string
|
|
1364
|
+
among booleans is the shape that made `markers.ledger` carry half of two decisions.
|
|
1365
|
+
|
|
1366
|
+
Three refusals, each of them a way for a namespace to fail to be one:
|
|
1367
|
+
|
|
1368
|
+
* **A prose role only.** The roadmap and the ledger hold lines and not headings, so a
|
|
1369
|
+
prefix on one addresses nothing — and the deferred store carries the section a pause
|
|
1370
|
+
kept, which is the prose role it came from and not a fourth namespace.
|
|
1371
|
+
* **Under an outline only.** The id scheme's anchor *is* the id, and ids are already one
|
|
1372
|
+
namespace this format refuses to spend twice; prefixing them would put a second address
|
|
1373
|
+
on a section whose first one the roadmap derives.
|
|
1374
|
+
* **Unique.** Two roles sharing a prefix is the collision this exists to end, one level
|
|
1375
|
+
up, and it would be the harder one to see: the addresses would agree and the files
|
|
1376
|
+
would not.
|
|
1377
|
+
|
|
1378
|
+
A role a project does not declare is refused too. It reads as configuration nothing
|
|
1379
|
+
applies, and the one thing worse than an unresolvable address is a declaration the author
|
|
1380
|
+
believes resolved it.
|
|
1381
|
+
"""
|
|
1382
|
+
if raw is None:
|
|
1383
|
+
return {}
|
|
1384
|
+
if not isinstance(raw, Mapping):
|
|
1385
|
+
problems.append("refs must be a table of role = \"<prefix>\"")
|
|
1386
|
+
return {}
|
|
1387
|
+
out: dict[str, str] = {}
|
|
1388
|
+
for role, value in raw.items():
|
|
1389
|
+
where = f"refs.{role}"
|
|
1390
|
+
if role not in PROSE_ROLES:
|
|
1391
|
+
problems.append(
|
|
1392
|
+
f"{where}: not a prose role ({', '.join(PROSE_ROLES)}): only a file that "
|
|
1393
|
+
f"declares headings has addresses to put in a namespace"
|
|
1394
|
+
)
|
|
1395
|
+
continue
|
|
1396
|
+
if not isinstance(value, str) or not REF_PREFIX_RE.match(value):
|
|
1397
|
+
problems.append(
|
|
1398
|
+
f"{where} must be one word of letters and digits starting with a letter: "
|
|
1399
|
+
f"it is written in front of an address as <prefix>{REF_SEPARATOR}<x.y>"
|
|
1400
|
+
)
|
|
1401
|
+
continue
|
|
1402
|
+
if ref_scheme != "outline":
|
|
1403
|
+
problems.append(
|
|
1404
|
+
f"{where}: a namespace is for ref_scheme = \"outline\" — under \"id\" the "
|
|
1405
|
+
f"anchor is the task's own id, which is already unique across the project"
|
|
1406
|
+
)
|
|
1407
|
+
continue
|
|
1408
|
+
if role not in declared:
|
|
1409
|
+
problems.append(
|
|
1410
|
+
f"{where}: this project declares no {role!r} file, so the namespace "
|
|
1411
|
+
f"addresses nothing — declare it under [files], or drop this line"
|
|
1412
|
+
)
|
|
1413
|
+
continue
|
|
1414
|
+
taken = next((other for other, one in out.items() if one == value), None)
|
|
1415
|
+
if taken is not None:
|
|
1416
|
+
problems.append(
|
|
1417
|
+
f"{where}: {value!r} is already {taken}'s namespace, and two roles sharing "
|
|
1418
|
+
f"one is the collision a namespace exists to end"
|
|
1419
|
+
)
|
|
1420
|
+
continue
|
|
1421
|
+
out[role] = value
|
|
1422
|
+
return out
|
|
1423
|
+
|
|
1424
|
+
|
|
1425
|
+
def _read_limits(raw: Mapping[str, object], where: str, problems: list[str]) -> dict[str, int]:
|
|
1426
|
+
out: dict[str, int] = {}
|
|
1427
|
+
for key, field_name in _LIMIT_KEYS.items():
|
|
1428
|
+
if key not in raw:
|
|
1429
|
+
continue
|
|
1430
|
+
value = raw[key]
|
|
1431
|
+
if not isinstance(value, int) or isinstance(value, bool):
|
|
1432
|
+
problems.append(f"{where}.{key} must be an integer")
|
|
1433
|
+
continue
|
|
1434
|
+
out[field_name] = value
|
|
1435
|
+
return out
|
|
1436
|
+
|
|
1437
|
+
|
|
1438
|
+
def _scope(raw: object, problems: list[str], table: str = "non_goals") -> Scope | None:
|
|
1439
|
+
"""`[non_goals]` — declared at all means governed, and each number may be left default.
|
|
1440
|
+
|
|
1441
|
+
An empty table is legal and is the shortest way to opt in: what a project is declaring
|
|
1442
|
+
is *that* the list is a schema, and the two limits are what it may then also tune (L6).
|
|
1443
|
+
|
|
1444
|
+
``table`` is which of the two lists is being read (RK1265). `[criteria]` is the same two
|
|
1445
|
+
numbers about the positive twin, so the reader is one function and only the problems it
|
|
1446
|
+
reports name the key — two copies would be two opt-ins that came to accept different shapes.
|
|
1447
|
+
"""
|
|
1448
|
+
if raw is None:
|
|
1449
|
+
return None
|
|
1450
|
+
if not isinstance(raw, Mapping):
|
|
1451
|
+
problems.append(f"{table} must be a table of lead = …, why = …")
|
|
1452
|
+
return None
|
|
1453
|
+
_reject_unknown(raw, _SCOPE_KEYS, f"{table}.", problems)
|
|
1454
|
+
numbers: dict[str, int] = {}
|
|
1455
|
+
for key in sorted(_SCOPE_KEYS):
|
|
1456
|
+
if key not in raw:
|
|
1457
|
+
continue
|
|
1458
|
+
value = raw[key]
|
|
1459
|
+
if not isinstance(value, int) or isinstance(value, bool) or value < 1:
|
|
1460
|
+
problems.append(f"{table}.{key} must be a positive integer")
|
|
1461
|
+
continue
|
|
1462
|
+
numbers[key] = value
|
|
1463
|
+
return Scope(**numbers)
|
|
1464
|
+
|
|
1465
|
+
|
|
1466
|
+
#: `[report]` — one key, and refused like every other. A table with room for a token or a
|
|
1467
|
+
#: URL is a table somebody puts a token in; the only thing declarable here is *where* a
|
|
1468
|
+
#: defect in this tool would be filed, and filing it is still a command a person types.
|
|
1469
|
+
_REPORT_KEYS = frozenset({"upstream"})
|
|
1470
|
+
|
|
1471
|
+
#: `owner/repo`, which is what `gh --repo` takes. Checked because the alternative to a
|
|
1472
|
+
#: shape here is a shape guessed by whatever the operator pipes the capture into.
|
|
1473
|
+
_UPSTREAM = re.compile(r"^[A-Za-z0-9._-]+/[A-Za-z0-9._-]+$")
|
|
1474
|
+
|
|
1475
|
+
|
|
1476
|
+
def _requirements(raw: object, problems: list[str]) -> tuple[str, ...]:
|
|
1477
|
+
"""`[requirements] declared` — the vocabulary a `(needs: …)` group quotes from (RK1297).
|
|
1478
|
+
|
|
1479
|
+
Empty undeclared, which is what makes the axis opt-in and refusable at once: a project
|
|
1480
|
+
that never wrote this table refuses the first requirement an author types, and the
|
|
1481
|
+
refusal names the table instead of listing nothing. Nothing here is defaulted for the
|
|
1482
|
+
reason `[non_goals]` is not — a built-in vocabulary would be this tool deciding what a
|
|
1483
|
+
backlog's world contains, and `hardware` means nothing to a project that ships prose.
|
|
1484
|
+
|
|
1485
|
+
Every token is held to the shape the line can carry, and it is checked *here* rather
|
|
1486
|
+
than only at the write: a word with a comma in it splits into two on the way back out,
|
|
1487
|
+
so a vocabulary nothing could quote would be declared once and refuse every `add` after
|
|
1488
|
+
it, in a file the author is not looking at.
|
|
1489
|
+
"""
|
|
1490
|
+
if raw is None:
|
|
1491
|
+
return ()
|
|
1492
|
+
if not isinstance(raw, Mapping):
|
|
1493
|
+
problems.append("requirements must be a table")
|
|
1494
|
+
return ()
|
|
1495
|
+
_reject_unknown(raw, _REQUIREMENTS_KEYS, "requirements.", problems)
|
|
1496
|
+
declared = tuple(
|
|
1497
|
+
dict.fromkeys(_string_list(raw.get("declared"), "requirements.declared", problems))
|
|
1498
|
+
)
|
|
1499
|
+
bad = [one for one in declared if not one or one.strip() != one or _UNQUOTABLE.search(one)]
|
|
1500
|
+
if bad:
|
|
1501
|
+
problems.append(
|
|
1502
|
+
f"requirements.declared names {', '.join(repr(one) for one in bad)}, which a "
|
|
1503
|
+
f"line cannot carry: the group closes at the first ')' and separates on ',', so "
|
|
1504
|
+
f"a requirement is one word with neither"
|
|
1505
|
+
)
|
|
1506
|
+
return tuple(one for one in declared if one not in bad)
|
|
1507
|
+
|
|
1508
|
+
|
|
1509
|
+
#: What a requirement may not contain, for the reason the deps group has the same rule: the
|
|
1510
|
+
#: `(needs: …)` slot closes at the first `)` and splits on `, `, so either inside a token is a
|
|
1511
|
+
#: line that stops parsing and no verb reaches again.
|
|
1512
|
+
_UNQUOTABLE = re.compile(r"[(),]")
|
|
1513
|
+
|
|
1514
|
+
|
|
1515
|
+
def _held(raw: object, problems: list[str]) -> int:
|
|
1516
|
+
"""`[claims] held` — minutes, bounded at both ends (RK151).
|
|
1517
|
+
|
|
1518
|
+
The bound is the design and not a guard rail. Below a minute a claim expires before the
|
|
1519
|
+
worker has read the brief it came with; above :data:`CLAIM_HELD_MAX` an abandoned claim
|
|
1520
|
+
outlives the session that abandoned it, which is the lock this mechanism exists not to be.
|
|
1521
|
+
Between them the number is a judgement about this backlog, which is why it is declarable
|
|
1522
|
+
at all — and the refusal names the unit, because the one way to be badly wrong here is to
|
|
1523
|
+
write seconds in a key that reads minutes.
|
|
1524
|
+
"""
|
|
1525
|
+
if raw is None:
|
|
1526
|
+
return CLAIM_HELD
|
|
1527
|
+
if not isinstance(raw, Mapping):
|
|
1528
|
+
problems.append("claims must be a table of held = <minutes>")
|
|
1529
|
+
return CLAIM_HELD
|
|
1530
|
+
_reject_unknown(raw, _CLAIMS_KEYS, "claims.", problems)
|
|
1531
|
+
value = raw.get("held")
|
|
1532
|
+
if value is None:
|
|
1533
|
+
return CLAIM_HELD
|
|
1534
|
+
if not isinstance(value, int) or isinstance(value, bool) or not 1 <= value <= CLAIM_HELD_MAX:
|
|
1535
|
+
problems.append(
|
|
1536
|
+
f"claims.held must be minutes, from 1 to {CLAIM_HELD_MAX}: a claim shorter than "
|
|
1537
|
+
f"that expires before the brief is read, and a longer one is the lock an expiry "
|
|
1538
|
+
f"exists not to be"
|
|
1539
|
+
)
|
|
1540
|
+
return CLAIM_HELD
|
|
1541
|
+
return value
|
|
1542
|
+
|
|
1543
|
+
|
|
1544
|
+
def _upstream(raw: object, problems: list[str]) -> str | None:
|
|
1545
|
+
if raw is None:
|
|
1546
|
+
return None
|
|
1547
|
+
if not isinstance(raw, Mapping):
|
|
1548
|
+
problems.append("report must be a table of upstream = 'owner/repo'")
|
|
1549
|
+
return None
|
|
1550
|
+
_reject_unknown(raw, _REPORT_KEYS, "report.", problems)
|
|
1551
|
+
value = raw.get("upstream")
|
|
1552
|
+
if value is None:
|
|
1553
|
+
return None
|
|
1554
|
+
if not isinstance(value, str) or not _UPSTREAM.match(value):
|
|
1555
|
+
problems.append("report.upstream must be 'owner/repo'")
|
|
1556
|
+
return None
|
|
1557
|
+
return value
|
|
1558
|
+
|
|
1559
|
+
|
|
1560
|
+
def _budgets(raw: object, base: Path, problems: list[str]) -> tuple[Budget, ...]:
|
|
1561
|
+
"""`[budgets]` — a path to what it may cost. Refused, like every other key here."""
|
|
1562
|
+
if raw is None:
|
|
1563
|
+
return ()
|
|
1564
|
+
if not isinstance(raw, Mapping):
|
|
1565
|
+
problems.append("budgets must be a table of path = { lines = …, bytes = … }")
|
|
1566
|
+
return ()
|
|
1567
|
+
out: list[Budget] = []
|
|
1568
|
+
for name, value in raw.items():
|
|
1569
|
+
where = f"budgets.'{name}'"
|
|
1570
|
+
if not isinstance(value, Mapping):
|
|
1571
|
+
problems.append(f"{where} must be a table with 'lines' and/or 'bytes'")
|
|
1572
|
+
continue
|
|
1573
|
+
_reject_unknown(value, _BUDGET_KEYS, f"{where}.", problems)
|
|
1574
|
+
if Path(name).is_absolute():
|
|
1575
|
+
problems.append(
|
|
1576
|
+
f"{where} must be relative to the project root: an absolute path is "
|
|
1577
|
+
f"checked in and then wrong on every other machine"
|
|
1578
|
+
)
|
|
1579
|
+
continue
|
|
1580
|
+
if not _BUDGET_KEYS & set(value):
|
|
1581
|
+
# Declared *nothing*, which is a different mistake from declaring a number
|
|
1582
|
+
# this rejected: reporting both would send the reader to fix the wrong line.
|
|
1583
|
+
problems.append(
|
|
1584
|
+
f"{where} declares neither lines nor bytes: an entry that holds nobody "
|
|
1585
|
+
f"to anything reads as a budget and is the arrangement being replaced"
|
|
1586
|
+
)
|
|
1587
|
+
continue
|
|
1588
|
+
numbers = _positive(value, where, problems)
|
|
1589
|
+
if numbers:
|
|
1590
|
+
out.append(Budget(path=(base / name).resolve(), **numbers))
|
|
1591
|
+
return tuple(out)
|
|
1592
|
+
|
|
1593
|
+
|
|
1594
|
+
def _positions(source: Path | None) -> dict[tuple[str, str], int]:
|
|
1595
|
+
"""Which line of the config each `table.key` is written on (RK1067).
|
|
1596
|
+
|
|
1597
|
+
Read off the text and never through the parse, for :func:`_declared_at`'s reason:
|
|
1598
|
+
`tomllib` keeps no positions, and a refusal that cited `roadkeep.toml:0` would be the
|
|
1599
|
+
one address in this tool that opens nothing. Coarse on purpose — the first assignment
|
|
1600
|
+
of a key under a header — because what a reader needs is the line to go and look at,
|
|
1601
|
+
and a second parser written to be exact about it is a second parser to keep right.
|
|
1602
|
+
"""
|
|
1603
|
+
if source is None:
|
|
1604
|
+
return {}
|
|
1605
|
+
try:
|
|
1606
|
+
text = source.read_text(encoding="utf-8")
|
|
1607
|
+
except OSError:
|
|
1608
|
+
return {}
|
|
1609
|
+
found: dict[tuple[str, str], int] = {}
|
|
1610
|
+
table = ""
|
|
1611
|
+
for lineno, line in enumerate(text.splitlines(), start=1):
|
|
1612
|
+
stripped = line.strip()
|
|
1613
|
+
header = re.match(r"^\[([^\]]+)\]$", stripped)
|
|
1614
|
+
if header:
|
|
1615
|
+
table = header.group(1)
|
|
1616
|
+
continue
|
|
1617
|
+
key = re.match(r'^([A-Za-z_][A-Za-z0-9_]*|"[^"]+")\s*=', stripped)
|
|
1618
|
+
if key and (table, key.group(1)) not in found:
|
|
1619
|
+
found[(table, key.group(1))] = lineno
|
|
1620
|
+
return found
|
|
1621
|
+
|
|
1622
|
+
|
|
1623
|
+
def _origins(
|
|
1624
|
+
source: Path | None, declared: Mapping[str, object], role: str = ""
|
|
1625
|
+
) -> tuple[tuple[str, str], ...]:
|
|
1626
|
+
"""Where each limit this project set was declared, as the clause a refusal prints.
|
|
1627
|
+
|
|
1628
|
+
Only the keys the project actually wrote: a limit it never declared has no line, and
|
|
1629
|
+
:meth:`Schema.source_of` says *this tool's default* rather than inventing a citation —
|
|
1630
|
+
which of the two numbers a refusal is about being exactly the fact the author needs.
|
|
1631
|
+
"""
|
|
1632
|
+
if source is None:
|
|
1633
|
+
return ()
|
|
1634
|
+
where = source.name
|
|
1635
|
+
table = f"limits.{role}" if role else "limits"
|
|
1636
|
+
at = _positions(source)
|
|
1637
|
+
out: list[tuple[str, str]] = []
|
|
1638
|
+
for key, attribute in _LIMIT_KEYS.items():
|
|
1639
|
+
# Either spelling, because the two callers hold different ones: the top-level table
|
|
1640
|
+
# arrives as it was written (`why`) and a role's arrives already translated to the
|
|
1641
|
+
# field it sets (`why_max`), and a citation that only knew one would silently drop
|
|
1642
|
+
# every per-role number — the ones RK50 exists for and the ones most worth citing.
|
|
1643
|
+
if key not in declared and attribute not in declared:
|
|
1644
|
+
continue
|
|
1645
|
+
lineno = at.get((table, key))
|
|
1646
|
+
address = f"{where}:{lineno}" if lineno else where
|
|
1647
|
+
out.append((attribute, f"{address} [{table}].{key}"))
|
|
1648
|
+
return tuple(out)
|
|
1649
|
+
|
|
1650
|
+
|
|
1651
|
+
def _grammars(raw: object, problems: list[str]) -> dict[str, Grammar]:
|
|
1652
|
+
"""`[grammar.<role>]` — one role's shape, refused key by key like every other table.
|
|
1653
|
+
|
|
1654
|
+
Every name is checked against a closed set and never taken (RK1064): a `drop` naming a
|
|
1655
|
+
field this format does not have is a slot the author believes is gone, which is the
|
|
1656
|
+
same failure an unignored `symptom_max` typo is one layer down. The role itself is
|
|
1657
|
+
checked too — a grammar for a file `[files]` does not declare is a shape nothing reads.
|
|
1658
|
+
"""
|
|
1659
|
+
if raw is None:
|
|
1660
|
+
return {}
|
|
1661
|
+
if not isinstance(raw, Mapping):
|
|
1662
|
+
problems.append("grammar must be a table of role = { extends = …, drop = […] }")
|
|
1663
|
+
return {}
|
|
1664
|
+
out: dict[str, Grammar] = {}
|
|
1665
|
+
for role, value in raw.items():
|
|
1666
|
+
where = f"grammar.{role}"
|
|
1667
|
+
if role not in ROLES:
|
|
1668
|
+
problems.append(f"{where} is not a role ({', '.join(ROLES)})")
|
|
1669
|
+
continue
|
|
1670
|
+
if not isinstance(value, Mapping):
|
|
1671
|
+
problems.append(f"{where} must be a table with {', '.join(sorted(_GRAMMAR_KEYS))}")
|
|
1672
|
+
continue
|
|
1673
|
+
_reject_unknown(value, _GRAMMAR_KEYS, f"{where}.", problems)
|
|
1674
|
+
extends = value.get("extends", "roadmap")
|
|
1675
|
+
if not isinstance(extends, str) or extends not in ROLES:
|
|
1676
|
+
problems.append(f"{where}.extends is not a role ({', '.join(ROLES)})")
|
|
1677
|
+
continue
|
|
1678
|
+
markers = _named(value.get("markers"), MARKER_NAMES, f"{where}.markers", problems)
|
|
1679
|
+
drop = _named(value.get("drop"), DROPPABLE, f"{where}.drop", problems)
|
|
1680
|
+
# The states a role carries are the tool's own and not a project's to declare, so
|
|
1681
|
+
# what a shipped grammar said stays said: a project reshapes the line under it.
|
|
1682
|
+
states = DEFAULT_GRAMMARS.get(role, Grammar()).states
|
|
1683
|
+
out[role] = Grammar(extends=extends, markers=markers, drop=drop, states=states)
|
|
1684
|
+
return out
|
|
1685
|
+
|
|
1686
|
+
|
|
1687
|
+
def _named(
|
|
1688
|
+
raw: object, allowed: Mapping[str, str], where: str, problems: list[str]
|
|
1689
|
+
) -> tuple[str, ...]:
|
|
1690
|
+
"""A list of names from a closed set, or a problem naming what the set holds."""
|
|
1691
|
+
if raw is None:
|
|
1692
|
+
return ()
|
|
1693
|
+
names = _string_list(raw, where, problems)
|
|
1694
|
+
unknown = [name for name in names if name not in allowed]
|
|
1695
|
+
if unknown:
|
|
1696
|
+
problems.append(
|
|
1697
|
+
f"{where} names {', '.join(unknown)}, which is not one of "
|
|
1698
|
+
f"{', '.join(sorted(allowed))}"
|
|
1699
|
+
)
|
|
1700
|
+
return ()
|
|
1701
|
+
return tuple(dict.fromkeys(names))
|
|
1702
|
+
|
|
1703
|
+
|
|
1704
|
+
def _read_budget(raw: object, problems: list[str]) -> int | None:
|
|
1705
|
+
"""`[reads] brief` — what the one read that replaces reading the file may cost (RK1286).
|
|
1706
|
+
|
|
1707
|
+
Opt-in and refused like every other key here rather than defaulted, which is `[tools]`'
|
|
1708
|
+
rule and `[criteria]`'s: a ceiling this tool chose for somebody's answer would be a number
|
|
1709
|
+
nobody looked at, and a gate that reported on the first run is one that gets bypassed.
|
|
1710
|
+
"""
|
|
1711
|
+
if raw is None:
|
|
1712
|
+
return None
|
|
1713
|
+
if not isinstance(raw, Mapping):
|
|
1714
|
+
problems.append("reads must be a table of brief = <characters>")
|
|
1715
|
+
return None
|
|
1716
|
+
_reject_unknown(raw, _READS_KEYS, "reads.", problems)
|
|
1717
|
+
value = raw.get("brief")
|
|
1718
|
+
if value is None:
|
|
1719
|
+
# `[tools]`' own refusal: a table that holds nobody to anything reads as a budget and
|
|
1720
|
+
# is exactly the arrangement being replaced.
|
|
1721
|
+
problems.append(
|
|
1722
|
+
"reads declares no brief: a table that holds nobody to anything reads as a "
|
|
1723
|
+
"budget and is the arrangement being replaced"
|
|
1724
|
+
)
|
|
1725
|
+
return None
|
|
1726
|
+
if not isinstance(value, int) or isinstance(value, bool) or value < 1:
|
|
1727
|
+
problems.append("reads.brief must be a positive integer")
|
|
1728
|
+
return None
|
|
1729
|
+
return value
|
|
1730
|
+
|
|
1731
|
+
|
|
1732
|
+
def _tool_budget(raw: object, problems: list[str]) -> tuple[int | None, int | None]:
|
|
1733
|
+
"""`[tools]` — what one served tool may cost, and what the whole surface may (RK1059/1097).
|
|
1734
|
+
|
|
1735
|
+
Refused like every other key here rather than defaulted: a ceiling this tool chose for
|
|
1736
|
+
somebody's surface would be a number nobody looked at, which is the state RK464 named
|
|
1737
|
+
and declined to fix by guessing.
|
|
1738
|
+
|
|
1739
|
+
`session` is optional beside a declared `characters` and never instead of it. Per tool is
|
|
1740
|
+
the one that names an author — it is refused by whoever just edited that description —
|
|
1741
|
+
and it was right about *which* tool to blame and silent about the sum, which is how this
|
|
1742
|
+
repo reached 52 tools and 50,673 characters against a ceiling of 135,200 nobody chose.
|
|
1743
|
+
A total is the only rule that catches a list growing by verbs each of which is
|
|
1744
|
+
unremarkable, and it is offered rather than imposed for exactly RK1059's reason.
|
|
1745
|
+
"""
|
|
1746
|
+
if raw is None:
|
|
1747
|
+
return None, None
|
|
1748
|
+
if not isinstance(raw, Mapping):
|
|
1749
|
+
problems.append("tools must be a table of { characters = … }")
|
|
1750
|
+
return None, None
|
|
1751
|
+
_reject_unknown(raw, _TOOLS_KEYS, "tools.", problems)
|
|
1752
|
+
if "characters" not in raw:
|
|
1753
|
+
# The same mistake `[budgets]` names: an entry that holds nobody to anything reads
|
|
1754
|
+
# as a budget and is exactly the arrangement being replaced. `session` alone does not
|
|
1755
|
+
# answer it: a surface under its total with one 30,000-character tool in it is the
|
|
1756
|
+
# state per-tool exists to refuse.
|
|
1757
|
+
problems.append(
|
|
1758
|
+
"tools declares no characters: a table that holds nobody to anything reads "
|
|
1759
|
+
"as a budget and is the arrangement being replaced"
|
|
1760
|
+
)
|
|
1761
|
+
return None, None
|
|
1762
|
+
numbers: dict[str, int | None] = {"characters": None, "session": None}
|
|
1763
|
+
for key in ("characters", "session"):
|
|
1764
|
+
if key not in raw:
|
|
1765
|
+
continue
|
|
1766
|
+
number = raw[key]
|
|
1767
|
+
if not isinstance(number, int) or isinstance(number, bool) or number < 1:
|
|
1768
|
+
problems.append(f"tools.{key} must be a positive integer")
|
|
1769
|
+
continue
|
|
1770
|
+
numbers[key] = number
|
|
1771
|
+
if numbers["characters"] is None:
|
|
1772
|
+
return None, None
|
|
1773
|
+
if numbers["session"] is not None and numbers["session"] < numbers["characters"]:
|
|
1774
|
+
# Not arithmetic pedantry: a total below what one tool may cost makes the per-tool
|
|
1775
|
+
# number unreachable, so one of the two was typed without reading the other.
|
|
1776
|
+
problems.append(
|
|
1777
|
+
f"tools.session is {numbers['session']} and tools.characters is "
|
|
1778
|
+
f"{numbers['characters']}: a surface may not cost less than one tool in it"
|
|
1779
|
+
)
|
|
1780
|
+
return numbers["characters"], None
|
|
1781
|
+
return numbers["characters"], numbers["session"]
|
|
1782
|
+
|
|
1783
|
+
|
|
1784
|
+
def _positive(
|
|
1785
|
+
value: Mapping[str, object], where: str, problems: list[str]
|
|
1786
|
+
) -> dict[str, int]:
|
|
1787
|
+
"""The budget's two numbers, each one a positive integer or a problem."""
|
|
1788
|
+
out: dict[str, int] = {}
|
|
1789
|
+
for key in sorted(_BUDGET_KEYS):
|
|
1790
|
+
if key not in value:
|
|
1791
|
+
continue
|
|
1792
|
+
number = value[key]
|
|
1793
|
+
if not isinstance(number, int) or isinstance(number, bool) or number < 1:
|
|
1794
|
+
problems.append(f"{where}.{key} must be a positive integer")
|
|
1795
|
+
continue
|
|
1796
|
+
out[key] = number
|
|
1797
|
+
return out
|
|
1798
|
+
|
|
1799
|
+
|
|
1800
|
+
def _paths(raw: object, base: Path, problems: list[str]) -> dict[str, Path]:
|
|
1801
|
+
if raw is None:
|
|
1802
|
+
return {role: base / rel for role, rel in DEFAULT_PATHS.items()}
|
|
1803
|
+
if not isinstance(raw, Mapping):
|
|
1804
|
+
problems.append("files must be a table of role = path")
|
|
1805
|
+
return {}
|
|
1806
|
+
_reject_unknown(raw, frozenset(ROLES), "files.", problems)
|
|
1807
|
+
out: dict[str, Path] = {}
|
|
1808
|
+
for role in ROLES:
|
|
1809
|
+
if role not in raw:
|
|
1810
|
+
continue
|
|
1811
|
+
value = raw[role]
|
|
1812
|
+
if not isinstance(value, str):
|
|
1813
|
+
problems.append(f"files.{role} must be a string path")
|
|
1814
|
+
continue
|
|
1815
|
+
candidate = Path(value)
|
|
1816
|
+
if candidate.is_absolute():
|
|
1817
|
+
problems.append(
|
|
1818
|
+
f"files.{role} must be relative to the project root: an absolute "
|
|
1819
|
+
f"path is checked in and then wrong on every other machine"
|
|
1820
|
+
)
|
|
1821
|
+
continue
|
|
1822
|
+
out[role] = (base / candidate).resolve()
|
|
1823
|
+
return out
|
|
1824
|
+
|
|
1825
|
+
|
|
1826
|
+
def _string_list(raw: object, where: str, problems: list[str]) -> list[str]:
|
|
1827
|
+
if raw is None:
|
|
1828
|
+
return []
|
|
1829
|
+
if not isinstance(raw, list) or not all(isinstance(item, str) for item in raw):
|
|
1830
|
+
problems.append(f"{where} must be a list of strings")
|
|
1831
|
+
return []
|
|
1832
|
+
return list(raw)
|