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/sections.py
ADDED
|
@@ -0,0 +1,4121 @@
|
|
|
1
|
+
"""Prose files have a different unit, so they get a different schema (RK9).
|
|
2
|
+
|
|
3
|
+
Three of the four governed files are lines; two are paragraphs. A rationale or a strategy
|
|
4
|
+
is prose under a heading, and applying the line schema to it would be the wrong law
|
|
5
|
+
twice over: there is no `symptom` to bound and no 320-character cap that means anything
|
|
6
|
+
about a paragraph. What a section *does* have is:
|
|
7
|
+
|
|
8
|
+
* **an anchor**, which is the whole reason the pointer on a task line resolves (RK27) —
|
|
9
|
+
so `§RK9` must name an open task, and a typo names nothing at all. Read **per scheme**
|
|
10
|
+
(RK44): `id` requires the § that tells an id from a word, while an outline numbers its
|
|
11
|
+
own headings and puts the sigil on the pointer alone, so reading one spelling into the
|
|
12
|
+
other turned Shio's 151 headings into 0 sections and 74 pointers into 74 dangling ones;
|
|
13
|
+
* **a word budget**, because the failure mode measured here was a rationale file reaching
|
|
14
|
+
539 KB one honest paragraph at a time — a limit in words is the one an author can act
|
|
15
|
+
on before writing, which is the same argument as `add`'s (L1);
|
|
16
|
+
* **a place**, which is derived twice over: a section for a task belongs under that task's
|
|
17
|
+
block, and a section for no task belongs under the section its anchor extends (RK45) —
|
|
18
|
+
§0.4 after §0.3, §RK34.1 inside §RK34. So the file's shape is a consequence of the
|
|
19
|
+
backlog's and of the outline's, and nobody chooses where to type.
|
|
20
|
+
|
|
21
|
+
`amend` is the door that was missing (RK123). Three correct refusals — `drop` while a live
|
|
22
|
+
pointer names the anchor, `add` on the duplicate, and the guard on the hand edit — added up
|
|
23
|
+
to a rationale that could not be corrected at all while its task was open, which is exactly
|
|
24
|
+
when a design changes. It rewrites the heading text and the section's **own** prose, never
|
|
25
|
+
the subtree and never the anchor: a subsection has an anchor of its own to be named by, and
|
|
26
|
+
an address under the id scheme is `renumber`'s.
|
|
27
|
+
|
|
28
|
+
`move` is the same sentence's other half (RK377). Under an outline the anchor is *not* an id,
|
|
29
|
+
so `renumber` never reaches it — line 172 there keeps the pointer as typed — and a doubled
|
|
30
|
+
address had no verb at all: `lint` reports `section.ambiguous`, `add` refuses the second one,
|
|
31
|
+
and Turing adopted the tool with 13 addresses its two prose files both declared. So the
|
|
32
|
+
re-address is a door, taking every refusal `add` computes about a destination
|
|
33
|
+
(:func:`unspent`) and moving the whole address in one transaction — the heading, every nested
|
|
34
|
+
anchor that extends it, and the `→ §<anchor>` on every line that points at one of them. Which
|
|
35
|
+
line meant which of two doubled sections is the thing the files do not say, so the pointers
|
|
36
|
+
move with the heading and are **named** in the answer, for the reason
|
|
37
|
+
:mod:`~roadkeep.renumbering` names the deps it moved. Only within the address's own parent:
|
|
38
|
+
the section stays where it is in the file, and a heading re-addressed across parents would
|
|
39
|
+
sit inside a subtree its address no longer names — where the next `drop` takes it.
|
|
40
|
+
|
|
41
|
+
`drop` is the operation `ship` (RK6) calls for rule one of its three edits — it lives here
|
|
42
|
+
rather than there because deleting a section is a fact about this file's grammar, not
|
|
43
|
+
about shipping, and the two would otherwise disagree about where a section ends. It takes
|
|
44
|
+
the **whole subtree**, and is refused before it writes when that subtree holds a section
|
|
45
|
+
some other open line points at (RK78): a heading nested under another is that other's
|
|
46
|
+
prose, right up until a second pointer names it, and then deleting it is a deletion the
|
|
47
|
+
transaction never named — measured on Shio, 160 lines removed by a command that reported
|
|
48
|
+
dropping one section, leaving two live pointers resolving to nothing.
|
|
49
|
+
|
|
50
|
+
Reflow is deliberately narrow. A plain paragraph is filled to the configured width, and
|
|
51
|
+
anything carrying a Markdown structure — a table, a list, a quote, a fence — is inserted
|
|
52
|
+
exactly as written: the tool re-flows prose, and never reformats a shape it did not
|
|
53
|
+
author. That is the same line L4 draws, one file down.
|
|
54
|
+
"""
|
|
55
|
+
|
|
56
|
+
from __future__ import annotations
|
|
57
|
+
|
|
58
|
+
import re
|
|
59
|
+
import textwrap
|
|
60
|
+
from collections.abc import Iterator, Mapping, Sequence
|
|
61
|
+
from dataclasses import dataclass, field, replace
|
|
62
|
+
from typing import TYPE_CHECKING
|
|
63
|
+
|
|
64
|
+
from roadkeep.backlog import Whereabouts
|
|
65
|
+
from roadkeep.config import PROSE_ROLES, Config
|
|
66
|
+
from roadkeep.kernel.document import Document, Heading, UnknownBlock, blank, save_all
|
|
67
|
+
from roadkeep.kernel.schema import (
|
|
68
|
+
OUTLINE_ANCHOR_RE,
|
|
69
|
+
REF_SEPARATOR,
|
|
70
|
+
Schema,
|
|
71
|
+
SchemaError,
|
|
72
|
+
Task,
|
|
73
|
+
Violation,
|
|
74
|
+
over_by,
|
|
75
|
+
split_ref,
|
|
76
|
+
)
|
|
77
|
+
|
|
78
|
+
if TYPE_CHECKING: # imported for the annotation alone: `history` reads this module back
|
|
79
|
+
from roadkeep.history import Anchor
|
|
80
|
+
|
|
81
|
+
#: Openers that are a shape whatever follows them: a table row, a blockquote, a fence. No
|
|
82
|
+
#: space is required after any of these, `|a|b|` and `>quoted` both being legal Markdown.
|
|
83
|
+
_VERBATIM = ("|", ">", "```", "~~~")
|
|
84
|
+
#: A list marker or a heading, which is the character **and the space after it** (RK397). The
|
|
85
|
+
#: space is the whole rule: `*` was read as a bullet, so a prose line breaking before a
|
|
86
|
+
#: `**bold**` span made the paragraph a structure and the tool stopped filling it — silently,
|
|
87
|
+
#: `lint` charging a body in words and never in width. `1.5 seconds` fell the same way.
|
|
88
|
+
_MARKER = re.compile(r"(?:[-*+]|#{1,6}|\d+[.)])(?:\s|$)")
|
|
89
|
+
#: The same characters with no space, which is a thematic break and is still a shape. Kept
|
|
90
|
+
#: apart from :data:`_MARKER` rather than folded in, because the two are opposite readings of
|
|
91
|
+
#: one prefix and a rule that guessed between them is the defect above with a longer alphabet.
|
|
92
|
+
_BREAK = re.compile(r"(?:-{3,}|\*{3,}|_{3,})\s*$")
|
|
93
|
+
#: What opens a block whose contents are quoted or generated rather than written (RK136).
|
|
94
|
+
_FENCES = ("```", "~~~")
|
|
95
|
+
#: A line that is data rather than argument, so the budget does not charge for it. A list
|
|
96
|
+
#: marker is deliberately absent: a bullet is how an argument is written in these files.
|
|
97
|
+
_DATA = ("|", ">")
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
class SectionError(SchemaError):
|
|
101
|
+
"""A section the schema refuses, carrying every violation, not the first.
|
|
102
|
+
|
|
103
|
+
A :class:`~roadkeep.kernel.schema.SchemaError` because it is the same law one file down —
|
|
104
|
+
which also means every caller that already reports violations reports these.
|
|
105
|
+
"""
|
|
106
|
+
|
|
107
|
+
|
|
108
|
+
class NoSuchSection(ValueError):
|
|
109
|
+
"""An anchor nothing in this file declares."""
|
|
110
|
+
|
|
111
|
+
def __init__(self, anchor: str, where: str = "", *, titled_too: bool = False) -> None:
|
|
112
|
+
self.anchor = anchor
|
|
113
|
+
# `titled_too` where the caller also tried the address as a **heading text** (RK1107):
|
|
114
|
+
# `show` and `amend` look an anchor up first and fall through to the title, so a
|
|
115
|
+
# refusal naming only the anchor would describe half the lookup that failed.
|
|
116
|
+
said = f"no §{anchor} section in {where or 'the document'}"
|
|
117
|
+
if titled_too:
|
|
118
|
+
said += f", and no heading reading {anchor!r} either"
|
|
119
|
+
super().__init__(said)
|
|
120
|
+
|
|
121
|
+
|
|
122
|
+
class NotOneOccurrence(ValueError):
|
|
123
|
+
"""`--replace` naming a string this prose does not hold exactly once (RK1263).
|
|
124
|
+
|
|
125
|
+
The refusal that makes the narrow edit safe. A substitution applied to whatever it happens
|
|
126
|
+
to match is a write whose blast radius the caller cannot see, which is the property the
|
|
127
|
+
whole-body form at least had — so the count is the contract: none means the string was
|
|
128
|
+
mistyped or already corrected, and several mean the call is ambiguous about which.
|
|
129
|
+
|
|
130
|
+
Neither is answered by picking one. The first occurrence is a guess, and `str.replace`'s own
|
|
131
|
+
default — all of them — is the edit a caller reaching for a one-clause fix least expects.
|
|
132
|
+
"""
|
|
133
|
+
|
|
134
|
+
def __init__(self, old: str, found: int, where: str) -> None:
|
|
135
|
+
self.old = old
|
|
136
|
+
self.found = found
|
|
137
|
+
said = (
|
|
138
|
+
f"{where} does not carry {old!r}"
|
|
139
|
+
if found == 0
|
|
140
|
+
else f"{where} carries {old!r} {found} times"
|
|
141
|
+
)
|
|
142
|
+
advice = (
|
|
143
|
+
"check the spelling against `section show`, which prints the prose as it is"
|
|
144
|
+
if found == 0
|
|
145
|
+
else "pass a longer string that occurs once, or --body for the whole prose"
|
|
146
|
+
)
|
|
147
|
+
super().__init__(f"--replace names one occurrence and {said}: {advice}")
|
|
148
|
+
|
|
149
|
+
|
|
150
|
+
@dataclass(frozen=True, slots=True)
|
|
151
|
+
class Substitution:
|
|
152
|
+
"""One string out and one string in, for an edit whose blast radius is the call (RK1263).
|
|
153
|
+
|
|
154
|
+
`amend` takes the whole body, so correcting one stale citation meant copying the section's
|
|
155
|
+
table, fence and block quote out of the file, retyping the clause and passing all of it
|
|
156
|
+
back — eight times over, on a corpus of eight sections whose prose was right except for one
|
|
157
|
+
reference each. Every round trip can drop a pipe from a row or a backtick from a fence, and
|
|
158
|
+
nothing checks: a body is prose to this tool, so a mangled fence validates exactly like a
|
|
159
|
+
clean one.
|
|
160
|
+
|
|
161
|
+
A pair and not two arguments threaded separately, because :meth:`applied` is the rule — one
|
|
162
|
+
occurrence or a refusal — and a caller holding the halves apart is a caller who could apply
|
|
163
|
+
it without asking. The whole-body form stays for a real rewrite.
|
|
164
|
+
"""
|
|
165
|
+
|
|
166
|
+
old: str
|
|
167
|
+
new: str
|
|
168
|
+
|
|
169
|
+
def applied(self, prose: str, where: str) -> str:
|
|
170
|
+
"""The prose with its one occurrence replaced, or :class:`NotOneOccurrence`.
|
|
171
|
+
|
|
172
|
+
**Matched with the wrapping collapsed** (RK1312). A section is written to a prose
|
|
173
|
+
width, so any sentence longer than that width is stored with a newline and some
|
|
174
|
+
indentation inside it — and a caller quoting the sentence, which is how the prose reads
|
|
175
|
+
to anybody looking at it, was refused for text the section plainly carries. Observed in
|
|
176
|
+
pportal, 2026-08-22, twice in one task: both fragments were full sentences copied from
|
|
177
|
+
`section show`, which prints the prose as it is, so the command the refusal recommends
|
|
178
|
+
is the command that produces the text the refusal rejected.
|
|
179
|
+
|
|
180
|
+
It also made this flag weaker than it looks. A short fragment is what fits inside one
|
|
181
|
+
stored line, and a short fragment is what *occurs exactly once* refuses — the two rules
|
|
182
|
+
pushed in opposite directions and the caller landed between them.
|
|
183
|
+
|
|
184
|
+
The stored form does not change: what is found is a **span** of the prose as it sits,
|
|
185
|
+
and the replacement is spliced into it, so a table or a fence the needle happens to
|
|
186
|
+
neighbour is untouched. A run of whitespace holding two newlines is a paragraph break
|
|
187
|
+
and stays a barrier — a needle is a sentence, and one that matched across a blank line
|
|
188
|
+
would be reaching into prose the caller was not looking at.
|
|
189
|
+
"""
|
|
190
|
+
spans = _spans(prose, self.old)
|
|
191
|
+
if len(spans) != 1:
|
|
192
|
+
raise NotOneOccurrence(self.old, len(spans), where)
|
|
193
|
+
first, last = spans[0]
|
|
194
|
+
return prose[:first] + self.new + prose[last:]
|
|
195
|
+
|
|
196
|
+
|
|
197
|
+
#: What a paragraph break becomes while a needle is looked for (RK1312) — a character no
|
|
198
|
+
#: needle can carry, so a fragment holding a single space cannot match across a blank line.
|
|
199
|
+
_PARAGRAPH = "\x00"
|
|
200
|
+
|
|
201
|
+
#: A run of whitespace, which is what wrapping is made of. Matched whole so the run's own
|
|
202
|
+
#: newline count decides whether it is a space or a barrier.
|
|
203
|
+
_WHITESPACE = re.compile(r"\s+")
|
|
204
|
+
|
|
205
|
+
|
|
206
|
+
def _flattened(prose: str) -> tuple[str, tuple[int, ...]]:
|
|
207
|
+
"""The prose with its wrapping collapsed, and where each character came from (RK1312).
|
|
208
|
+
|
|
209
|
+
The index list is the whole point: a needle is found in the flat text and replaced in the
|
|
210
|
+
stored one, so nothing about how the file holds its paragraphs has to change. Every flat
|
|
211
|
+
character maps to the offset it started at, and the list carries one entry past the end so
|
|
212
|
+
a match ending on the last character has a stop to name.
|
|
213
|
+
"""
|
|
214
|
+
out: list[str] = []
|
|
215
|
+
at: list[int] = []
|
|
216
|
+
index = 0
|
|
217
|
+
for part in _WHITESPACE.split(prose):
|
|
218
|
+
run = _WHITESPACE.match(prose, index + len(part))
|
|
219
|
+
out.append(part)
|
|
220
|
+
at.extend(range(index, index + len(part)))
|
|
221
|
+
index += len(part)
|
|
222
|
+
if run is None:
|
|
223
|
+
continue
|
|
224
|
+
# Two newlines is a paragraph break and one is a wrap: the first stays a barrier and
|
|
225
|
+
# the second becomes the space the reader sees.
|
|
226
|
+
out.append(_PARAGRAPH if run.group().count("\n") > 1 else " ")
|
|
227
|
+
at.append(index)
|
|
228
|
+
index = run.end()
|
|
229
|
+
at.append(len(prose))
|
|
230
|
+
return "".join(out), tuple(at)
|
|
231
|
+
|
|
232
|
+
|
|
233
|
+
def _spans(prose: str, needle: str) -> list[tuple[int, int]]:
|
|
234
|
+
"""Every span of ``prose`` whose collapsed text reads as ``needle`` (RK1312).
|
|
235
|
+
|
|
236
|
+
Empty for a needle that is only whitespace, which is not a fragment of anything: the
|
|
237
|
+
caller passed nothing to look for, and reporting the prose's every gap as a match would
|
|
238
|
+
turn a mistyped argument into an ambiguity refusal about the wrong thing.
|
|
239
|
+
"""
|
|
240
|
+
wanted = " ".join(needle.split())
|
|
241
|
+
if not wanted:
|
|
242
|
+
return []
|
|
243
|
+
flat, at = _flattened(prose)
|
|
244
|
+
out: list[tuple[int, int]] = []
|
|
245
|
+
start = flat.find(wanted)
|
|
246
|
+
while start != -1:
|
|
247
|
+
out.append((at[start], at[start + len(wanted) - 1] + 1))
|
|
248
|
+
start = flat.find(wanted, start + 1)
|
|
249
|
+
return out
|
|
250
|
+
|
|
251
|
+
|
|
252
|
+
class SectionExists(ValueError):
|
|
253
|
+
"""One anchor, one section: two would make the pointer ambiguous.
|
|
254
|
+
|
|
255
|
+
Asked of **the project's declarations and not the file's** (RK302). This checked the
|
|
256
|
+
document it was writing into and nobody else, so on a project declaring two prose roles
|
|
257
|
+
the same four `section add` calls into each file all succeeded and printed their line
|
|
258
|
+
counts — and `lint` then reported four `section.ambiguous` findings whose own message is
|
|
259
|
+
the argument for refusing here: one anchor names one section, so no pointer resolves and
|
|
260
|
+
every verb that reads one refuses. The write path was building a state its own gate calls
|
|
261
|
+
unresolvable, out of which `drop` was the only exit — and that deletes prose somebody
|
|
262
|
+
wrote.
|
|
263
|
+
|
|
264
|
+
No `--force`, deliberately. RK297's measurement is that the doubled anchors in both live
|
|
265
|
+
corpora were made by hand rather than by this verb, so a door that never opens is the
|
|
266
|
+
cheaper answer than one whose only correct use is a hand edit the guard already denies.
|
|
267
|
+
"""
|
|
268
|
+
|
|
269
|
+
def __init__(
|
|
270
|
+
self, anchor: str, where: str, lineno: int, *, elsewhere: bool = False
|
|
271
|
+
) -> None:
|
|
272
|
+
self.anchor = anchor
|
|
273
|
+
self.lineno = lineno
|
|
274
|
+
self.elsewhere = elsewhere
|
|
275
|
+
span = (
|
|
276
|
+
"an anchor names one section across every prose file this project declares"
|
|
277
|
+
if elsewhere
|
|
278
|
+
else "an anchor names one section"
|
|
279
|
+
)
|
|
280
|
+
super().__init__(
|
|
281
|
+
f"§{anchor} is already at {where}:{lineno}: {span}, "
|
|
282
|
+
f"and a pointer that resolves to two resolves to neither"
|
|
283
|
+
)
|
|
284
|
+
|
|
285
|
+
|
|
286
|
+
class SectionOccupied(ValueError):
|
|
287
|
+
"""A drop whose subtree holds prose another open line owns (RK78).
|
|
288
|
+
|
|
289
|
+
The counterpart, one level down, of the multi-owner check `ship` already makes about the
|
|
290
|
+
anchor it was given: that one asks who else points *here*, and this one asks who else
|
|
291
|
+
points at anything **nested** here. Both refuse rather than repair, because a drop is
|
|
292
|
+
contiguous — a subtree with a stranger in the middle has no partial deletion that is not
|
|
293
|
+
a decision about someone else's prose — and the author's remedy is to lift the section
|
|
294
|
+
out or to ship the line that claims it.
|
|
295
|
+
|
|
296
|
+
Refused *before* the write and not reported after, which is the whole difference this
|
|
297
|
+
closes: `lint` named the damage as two `ref.unresolved` immediately afterwards, by which
|
|
298
|
+
point the only remedy was `git checkout` on the file, discarding the part of the ship
|
|
299
|
+
that was correct along with the part that was not (L1, one verb along from `add`).
|
|
300
|
+
"""
|
|
301
|
+
|
|
302
|
+
def __init__(
|
|
303
|
+
self, anchor: str, occupied: Sequence[tuple[str, Sequence[str]]], where: str = ""
|
|
304
|
+
) -> None:
|
|
305
|
+
self.anchor = anchor
|
|
306
|
+
self.occupied = tuple((child, tuple(owners)) for child, owners in occupied)
|
|
307
|
+
named = ", ".join(
|
|
308
|
+
f"§{child} ({', '.join(owners)})" for child, owners in self.occupied
|
|
309
|
+
)
|
|
310
|
+
file = f" in {where}" if where else ""
|
|
311
|
+
super().__init__(
|
|
312
|
+
f"§{anchor}{file} nests {len(self.occupied)} section(s) another open line "
|
|
313
|
+
f"points at: {named} — dropping it deletes prose this transaction never "
|
|
314
|
+
f"named, and leaves those pointers resolving to nothing"
|
|
315
|
+
)
|
|
316
|
+
|
|
317
|
+
|
|
318
|
+
class SectionClaimed(ValueError):
|
|
319
|
+
"""A drop of the section an open line points at, refused before the write (RK112).
|
|
320
|
+
|
|
321
|
+
:class:`SectionOccupied` one level up, and the level that was missing: that one asks who
|
|
322
|
+
points at anything *nested* under the anchor, `ship` asks who else points *at* it — and
|
|
323
|
+
`section drop`, the verb whose whole job is removing one section, asked neither. Found by
|
|
324
|
+
using the tool: `section drop VIII.11` succeeded on a section stale by every other
|
|
325
|
+
measure, and the next `lint` reported `ref.unresolved` for an open line that owned it.
|
|
326
|
+
|
|
327
|
+
A refusal and not a report, because the drop was one of seven in a triage pass: `lint`
|
|
328
|
+
names the damage afterwards, and by then `git checkout` discards the six that were right
|
|
329
|
+
along with the one that was not. `ship` still drops its own task's section — that caller
|
|
330
|
+
passes ``leaving``, so the claim that is the reason for the drop is not one of these.
|
|
331
|
+
"""
|
|
332
|
+
|
|
333
|
+
def __init__(
|
|
334
|
+
self, anchor: str, owners: Sequence[str], where: str = "", *, recorded: bool = False
|
|
335
|
+
) -> None:
|
|
336
|
+
self.anchor = anchor
|
|
337
|
+
self.owners = tuple(owners)
|
|
338
|
+
file = f" in {where}" if where else ""
|
|
339
|
+
# The decisions file claims by id and has no door out (RK1361), so the two remedies
|
|
340
|
+
# below are both wrong there: there is no pointer to repoint and no line to ship. What
|
|
341
|
+
# a body written badly takes is `section amend`, which is the same escape the entry
|
|
342
|
+
# one line above it has.
|
|
343
|
+
if recorded:
|
|
344
|
+
super().__init__(
|
|
345
|
+
f"§{anchor}{file} is the body of {', '.join(self.owners)}, a decision this "
|
|
346
|
+
f"file still records — nothing here is ever deleted, a superseded entry "
|
|
347
|
+
f"included: `section amend {anchor} --role decisions --body -` is how prose "
|
|
348
|
+
f"that came out wrong is corrected"
|
|
349
|
+
)
|
|
350
|
+
return
|
|
351
|
+
super().__init__(
|
|
352
|
+
f"§{anchor}{file} is pointed at by {', '.join(self.owners)} — dropping it "
|
|
353
|
+
f"leaves {'that pointer' if len(self.owners) == 1 else 'those pointers'} "
|
|
354
|
+
f"resolving to nothing: repoint the line, or ship the one that claims it"
|
|
355
|
+
)
|
|
356
|
+
|
|
357
|
+
|
|
358
|
+
class AnchorClaimed(ValueError):
|
|
359
|
+
"""A drop whose anchor an open line's pointer descends from, by name (RK169).
|
|
360
|
+
|
|
361
|
+
:class:`SectionOccupied` decides ownership by walking the *sections* inside the span, and
|
|
362
|
+
a section is a **heading**. Measured adopting Turing: `section drop XIV` was accepted and
|
|
363
|
+
took `§XIV.8` with it, and under that heading sat
|
|
364
|
+
`- **XIV.8.7 — ship Cloud default config as a GLOBAL seed ZIP (T373).**` — the design of
|
|
365
|
+
an open task, deleted without a word, because a bullet is not a section and the subtree
|
|
366
|
+
looked unowned.
|
|
367
|
+
|
|
368
|
+
Two things were true there and only one of them was a defect. That T373's pointer did not
|
|
369
|
+
resolve is Turing's, and `lint` says so. That the verb whose whole job is *the orphan*
|
|
370
|
+
deleted a live design **because** the pointer was already broken is this tool's: the
|
|
371
|
+
finding made the content invisible to the guard that would have protected it, so two
|
|
372
|
+
reports compounded into data loss.
|
|
373
|
+
|
|
374
|
+
So the guard reads the **name** and not the shape. An address under the anchor is claimed
|
|
375
|
+
prose whether the corpus writes it as a heading, as a bullet or as a table row — which
|
|
376
|
+
needs no parsing of the prose at all, and is exactly the check the adoption script had to
|
|
377
|
+
write by hand before it could proceed safely.
|
|
378
|
+
"""
|
|
379
|
+
|
|
380
|
+
def __init__(
|
|
381
|
+
self, anchor: str, claimed: Sequence[tuple[str, Sequence[str]]], where: str = ""
|
|
382
|
+
) -> None:
|
|
383
|
+
self.anchor = anchor
|
|
384
|
+
self.claimed = tuple((ref, tuple(owners)) for ref, owners in claimed)
|
|
385
|
+
named = ", ".join(f"§{ref} ({', '.join(owners)})" for ref, owners in self.claimed)
|
|
386
|
+
file = f" in {where}" if where else ""
|
|
387
|
+
super().__init__(
|
|
388
|
+
f"§{anchor}{file} is above {named}, which an open line points at: a drop takes "
|
|
389
|
+
f"everything under the anchor, and an address under it is claimed prose whether "
|
|
390
|
+
f"this file writes it as a heading or as a bullet — repoint the line, or ship "
|
|
391
|
+
f"the one that claims it"
|
|
392
|
+
)
|
|
393
|
+
|
|
394
|
+
|
|
395
|
+
class AnchorRetired(ValueError):
|
|
396
|
+
"""An outline address a heading already used, and a ship deleted (RK247).
|
|
397
|
+
|
|
398
|
+
:class:`SectionExists` for the anchors that are no longer there. Under an outline the
|
|
399
|
+
caller names the anchor, and the only list they are ever shown is of the sections that
|
|
400
|
+
**exist** — so after a fully-shipped family "the next one" looks like `.1`, and writing
|
|
401
|
+
it silently re-points every ledger entry whose prose cites that address at prose about
|
|
402
|
+
something else. `as_ledger` keeps no pointer, so nothing in the files says the address
|
|
403
|
+
was ever spent; the diff does, which is where this reads it.
|
|
404
|
+
|
|
405
|
+
The same rule ids have had since RK4, one file over: retired-never-reused. The remedy is
|
|
406
|
+
an address nobody used, so the refusal carries the derived one rather than sending the
|
|
407
|
+
author to grep a ledger — which is how the safe number was found before this existed.
|
|
408
|
+
"""
|
|
409
|
+
|
|
410
|
+
def __init__(self, anchor: str, written_in: str, free: str = "", where: str = "") -> None:
|
|
411
|
+
self.anchor = anchor
|
|
412
|
+
self.written_in = written_in
|
|
413
|
+
#: The derived free child, or empty for a **top-level** address: what follows
|
|
414
|
+
#: `XXXVII` is somebody's numbering — roman, lettered, a phase — and inventing the
|
|
415
|
+
#: next one would be this tool choosing an author's outline (L4).
|
|
416
|
+
self.free = free
|
|
417
|
+
file = f" in {where}" if where else ""
|
|
418
|
+
commit = f" ({written_in[:7]})" if written_in else ""
|
|
419
|
+
remedy = (
|
|
420
|
+
f"§{free} is the next one nothing ever used"
|
|
421
|
+
if free
|
|
422
|
+
else "name an address this file has never declared"
|
|
423
|
+
)
|
|
424
|
+
super().__init__(
|
|
425
|
+
f"§{anchor}{file} was declared before{commit} and its section is gone: the "
|
|
426
|
+
f"entries whose prose cites it are still there, and reusing the address makes "
|
|
427
|
+
f"them cite this — {remedy}"
|
|
428
|
+
)
|
|
429
|
+
|
|
430
|
+
|
|
431
|
+
class UnknownParent(ValueError):
|
|
432
|
+
"""An anchor states its place, and this file declares nothing it extends (RK45).
|
|
433
|
+
|
|
434
|
+
The counterpart of :class:`~roadkeep.kernel.document.UnknownBlock`, for prose that belongs to
|
|
435
|
+
no task: a §0.4 appended after the last block reads as that block's rationale, which is
|
|
436
|
+
the mistake this module already refuses one case over. So everything under the top level
|
|
437
|
+
is derived, and a **nested** anchor whose parent is missing stays a refusal — that is a
|
|
438
|
+
typo in an address, and appending it would file somebody's paragraph under a design it
|
|
439
|
+
does not extend.
|
|
440
|
+
|
|
441
|
+
What is no longer refused is the **top level itself** (RK166). "A heading that is merely
|
|
442
|
+
missing is a heading they can add" was this class's own argument, and the guard denies
|
|
443
|
+
exactly that edit — RK141's deadlock, one file over: `block add` skips a prose file
|
|
444
|
+
organised by an outline rather than by blocks, so a newly declared block's first section
|
|
445
|
+
was reachable by nothing at all. A top-level anchor under an outline is now placed after
|
|
446
|
+
the last top-level section, which is the same derivation this file already makes one
|
|
447
|
+
level down.
|
|
448
|
+
|
|
449
|
+
``opens`` is every ancestor of this anchor the file does not declare, outermost first
|
|
450
|
+
(RK1207). Until it existed every clause of this sentence was true and none of them was a
|
|
451
|
+
verb: the listing of what the file declares came closest, and on a file whose outline has
|
|
452
|
+
not started that listing is the word `none`. The write that makes room is the **same
|
|
453
|
+
command one address up**, which is why it reads as a wall rather than a step — a caller
|
|
454
|
+
told `section add` refuses naturally looks for a different verb, and there is none.
|
|
455
|
+
|
|
456
|
+
Derived rather than described, so what is left for the author is the title, which is
|
|
457
|
+
editorial and L4's to leave alone. A chain, because `§I.1.2` on an empty outline is two
|
|
458
|
+
calls before this one: reporting the first alone is the staircase RK1198 took out of the
|
|
459
|
+
door one file over, and this is the same staircase met by a caller who arrived directly —
|
|
460
|
+
writing a design before the line, which is the order an outline invites.
|
|
461
|
+
|
|
462
|
+
``role`` rides with it for RK197's reason: a project whose only prose file is the strategy
|
|
463
|
+
one would be handed `section add`'s default, which is a remedy that cannot run.
|
|
464
|
+
"""
|
|
465
|
+
|
|
466
|
+
def __init__(
|
|
467
|
+
self,
|
|
468
|
+
anchor: str,
|
|
469
|
+
declared: Sequence[str],
|
|
470
|
+
where: str = "",
|
|
471
|
+
*,
|
|
472
|
+
opens: Sequence[str] = (),
|
|
473
|
+
role: str = "",
|
|
474
|
+
) -> None:
|
|
475
|
+
from roadkeep.provenance import invocation # noqa: PLC0415 - RK260
|
|
476
|
+
|
|
477
|
+
self.anchor = anchor
|
|
478
|
+
self.declared = tuple(declared)
|
|
479
|
+
self.opens = tuple(opens)
|
|
480
|
+
known = ", ".join(f"§{a}" for a in self.declared) or "none"
|
|
481
|
+
file = f"{where} " if where else ""
|
|
482
|
+
named = "" if role in ("", "improvements") else f" --role {role}"
|
|
483
|
+
steps = ", then ".join(
|
|
484
|
+
f"`{invocation()} section add {one} --title …{named}`" for one in self.opens
|
|
485
|
+
)
|
|
486
|
+
# Silent where nothing derives one, which is a one-segment anchor under the id scheme:
|
|
487
|
+
# there this refusal means the id names no open line, and a `section add` above it
|
|
488
|
+
# would be an address invented out of a task number.
|
|
489
|
+
opening = f" — {steps} opens what it extends" if self.opens else ""
|
|
490
|
+
super().__init__(
|
|
491
|
+
f"no section §{anchor} extends ({file}declares: {known}): an anchor states "
|
|
492
|
+
f"its own place, and appending files the prose under the last block{opening}"
|
|
493
|
+
)
|
|
494
|
+
|
|
495
|
+
|
|
496
|
+
class SameAnchor(ValueError):
|
|
497
|
+
"""A move to the address the section already carries (RK377)."""
|
|
498
|
+
|
|
499
|
+
def __init__(self, anchor: str) -> None:
|
|
500
|
+
self.anchor = anchor
|
|
501
|
+
super().__init__(
|
|
502
|
+
f"§{anchor} already is that address: a move that changes nothing would still "
|
|
503
|
+
f"rewrite the file, and an untouched file with a moved mtime reads as an edit"
|
|
504
|
+
)
|
|
505
|
+
|
|
506
|
+
|
|
507
|
+
class AnchorIsId(ValueError):
|
|
508
|
+
"""A re-address under `ref_scheme = "id"`, where the address is the task's (RK377).
|
|
509
|
+
|
|
510
|
+
The one scheme this verb has nothing to do. There the anchor *is* the id, so a section
|
|
511
|
+
whose address moved and whose line did not is a section its own task no longer points at
|
|
512
|
+
— and moving both is :func:`~roadkeep.renumbering.renumber`, which does it in one
|
|
513
|
+
transaction with every dep. The other reason to be here is a doubled anchor, and under
|
|
514
|
+
this scheme that is two files holding one task's design rather than two addresses
|
|
515
|
+
colliding: one of them is the design and the other is a copy, which is `section drop`.
|
|
516
|
+
"""
|
|
517
|
+
|
|
518
|
+
def __init__(self, anchor: str, where: str = "") -> None:
|
|
519
|
+
self.anchor = anchor
|
|
520
|
+
file = f" in {where}" if where else ""
|
|
521
|
+
super().__init__(
|
|
522
|
+
f"§{anchor}{file} is addressed by its task's id, so the address is not this "
|
|
523
|
+
f"verb's to move: `renumber {anchor} --to <id>` moves the line, the heading, the "
|
|
524
|
+
f"subtree and every dep together, and a second file holding the same design is "
|
|
525
|
+
f"`section drop`"
|
|
526
|
+
)
|
|
527
|
+
|
|
528
|
+
|
|
529
|
+
class NotASibling(ValueError):
|
|
530
|
+
"""A destination under a different parent, which is a relocation and not a move (RK377).
|
|
531
|
+
|
|
532
|
+
The bound that keeps this verb honest about what it does. A section's **place** is derived
|
|
533
|
+
from its address (RK45), and this write changes the address without moving a line of prose
|
|
534
|
+
— which is right while the parent is the same, and wrong the moment it is not: a `§XIV.5`
|
|
535
|
+
re-addressed in place still sits inside `§I`'s subtree, where :func:`_span` ends it, `drop`
|
|
536
|
+
takes it and `_extends` reads the file's shape past it. So the two would disagree, and the
|
|
537
|
+
disagreement is invisible until a deletion acts on it.
|
|
538
|
+
|
|
539
|
+
Refused rather than relocated, because relocating carries prose the caller never named:
|
|
540
|
+
a subtree holds sections other lines point at (:class:`SectionOccupied`'s whole argument),
|
|
541
|
+
and re-levelling one to fit a new depth is a rewrite of headings nobody asked about.
|
|
542
|
+
"""
|
|
543
|
+
|
|
544
|
+
def __init__(self, anchor: str, to: str, parent: str, free: str = "") -> None:
|
|
545
|
+
self.anchor = anchor
|
|
546
|
+
self.to = to
|
|
547
|
+
self.parent = parent
|
|
548
|
+
#: The free address under that parent, where history could be read for it (RK1378).
|
|
549
|
+
#: This refusal named the family and stopped, and a caller has no way to the address
|
|
550
|
+
#: but a guess — which is the last step every other complete door here already takes:
|
|
551
|
+
#: `add --ref` on a block whose prose has not started carries the whole path with the
|
|
552
|
+
#: arguments filled in. Empty where `anchors` could not be read, and then the sentence
|
|
553
|
+
#: names *that* read rather than claiming an address it does not have.
|
|
554
|
+
self.free = free
|
|
555
|
+
under = f"under §{parent}" if parent else "at the top level"
|
|
556
|
+
from roadkeep.provenance import invocation # noqa: PLC0415 - RK260
|
|
557
|
+
|
|
558
|
+
# The address, or the read that gives it. Never a composed `section move`: the address
|
|
559
|
+
# is derivable and which sibling a heading should become is the caller's, so what is
|
|
560
|
+
# offered is the free anchor and not a call somebody would run without reading.
|
|
561
|
+
says = (
|
|
562
|
+
f", where §{free} is free"
|
|
563
|
+
if free
|
|
564
|
+
else f" (`{invocation()} anchors --family {parent}` says which is free)"
|
|
565
|
+
if parent
|
|
566
|
+
else ""
|
|
567
|
+
)
|
|
568
|
+
super().__init__(
|
|
569
|
+
f"§{anchor} cannot move to §{to}: this write changes the address and not the "
|
|
570
|
+
f"place, so a destination under another parent leaves the heading inside the "
|
|
571
|
+
f"subtree it no longer names — name an address {under}{says}"
|
|
572
|
+
)
|
|
573
|
+
|
|
574
|
+
|
|
575
|
+
def _free_under(config: Config, family: str) -> str:
|
|
576
|
+
"""The next address nothing under ``family`` ever used, or `""` (RK1378).
|
|
577
|
+
|
|
578
|
+
:func:`~roadkeep.history.next_child` and never a count of the headings on file, for that
|
|
579
|
+
function's own reason: an address a ship retired is spent, and a family reopened over one
|
|
580
|
+
is the collision `section add` refuses by name. So this reads history, and where history
|
|
581
|
+
cannot be read — a checkout with no git, a repository this process cannot run — it answers
|
|
582
|
+
nothing and the refusal names the command instead of stating an address it did not get.
|
|
583
|
+
"""
|
|
584
|
+
if not family:
|
|
585
|
+
return ""
|
|
586
|
+
from roadkeep.history import HistoryUnavailable, anchors, next_child # noqa: PLC0415 - RK260
|
|
587
|
+
|
|
588
|
+
try:
|
|
589
|
+
return next_child(anchors(config), family)
|
|
590
|
+
except (HistoryUnavailable, OSError):
|
|
591
|
+
return ""
|
|
592
|
+
|
|
593
|
+
|
|
594
|
+
@dataclass(frozen=True, slots=True)
|
|
595
|
+
class Section:
|
|
596
|
+
"""A heading, its prose, and the lines it occupies. ``last`` includes the blank."""
|
|
597
|
+
|
|
598
|
+
anchor: str
|
|
599
|
+
title: str
|
|
600
|
+
level: int
|
|
601
|
+
first: int # 1-based, as an editor counts
|
|
602
|
+
last: int
|
|
603
|
+
body: str = ""
|
|
604
|
+
#: This section's **own** prose, where :attr:`body` is a subtree (RK287). None where the
|
|
605
|
+
#: two are the same string — :func:`anchored`'s reading — and set by :func:`find`, which
|
|
606
|
+
#: is the constructor that returns the children with the parent. The **text** and not a
|
|
607
|
+
#: count of it since RK1112: `amend` replaces exactly this, so a reader that could state
|
|
608
|
+
#: its size but not print it left `show` unable to offer what the write takes.
|
|
609
|
+
own: str | None = None
|
|
610
|
+
|
|
611
|
+
@property
|
|
612
|
+
def words(self) -> int:
|
|
613
|
+
"""What the budget charges this section: its argument, not its whole text (RK136)."""
|
|
614
|
+
return words(self.body)
|
|
615
|
+
|
|
616
|
+
@property
|
|
617
|
+
def prose(self) -> str:
|
|
618
|
+
"""This section's own text, subsections excluded — what `amend --body` replaces."""
|
|
619
|
+
return self.body if self.own is None else self.own
|
|
620
|
+
|
|
621
|
+
@property
|
|
622
|
+
def own_words(self) -> int:
|
|
623
|
+
"""The same count over this section's own prose, with no subsection in it (RK287).
|
|
624
|
+
|
|
625
|
+
Equal to :attr:`words` for a leaf, and the whole point for a parent: a container
|
|
626
|
+
like this repository's `§0` has no paragraph of its own, so :attr:`words` measures
|
|
627
|
+
the file's shape rather than anyone's argument.
|
|
628
|
+
"""
|
|
629
|
+
return words(self.prose)
|
|
630
|
+
|
|
631
|
+
@property
|
|
632
|
+
def nests(self) -> bool:
|
|
633
|
+
"""Whether the two counts differ, which is when printing only one of them misleads.
|
|
634
|
+
|
|
635
|
+
The rule RK245 and RK265 each found at another door: a verb printing a number beside
|
|
636
|
+
a limit is claiming the two are the same number. Here they are two numbers, and which
|
|
637
|
+
one the gate charges depends on whether a line points at this anchor (RK215) — so
|
|
638
|
+
both are said, and neither is presented as the verdict.
|
|
639
|
+
"""
|
|
640
|
+
return self.own_words != self.words
|
|
641
|
+
|
|
642
|
+
def names(self, pattern: re.Pattern[str]) -> tuple[str, ...]:
|
|
643
|
+
"""The task ids this heading names, in order (RK61).
|
|
644
|
+
|
|
645
|
+
Whose section this is, for a project that numbers by hand: under
|
|
646
|
+
`ref_scheme = "outline"` the anchor is `XVI.12` and the id lives in the title —
|
|
647
|
+
`§XVI.12 A design (SH123)` — so ownership is unreadable from the anchor alone, and
|
|
648
|
+
both `section.orphan` and `section.stale` fired for nobody in the two live corpora.
|
|
649
|
+
|
|
650
|
+
The **title** and never the body: a section quoting another id is discussing it, not
|
|
651
|
+
owning it, and reading the prose would report every cross-reference in the file.
|
|
652
|
+
"""
|
|
653
|
+
return tuple(dict.fromkeys(pattern.findall(self.title)))
|
|
654
|
+
|
|
655
|
+
def __str__(self) -> str:
|
|
656
|
+
return f"§{self.anchor} ({self.first}-{self.last})"
|
|
657
|
+
|
|
658
|
+
def counted(self, limit: int) -> str:
|
|
659
|
+
"""This section's size as every verb that prints it says it (RK287).
|
|
660
|
+
|
|
661
|
+
Both figures where they differ, and the limit beside them either way. A bare `310 words`
|
|
662
|
+
on a section whose own prose is 48 invites cutting prose that was never over — and the
|
|
663
|
+
limit is what makes the number act on something, which is the whole of RK283 one door
|
|
664
|
+
over. Which of the two the gate charges depends on whether a line points at the anchor
|
|
665
|
+
(RK215), so neither is spelled as the verdict and the refusal states its own.
|
|
666
|
+
|
|
667
|
+
Here since RK1170: three verb files and a view all print this, and a helper in
|
|
668
|
+
`rendering.py` was the fifth place a fact about a section was spelled.
|
|
669
|
+
"""
|
|
670
|
+
if not self.nests:
|
|
671
|
+
return f"{self.words} words (limit {limit})"
|
|
672
|
+
return f"{self.own_words} words, {self.words} with subsections (limit {limit})"
|
|
673
|
+
|
|
674
|
+
def payload(self, where: str) -> dict[str, object]:
|
|
675
|
+
"""This section as data, at every door that publishes one (RK1170).
|
|
676
|
+
|
|
677
|
+
`where` is passed and not stored, for `counted`'s reason: the file a section was read
|
|
678
|
+
from is a fact about the project, and an `add` publishes the same record about a file it
|
|
679
|
+
is writing into.
|
|
680
|
+
"""
|
|
681
|
+
return {
|
|
682
|
+
"anchor": self.anchor,
|
|
683
|
+
"title": self.title,
|
|
684
|
+
"level": self.level,
|
|
685
|
+
"file": where,
|
|
686
|
+
"first": self.first,
|
|
687
|
+
"last": self.last,
|
|
688
|
+
"words": self.words,
|
|
689
|
+
# The figure the limit is measured on, beside the one a reader pays (RK287). `words`
|
|
690
|
+
# keeps its meaning — the subtree, which is what a drop takes — and this is the
|
|
691
|
+
# section's own argument, which for a container is none of it.
|
|
692
|
+
"own_words": self.own_words,
|
|
693
|
+
}
|
|
694
|
+
|
|
695
|
+
|
|
696
|
+
def local(schema: Schema, anchor: str) -> str | None:
|
|
697
|
+
"""This address as the *file* writes it, or None where it is another role's (RK340).
|
|
698
|
+
|
|
699
|
+
The one seam between the project's namespace and a document's own. A role that declares
|
|
700
|
+
`[refs] <role> = "S"` answers `S:I` and never a bare `I`; a role that declares none
|
|
701
|
+
answers the bare address and never a prefixed one — which is what makes the two
|
|
702
|
+
addresses rather than one anchor read twice, and it is symmetric on purpose: a project
|
|
703
|
+
that prefixed only one of its files would otherwise have `S:I` and `I` both resolving in
|
|
704
|
+
strategy, and the collision back one file over.
|
|
705
|
+
|
|
706
|
+
None and not a raise, because every caller already has an answer for an anchor this file
|
|
707
|
+
does not hold: `find` returns nothing, `declaring` leaves the role out, and the gate says
|
|
708
|
+
`ref.unresolved` naming the files it looked in.
|
|
709
|
+
"""
|
|
710
|
+
prefix, bare = split_ref(anchor)
|
|
711
|
+
return bare if prefix == schema.ref_prefix else None
|
|
712
|
+
|
|
713
|
+
|
|
714
|
+
def qualified(schema: Schema, anchor: str) -> str:
|
|
715
|
+
"""This file's address as a *pointer* writes it — `I.2` → `S:I.2` (RK340).
|
|
716
|
+
|
|
717
|
+
The inverse of :func:`local`, and the one writer of the prefixed spelling for the reason
|
|
718
|
+
:func:`anchor_text` is the one writer of the heading's: an address rendered by hand at a
|
|
719
|
+
call site is how the two ends of a pointer come to disagree.
|
|
720
|
+
"""
|
|
721
|
+
return f"{schema.ref_prefix}{REF_SEPARATOR}{anchor}" if schema.ref_prefix else anchor
|
|
722
|
+
|
|
723
|
+
|
|
724
|
+
def find(document: Document, anchor: str) -> Section | None:
|
|
725
|
+
"""The section this anchor names, or None. Subsections belong to it, not after it."""
|
|
726
|
+
span = _span(document, anchor)
|
|
727
|
+
if span is None:
|
|
728
|
+
return None
|
|
729
|
+
_, end, heading = span
|
|
730
|
+
body = "".join(document.lines[heading.lineno : end]).strip("\r\n")
|
|
731
|
+
# Both spans off the one heading (RK287). The subtree is what a drop deletes and what a
|
|
732
|
+
# reader pays; the prose is what the argument costs — and a Section that carried only the
|
|
733
|
+
# first left every printer stating a figure no limit is measured against.
|
|
734
|
+
own = "".join(document.lines[heading.lineno : document.prose_end(heading)]).strip("\r\n")
|
|
735
|
+
return Section(
|
|
736
|
+
anchor=anchor,
|
|
737
|
+
title=_title_of(heading.text, document.schema),
|
|
738
|
+
level=heading.level,
|
|
739
|
+
first=heading.lineno,
|
|
740
|
+
last=end,
|
|
741
|
+
body=body,
|
|
742
|
+
own=own,
|
|
743
|
+
)
|
|
744
|
+
|
|
745
|
+
|
|
746
|
+
def declaring(config: Config, anchor: str) -> tuple[str, ...]:
|
|
747
|
+
"""Which declared prose roles actually hold this anchor, in `[files]` order (RK196).
|
|
748
|
+
|
|
749
|
+
The resolution no verb may assume: `ship` deletes the design and `defer` reports where it
|
|
750
|
+
stayed, and both were written naming `improvements` outright — the reason a project
|
|
751
|
+
declaring `strategy` alone was told its own section is missing while the section sat
|
|
752
|
+
there. `show` asks the same question with one distinction more, a declared file that is
|
|
753
|
+
not on disk yet being an answer of its own, so it keeps its own reading and this stays
|
|
754
|
+
the shape a writer needs.
|
|
755
|
+
|
|
756
|
+
A **tuple**, because the answers to none and to two are not this function's: an absence
|
|
757
|
+
is where the design would go for one caller and a refusal for another, and two roles
|
|
758
|
+
declaring one anchor is the `ref.ambiguous` the gate reports and no verb resolves by
|
|
759
|
+
picking. Only which files say so is the same question everywhere.
|
|
760
|
+
"""
|
|
761
|
+
return tuple(
|
|
762
|
+
role
|
|
763
|
+
for role in PROSE_ROLES
|
|
764
|
+
if config.has(role)
|
|
765
|
+
and config.path(role).is_file()
|
|
766
|
+
and find(config.document(role), anchor) is not None
|
|
767
|
+
)
|
|
768
|
+
|
|
769
|
+
|
|
770
|
+
def bind(document: Document, section: Section, task_id: str) -> Document:
|
|
771
|
+
"""Append a task's id to a heading that names none, changing nothing else (RK452).
|
|
772
|
+
|
|
773
|
+
The binding written from the **pointer's** end. :func:`_bound` renders it into a title a
|
|
774
|
+
caller passed; this one is for the write where nobody passed a title at all — `add --ref`
|
|
775
|
+
on an outline anchor whose design was written first — so what it may touch is the id and
|
|
776
|
+
not one byte more.
|
|
777
|
+
|
|
778
|
+
Which is why it appends to the heading's own line rather than re-rendering it. RK388
|
|
779
|
+
settled that a `--title` amend restyles on purpose: the caller asked for the heading to
|
|
780
|
+
change, so the canonical spelling is right there. Nobody asked here, and re-rendering
|
|
781
|
+
would take the `§` an author wrote and whatever spacing that heading had (RK44) as the
|
|
782
|
+
silent price of a binding — the exact restyle RK388 removed from the body-only path.
|
|
783
|
+
|
|
784
|
+
The caller has already established that the heading names no task: this appends, and
|
|
785
|
+
deciding whether it should is :func:`owners`'.
|
|
786
|
+
"""
|
|
787
|
+
heading = next(
|
|
788
|
+
(one for one in document.headings if anchor_of(one.text, document.schema) == section.anchor),
|
|
789
|
+
None,
|
|
790
|
+
)
|
|
791
|
+
if heading is None: # pragma: no cover - the caller found this section a moment ago
|
|
792
|
+
return document
|
|
793
|
+
line = document.lines[heading.lineno - 1]
|
|
794
|
+
body = line.rstrip("\r\n")
|
|
795
|
+
return document.replace_line(heading.lineno - 1, f"{body.rstrip()} ({task_id})")
|
|
796
|
+
|
|
797
|
+
|
|
798
|
+
def owners(section: Section, ids: re.Pattern[str]) -> tuple[str, ...]:
|
|
799
|
+
"""The tasks this section belongs to, whichever scheme addresses it (RK61).
|
|
800
|
+
|
|
801
|
+
Under `ref_scheme = "id"` the anchor *is* the id. Under an outline the anchor is
|
|
802
|
+
`XVI.12` and the id is in the heading — `§XVI.12 A design (SH123)` — which is why both
|
|
803
|
+
checks below fired for nobody in the two live corpora until this read it.
|
|
804
|
+
|
|
805
|
+
So **naming a task in a heading is the claim to be its rationale**, with no exemption for
|
|
806
|
+
where the section sits. The first attempt made one — "a task's section is under a `Block X`
|
|
807
|
+
heading", read off this repository's own file — and it disabled the check on the corpus it
|
|
808
|
+
was written for: Shio files its rationale under `## VIII. The Agent Gateway (Block H)`,
|
|
809
|
+
which is an outline heading, so all 146 of its sections looked unowned. A section that
|
|
810
|
+
means to cite a task rather than belong to it says so in its prose, which this never reads.
|
|
811
|
+
|
|
812
|
+
A **sub-anchor under the id scheme is derived from an id** and belongs to it (RK114):
|
|
813
|
+
`§RK34.1` is `RK34`'s subsection and the anchor says so, segment by segment — the same
|
|
814
|
+
reading :func:`~roadkeep.sections._extends` gives it one module over. Matching the whole
|
|
815
|
+
anchor cannot see that, which exempted every sub-anchor from both checks and let a
|
|
816
|
+
`renumber RK1 --to RK9` leave `§RK1.1` behind on a file `lint` then called clean. Only
|
|
817
|
+
the first segment is asked, so `§0.1` and `§XVI.12` still reach the heading below: prose
|
|
818
|
+
belonging to no task stays nobody's orphan.
|
|
819
|
+
|
|
820
|
+
Here rather than inside `lint` because the **writer needs the same answer** (RK236): a
|
|
821
|
+
departure deletes the section it owns, and ownership read one way by the gate and another
|
|
822
|
+
by the drop is how Turing's standing GEO memo lost two subsections to a retirement.
|
|
823
|
+
"""
|
|
824
|
+
if ids.match(section.anchor):
|
|
825
|
+
return (section.anchor,)
|
|
826
|
+
root = section.anchor.split(".")[0]
|
|
827
|
+
if root != section.anchor and ids.match(root):
|
|
828
|
+
return (root,)
|
|
829
|
+
return section.names(re.compile(rf"\b{ids.pattern.strip('^$')}\b"))
|
|
830
|
+
|
|
831
|
+
|
|
832
|
+
def citing(
|
|
833
|
+
document: Document, anchors: Sequence[str], *, ignore: Sequence[str] = ()
|
|
834
|
+
) -> tuple[tuple[str, str], ...]:
|
|
835
|
+
"""Which sections' prose cites which of ``anchors`` — the other end of a pointer (RK206).
|
|
836
|
+
|
|
837
|
+
`_pointers` resolves the ref a *task line* carries, and nothing resolves the references
|
|
838
|
+
a section's prose makes, so `ship` deletes a design that another design cites and every
|
|
839
|
+
check answers clean: `ref.unresolved` reads task lines, `section.orphan` reads what
|
|
840
|
+
points at a section, and citing prose is neither. Measured on claude-tray: `§XVIII.9`
|
|
841
|
+
cited `§XVIII.12`, `ship` took §XVIII.12 with the line that owned it, and `lint`
|
|
842
|
+
reported `clean` for a day.
|
|
843
|
+
|
|
844
|
+
**Membership and not shape.** The caller names the anchors that are going away, so an
|
|
845
|
+
anchor-shaped token is interesting only when it is one of them — which removes RK15's
|
|
846
|
+
quotation problem from the pattern entirely: `§RK15` in a sentence about pointers is
|
|
847
|
+
text nobody is deleting. What is left of that problem is prose that quotes a reference
|
|
848
|
+
to a section this very transaction removes, and three exclusions answer it, each
|
|
849
|
+
measured across four trees rather than guessed:
|
|
850
|
+
|
|
851
|
+
* a **fenced block** is quoted or generated (the reading :data:`_FENCES` already makes);
|
|
852
|
+
* an **inline code span**, which is how this repository writes a pointer it is talking
|
|
853
|
+
about — 3 of them in `docs/IMPROVEMENTS.md`;
|
|
854
|
+
* a **blockquote**, which is 18 of Shio's anchor-shaped tokens and 19 of Turing's, all
|
|
855
|
+
of them quoted material;
|
|
856
|
+
* a token directly after a **`→`**, which is a task line reproduced as an example — 3 in
|
|
857
|
+
claude-tray, and the shape `Schema.render` writes.
|
|
858
|
+
|
|
859
|
+
``ignore`` is what the transaction is deleting: a section citing its own subtree, or a
|
|
860
|
+
sibling going in the same drop, is prose that leaves with the reference.
|
|
861
|
+
|
|
862
|
+
Membership is the **filter** and no longer the scan (RK1106): :func:`references` reads the
|
|
863
|
+
prose once and this selects from it, because the gate asks the same file the opposite
|
|
864
|
+
question — which citations resolve to nothing — and two scanners would give a project two
|
|
865
|
+
counts of its own dead citations.
|
|
866
|
+
"""
|
|
867
|
+
wanted = {anchor for anchor in anchors if anchor}
|
|
868
|
+
if not wanted:
|
|
869
|
+
return ()
|
|
870
|
+
skipped = set(ignore)
|
|
871
|
+
return tuple(
|
|
872
|
+
(cited.anchor, cited.by)
|
|
873
|
+
for cited in references(document)
|
|
874
|
+
if cited.anchor in wanted and cited.by not in skipped
|
|
875
|
+
)
|
|
876
|
+
|
|
877
|
+
|
|
878
|
+
@dataclass(frozen=True, slots=True)
|
|
879
|
+
class Cite:
|
|
880
|
+
"""One `§<anchor>` a section's prose makes, and where it is written (RK1106).
|
|
881
|
+
|
|
882
|
+
The record the fourth relation resolves — a citation, beside the dep, the pointer and the
|
|
883
|
+
queue entry :mod:`roadkeep.referring` already declares. It carries the place because the
|
|
884
|
+
gate reports `file:line`, and the citing section because that is who has to make the edit:
|
|
885
|
+
a dangling reference is a defect in the prose that makes it, not in the section it names.
|
|
886
|
+
"""
|
|
887
|
+
|
|
888
|
+
#: What is cited, as the prose spells it — namespaced (`S:I.2`) where the pointer is.
|
|
889
|
+
anchor: str
|
|
890
|
+
#: The anchor of the section whose prose cites it.
|
|
891
|
+
by: str
|
|
892
|
+
#: 1-based, as an editor counts.
|
|
893
|
+
lineno: int
|
|
894
|
+
|
|
895
|
+
|
|
896
|
+
#: An anchor-shaped token after a `§`, in either scheme (RK1106). Deliberately looser than
|
|
897
|
+
#: :data:`~roadkeep.kernel.schema.OUTLINE_ANCHOR_RE` and than any id shape, because the two
|
|
898
|
+
#: questions are different: a *reference* is anything an author wrote as one, and whether the
|
|
899
|
+
#: token is a well-formed address of this project is what resolving it answers. A pattern that
|
|
900
|
+
#: only matched valid anchors would read a typo as prose and report nothing about it, which is
|
|
901
|
+
#: the citation this exists to find.
|
|
902
|
+
#:
|
|
903
|
+
#: **Atomic**, which is the whole of RK1111: the address is taken whole or not at all. The
|
|
904
|
+
#: earlier boundary `(?![\w.])` refused a sentence-final `.` — punctuation the address does not
|
|
905
|
+
#: own — and the engine answered by *shortening the match* until the lookahead passed, so the
|
|
906
|
+
#: prose `§S:V.` was read as a citation of `§S` and `§I.2.` as no citation at all. Both silent:
|
|
907
|
+
#: one reported a live anchor as dangling in every project that namespaces a second file, the
|
|
908
|
+
#: other reported nothing over a dead one. What follows a whole address may be anything that is
|
|
909
|
+
#: not a word character — a period, a comma, a paren, a fence — and a token that runs on into
|
|
910
|
+
#: `\w` after the scheme's own separators is not an address in either scheme.
|
|
911
|
+
_CITED_RE = re.compile(r"§((?>[A-Za-z0-9]+(?::[A-Za-z0-9]+)?(?:\.[A-Za-z0-9]+)*))(?!\w)")
|
|
912
|
+
|
|
913
|
+
|
|
914
|
+
def cited_in(body: str) -> tuple[str, ...]:
|
|
915
|
+
"""Every anchor a body cites, in order and without repeats (RK1227).
|
|
916
|
+
|
|
917
|
+
:func:`references` asks this of a **document**, for the gate; this asks it of a paragraph
|
|
918
|
+
somebody is about to write, for the door. Both go through :func:`_argument` and
|
|
919
|
+
:data:`_CITED_RE`, so what counts as a citation — the four exclusions, each measured
|
|
920
|
+
across four trees — is decided once and the two cannot come to disagree about a quotation.
|
|
921
|
+
|
|
922
|
+
Distinct here and every occurrence there, which is the same split :func:`citing` makes:
|
|
923
|
+
the gate reports a place per dead citation because each is an edit, and a refusal is about
|
|
924
|
+
*which addresses do not resolve*, where naming one twice is noise.
|
|
925
|
+
"""
|
|
926
|
+
return tuple(dict.fromkeys(_CITED_RE.findall(_argument(body))))
|
|
927
|
+
|
|
928
|
+
|
|
929
|
+
def references(document: Document) -> tuple[Cite, ...]:
|
|
930
|
+
"""Every citation this file's prose makes, unresolved (RK1106).
|
|
931
|
+
|
|
932
|
+
One scan, two questions. :func:`citing` asks which of *these* anchors are cited, at the
|
|
933
|
+
moment a transaction deletes them; the gate asks which citations name nothing at all. The
|
|
934
|
+
reading of what counts as a citation — :func:`_argument`'s four exclusions, each measured
|
|
935
|
+
across four trees — belongs to neither of them and is made once, here.
|
|
936
|
+
|
|
937
|
+
Every occurrence and not the distinct set: two dead citations on two lines are two edits,
|
|
938
|
+
and a reader handed one of them fixes the file halfway. `citing` de-duplicates on its own
|
|
939
|
+
side, where the answer is *which* section to warn about and saying it twice is noise.
|
|
940
|
+
"""
|
|
941
|
+
out: list[Cite] = []
|
|
942
|
+
for section in anchored(document):
|
|
943
|
+
# Off the document's own lines and **not** off `Section.body`, which is stripped of the
|
|
944
|
+
# blank after the heading — measured: that shift reported claude-tray's §I.7 two lines
|
|
945
|
+
# early, onto prose carrying no citation at all. `_argument` blanks a quotation in
|
|
946
|
+
# place rather than dropping it, so this slice and its output stay index-for-index.
|
|
947
|
+
raw = "".join(document.lines[section.first : section.last])
|
|
948
|
+
for offset, line in enumerate(_argument(raw).splitlines()):
|
|
949
|
+
for found in _CITED_RE.findall(line):
|
|
950
|
+
out.append(
|
|
951
|
+
Cite(anchor=found, by=section.anchor, lineno=section.first + 1 + offset)
|
|
952
|
+
)
|
|
953
|
+
return tuple(out)
|
|
954
|
+
|
|
955
|
+
|
|
956
|
+
#: A mark that **carries its file**: the outward citation (RK1181). Prose in a governed file
|
|
957
|
+
#: legitimately argues from another document's numbered sections — a spec, an RFC, a standard —
|
|
958
|
+
#: and those documents number themselves with the same mark, so `§3.1` written plainly is read as
|
|
959
|
+
#: a pointer into this file and refused as dangling. Met twice in one session in a project whose
|
|
960
|
+
#: specs live beside the governed files; both times the repair was to strike the mark and spell
|
|
961
|
+
#: the reference in words, which is a worse sentence, and both times the turn was already spent.
|
|
962
|
+
#:
|
|
963
|
+
#: Not a suppression flag, which is what this must never become: an author who can silence the
|
|
964
|
+
#: check silences it for the typo too, and a bare mark naming nothing is usually exactly that —
|
|
965
|
+
#: the case the rule was built for, which it goes on catching. What earns the silence is the
|
|
966
|
+
#: **file**, named the way a Markdown link already names one. This repository's own `agents.md`
|
|
967
|
+
#: writes `[§0.3](docs/IMPROVEMENTS.md)`, so the form is the corpus's and not an invention.
|
|
968
|
+
#:
|
|
969
|
+
#: A fragment (`[§I.2](#i-2)`) is *this* document and buys nothing: a target that names no path
|
|
970
|
+
#: would be the suppression flag with an extra two characters.
|
|
971
|
+
_OUTWARD_RE = re.compile(r"\[(§[^\]]*)\]\(\s*(?!#)([^)\s]+)[^)]*\)")
|
|
972
|
+
|
|
973
|
+
|
|
974
|
+
def _argument(body: str) -> str:
|
|
975
|
+
"""A section's prose with every quotation blanked out, so a reference in one is not one.
|
|
976
|
+
|
|
977
|
+
Blanked rather than dropped: the lines keep their positions, which is what lets a caller
|
|
978
|
+
report a place without the two readings of the file disagreeing about which line it is.
|
|
979
|
+
|
|
980
|
+
The **outward citation** is blanked the same way (RK1181): a mark inside a Markdown link
|
|
981
|
+
whose target is a path is a reference into that document, which this file's outline cannot
|
|
982
|
+
answer for and the gate has nothing to resolve it against.
|
|
983
|
+
"""
|
|
984
|
+
out: list[str] = []
|
|
985
|
+
fence: str | None = None
|
|
986
|
+
#: Whether an **indented** code block is open, and what the last line was — the two the
|
|
987
|
+
#: fourth exclusion needs (RK1151). A block and not a line, because four spaces mean two
|
|
988
|
+
#: different things: sample output where a blank line came before, and a list item's own
|
|
989
|
+
#: continuation where a bullet did. A rule reading indentation alone would blank the
|
|
990
|
+
#: second, and a citation nobody scans is worse than one falsely reported — this is the
|
|
991
|
+
#: backstop that is supposed to notice.
|
|
992
|
+
indented = False
|
|
993
|
+
previous = ""
|
|
994
|
+
for raw in body.splitlines():
|
|
995
|
+
# The link text first and in place, so an address inside one is gone before any other
|
|
996
|
+
# rule reads the line and every column after it still lines up.
|
|
997
|
+
line = _OUTWARD_RE.sub(lambda m: " " * len(m[0]), raw)
|
|
998
|
+
stripped = line.strip()
|
|
999
|
+
if fence is not None:
|
|
1000
|
+
if stripped.startswith(fence):
|
|
1001
|
+
fence = None
|
|
1002
|
+
out.append("")
|
|
1003
|
+
previous = stripped
|
|
1004
|
+
continue
|
|
1005
|
+
if stripped.startswith(_FENCES):
|
|
1006
|
+
fence = stripped[:3]
|
|
1007
|
+
out.append("")
|
|
1008
|
+
previous = stripped
|
|
1009
|
+
continue
|
|
1010
|
+
if stripped.startswith(">"):
|
|
1011
|
+
out.append("")
|
|
1012
|
+
previous = stripped
|
|
1013
|
+
continue
|
|
1014
|
+
if indented and stripped and not line.startswith(_INDENT):
|
|
1015
|
+
# Closed by the first line indented less, which is Markdown's own rule — a blank
|
|
1016
|
+
# line inside an indented block does not end it.
|
|
1017
|
+
indented = False
|
|
1018
|
+
elif not indented and stripped and line.startswith(_INDENT) and not previous:
|
|
1019
|
+
# Opened only after a blank line: indented code cannot interrupt a paragraph, and
|
|
1020
|
+
# under a bullet the blank is the item's, so `_BULLET` is what tells them apart.
|
|
1021
|
+
indented = not _BULLET.match(_before(out))
|
|
1022
|
+
if indented:
|
|
1023
|
+
out.append("")
|
|
1024
|
+
previous = stripped
|
|
1025
|
+
continue
|
|
1026
|
+
out.append(_QUOTED.sub(lambda m: " " * len(m.group()), line))
|
|
1027
|
+
previous = stripped
|
|
1028
|
+
return "\n".join(out)
|
|
1029
|
+
|
|
1030
|
+
|
|
1031
|
+
#: Four spaces: Markdown's other code block, and the width a list item's continuation shares
|
|
1032
|
+
#: with it. A tab is deliberately not read as one — no line in any of the four trees measured
|
|
1033
|
+
#: for RK1151 opens a block that way, and treating one as code would blank a Markdown table.
|
|
1034
|
+
_INDENT = " "
|
|
1035
|
+
#: What opens a list item, whose continuation is prose (RK1151). Ordered and unordered both:
|
|
1036
|
+
#: a numbered argument's second paragraph is indented exactly like sample output.
|
|
1037
|
+
_BULLET = re.compile(r"^\s*(?:[-*+]|\d+[.)])\s")
|
|
1038
|
+
|
|
1039
|
+
|
|
1040
|
+
def _before(rendered: list[str]) -> str:
|
|
1041
|
+
"""The last line that said anything, for deciding what an indent belongs to.
|
|
1042
|
+
|
|
1043
|
+
Read off what is already rendered rather than off the source, so a blockquote or a fence —
|
|
1044
|
+
both blanked above — cannot be mistaken for the bullet an indent hangs from.
|
|
1045
|
+
"""
|
|
1046
|
+
for line in reversed(rendered):
|
|
1047
|
+
if line.strip():
|
|
1048
|
+
return line
|
|
1049
|
+
return ""
|
|
1050
|
+
|
|
1051
|
+
|
|
1052
|
+
#: What is being talked about rather than said: a code span, and a pointer reproduced whole.
|
|
1053
|
+
_QUOTED = re.compile(r"`[^`]*`|→\s*§[\w.]+")
|
|
1054
|
+
|
|
1055
|
+
|
|
1056
|
+
def unanchored(document: Document) -> tuple[Heading, ...]:
|
|
1057
|
+
"""Headings that are where a section would be, and carry no anchor (RK281).
|
|
1058
|
+
|
|
1059
|
+
:func:`anchored` finds `§<anchor>` headings, and the sigil is **this tool's convention**
|
|
1060
|
+
rather than Markdown's — so `adopt --sections` read a rationale file correctly exactly
|
|
1061
|
+
when that file had already adopted the format, which is the one case nobody needs an
|
|
1062
|
+
estimate for. A real `DESIGN.md` answered 0 sections and 0 would change: RK98's zero,
|
|
1063
|
+
one command over from where RK279 closed it.
|
|
1064
|
+
|
|
1065
|
+
A second reader over the same headings and never a second grammar, the line RK98 drew
|
|
1066
|
+
when it counted table rows without parsing cells. Nothing here composes an anchor — an
|
|
1067
|
+
address the file does not have is not this tool's to invent (L4) — so what comes back is
|
|
1068
|
+
the heading, and the estimate takes a count and a word measure off its span.
|
|
1069
|
+
|
|
1070
|
+
Two exclusions, both because they are frame rather than work: a level-1 heading is the
|
|
1071
|
+
document's title and not a section in it, and a heading with no prose of its own is a
|
|
1072
|
+
container — `## Block B` above a list of subsections describes them, and counting it
|
|
1073
|
+
would measure the file's shape rather than anyone's paragraph, which is the distinction
|
|
1074
|
+
:func:`anchored` already makes for `§0`.
|
|
1075
|
+
"""
|
|
1076
|
+
out: list[Heading] = []
|
|
1077
|
+
for heading in document.headings:
|
|
1078
|
+
if heading.level < 2 or anchor_of(heading.text, document.schema) is not None:
|
|
1079
|
+
continue
|
|
1080
|
+
end = document.prose_end(heading)
|
|
1081
|
+
if any(not blank(line) for line in document.lines[heading.lineno : end]):
|
|
1082
|
+
out.append(heading)
|
|
1083
|
+
return tuple(out)
|
|
1084
|
+
|
|
1085
|
+
|
|
1086
|
+
def anchored(document: Document) -> tuple[Section, ...]:
|
|
1087
|
+
"""Every `§<anchor>` section in file order, each carrying only its **own** prose.
|
|
1088
|
+
|
|
1089
|
+
The gate (RK15) needs the set and not one lookup: a pointer resolves in one
|
|
1090
|
+
direction, and an orphan — a section nothing points at — is only visible from the
|
|
1091
|
+
other. **Own** prose, because :func:`find` deliberately returns the subtree (`drop`
|
|
1092
|
+
has to delete it whole, and a task's rationale is charged for the subsection it
|
|
1093
|
+
grew), and a container like this repository's `§0` has no prose of its own at all —
|
|
1094
|
+
counting its children against it would measure the file's shape rather than anyone's
|
|
1095
|
+
paragraph. Which of the two the budget uses is the gate's decision, not this one's.
|
|
1096
|
+
|
|
1097
|
+
Each anchor is the **project's** address and not the heading's (RK340): a heading writes
|
|
1098
|
+
`I` and a pointer writes `S:I` where `[refs]` gives this role a namespace, and the gate
|
|
1099
|
+
reads these sections into one index across both prose files — which is the index the
|
|
1100
|
+
collision was in. So the qualification happens here, once, and every reader downstream
|
|
1101
|
+
compares addresses that are comparable. :func:`anchor_text` is the way back.
|
|
1102
|
+
"""
|
|
1103
|
+
out: list[Section] = []
|
|
1104
|
+
for heading in document.headings:
|
|
1105
|
+
anchor = anchor_of(heading.text, document.schema)
|
|
1106
|
+
if anchor is None:
|
|
1107
|
+
continue
|
|
1108
|
+
end = document.prose_end(heading)
|
|
1109
|
+
out.append(
|
|
1110
|
+
Section(
|
|
1111
|
+
anchor=qualified(document.schema, anchor),
|
|
1112
|
+
title=_title_of(heading.text, document.schema),
|
|
1113
|
+
level=heading.level,
|
|
1114
|
+
first=heading.lineno,
|
|
1115
|
+
last=end,
|
|
1116
|
+
body="".join(document.lines[heading.lineno : end]).strip("\r\n"),
|
|
1117
|
+
)
|
|
1118
|
+
)
|
|
1119
|
+
return tuple(out)
|
|
1120
|
+
|
|
1121
|
+
|
|
1122
|
+
def nested(document: Document, anchor: str) -> tuple[Section, ...]:
|
|
1123
|
+
"""The anchored sections a drop of this one would take with it, in file order (RK78).
|
|
1124
|
+
|
|
1125
|
+
What :func:`find` returns as one body, enumerated as the headings it actually is — the
|
|
1126
|
+
honest report of a deletion whose size is not the size of the section that was named.
|
|
1127
|
+
Empty for an anchor this file does not declare, because "nothing is nested under a
|
|
1128
|
+
section that is not there" is the same answer as the refusal :func:`drop` raises, and
|
|
1129
|
+
a reader asking this question is not the one to tell about the missing heading.
|
|
1130
|
+
"""
|
|
1131
|
+
span = _span(document, anchor)
|
|
1132
|
+
if span is None:
|
|
1133
|
+
return ()
|
|
1134
|
+
_, end, heading = span
|
|
1135
|
+
return tuple(
|
|
1136
|
+
section for section in anchored(document) if heading.lineno < section.first <= end
|
|
1137
|
+
)
|
|
1138
|
+
|
|
1139
|
+
|
|
1140
|
+
def descending(document: Document, anchor: str) -> tuple[Section, ...]:
|
|
1141
|
+
"""The nested sections that are this address's own numbering — `I.2.1`, never `XIV.8`.
|
|
1142
|
+
|
|
1143
|
+
:func:`nested` bounded by the **name** rather than by the span, which is the difference
|
|
1144
|
+
that matters to anything re-addressing a subtree: a `§I.2.1` travels with `§I.2` because
|
|
1145
|
+
the address says it is part of it, and a `§XIV.8` somebody filed inside that subtree keeps
|
|
1146
|
+
the address of the thing that owns it. Segment by segment and never as a string prefix,
|
|
1147
|
+
the care :func:`_extends` takes at the other end of the same question — `§0.1` is not
|
|
1148
|
+
above `§0.10`.
|
|
1149
|
+
|
|
1150
|
+
Public and here rather than beside either caller (RK377): `renumber` asks it of an id's
|
|
1151
|
+
subtree and `move` of an outline address's, and two readings of "which anchors are this
|
|
1152
|
+
one's own" is how one door renames half a subtree the other would have renamed whole.
|
|
1153
|
+
"""
|
|
1154
|
+
segments = anchor.split(".")
|
|
1155
|
+
return tuple(
|
|
1156
|
+
child
|
|
1157
|
+
for child in nested(document, anchor)
|
|
1158
|
+
if child.anchor.split(".")[: len(segments)] == segments
|
|
1159
|
+
)
|
|
1160
|
+
|
|
1161
|
+
|
|
1162
|
+
def pointers(config: Config, *, leaving: str = "") -> dict[str, tuple[str, ...]]:
|
|
1163
|
+
"""Which open lines point at which anchor — the claims a drop may not orphan (RK78).
|
|
1164
|
+
|
|
1165
|
+
Read from the roadmap and never from the prose file, because a claim is a pointer and a
|
|
1166
|
+
pointer only exists on a task line: a heading nested under another is that other's prose
|
|
1167
|
+
until a line names it, and this is the one place that says which ones do. `leaving` is
|
|
1168
|
+
the line being shipped, whose own claim is the reason the drop is happening.
|
|
1169
|
+
|
|
1170
|
+
And from the decisions file, whose records claim by **id** rather than by pointer
|
|
1171
|
+
(RK1361). Nothing in that file is ever deleted — the one departure is `supersede`, which
|
|
1172
|
+
keeps both entries — so the body of a decision that stands is a body no verb removes, and
|
|
1173
|
+
`section drop` was the one door that did not know it. Read here rather than refused at
|
|
1174
|
+
that door, because `drop`, `ship` and the gate all ask this one function and a check in
|
|
1175
|
+
one of them would be a rule the other two disagreed with. A superseded entry claims its
|
|
1176
|
+
own too: what a replacement was needed against is the body it replaced.
|
|
1177
|
+
"""
|
|
1178
|
+
out: dict[str, list[str]] = {}
|
|
1179
|
+
for entry in config.document("roadmap").entries:
|
|
1180
|
+
if entry.task.ref and entry.task.id != leaving:
|
|
1181
|
+
out.setdefault(entry.task.ref, []).append(entry.task.id)
|
|
1182
|
+
if config.has("decisions") and config.path("decisions").is_file():
|
|
1183
|
+
for entry in config.document("decisions").entries:
|
|
1184
|
+
anchor = entry.task.ref or entry.task.id
|
|
1185
|
+
if entry.task.id not in out.setdefault(anchor, []):
|
|
1186
|
+
out[anchor].append(entry.task.id)
|
|
1187
|
+
return {anchor: tuple(ids) for anchor, ids in out.items() if ids}
|
|
1188
|
+
|
|
1189
|
+
|
|
1190
|
+
@dataclass(frozen=True, slots=True)
|
|
1191
|
+
class Shown:
|
|
1192
|
+
"""One section as `show` answers it: the extent asked for, and what carries the rest.
|
|
1193
|
+
|
|
1194
|
+
The result that read had none of (RK1170). The door looked the address up two ways, chose
|
|
1195
|
+
an extent off a flag, gathered the nested anchors and composed both registers from the
|
|
1196
|
+
four — so neither reading had a result to derive from, which is that task's whole subject.
|
|
1197
|
+
"""
|
|
1198
|
+
|
|
1199
|
+
section: Section
|
|
1200
|
+
#: The extent the caller asked for (RK1112): the subtree is what a reader of the design
|
|
1201
|
+
#: wants and the own prose is what `amend` replaces, so the flag says which question this
|
|
1202
|
+
#: call is. `body` stays the key either way — it is the body of what was asked for, and
|
|
1203
|
+
#: `own_words` beside it already states that the two extents differ.
|
|
1204
|
+
body: str
|
|
1205
|
+
#: The anchors nested under it, named rather than left as a blank line (RK1118): a
|
|
1206
|
+
#: container has no prose of its own, so `--own` on this repository's `§0` answered with a
|
|
1207
|
+
#: heading and nothing — correct, and indistinguishable from a command that printed nothing.
|
|
1208
|
+
nested: tuple[str, ...]
|
|
1209
|
+
#: The file, as this project spells it.
|
|
1210
|
+
where: str
|
|
1211
|
+
|
|
1212
|
+
@classmethod
|
|
1213
|
+
def of(cls, config: Config, role: str, address: str, own: bool) -> Shown:
|
|
1214
|
+
"""Look the address up the way every reader here does, or raise `NoSuchSection`.
|
|
1215
|
+
|
|
1216
|
+
**An anchor first and a heading text second** (RK1107): an anchor is the project's
|
|
1217
|
+
chosen name and wins, and the fall-through is what makes `section show 'Table of
|
|
1218
|
+
contents'` an answer instead of a refusal.
|
|
1219
|
+
"""
|
|
1220
|
+
document = config.document(role)
|
|
1221
|
+
where = config.relative(config.path(role))
|
|
1222
|
+
section = find(document, address)
|
|
1223
|
+
if section is None:
|
|
1224
|
+
heading = titled(document, address)
|
|
1225
|
+
section = (
|
|
1226
|
+
None
|
|
1227
|
+
if heading is None
|
|
1228
|
+
else next(
|
|
1229
|
+
(one for one in untitled(document) if one.first == heading.lineno),
|
|
1230
|
+
None,
|
|
1231
|
+
)
|
|
1232
|
+
)
|
|
1233
|
+
if section is None:
|
|
1234
|
+
raise NoSuchSection(address, where, titled_too=True)
|
|
1235
|
+
return cls(
|
|
1236
|
+
section=section,
|
|
1237
|
+
body=section.prose if own else section.body,
|
|
1238
|
+
nested=tuple(one.anchor for one in nested(document, section.anchor)),
|
|
1239
|
+
where=where,
|
|
1240
|
+
)
|
|
1241
|
+
|
|
1242
|
+
def stated(self, schema: Schema) -> str:
|
|
1243
|
+
"""The heading, a blank line, and the prose — which is what an `amend --body-file` is
|
|
1244
|
+
composed from, so nothing else may reach stdout."""
|
|
1245
|
+
return chr(10).join([heading_of(schema, self.section), "", self.body])
|
|
1246
|
+
|
|
1247
|
+
def silence(self) -> list[str]:
|
|
1248
|
+
"""Which of the two empty answers this is, for **stderr** (RK1118).
|
|
1249
|
+
|
|
1250
|
+
Two, because a section with no text has two shapes and one of them is a defect: a
|
|
1251
|
+
**container** is the ordinary structure of a rationale file — this repository's `§0`,
|
|
1252
|
+
and every `## <Block>` heading over subsections — while a leaf with nothing in it is
|
|
1253
|
+
what the gate calls `body.empty`. Saying "no prose" to both would send half the readers
|
|
1254
|
+
to `lint` and the other half looking for a bug in the reader.
|
|
1255
|
+
|
|
1256
|
+
On stderr and not beside the prose, for the reason above: this output is piped into a
|
|
1257
|
+
file, and a sentence on stdout would end up in it.
|
|
1258
|
+
"""
|
|
1259
|
+
if self.body.strip():
|
|
1260
|
+
return []
|
|
1261
|
+
if self.nested:
|
|
1262
|
+
named = ", ".join("§" + one for one in self.nested)
|
|
1263
|
+
return [
|
|
1264
|
+
f"roadkeep: §{self.section.anchor} carries no prose of its own — its "
|
|
1265
|
+
f"{self.section.words} words are {named}, each amended by its own anchor"
|
|
1266
|
+
]
|
|
1267
|
+
return [
|
|
1268
|
+
f"roadkeep: §{self.section.anchor} is empty in {self.where}: a heading with no "
|
|
1269
|
+
f"paragraph under it, which `lint` reports as `body.empty`"
|
|
1270
|
+
]
|
|
1271
|
+
|
|
1272
|
+
def payload(self) -> dict[str, object]:
|
|
1273
|
+
"""The same answer as data, with the nested anchors under their own key — so the
|
|
1274
|
+
payload and the report cannot disagree about why a body came back empty."""
|
|
1275
|
+
return {
|
|
1276
|
+
**self.section.payload(self.where),
|
|
1277
|
+
"body": self.body,
|
|
1278
|
+
"nested": list(self.nested),
|
|
1279
|
+
}
|
|
1280
|
+
|
|
1281
|
+
|
|
1282
|
+
@dataclass(frozen=True, slots=True)
|
|
1283
|
+
class Carrier:
|
|
1284
|
+
"""One section whose own prose holds a sought string, and how often (RK1310)."""
|
|
1285
|
+
|
|
1286
|
+
anchor: str
|
|
1287
|
+
role: str
|
|
1288
|
+
where: str
|
|
1289
|
+
line: int
|
|
1290
|
+
title: str
|
|
1291
|
+
count: int
|
|
1292
|
+
|
|
1293
|
+
def payload(self) -> dict[str, object]:
|
|
1294
|
+
return {
|
|
1295
|
+
"anchor": self.anchor,
|
|
1296
|
+
"role": self.role,
|
|
1297
|
+
"file": self.where,
|
|
1298
|
+
"line": self.line,
|
|
1299
|
+
"title": self.title,
|
|
1300
|
+
"count": self.count,
|
|
1301
|
+
}
|
|
1302
|
+
|
|
1303
|
+
|
|
1304
|
+
@dataclass(frozen=True, slots=True)
|
|
1305
|
+
class Found:
|
|
1306
|
+
"""Which anchors carry a sentence — the lookup that had no verb (RK1310).
|
|
1307
|
+
|
|
1308
|
+
Observed in pportal, 2026-08-22. A line count stated in the prose had gone stale, and the
|
|
1309
|
+
correction is `section amend <anchor> --replace <old> --with <new>`. The anchor was wrong:
|
|
1310
|
+
the claim sized one C file, the task about that file was one id, and the sentence sizing it
|
|
1311
|
+
lived in the section of a *different* id — the one covering three such files together.
|
|
1312
|
+
|
|
1313
|
+
The refusal was a good one. It said the text does not occur in the section named and
|
|
1314
|
+
pointed at `section show`, which is the right next command. What it could not say is the
|
|
1315
|
+
thing the caller wanted: that the text occurs once, and where. Every fact needed to say so
|
|
1316
|
+
had just been read.
|
|
1317
|
+
|
|
1318
|
+
The general shape is that `amend` and `section amend` are addressed **by anchor** and the
|
|
1319
|
+
caller often knows only the text. A pointer resolves an id to a section; nothing resolved a
|
|
1320
|
+
sentence to one, so the loop was show, read, guess again — and for an agent caller each
|
|
1321
|
+
turn of it is a file printed into a context window.
|
|
1322
|
+
|
|
1323
|
+
Reads and writes nothing, which is why it can be cheap: the count per anchor is the whole
|
|
1324
|
+
answer, because it is what decides whether `--replace` will be accepted and by which one.
|
|
1325
|
+
Never the prose — that is `section show`'s, and printing it here would be the file back.
|
|
1326
|
+
"""
|
|
1327
|
+
|
|
1328
|
+
text: str
|
|
1329
|
+
carriers: tuple[Carrier, ...]
|
|
1330
|
+
#: Every prose role looked in, so an empty answer is about the files and not about a filter
|
|
1331
|
+
#: the caller forgot they passed.
|
|
1332
|
+
roles: tuple[str, ...]
|
|
1333
|
+
|
|
1334
|
+
@property
|
|
1335
|
+
def total(self) -> int:
|
|
1336
|
+
return sum(one.count for one in self.carriers)
|
|
1337
|
+
|
|
1338
|
+
@property
|
|
1339
|
+
def replaceable(self) -> tuple[Carrier, ...]:
|
|
1340
|
+
"""The anchors a `--replace` would be accepted by: exactly one occurrence (RK1263)."""
|
|
1341
|
+
return tuple(one for one in self.carriers if one.count == 1)
|
|
1342
|
+
|
|
1343
|
+
def stated(self) -> str:
|
|
1344
|
+
if not self.carriers:
|
|
1345
|
+
return (
|
|
1346
|
+
f"no section in {', '.join(self.roles)} carries {self.text!r} — "
|
|
1347
|
+
f"`section show <anchor>` prints the prose as it is"
|
|
1348
|
+
)
|
|
1349
|
+
rows = [
|
|
1350
|
+
f"{self.total} occurrence(s) of {self.text!r} in "
|
|
1351
|
+
f"{len(self.carriers)} section(s), in file order"
|
|
1352
|
+
]
|
|
1353
|
+
for one in self.carriers:
|
|
1354
|
+
# The count beside the address, because it is the half that decides the next call:
|
|
1355
|
+
# one is what `--replace` accepts, and more is the ambiguity it refuses.
|
|
1356
|
+
takes = " (`--replace` takes it)" if one.count == 1 else ""
|
|
1357
|
+
rows.append(
|
|
1358
|
+
f" §{one.anchor} {one.count}x {one.where}:{one.line} "
|
|
1359
|
+
f"{one.title}{takes}"
|
|
1360
|
+
)
|
|
1361
|
+
return "\n".join(rows)
|
|
1362
|
+
|
|
1363
|
+
def payload(self, served: str = "") -> dict[str, object]:
|
|
1364
|
+
from roadkeep.remedying import BLANK, Door # noqa: PLC0415 - RK260
|
|
1365
|
+
|
|
1366
|
+
return {
|
|
1367
|
+
"text": self.text,
|
|
1368
|
+
"roles": list(self.roles),
|
|
1369
|
+
"total": self.total,
|
|
1370
|
+
"carriers": [one.payload() for one in self.carriers],
|
|
1371
|
+
# The subset a narrow edit can address, named rather than left to be derived: the
|
|
1372
|
+
# rule is `Substitution`'s and a consumer recomputing it would be its second reader.
|
|
1373
|
+
"replaceable": [one.anchor for one in self.replaceable],
|
|
1374
|
+
# And the door the empty sentence names (RK1307's rule, which caught this verb the
|
|
1375
|
+
# day it was written): nothing carries the string, so the next read is the prose as
|
|
1376
|
+
# the file spells it — and the caller reaching this through the served answer is
|
|
1377
|
+
# the one the whole verb is for. Absent where something was found, there being
|
|
1378
|
+
# nothing to look up.
|
|
1379
|
+
**(
|
|
1380
|
+
{}
|
|
1381
|
+
if self.carriers
|
|
1382
|
+
else {
|
|
1383
|
+
# `doors` and always a list (RK1324), which is the one shape a consumer
|
|
1384
|
+
# reads wherever a payload offers a runnable command.
|
|
1385
|
+
"doors": [
|
|
1386
|
+
Door(
|
|
1387
|
+
("section", "show", BLANK),
|
|
1388
|
+
"nothing carries it, so the prose as the file spells it is the read",
|
|
1389
|
+
).payload(served)
|
|
1390
|
+
]
|
|
1391
|
+
}
|
|
1392
|
+
),
|
|
1393
|
+
}
|
|
1394
|
+
|
|
1395
|
+
|
|
1396
|
+
def carrying(config: Config, text: str, role: str | None = None) -> Found:
|
|
1397
|
+
"""Every section whose **own** prose holds ``text``, in file order (RK1310).
|
|
1398
|
+
|
|
1399
|
+
Own prose and not the subtree, because that is the extent `amend --replace` writes into: a
|
|
1400
|
+
container counted for its children would name an anchor the substitution then refuses, which
|
|
1401
|
+
is the wrong answer arriving through the read that exists to stop it.
|
|
1402
|
+
|
|
1403
|
+
Every declared prose role unless one is named — the sentence a caller is hunting may be in
|
|
1404
|
+
either file, and a default that looked in one would answer *not found* about the other.
|
|
1405
|
+
"""
|
|
1406
|
+
asked = [role] if role else [one for one in PROSE_ROLES if config.has(one)]
|
|
1407
|
+
out: list[Carrier] = []
|
|
1408
|
+
for name in asked:
|
|
1409
|
+
document = config.document(name)
|
|
1410
|
+
where = config.relative(config.path(name))
|
|
1411
|
+
for section in anchored(document):
|
|
1412
|
+
count = section.prose.count(text)
|
|
1413
|
+
if count:
|
|
1414
|
+
out.append(
|
|
1415
|
+
Carrier(
|
|
1416
|
+
anchor=section.anchor,
|
|
1417
|
+
role=name,
|
|
1418
|
+
where=where,
|
|
1419
|
+
line=section.first,
|
|
1420
|
+
title=section.title,
|
|
1421
|
+
count=count,
|
|
1422
|
+
)
|
|
1423
|
+
)
|
|
1424
|
+
return Found(text=text, carriers=tuple(out), roles=tuple(asked))
|
|
1425
|
+
|
|
1426
|
+
|
|
1427
|
+
@dataclass(frozen=True, slots=True)
|
|
1428
|
+
class Deleted:
|
|
1429
|
+
"""One section removed whole, and who is left citing it (RK78, RK206).
|
|
1430
|
+
|
|
1431
|
+
A record and no longer a three-tuple (RK1170): the design that task rests on is that both
|
|
1432
|
+
registers come off **one result**, and a tuple has no place to put a method. What the change
|
|
1433
|
+
bought beyond that is :attr:`nested` — the door recomputed the subtree with a second reader
|
|
1434
|
+
to say what went with the heading, and :func:`drop` had the same list in hand to delete it.
|
|
1435
|
+
"""
|
|
1436
|
+
|
|
1437
|
+
#: The file without the section, unsaved: the caller mid-transaction decides when.
|
|
1438
|
+
document: Document
|
|
1439
|
+
section: Section
|
|
1440
|
+
#: Sections whose **prose** still names what this deleted (RK206). Reported and never
|
|
1441
|
+
#: refused: a citation is a sentence, and re-wording one is an edit rather than a
|
|
1442
|
+
#: transaction to abandon.
|
|
1443
|
+
cited: tuple[str, ...] = ()
|
|
1444
|
+
#: The anchors that went with it, nested under the one named (RK78). On the record because
|
|
1445
|
+
#: after the write no file holds them, and this answer is their only record.
|
|
1446
|
+
nested: tuple[str, ...] = ()
|
|
1447
|
+
#: The file this was dropped from, as the caller spells it — the same string the refusals
|
|
1448
|
+
#: above take, so a report and a refusal can never name two different files.
|
|
1449
|
+
where: str = ""
|
|
1450
|
+
|
|
1451
|
+
def stated(self, config: Config, wrote: Sequence[Path]) -> str:
|
|
1452
|
+
"""What went, and who is left pointing at it."""
|
|
1453
|
+
from roadkeep.rendering import _cited_rows, _staging_rows # noqa: PLC0415 - RK260
|
|
1454
|
+
|
|
1455
|
+
rows = [f"dropped {self.section} from {self.where}"]
|
|
1456
|
+
if self.nested:
|
|
1457
|
+
rows.append(f" nested {', '.join(f'§{a}' for a in self.nested)} went with it")
|
|
1458
|
+
rows += _cited_rows(self.cited)
|
|
1459
|
+
rows += _staging_rows(config.relative(one) for one in wrote)
|
|
1460
|
+
return "\n".join(rows)
|
|
1461
|
+
|
|
1462
|
+
def payload(self, config: Config, wrote: Sequence[Path]) -> dict[str, object]:
|
|
1463
|
+
"""The same answer as data, with the subtree the anchor does not state (RK78)."""
|
|
1464
|
+
from roadkeep.rendering import _wrote_json # noqa: PLC0415 - RK260
|
|
1465
|
+
|
|
1466
|
+
return {
|
|
1467
|
+
**self.section.payload(self.where),
|
|
1468
|
+
"nested": list(self.nested),
|
|
1469
|
+
"cited": list(self.cited),
|
|
1470
|
+
**_wrote_json(config, wrote),
|
|
1471
|
+
}
|
|
1472
|
+
|
|
1473
|
+
|
|
1474
|
+
@dataclass(frozen=True, slots=True)
|
|
1475
|
+
class Written:
|
|
1476
|
+
"""One section placed under its block or its anchor (RK93).
|
|
1477
|
+
|
|
1478
|
+
A record and no longer a two-tuple, for :class:`Deleted`'s reason (RK1170). It carries the
|
|
1479
|
+
role because both registers need it — the path to name, and the word limit to count the
|
|
1480
|
+
prose against, which is per role and not per project.
|
|
1481
|
+
"""
|
|
1482
|
+
|
|
1483
|
+
document: Document
|
|
1484
|
+
section: Section
|
|
1485
|
+
role: str = "improvements"
|
|
1486
|
+
|
|
1487
|
+
def stated(self, config: Config, wrote: Sequence[Path]) -> str:
|
|
1488
|
+
from roadkeep.rendering import _staging_rows # noqa: PLC0415 - RK260
|
|
1489
|
+
|
|
1490
|
+
where = config.relative(config.path(self.role))
|
|
1491
|
+
rows = [
|
|
1492
|
+
f"§{self.section.anchor} → {where}:{self.section.first} "
|
|
1493
|
+
f"{self.section.counted(config.schema_for(self.role).section_max)}"
|
|
1494
|
+
]
|
|
1495
|
+
rows += _staging_rows(config.relative(one) for one in wrote)
|
|
1496
|
+
return "\n".join(rows)
|
|
1497
|
+
|
|
1498
|
+
def payload(self, config: Config, wrote: Sequence[Path]) -> dict[str, object]:
|
|
1499
|
+
from roadkeep.rendering import _wrote_json # noqa: PLC0415 - RK260
|
|
1500
|
+
|
|
1501
|
+
return {
|
|
1502
|
+
**self.section.payload(config.relative(config.path(self.role))),
|
|
1503
|
+
**_wrote_json(config, wrote),
|
|
1504
|
+
}
|
|
1505
|
+
|
|
1506
|
+
|
|
1507
|
+
@dataclass(frozen=True, slots=True)
|
|
1508
|
+
class Rewritten:
|
|
1509
|
+
"""One section's heading text or prose corrected in place (RK123, RK1107).
|
|
1510
|
+
|
|
1511
|
+
One record for both doors — anchored and unanchored — because what differs between them is
|
|
1512
|
+
what the write *may* do and not what it answers with: an unanchored section is named by its
|
|
1513
|
+
heading and carries no word count, and :attr:`Section.anchor` being empty is what says so.
|
|
1514
|
+
"""
|
|
1515
|
+
|
|
1516
|
+
document: Document
|
|
1517
|
+
section: Section
|
|
1518
|
+
#: Which fields moved. Empty when the file already read that way, and then nothing was
|
|
1519
|
+
#: written — the one answer here with nothing in it to read (RK1109).
|
|
1520
|
+
changed: tuple[str, ...] = ()
|
|
1521
|
+
role: str = "improvements"
|
|
1522
|
+
|
|
1523
|
+
def stated(self, config: Config, wrote: Sequence[Path], read_body: bool) -> str:
|
|
1524
|
+
"""What moved, or why nothing did (RK1109).
|
|
1525
|
+
|
|
1526
|
+
`read_body` is the caller's: whether this call looked at the prose at all is a fact
|
|
1527
|
+
about the argv — a piped body and a `--title` land in the unchanged answer together,
|
|
1528
|
+
and one of them means the paragraph was never read.
|
|
1529
|
+
"""
|
|
1530
|
+
from roadkeep.rendering import _staging_rows # noqa: PLC0415 - RK260
|
|
1531
|
+
from roadkeep.verbs.reading import unread_prose # noqa: PLC0415 - RK260
|
|
1532
|
+
|
|
1533
|
+
where = config.relative(config.path(self.role))
|
|
1534
|
+
# An unanchored section is named by its heading and never by a bare sigil (RK1107), and
|
|
1535
|
+
# it carries no word count: `section = <n>` is what a *rationale* may spend, and printing
|
|
1536
|
+
# a figure beside a limit is claiming the two are the same number — which the file's
|
|
1537
|
+
# opening paragraph and its contents table are not measured by. `[budgets]` counts bytes.
|
|
1538
|
+
named = f"§{self.section.anchor}" if self.section.anchor else f"'{self.section.title}'"
|
|
1539
|
+
if not self.changed:
|
|
1540
|
+
# RK1109. `unchanged` at exit 0 is the one answer here with nothing in it to read:
|
|
1541
|
+
# the changed path lists its fields, so a caller sees `(title)` and knows the prose
|
|
1542
|
+
# was left alone, and this path listed nothing at all.
|
|
1543
|
+
aside = "" if read_body else f" — {unread_prose()}"
|
|
1544
|
+
return f"{named} unchanged: it already reads that way{aside}"
|
|
1545
|
+
counted = (
|
|
1546
|
+
f" {self.section.counted(config.schema_for(self.role).section_max)}"
|
|
1547
|
+
if self.section.anchor
|
|
1548
|
+
else ""
|
|
1549
|
+
)
|
|
1550
|
+
rows = [
|
|
1551
|
+
f"{named} amended {where}:{self.section.first} "
|
|
1552
|
+
f"({', '.join(self.changed)}){counted}"
|
|
1553
|
+
]
|
|
1554
|
+
rows += _staging_rows(config.relative(one) for one in wrote)
|
|
1555
|
+
return "\n".join(rows)
|
|
1556
|
+
|
|
1557
|
+
def payload(
|
|
1558
|
+
self, config: Config, wrote: Sequence[Path], read_body: bool
|
|
1559
|
+
) -> dict[str, object]:
|
|
1560
|
+
from roadkeep.rendering import _wrote_json # noqa: PLC0415 - RK260
|
|
1561
|
+
|
|
1562
|
+
return {
|
|
1563
|
+
**self.section.payload(config.relative(config.path(self.role))),
|
|
1564
|
+
"changed": list(self.changed),
|
|
1565
|
+
# The same fact as a field (RK1109): whether this call looked at the prose at all.
|
|
1566
|
+
# `changed: []` says nothing moved and cannot say why, which is the ambiguity a
|
|
1567
|
+
# piped body and a `--title` land in together.
|
|
1568
|
+
"read_body": read_body,
|
|
1569
|
+
**_wrote_json(config, wrote),
|
|
1570
|
+
}
|
|
1571
|
+
|
|
1572
|
+
|
|
1573
|
+
def drop(
|
|
1574
|
+
document: Document,
|
|
1575
|
+
anchor: str,
|
|
1576
|
+
*,
|
|
1577
|
+
claimed: Mapping[str, Sequence[str]] | None = None,
|
|
1578
|
+
where: str = "",
|
|
1579
|
+
recorded: bool = False,
|
|
1580
|
+
) -> Deleted:
|
|
1581
|
+
"""Delete the section whole — subsections included — and report what went, and who is
|
|
1582
|
+
left citing it.
|
|
1583
|
+
|
|
1584
|
+
A subsection left behind is orphaned prose under the *next* task's heading, which
|
|
1585
|
+
reads as that task's design and is the one outcome worse than deleting too much.
|
|
1586
|
+
|
|
1587
|
+
Unless one of them is not this section's at all. `claimed` is :func:`pointers`' answer,
|
|
1588
|
+
and a nested anchor in it stops the whole write with :class:`SectionOccupied` (RK78) —
|
|
1589
|
+
the deletion is bounded by ownership rather than by depth, so a level-2 grouping four
|
|
1590
|
+
level-3 designs is refused while a task's own `§RK34.1` still goes with `§RK34`. Omitted,
|
|
1591
|
+
nothing is claimed: a caller with no roadmap to read cannot be told about a pointer, and
|
|
1592
|
+
both callers that have one pass it.
|
|
1593
|
+
|
|
1594
|
+
The anchor that was **named** is asked first and answered the same way (RK112). It is the
|
|
1595
|
+
obvious half and it was the missing one: `ship` made that check on its own path and the
|
|
1596
|
+
standalone verb inherited nothing, so the one command that exists to delete a section was
|
|
1597
|
+
the one that could strand a live pointer.
|
|
1598
|
+
|
|
1599
|
+
``where`` is the file as the report spells it, rendered by the caller and passed in the
|
|
1600
|
+
way ``claimed`` is (RK181): this function takes a :class:`Document` and not a
|
|
1601
|
+
:class:`Config`, so `config.relative` — the one function that renders an address — is out
|
|
1602
|
+
of its reach, and building the string here from ``document.path`` is what printed an
|
|
1603
|
+
absolute path beside a `lint` naming the same file as `IMPROVEMENTS.md:5`.
|
|
1604
|
+
|
|
1605
|
+
The **third** answer is who cited what just went (RK206, RK209), and it is returned
|
|
1606
|
+
rather than left to the callers for this module's own reason: what a deletion breaks is
|
|
1607
|
+
a fact about this file's grammar, the same argument that puts `drop` here instead of in
|
|
1608
|
+
`shipping`. It arrived through the departure path first, so `ship` and `retire` named it
|
|
1609
|
+
and the one verb whose whole job is deleting a section stayed silent — and every refusal
|
|
1610
|
+
above reads a *pointer*, which is the end of the reference that was already read.
|
|
1611
|
+
|
|
1612
|
+
``recorded`` says this file's records claim their own bodies by id (RK1361), which is the
|
|
1613
|
+
decisions role and nothing else. It changes no outcome and one sentence: the refusal there
|
|
1614
|
+
may not offer a pointer to repoint or a line to ship, neither of which that file has.
|
|
1615
|
+
|
|
1616
|
+
Reported and never refused, unlike everything above it. Those refuse because a pointer is
|
|
1617
|
+
a promise the format makes: a line says `→ §<anchor>` and the anchor has to be there. A
|
|
1618
|
+
citation in prose is a sentence, and a sentence that has to be re-worded is an edit and
|
|
1619
|
+
not a transaction to abandon. Computed **before** the removal, because afterwards the
|
|
1620
|
+
prose is the only end of the reference still in the file.
|
|
1621
|
+
"""
|
|
1622
|
+
span = _span(document, anchor)
|
|
1623
|
+
section = find(document, anchor)
|
|
1624
|
+
if span is None or section is None:
|
|
1625
|
+
raise NoSuchSection(anchor, where)
|
|
1626
|
+
if claimed:
|
|
1627
|
+
owners = claimed.get(anchor)
|
|
1628
|
+
if owners:
|
|
1629
|
+
raise SectionClaimed(anchor, owners, where, recorded=recorded)
|
|
1630
|
+
occupied = [
|
|
1631
|
+
(child.anchor, claimed[child.anchor])
|
|
1632
|
+
for child in nested(document, anchor)
|
|
1633
|
+
if child.anchor in claimed
|
|
1634
|
+
]
|
|
1635
|
+
if occupied:
|
|
1636
|
+
raise SectionOccupied(anchor, occupied, where)
|
|
1637
|
+
# And the same question asked of the **name** rather than of the headings (RK169),
|
|
1638
|
+
# which is the half a corpus addressing its prose as bullets fell through: the check
|
|
1639
|
+
# above proves containment and misses everything that is not a heading, and this one
|
|
1640
|
+
# proves nothing about the file and misses nothing an open line has claimed.
|
|
1641
|
+
descended = _descended(anchor, claimed)
|
|
1642
|
+
if descended:
|
|
1643
|
+
raise AnchorClaimed(anchor, descended, where)
|
|
1644
|
+
leaving = (anchor, *(child.anchor for child in nested(document, anchor)))
|
|
1645
|
+
cited = tuple(dict.fromkeys(by for _, by in citing(document, leaving, ignore=leaving)))
|
|
1646
|
+
start, end, _ = span
|
|
1647
|
+
# One edit, not one per line (RK54): a loop validates every half-deleted state, and a
|
|
1648
|
+
# section quoting a fenced example is briefly a file whose fence has no opening line.
|
|
1649
|
+
return Deleted(
|
|
1650
|
+
document.remove_lines(start, end),
|
|
1651
|
+
section,
|
|
1652
|
+
cited=cited,
|
|
1653
|
+
# The subtree, from the list the deletion itself was computed from — the door
|
|
1654
|
+
# used to read it again with a second reader (RK1170).
|
|
1655
|
+
nested=leaving[1:],
|
|
1656
|
+
where=where,
|
|
1657
|
+
)
|
|
1658
|
+
|
|
1659
|
+
|
|
1660
|
+
def add(
|
|
1661
|
+
config: Config,
|
|
1662
|
+
role: str,
|
|
1663
|
+
anchor: str,
|
|
1664
|
+
title: str,
|
|
1665
|
+
body: str,
|
|
1666
|
+
*,
|
|
1667
|
+
level: int | None = None,
|
|
1668
|
+
task: Task | None = None,
|
|
1669
|
+
opens: tuple[str, str] | None = None,
|
|
1670
|
+
) -> Written:
|
|
1671
|
+
"""Place one section under its block or its anchor, reflowed. Validates first.
|
|
1672
|
+
|
|
1673
|
+
Returns the document unsaved, so a caller mid-transaction (`ship`, `init`) decides
|
|
1674
|
+
when the file is touched.
|
|
1675
|
+
|
|
1676
|
+
``level`` is **derived** where the caller names none (RK166), and it has to be: a
|
|
1677
|
+
top-level section written at the depth a subsection uses is not a top-level section at
|
|
1678
|
+
all — it lands inside the previous one's subtree, where every reader that asks a heading
|
|
1679
|
+
where it ends would find it. So the depth of a new top level is read off the file's own
|
|
1680
|
+
existing top level, the way `block add` reads a heading's level off the first block
|
|
1681
|
+
heading, and a subsection keeps the depth every caller already got.
|
|
1682
|
+
|
|
1683
|
+
`task` is the line this anchor names, for the one caller holding a line the roadmap
|
|
1684
|
+
does not carry yet: `add --section` (RK93) validates both files before writing either,
|
|
1685
|
+
so its owner cannot be read back off disk — and read off disk it would be absent,
|
|
1686
|
+
which is `anchor.unknown`, a refusal about a line that is one save away. Omitted, the
|
|
1687
|
+
owner is read from the roadmap, which is every other caller.
|
|
1688
|
+
|
|
1689
|
+
``opens`` is the family this same write declares first, as ``(anchor, title)`` (RK1258) —
|
|
1690
|
+
the one caller being a block's **first** task, whose child address extends a top level no
|
|
1691
|
+
prose file has opened. Without it that call is refused (:class:`UnknownParent`) and the
|
|
1692
|
+
only address available is the family itself, so a block's first design was filed *as* the
|
|
1693
|
+
family heading and every later one as a child of it: two shapes for one thing, and the
|
|
1694
|
+
difference was never a choice anybody made. What is opened is a **container** — a heading
|
|
1695
|
+
and no prose — which is the ordinary structure of a rationale file and the one shape
|
|
1696
|
+
``body.empty`` does not name, that finding being about a leaf a pointer resolves to.
|
|
1697
|
+
"""
|
|
1698
|
+
document = config.document(role)
|
|
1699
|
+
where = config.relative(config.path(role))
|
|
1700
|
+
if task is None:
|
|
1701
|
+
task = _task_for(config, anchor, role)
|
|
1702
|
+
# Bound before it is checked and before it is rendered, so the title this function
|
|
1703
|
+
# validates is the one it writes (RK262) — a heading checked in one spelling and filed
|
|
1704
|
+
# in another is the disagreement L3 refuses a file over.
|
|
1705
|
+
title = _bound(document.schema, anchor, title, task)
|
|
1706
|
+
# The files are read only where nothing live answered *and* the anchor is an id (RK238,
|
|
1707
|
+
# narrowed by RK240): a section written for an open line, or under an outline anchor,
|
|
1708
|
+
# costs no second parse for a door it will never be handed.
|
|
1709
|
+
try:
|
|
1710
|
+
_check(
|
|
1711
|
+
document.schema,
|
|
1712
|
+
anchor,
|
|
1713
|
+
title,
|
|
1714
|
+
body,
|
|
1715
|
+
task,
|
|
1716
|
+
elsewhere=_elsewhere(config, document.schema, anchor, task),
|
|
1717
|
+
known=known(config, anchor, task),
|
|
1718
|
+
# The same question `amend` now asks (RK1227), so the two writers into one file
|
|
1719
|
+
# cannot come to disagree about which addresses a paragraph may cite.
|
|
1720
|
+
resolves=resolvable(config, anchor),
|
|
1721
|
+
)
|
|
1722
|
+
except SectionError as error:
|
|
1723
|
+
# The third door onto the same gap (RK349). `anchor.format` fires on the caller who
|
|
1724
|
+
# typed an id where this scheme numbers its own headings, and the address they now
|
|
1725
|
+
# need is the free child of this block's family — which is what the line writes have
|
|
1726
|
+
# been told since RK312. An anchor naming no task is answered too (RK360), with the
|
|
1727
|
+
# free top-level: that caller has no address at all, which is more and not less.
|
|
1728
|
+
raise naming_the_anchor(
|
|
1729
|
+
config,
|
|
1730
|
+
task.block if task is not None else None,
|
|
1731
|
+
error,
|
|
1732
|
+
namespace=document.schema.ref_prefix or "",
|
|
1733
|
+
anchor=anchor,
|
|
1734
|
+
) from None
|
|
1735
|
+
unspent(config, role, anchor, document=document, where=where)
|
|
1736
|
+
|
|
1737
|
+
# The file as it was read, for the delta :func:`_refuse_overflow` charges (RK1033).
|
|
1738
|
+
was = document
|
|
1739
|
+
# After every refusal the child can raise and before its placement is computed (RK1258):
|
|
1740
|
+
# the family has to exist for :func:`_extended` to find it, and a transaction that opened
|
|
1741
|
+
# one and then refused the design would leave a heading nobody asked for.
|
|
1742
|
+
if opens is not None:
|
|
1743
|
+
document = _opening(config, role, document, opens, where)
|
|
1744
|
+
lines = _render(document.schema, anchor, title, body, _depth(document, anchor, level))
|
|
1745
|
+
index = _placement(document, anchor, task, where, role)
|
|
1746
|
+
document = _inserted(document, index, lines)
|
|
1747
|
+
|
|
1748
|
+
placed = find(document, anchor)
|
|
1749
|
+
assert placed is not None # rendered by this function a moment ago
|
|
1750
|
+
_refuse_overflow(config, document, anchor, was)
|
|
1751
|
+
return Written(document, placed, role)
|
|
1752
|
+
|
|
1753
|
+
|
|
1754
|
+
#: The second half of the overage refusal, by the door that raised it (RK1034). The
|
|
1755
|
+
#: arithmetic above it is one number and is shared; what changes is the list of ways out,
|
|
1756
|
+
#: which is what a refusal is *for* — and RK1033 shipped `add`'s list at both doors.
|
|
1757
|
+
#:
|
|
1758
|
+
#: At an `add` the address has not been chosen, so "put it somewhere else" is one flag away.
|
|
1759
|
+
#: At an `amend` the section is already there and the prose being handed over replaces prose
|
|
1760
|
+
#: that exists: `anchors --next` opens nothing, and taking the subtree elsewhere is `section
|
|
1761
|
+
#: move`, a different act with consequences for every pointer at it. What is left is shorten
|
|
1762
|
+
#: this, or shorten the parent — and the second is invisible from here, the overage being the
|
|
1763
|
+
#: parent's while the paragraph in front of the caller is the child's.
|
|
1764
|
+
_WAYS_OUT = {
|
|
1765
|
+
"add": (
|
|
1766
|
+
"a subsection is charged to the address that owns it, so this prose belongs at a "
|
|
1767
|
+
"free top-level anchor (`anchors --next`) rather than under §{parent}"
|
|
1768
|
+
),
|
|
1769
|
+
"amend": (
|
|
1770
|
+
"the overage is §{parent}'s and this paragraph is §{anchor}'s, so the ways out are "
|
|
1771
|
+
"shortening this body or amending §{parent}'s own prose — `section move {anchor} "
|
|
1772
|
+
"--to <free anchor>` is what takes the subtree out from under it"
|
|
1773
|
+
),
|
|
1774
|
+
}
|
|
1775
|
+
|
|
1776
|
+
|
|
1777
|
+
def _refuse_overflow(
|
|
1778
|
+
config: Config,
|
|
1779
|
+
document: Document,
|
|
1780
|
+
anchor: str,
|
|
1781
|
+
before: Document | None = None,
|
|
1782
|
+
door: str = "add",
|
|
1783
|
+
) -> None:
|
|
1784
|
+
"""Refuse a write that leaves an ancestor over its own limit and worse than it was.
|
|
1785
|
+
|
|
1786
|
+
RK1024 for an `add`, and RK1033 for the `amend` that door left open — which is the one an
|
|
1787
|
+
author reaches more often, a design being amended more than once and written once.
|
|
1788
|
+
|
|
1789
|
+
`add` opens its help with the promise that nothing is written unless every field passes,
|
|
1790
|
+
because *a limit reported after the prose exists is a limit discovered too late to save
|
|
1791
|
+
the tokens it was meant to save*. Charged on the child alone, that promise was false for
|
|
1792
|
+
every nested address: measured in one sitting, `anchors --block AJ` offered `§L.1`,
|
|
1793
|
+
`budget` reported 51 words left, `add` **accepted** a 278-word section, and `lint` then
|
|
1794
|
+
failed the parent by 277. `§L` was 299 words of its own 300 — so every child of it,
|
|
1795
|
+
including an empty one, was over before a word of it was composed, and no writer said so.
|
|
1796
|
+
|
|
1797
|
+
Measured against the file this call has already built rather than against a sum, so the
|
|
1798
|
+
number is the one the gate will read: the walk is the same :func:`find`, the limit is the
|
|
1799
|
+
same `section_max`, and the pointer decides the charge exactly as `_pointed_at` says
|
|
1800
|
+
(RK215). An ancestor nothing points at is a container, and counting its children against
|
|
1801
|
+
it here would refuse prose the gate calls clean — which is the disagreement that made
|
|
1802
|
+
this a defect rather than a limit.
|
|
1803
|
+
|
|
1804
|
+
Every ancestor and not only the immediate one: `L.1.2` is inside `L.1` and inside `L`,
|
|
1805
|
+
and a parent with room under a grandparent with none is still a write `lint` fails.
|
|
1806
|
+
|
|
1807
|
+
``before`` is the file as it was read, and it makes the rule a **delta** rather than a
|
|
1808
|
+
state: a shorter body that leaves an already-over parent over is a correction in the
|
|
1809
|
+
right direction, and refusing it is RK215's deadlock exactly — every door closed and the
|
|
1810
|
+
file left saying something untrue. So what is refused is a write that makes the total
|
|
1811
|
+
worse, never one that arrives at a file somebody else left over. An `add` passes it too:
|
|
1812
|
+
a section body cannot be empty, so an insert is always worse by its own words, and
|
|
1813
|
+
stating the rule once is what keeps the two doors from disagreeing about it.
|
|
1814
|
+
"""
|
|
1815
|
+
limit = document.schema.section_max
|
|
1816
|
+
parent = _parent(anchor)
|
|
1817
|
+
while parent:
|
|
1818
|
+
whole = find(document, parent)
|
|
1819
|
+
if whole is None or whole.words <= limit or not _pointed_at(config, parent):
|
|
1820
|
+
parent = _parent(parent)
|
|
1821
|
+
continue
|
|
1822
|
+
was = find(before, parent) if before is not None else None
|
|
1823
|
+
if was is not None and whole.words <= was.words:
|
|
1824
|
+
parent = _parent(parent)
|
|
1825
|
+
continue
|
|
1826
|
+
raise SectionError(
|
|
1827
|
+
(
|
|
1828
|
+
Violation(
|
|
1829
|
+
"body.too-long",
|
|
1830
|
+
"body",
|
|
1831
|
+
f"§{parent} would be "
|
|
1832
|
+
f"{over_by(whole.words, limit, unit='word', because=' with this section under it')}"
|
|
1833
|
+
f" — {_WAYS_OUT[door].format(parent=parent, anchor=anchor)}",
|
|
1834
|
+
),
|
|
1835
|
+
)
|
|
1836
|
+
)
|
|
1837
|
+
|
|
1838
|
+
|
|
1839
|
+
def unspent(config: Config, role: str, anchor: str, *, document: Document, where: str) -> None:
|
|
1840
|
+
"""Refuse an address anything has already taken — this file, a sibling, or history.
|
|
1841
|
+
|
|
1842
|
+
The three questions `add` asks about a destination, asked once (RK377). `move` asks the
|
|
1843
|
+
same three about the address it is re-writing to, and a second call site spelling them out
|
|
1844
|
+
is how one door comes to refuse what the other writes: the whole reason RK302 exists is
|
|
1845
|
+
that the doubling check was made against the file being written and not against the
|
|
1846
|
+
project, and a repair verb that inherited two of the three would recreate the state it was
|
|
1847
|
+
added to fix.
|
|
1848
|
+
|
|
1849
|
+
``document`` is the caller's own parse rather than a fourth read of the same file: both
|
|
1850
|
+
callers already hold it, and reading it again is what makes two readings possible.
|
|
1851
|
+
"""
|
|
1852
|
+
existing = find(document, anchor)
|
|
1853
|
+
if existing is not None:
|
|
1854
|
+
raise SectionExists(anchor, where, existing.first)
|
|
1855
|
+
_refuse_doubling(config, role, anchor)
|
|
1856
|
+
_refuse_reuse(config, role, anchor, where)
|
|
1857
|
+
|
|
1858
|
+
|
|
1859
|
+
def _refuse_doubling(config: Config, role: str, anchor: str) -> None:
|
|
1860
|
+
"""Refuse an anchor a **sibling** prose file already declares (RK302).
|
|
1861
|
+
|
|
1862
|
+
:func:`_refuse_reuse` catches the address a heading in history spent, which is the case
|
|
1863
|
+
where history is the only witness. A live one is visible in the file next to it, and until
|
|
1864
|
+
this ran nothing looked: RK297 taught the *read* that an outline spans every declared prose
|
|
1865
|
+
file, and the write kept asking the document it was writing into.
|
|
1866
|
+
|
|
1867
|
+
:func:`declaring` and not a fourth reading of the same question (RK229) — the one resolver
|
|
1868
|
+
three verbs already ask which file holds an anchor. The target role is skipped because the
|
|
1869
|
+
caller checked it a line earlier, against the document it has open, and that refusal names
|
|
1870
|
+
the file the author is writing to rather than one they did not mention.
|
|
1871
|
+
|
|
1872
|
+
Both schemes, unlike :func:`_refuse_reuse`: under `id` the anchor is the id and
|
|
1873
|
+
:func:`~roadkeep.authoring.refuse_reuse` covers the roadmap, but two prose files can still
|
|
1874
|
+
hold `§RK2` between them, which is the same `section.ambiguous` by the same reading.
|
|
1875
|
+
"""
|
|
1876
|
+
for other in declaring(config, anchor):
|
|
1877
|
+
if other == role:
|
|
1878
|
+
continue
|
|
1879
|
+
held = find(config.document(other), anchor)
|
|
1880
|
+
if held is not None:
|
|
1881
|
+
raise SectionExists(
|
|
1882
|
+
anchor,
|
|
1883
|
+
config.relative(config.path(other)),
|
|
1884
|
+
held.first,
|
|
1885
|
+
elsewhere=True,
|
|
1886
|
+
)
|
|
1887
|
+
|
|
1888
|
+
|
|
1889
|
+
def _refuse_reuse(config: Config, role: str, anchor: str, where: str) -> None:
|
|
1890
|
+
"""Refuse an outline address a heading in this file's history already spent (RK247).
|
|
1891
|
+
|
|
1892
|
+
**Outline only.** Under the id scheme the anchor is the id, so reuse is refused one file
|
|
1893
|
+
over by `refuse_reuse` (RK4) and an anchor whose task shipped fails `anchor.unknown`
|
|
1894
|
+
before ever reaching here — a second check would be a second opinion about a closed
|
|
1895
|
+
question, on every `add --section` this project makes.
|
|
1896
|
+
|
|
1897
|
+
Silence where history cannot answer, the rule every reader of it keeps: a shallow clone
|
|
1898
|
+
and a directory that is not a repository must not stop a write, and what is lost is a
|
|
1899
|
+
refusal and never a file. Imported here rather than at the top because `history` reads
|
|
1900
|
+
this module (RK260), and the cycle is only avoided at the direction the caller is in.
|
|
1901
|
+
"""
|
|
1902
|
+
if config.schema_for(role).ref_scheme == "id":
|
|
1903
|
+
return
|
|
1904
|
+
from roadkeep.history import anchors, next_child # noqa: PLC0415 - RK260
|
|
1905
|
+
|
|
1906
|
+
# The project's addresses and not this file's (RK297): an outline spans every prose file
|
|
1907
|
+
# a project declares, so a write refused against one of them is a write that takes an
|
|
1908
|
+
# address the sibling spent — which is the doubled anchor, made by the check against it.
|
|
1909
|
+
taken = anchors(config)
|
|
1910
|
+
spent = next((one for one in taken if one.anchor == anchor and not one.live), None)
|
|
1911
|
+
if spent is None:
|
|
1912
|
+
return
|
|
1913
|
+
free = next_child(taken, anchor.rsplit(".", 1)[0]) if "." in anchor else ""
|
|
1914
|
+
raise AnchorRetired(anchor, spent.written_in, free, where)
|
|
1915
|
+
|
|
1916
|
+
|
|
1917
|
+
def _refuse_subtree(document: Document, anchor: str, body: str) -> None:
|
|
1918
|
+
"""Refuse a body that carries a subsection's own heading (RK1112).
|
|
1919
|
+
|
|
1920
|
+
`show` prints the subtree and this verb replaces the own prose, so the obvious round-trip
|
|
1921
|
+
— show a section, correct one sentence, amend it back — arrived at the word limit instead:
|
|
1922
|
+
measured in claude-tray, 1692 words against 300 on a `§XXIII` with six subsections. That
|
|
1923
|
+
refusal is right about the number and says nothing about the cause, and an author reads
|
|
1924
|
+
*"a section this long is two sections"* as a verdict on prose they only meant to pass
|
|
1925
|
+
through. Asked **before** the limit, because a mistake about extent is not a mistake about
|
|
1926
|
+
length and the two have no remedy in common.
|
|
1927
|
+
|
|
1928
|
+
Read off the file's own heading lines and never by parsing the pasted text: what a child's
|
|
1929
|
+
heading is, this document already decided, so the check is whether the body carries one of
|
|
1930
|
+
those strings — no second grammar for headings, and a body carrying none of them is prose
|
|
1931
|
+
however long. The remedy is the extent, so the message names both halves of it: the
|
|
1932
|
+
reader that prints what this verb takes, and the anchor a subsection is amended by.
|
|
1933
|
+
"""
|
|
1934
|
+
lines = {line.strip() for line in body.splitlines() if line.strip()}
|
|
1935
|
+
for child in nested(document, anchor):
|
|
1936
|
+
heading = document.lines[child.first - 1].strip()
|
|
1937
|
+
if heading in lines:
|
|
1938
|
+
raise SectionError(
|
|
1939
|
+
(
|
|
1940
|
+
Violation(
|
|
1941
|
+
"body.subtree",
|
|
1942
|
+
"body",
|
|
1943
|
+
f"the body carries §{child.anchor}'s own heading, so this is "
|
|
1944
|
+
f"§{anchor}'s subtree and not its prose: `section show {anchor} "
|
|
1945
|
+
f"--own` prints the extent this replaces, and §{child.anchor} is "
|
|
1946
|
+
f"amended by its own anchor",
|
|
1947
|
+
),
|
|
1948
|
+
)
|
|
1949
|
+
)
|
|
1950
|
+
|
|
1951
|
+
|
|
1952
|
+
def amend(
|
|
1953
|
+
config: Config,
|
|
1954
|
+
role: str,
|
|
1955
|
+
anchor: str,
|
|
1956
|
+
*,
|
|
1957
|
+
title: str | None = None,
|
|
1958
|
+
body: str | None = None,
|
|
1959
|
+
substitute: Substitution | None = None,
|
|
1960
|
+
) -> Rewritten:
|
|
1961
|
+
"""Rewrite one live section's heading text or its prose, in place (RK123).
|
|
1962
|
+
|
|
1963
|
+
The gap this closes is a union of three correct refusals: `drop` refuses while an open
|
|
1964
|
+
line points at the anchor, `add` refuses the duplicate, and the guard denies the hand
|
|
1965
|
+
edit — so the rationale of an **open** task could not be changed at all, by anybody,
|
|
1966
|
+
until it shipped and the section was deleted. That is the ordinary case and not an edge
|
|
1967
|
+
one: a design under a marker that is not ✅ is expected to change.
|
|
1968
|
+
|
|
1969
|
+
Its **own** prose and never the subtree. A `§<id>.1` is a section with an anchor of its
|
|
1970
|
+
own, amended by naming it — replacing the subtree here would delete somebody's
|
|
1971
|
+
subsection as a side effect of correcting a paragraph, which is `drop`'s job and
|
|
1972
|
+
`drop`'s refusals.
|
|
1973
|
+
|
|
1974
|
+
The anchor is not a field. An address is `renumber`'s (RK97) under the id scheme and
|
|
1975
|
+
:func:`move`'s under an outline (RK377), and either way a section that changed anchor is a
|
|
1976
|
+
section every pointer at it has to change with — which is a transaction and not a field.
|
|
1977
|
+
|
|
1978
|
+
A rewrite that leaves nothing of the original is **not** refused, and the question the
|
|
1979
|
+
design left open is answered here: the falsifiable claim is the `symptom` on the task
|
|
1980
|
+
line, which `amend` already refuses to touch (RK7). A rationale rewritten under an
|
|
1981
|
+
unchanged symptom is still that symptom's rationale; one rewritten because the symptom
|
|
1982
|
+
changed is a line the other verb will not let you rewrite. A second guard here would be
|
|
1983
|
+
a second opinion about a question already answered one file over.
|
|
1984
|
+
|
|
1985
|
+
``substitute`` is the **narrow** form of the same write (RK1263): one string out, one in,
|
|
1986
|
+
derived from the prose already on disk so a table or a fence is never retyped. What it
|
|
1987
|
+
changes about the rules is one thing, and it is the reason this parameter is not just sugar
|
|
1988
|
+
at the verb layer — a section already over the word limit for reasons the edit has nothing
|
|
1989
|
+
to do with was refused for a four-character correction, and the way out was shortening
|
|
1990
|
+
prose the caller never came to touch. So an edit that does not *grow* the prose inherits
|
|
1991
|
+
the overrun instead of being charged it, which is `lint --baseline`'s argument arriving at
|
|
1992
|
+
a door: the standing debt stays a finding, and this call is not what it is about. Only
|
|
1993
|
+
here, because only here is the growth bounded by the replacement's own delta — a
|
|
1994
|
+
whole-body rewrite that happens to come back no longer is still a body somebody composed.
|
|
1995
|
+
"""
|
|
1996
|
+
document = config.document(role)
|
|
1997
|
+
span = _span(document, anchor)
|
|
1998
|
+
section = find(document, anchor)
|
|
1999
|
+
if span is None or section is None:
|
|
2000
|
+
raise NoSuchSection(anchor, config.relative(config.path(role)))
|
|
2001
|
+
_, _, heading = span
|
|
2002
|
+
# The one reading of "this section's own prose", off the record `find` already built
|
|
2003
|
+
# (RK1112): a second slice here is the second answer that let `show` print one extent and
|
|
2004
|
+
# this verb take another.
|
|
2005
|
+
own = section.prose
|
|
2006
|
+
if body is not None:
|
|
2007
|
+
_refuse_subtree(document, anchor, body)
|
|
2008
|
+
|
|
2009
|
+
# Read before the no-op check rather than after it, because a `--title` has to be bound
|
|
2010
|
+
# before it can be compared (RK262): the title that differs from the file only by the id
|
|
2011
|
+
# it omits is a no-op, and comparing the unbound spelling would report a change and
|
|
2012
|
+
# rewrite the heading to the bytes it already holds. The cost is one roadmap parse on the
|
|
2013
|
+
# path that returns without writing, which is the rarest one here.
|
|
2014
|
+
owner = _task_for(config, anchor, role)
|
|
2015
|
+
# Only a title that was **passed** is bound. A body-only amend leaves the heading alone,
|
|
2016
|
+
# id or no id: correcting a paragraph is not the call in which a heading silently changes.
|
|
2017
|
+
wanted_title = (
|
|
2018
|
+
section.title if title is None else _bound(document.schema, anchor, title, owner)
|
|
2019
|
+
)
|
|
2020
|
+
# The prose on disk is what a substitution is applied to, which is the whole point: the
|
|
2021
|
+
# bytes the caller never named are the bytes that cannot be lost (RK1263).
|
|
2022
|
+
wanted_body = own if body is None else body
|
|
2023
|
+
if substitute is not None:
|
|
2024
|
+
wanted_body = substitute.applied(own, f"§{anchor}")
|
|
2025
|
+
changed = tuple(
|
|
2026
|
+
name
|
|
2027
|
+
for name, before, after in (
|
|
2028
|
+
("title", section.title, wanted_title.strip()),
|
|
2029
|
+
("body", own, _normalize(wanted_body)),
|
|
2030
|
+
)
|
|
2031
|
+
if before != after
|
|
2032
|
+
)
|
|
2033
|
+
if not changed:
|
|
2034
|
+
return Rewritten(document, section, (), role)
|
|
2035
|
+
|
|
2036
|
+
_check(
|
|
2037
|
+
document.schema,
|
|
2038
|
+
anchor,
|
|
2039
|
+
wanted_title,
|
|
2040
|
+
wanted_body,
|
|
2041
|
+
owner,
|
|
2042
|
+
elsewhere=_elsewhere(config, document.schema, anchor, owner),
|
|
2043
|
+
known=known(config, anchor, owner),
|
|
2044
|
+
# The addresses this body may cite (RK1227), read from the project because `_check`
|
|
2045
|
+
# takes a schema and cannot.
|
|
2046
|
+
resolves=resolvable(config, anchor),
|
|
2047
|
+
# What the prose already spent, where this edit did not compose it (RK1263).
|
|
2048
|
+
standing=None if substitute is None else words(own),
|
|
2049
|
+
)
|
|
2050
|
+
updated = _rewrite(
|
|
2051
|
+
document,
|
|
2052
|
+
heading,
|
|
2053
|
+
replace(section, title=wanted_title.strip()),
|
|
2054
|
+
wanted_body,
|
|
2055
|
+
retitle="title" in changed,
|
|
2056
|
+
)
|
|
2057
|
+
amended = find(updated, anchor)
|
|
2058
|
+
assert amended is not None # the heading this function just wrote
|
|
2059
|
+
# Charged against the subtree **only where a line points at this anchor**, which is
|
|
2060
|
+
# exactly what the gate charges (RK215). The subtree unconditionally was a writer holding
|
|
2061
|
+
# a file to a limit `lint` does not: measured in Claude Code Tray, a nine-word correction
|
|
2062
|
+
# to a two-sentence intro was refused for 934 words — 900 of them three live
|
|
2063
|
+
# subsections' — on a file that passes the gate. With `drop` refused by those same live
|
|
2064
|
+
# pointers and the guard denying the hand edit, every door was closed and the file left
|
|
2065
|
+
# saying something untrue, which is RK141's deadlock one level over.
|
|
2066
|
+
#
|
|
2067
|
+
# So an intro **is** a section like any other, which is the question the design left open:
|
|
2068
|
+
# `add` already writes a top-level anchor's own prose (RK166), `_rewrite` above already
|
|
2069
|
+
# replaces only that prose, and where nothing points at the anchor `_check` has already
|
|
2070
|
+
# charged it — so there is nothing further to ask.
|
|
2071
|
+
# And the same inheritance one measurement over (RK1263): the subtree is what a pointed-at
|
|
2072
|
+
# section is billed, so a narrow edit inside an already-over subtree is refused here for
|
|
2073
|
+
# words in somebody's subsections — which is the deadlock above with one more layer of
|
|
2074
|
+
# prose the caller never came to touch.
|
|
2075
|
+
if (
|
|
2076
|
+
_pointed_at(config, anchor)
|
|
2077
|
+
and amended.words > document.schema.section_max
|
|
2078
|
+
and not (substitute is not None and amended.words <= section.words)
|
|
2079
|
+
):
|
|
2080
|
+
counted = over_by(
|
|
2081
|
+
amended.words,
|
|
2082
|
+
document.schema.section_max,
|
|
2083
|
+
unit="word",
|
|
2084
|
+
because=" with its subsections",
|
|
2085
|
+
)
|
|
2086
|
+
raise SectionError(
|
|
2087
|
+
(
|
|
2088
|
+
Violation(
|
|
2089
|
+
"body.too-long",
|
|
2090
|
+
"body",
|
|
2091
|
+
f"{counted}; a section this long is two sections, or a paragraph "
|
|
2092
|
+
f"that belongs in the commit",
|
|
2093
|
+
),
|
|
2094
|
+
)
|
|
2095
|
+
)
|
|
2096
|
+
# The door RK1024 and RK1029 left open (RK1033): a rewrite of `§L.3` that puts `§L`
|
|
2097
|
+
# eighty words over was accepted and reported by `lint` afterwards, which is the
|
|
2098
|
+
# sequence both of those closed at `add`. The delta is what makes it safe here — an
|
|
2099
|
+
# amend is where the prose already exists, and refusing a *shortening* is RK215's
|
|
2100
|
+
# deadlock in the one direction an author can act in.
|
|
2101
|
+
_refuse_overflow(config, updated, anchor, document, door="amend")
|
|
2102
|
+
return Rewritten(updated, amended, changed, role)
|
|
2103
|
+
|
|
2104
|
+
|
|
2105
|
+
def amend_untitled(
|
|
2106
|
+
config: Config,
|
|
2107
|
+
role: str,
|
|
2108
|
+
title: str,
|
|
2109
|
+
*,
|
|
2110
|
+
body: str | None = None,
|
|
2111
|
+
retitle: str | None = None,
|
|
2112
|
+
substitute: Substitution | None = None,
|
|
2113
|
+
) -> Rewritten:
|
|
2114
|
+
"""Rewrite an unanchored section's prose or its heading, in place (RK1107).
|
|
2115
|
+
|
|
2116
|
+
:func:`amend`'s twin for the two regions a prose file has that carry no address — its
|
|
2117
|
+
opening, and a `## Table of contents`. The same three properties and one fewer: own prose
|
|
2118
|
+
and never the subtree, nothing written unless something changed, and **no `owner`** —
|
|
2119
|
+
an unanchored section belongs to no task, so there is no id to bind into the heading and no
|
|
2120
|
+
pointer that a re-titling has to move with it. That last is the whole reason this is a
|
|
2121
|
+
second function rather than a branch in the first: `amend`'s body is about the anchor, the
|
|
2122
|
+
task that owns it, and the budget the two decide between them, and an unanchored section
|
|
2123
|
+
has none of the three.
|
|
2124
|
+
|
|
2125
|
+
Not budgeted, deliberately. `section = <n>` is what a *rationale* may spend, measured
|
|
2126
|
+
against a corpus of rationale sections; a file's opening paragraph and a contents table are
|
|
2127
|
+
neither, and charging them a limit nobody measured them against is how a ceiling comes to
|
|
2128
|
+
refuse the prose it was derived from. What holds them is `[budgets]` on the whole file,
|
|
2129
|
+
which already counts every byte of both.
|
|
2130
|
+
"""
|
|
2131
|
+
document = config.document(role)
|
|
2132
|
+
heading = titled(document, title)
|
|
2133
|
+
if heading is None:
|
|
2134
|
+
raise NoSuchSection(title, config.relative(config.path(role)))
|
|
2135
|
+
end = document.prose_end(heading)
|
|
2136
|
+
own = "".join(document.lines[heading.lineno : end]).strip("\r\n")
|
|
2137
|
+
section = Section(
|
|
2138
|
+
anchor="",
|
|
2139
|
+
title=heading.text.strip(),
|
|
2140
|
+
level=heading.level,
|
|
2141
|
+
first=heading.lineno,
|
|
2142
|
+
last=end,
|
|
2143
|
+
body=own,
|
|
2144
|
+
)
|
|
2145
|
+
wanted_title = section.title if retitle is None else retitle.strip()
|
|
2146
|
+
# The narrow form reaches here too (RK1263), and this is the region it is most obviously
|
|
2147
|
+
# for: a `## Table of contents` is a table whose every row is a heading somebody's ship
|
|
2148
|
+
# moved, and retyping the whole of it to correct one row is the risk that task is about.
|
|
2149
|
+
wanted_body = own if body is None else body
|
|
2150
|
+
if substitute is not None:
|
|
2151
|
+
wanted_body = substitute.applied(own, repr(section.title))
|
|
2152
|
+
changed = tuple(
|
|
2153
|
+
name
|
|
2154
|
+
for name, before, after in (
|
|
2155
|
+
("title", section.title, wanted_title),
|
|
2156
|
+
("body", own, _normalize(wanted_body)),
|
|
2157
|
+
)
|
|
2158
|
+
if before != after
|
|
2159
|
+
)
|
|
2160
|
+
if not changed:
|
|
2161
|
+
return Rewritten(document, section, (), role)
|
|
2162
|
+
if not wanted_title:
|
|
2163
|
+
raise SectionError(
|
|
2164
|
+
(
|
|
2165
|
+
Violation(
|
|
2166
|
+
"title.empty",
|
|
2167
|
+
"title",
|
|
2168
|
+
"an unanchored section is addressed by its heading, so a blank one "
|
|
2169
|
+
"leaves it with no address at all",
|
|
2170
|
+
),
|
|
2171
|
+
)
|
|
2172
|
+
)
|
|
2173
|
+
updated = _rewrite(
|
|
2174
|
+
document,
|
|
2175
|
+
heading,
|
|
2176
|
+
replace(section, title=wanted_title),
|
|
2177
|
+
wanted_body,
|
|
2178
|
+
retitle="title" in changed,
|
|
2179
|
+
)
|
|
2180
|
+
return Rewritten(
|
|
2181
|
+
updated,
|
|
2182
|
+
replace(section, title=wanted_title, body=_normalize(wanted_body)),
|
|
2183
|
+
changed,
|
|
2184
|
+
role,
|
|
2185
|
+
)
|
|
2186
|
+
|
|
2187
|
+
|
|
2188
|
+
#: The governed files whose lines carry a `→ §<anchor>`, which is the end of a pointer a
|
|
2189
|
+
#: re-address has to move with the heading. The deferred store is one (RK96): pausing a line
|
|
2190
|
+
#: keeps its section, so its pointer is as live as the roadmap's and the gate reads both.
|
|
2191
|
+
POINTING_ROLES = ("roadmap", "deferred")
|
|
2192
|
+
|
|
2193
|
+
|
|
2194
|
+
@dataclass(frozen=True, slots=True)
|
|
2195
|
+
class Moved:
|
|
2196
|
+
"""Every edit one section's change of address makes, as data, before it is written."""
|
|
2197
|
+
|
|
2198
|
+
anchor: str
|
|
2199
|
+
to: str
|
|
2200
|
+
role: str
|
|
2201
|
+
#: The section as it now reads, at its new address.
|
|
2202
|
+
section: Section
|
|
2203
|
+
#: The nested addresses re-written with it, `(before, after)` in file order.
|
|
2204
|
+
subsections: tuple[tuple[str, str], ...] = ()
|
|
2205
|
+
#: The governed files this write leaves changed, by role. A mapping and not named fields
|
|
2206
|
+
#: for :class:`~roadkeep.renumbering.Renumbering`'s reason: which files are in it is a
|
|
2207
|
+
#: property of the project, a deferred store being optional and a pointer being a line
|
|
2208
|
+
#: some backlogs carry none of.
|
|
2209
|
+
documents: Mapping[str, Document] = field(default_factory=dict)
|
|
2210
|
+
#: Every line whose pointer followed, as `(id, address)`. Its own address and not the
|
|
2211
|
+
#: named one: a line pointing at a subsection follows to `§I.11.1` while the section this
|
|
2212
|
+
#: was called about lands at `§I.11`, and one destination for both would be a report
|
|
2213
|
+
#: nobody can check against the file. Named and never silent — a pointer is the other end
|
|
2214
|
+
#: of the address that moved, and the author is who can say whether it should have.
|
|
2215
|
+
repointed: tuple[tuple[str, str], ...] = ()
|
|
2216
|
+
#: Lines left pointing at the old address because a sibling prose file still declares it,
|
|
2217
|
+
#: as `(id, address)` — the doubling this verb is usually called for, resolving to the
|
|
2218
|
+
#: section that stayed rather than following the one that moved.
|
|
2219
|
+
kept: tuple[tuple[str, str], ...] = ()
|
|
2220
|
+
#: Sections whose **prose** still cites an address that moved, as `(address, by)`.
|
|
2221
|
+
#: Reported and never rewritten, for the reason `drop` reports the same thing: a pointer
|
|
2222
|
+
#: is a promise the format makes and a citation is a sentence (L4).
|
|
2223
|
+
cited: tuple[tuple[str, str], ...] = ()
|
|
2224
|
+
|
|
2225
|
+
def save(self) -> tuple[Path, ...]:
|
|
2226
|
+
"""Write every file this move touched, and answer them all (RK1130)."""
|
|
2227
|
+
return save_all(*self.documents.values())
|
|
2228
|
+
|
|
2229
|
+
def stated(self, config: Config, wrote: Sequence[Path]) -> str:
|
|
2230
|
+
"""Where the address went, and every line that followed it (RK377).
|
|
2231
|
+
|
|
2232
|
+
Beside :meth:`payload` since RK1170. Four lists and never a count: a pointer is the
|
|
2233
|
+
other end of an address that moved, and the line that changed is the one whose author
|
|
2234
|
+
has to agree it should have (RK97).
|
|
2235
|
+
"""
|
|
2236
|
+
from roadkeep.rendering import _staging_rows # noqa: PLC0415 - RK260
|
|
2237
|
+
|
|
2238
|
+
where = config.relative(config.path(self.role))
|
|
2239
|
+
rows = [
|
|
2240
|
+
f"§{self.anchor} → §{self.to} {where}:{self.section.first}",
|
|
2241
|
+
*(f" nested §{before} → §{after}" for before, after in self.subsections),
|
|
2242
|
+
*(f" pointer {one} follows it to §{a}" for one, a in self.repointed),
|
|
2243
|
+
# The doubling this verb is usually called for: the address still resolves, to the
|
|
2244
|
+
# section that stayed, and that is the answer rather than a thing left half done.
|
|
2245
|
+
*(
|
|
2246
|
+
f" kept {one} still points at §{a}, which the other file declares"
|
|
2247
|
+
for one, a in self.kept
|
|
2248
|
+
),
|
|
2249
|
+
*(
|
|
2250
|
+
f" cited §{by} names §{a} in its prose — that address has moved"
|
|
2251
|
+
for a, by in self.cited
|
|
2252
|
+
),
|
|
2253
|
+
]
|
|
2254
|
+
rows += _staging_rows(config.relative(one) for one in wrote)
|
|
2255
|
+
return "\n".join(rows)
|
|
2256
|
+
|
|
2257
|
+
def payload(self, config: Config, wrote: Sequence[Path]) -> dict[str, object]:
|
|
2258
|
+
"""The same answer as data, with each list as pairs a caller can act on."""
|
|
2259
|
+
from roadkeep.rendering import _wrote_json # noqa: PLC0415 - RK260
|
|
2260
|
+
|
|
2261
|
+
where = config.relative(config.path(self.role))
|
|
2262
|
+
return {
|
|
2263
|
+
**self.section.payload(where),
|
|
2264
|
+
"from": self.anchor,
|
|
2265
|
+
"subsections": [
|
|
2266
|
+
{"from": before, "to": after} for before, after in self.subsections
|
|
2267
|
+
],
|
|
2268
|
+
"repointed": [{"id": one, "to": a} for one, a in self.repointed],
|
|
2269
|
+
"kept": [{"id": one, "address": a} for one, a in self.kept],
|
|
2270
|
+
"cited": [{"address": a, "by": by} for a, by in self.cited],
|
|
2271
|
+
**_wrote_json(config, wrote),
|
|
2272
|
+
}
|
|
2273
|
+
|
|
2274
|
+
|
|
2275
|
+
def move(config: Config, role: str, anchor: str, to: str) -> Moved:
|
|
2276
|
+
"""Re-address one live section, its own subtree and every pointer at it (RK377).
|
|
2277
|
+
|
|
2278
|
+
The verb an outline had none of. `renumber` moves an **id**, and keeps the pointer as
|
|
2279
|
+
typed wherever the scheme is not `id` — which is precisely the scheme a project with a
|
|
2280
|
+
hand-kept outline is on — so a doubled address, the thing `lint` reports as
|
|
2281
|
+
`section.ambiguous` and the write path refuses to create, was repairable only by the hand
|
|
2282
|
+
edit the guard denies. Turing adopted the tool with 13 of them.
|
|
2283
|
+
|
|
2284
|
+
Everything the address owns, or nothing. The heading, every nested anchor that
|
|
2285
|
+
:func:`descending` says is this one's own numbering, and the `→ §<anchor>` on every line
|
|
2286
|
+
in :data:`POINTING_ROLES` naming one of them, validated before a file is touched — a
|
|
2287
|
+
re-address that moved the heading and not the pointer is the dangling reference this
|
|
2288
|
+
module exists to prevent, one verb over.
|
|
2289
|
+
|
|
2290
|
+
The destination takes :func:`unspent`, which is every refusal `add` computes about an
|
|
2291
|
+
address: taken here, declared by a sibling prose file, or spent by a heading in this
|
|
2292
|
+
file's history. Each **new** address is asked, not only the named one, because a
|
|
2293
|
+
subsection's is derived from its parent's and a collision on `§I.14.1` is the same
|
|
2294
|
+
collision one segment down.
|
|
2295
|
+
|
|
2296
|
+
**A pointer follows the section when nothing else answers its address, or when this
|
|
2297
|
+
heading names its task.** Both halves are readings this module already makes, and neither
|
|
2298
|
+
is a guess. The ordinary re-address is the first: nothing else declares the old address,
|
|
2299
|
+
so a pointer left behind is the dangling reference, and it moves. The doubling this verb
|
|
2300
|
+
exists for is the second, and moving every pointer there would be exactly wrong — the
|
|
2301
|
+
address resolved to two sections, one of them names the task in its heading
|
|
2302
|
+
(:func:`owners`), and repairing the *other* file must leave that line pointing where its
|
|
2303
|
+
design still is. What stays is reported as :attr:`Moved.kept`, because a line the caller
|
|
2304
|
+
expected to move and that did not is the half of the answer the files no longer state.
|
|
2305
|
+
|
|
2306
|
+
What it does not do is move prose. The section stays exactly where it is in the file and
|
|
2307
|
+
only its address changes, which is why :class:`NotASibling` bounds the destination to the
|
|
2308
|
+
parent the source already had — see that class for why the two cannot be separated.
|
|
2309
|
+
"""
|
|
2310
|
+
document = config.document(role)
|
|
2311
|
+
where = config.relative(config.path(role))
|
|
2312
|
+
schema = document.schema
|
|
2313
|
+
if schema.ref_scheme == "id":
|
|
2314
|
+
raise AnchorIsId(anchor, where)
|
|
2315
|
+
section = find(document, anchor)
|
|
2316
|
+
if section is None:
|
|
2317
|
+
raise NoSuchSection(anchor, where)
|
|
2318
|
+
# The project's spelling of the address and not the caller's: `find` resolves a bare `I.2`
|
|
2319
|
+
# in a namespaced file, and every comparison below is against anchors :func:`anchored`
|
|
2320
|
+
# already qualified (RK340).
|
|
2321
|
+
anchor = section.anchor
|
|
2322
|
+
if (bad := _address_violation(schema, to)) is not None:
|
|
2323
|
+
raise SectionError((bad,))
|
|
2324
|
+
if to == anchor:
|
|
2325
|
+
raise SameAnchor(anchor)
|
|
2326
|
+
if _parent(to) != _parent(anchor):
|
|
2327
|
+
raise NotASibling(anchor, to, _parent(anchor), _free_under(config, _parent(anchor)))
|
|
2328
|
+
|
|
2329
|
+
children = descending(document, anchor)
|
|
2330
|
+
subsections = tuple(
|
|
2331
|
+
(child.anchor, f"{to}{child.anchor[len(anchor) :]}") for child in children
|
|
2332
|
+
)
|
|
2333
|
+
for address in (to, *(after for _, after in subsections)):
|
|
2334
|
+
unspent(config, role, address, document=document, where=where)
|
|
2335
|
+
|
|
2336
|
+
ids = schema.id_pattern()
|
|
2337
|
+
carried = {
|
|
2338
|
+
moving.anchor: Carried(
|
|
2339
|
+
to=after,
|
|
2340
|
+
owns=owners(moving, ids),
|
|
2341
|
+
# Whichever files answer the old address once this one stops: empty is the plain
|
|
2342
|
+
# re-address, where a pointer left behind resolves to nothing.
|
|
2343
|
+
answered_by=tuple(r for r in declaring(config, moving.anchor) if r != role),
|
|
2344
|
+
)
|
|
2345
|
+
for moving, after in ((section, to), *zip(children, (a for _, a in subsections), strict=True))
|
|
2346
|
+
}
|
|
2347
|
+
# Read before the rewrite, while the prose and the addresses it names still agree. Nothing
|
|
2348
|
+
# is ignored: a citation inside the moving subtree is as stale afterwards as one outside it.
|
|
2349
|
+
cited = citing(document, tuple(carried))
|
|
2350
|
+
# By line number and applied to a document that reparses, which is why the headings are
|
|
2351
|
+
# collected first: one `replace_line` is one line for one line, so no heading below an edit
|
|
2352
|
+
# has moved under the edits above it (the care :func:`_rewrite` takes for the same reason).
|
|
2353
|
+
updated = document.replace_line(
|
|
2354
|
+
section.first - 1, heading_of(schema, replace(section, anchor=to))
|
|
2355
|
+
)
|
|
2356
|
+
for child, after in zip(children, (after for _, after in subsections), strict=True):
|
|
2357
|
+
updated = updated.replace_line(
|
|
2358
|
+
child.first - 1, heading_of(schema, replace(child, anchor=after))
|
|
2359
|
+
)
|
|
2360
|
+
documents: dict[str, Document] = {role: updated}
|
|
2361
|
+
repointed, kept = _repoint(config, carried, documents)
|
|
2362
|
+
|
|
2363
|
+
landed = find(updated, to)
|
|
2364
|
+
assert landed is not None # the heading this function wrote a moment ago
|
|
2365
|
+
return Moved(
|
|
2366
|
+
anchor=anchor,
|
|
2367
|
+
to=to,
|
|
2368
|
+
role=role,
|
|
2369
|
+
section=landed,
|
|
2370
|
+
subsections=subsections,
|
|
2371
|
+
documents=documents,
|
|
2372
|
+
repointed=repointed,
|
|
2373
|
+
kept=kept,
|
|
2374
|
+
cited=cited,
|
|
2375
|
+
)
|
|
2376
|
+
|
|
2377
|
+
|
|
2378
|
+
@dataclass(frozen=True, slots=True)
|
|
2379
|
+
class Carried:
|
|
2380
|
+
"""One address on the move, and what decides whether a pointer at it goes too (RK377)."""
|
|
2381
|
+
|
|
2382
|
+
to: str
|
|
2383
|
+
#: The task ids this heading names, which is the claim to be their design (:func:`owners`).
|
|
2384
|
+
owns: tuple[str, ...]
|
|
2385
|
+
#: The other prose roles still declaring the address after this write — the doubling.
|
|
2386
|
+
answered_by: tuple[str, ...]
|
|
2387
|
+
|
|
2388
|
+
def follows(self, task_id: str) -> bool:
|
|
2389
|
+
"""Whether this line's pointer moves with the heading — see :func:`move`."""
|
|
2390
|
+
return not self.answered_by or task_id in self.owns
|
|
2391
|
+
|
|
2392
|
+
|
|
2393
|
+
def _repoint(
|
|
2394
|
+
config: Config, carried: Mapping[str, Carried], documents: dict[str, Document]
|
|
2395
|
+
) -> tuple[tuple[tuple[str, str], ...], tuple[tuple[str, str], ...]]:
|
|
2396
|
+
"""Rewrite every `→ §<old>` that follows its heading, by line file (RK377).
|
|
2397
|
+
|
|
2398
|
+
Which lines those are is read once, before any of them is rewritten, and re-fetched by id
|
|
2399
|
+
inside the loop: `replace_task` reparses, so an entry held across an edit is one whose line
|
|
2400
|
+
number may already have moved — the care every mutator in :mod:`roadkeep.kernel.document` takes.
|
|
2401
|
+
|
|
2402
|
+
Through `schema.check`, which is what refuses a longer address that pushes the rendered
|
|
2403
|
+
line past its limit. That refusal belongs here rather than after the write: a pointer left
|
|
2404
|
+
behind because the line would not fit is the dangling reference, and this transaction has
|
|
2405
|
+
touched nothing yet.
|
|
2406
|
+
"""
|
|
2407
|
+
moved: list[tuple[str, str]] = []
|
|
2408
|
+
stayed: list[tuple[str, str]] = []
|
|
2409
|
+
for name in POINTING_ROLES:
|
|
2410
|
+
if not config.has(name) or not config.path(name).is_file():
|
|
2411
|
+
continue
|
|
2412
|
+
lines = config.document(name)
|
|
2413
|
+
pointing = _following(lines, carried, stayed)
|
|
2414
|
+
for task_id in pointing:
|
|
2415
|
+
current = next(e for e in lines.entries if e.task.id == task_id)
|
|
2416
|
+
lines = lines.replace_task(
|
|
2417
|
+
current,
|
|
2418
|
+
lines.schema.check(
|
|
2419
|
+
replace(current.task, ref=carried[current.task.ref].to)
|
|
2420
|
+
),
|
|
2421
|
+
)
|
|
2422
|
+
if pointing:
|
|
2423
|
+
documents[name] = lines
|
|
2424
|
+
moved.extend((one, carried[ref].to) for one, ref in pointing.items())
|
|
2425
|
+
return tuple(moved), tuple(stayed)
|
|
2426
|
+
|
|
2427
|
+
|
|
2428
|
+
def _following(
|
|
2429
|
+
lines: Document, carried: Mapping[str, Carried], stayed: list[tuple[str, str]]
|
|
2430
|
+
) -> dict[str, str]:
|
|
2431
|
+
"""Which of this file's lines follow their heading, by id, and which are left behind."""
|
|
2432
|
+
out: dict[str, str] = {}
|
|
2433
|
+
for entry in lines.entries:
|
|
2434
|
+
one = carried.get(entry.task.ref)
|
|
2435
|
+
if one is None:
|
|
2436
|
+
continue
|
|
2437
|
+
if one.follows(entry.task.id):
|
|
2438
|
+
out[entry.task.id] = entry.task.ref
|
|
2439
|
+
else:
|
|
2440
|
+
stayed.append((entry.task.id, entry.task.ref))
|
|
2441
|
+
return out
|
|
2442
|
+
|
|
2443
|
+
|
|
2444
|
+
def _parent(anchor: str) -> str:
|
|
2445
|
+
"""The address one segment up — `S:I.2` → `S:I`, and `''` for a top level.
|
|
2446
|
+
|
|
2447
|
+
The namespace is not a segment (RK340): `S:I` is one address whose separator is a colon,
|
|
2448
|
+
so a top level keeps its prefix and answers `''` here like any other.
|
|
2449
|
+
"""
|
|
2450
|
+
return anchor.rsplit(".", 1)[0] if "." in anchor else ""
|
|
2451
|
+
|
|
2452
|
+
|
|
2453
|
+
def _rewrite(
|
|
2454
|
+
document: Document,
|
|
2455
|
+
heading: Heading,
|
|
2456
|
+
section: Section,
|
|
2457
|
+
body: str,
|
|
2458
|
+
*,
|
|
2459
|
+
retitle: bool = True,
|
|
2460
|
+
) -> Document:
|
|
2461
|
+
"""Swap a heading's line and the prose under it for the reflowed replacement.
|
|
2462
|
+
|
|
2463
|
+
One removal and one insertion per line rather than a patch, because every mutator in
|
|
2464
|
+
:mod:`roadkeep.kernel.document` reparses — so the region is taken out first and the new lines
|
|
2465
|
+
go in at the heading's own index, where nothing below has moved yet.
|
|
2466
|
+
|
|
2467
|
+
``retitle`` is false where only the prose changed, and then the heading line is not
|
|
2468
|
+
touched at all (RK388). It used to be re-rendered unconditionally, and under an outline
|
|
2469
|
+
that is a **silent rewrite of something nobody named**: the reader accepts `## §I A
|
|
2470
|
+
design` because a sigil an author wrote is not a spelling to punish (RK44), and
|
|
2471
|
+
:func:`anchor_text` then writes the canonical `## I A design` — so a `section amend
|
|
2472
|
+
--body` on any section in the file took the `§` off the one it was passed, along with
|
|
2473
|
+
whatever spacing that heading had. `lint` called the result clean, because L3 is held
|
|
2474
|
+
over task lines and a prose file has none.
|
|
2475
|
+
|
|
2476
|
+
Of the three repairs the design weighed — refuse the file, make the sigil canonical, or
|
|
2477
|
+
narrow the reader — this is a fourth, and it is the one that costs nothing: the writer
|
|
2478
|
+
stops reproducing a line it was not asked about. An amend that *does* pass `--title` is
|
|
2479
|
+
the caller asking for the heading to change, and there the canonical spelling is right.
|
|
2480
|
+
"""
|
|
2481
|
+
end = document.prose_end(heading)
|
|
2482
|
+
payload = ["", *_body_lines(document.schema, body)]
|
|
2483
|
+
if end < len(document.lines):
|
|
2484
|
+
# The blank that separates this section's prose from the next heading. Kept when
|
|
2485
|
+
# there is a next heading and omitted at the end of the file, which is where a
|
|
2486
|
+
# trailing blank is one nobody put there.
|
|
2487
|
+
payload.append("")
|
|
2488
|
+
updated = document.remove_lines(heading.lineno, end)
|
|
2489
|
+
for offset, raw in enumerate(payload):
|
|
2490
|
+
updated = updated.insert_line(heading.lineno + offset, raw)
|
|
2491
|
+
if not retitle:
|
|
2492
|
+
return updated
|
|
2493
|
+
# The heading last and through :func:`heading_of`, so the one writer of that spelling
|
|
2494
|
+
# stays one (RK44) — an amend that composed it here would be the second.
|
|
2495
|
+
return updated.replace_line(heading.lineno - 1, heading_of(document.schema, section))
|
|
2496
|
+
|
|
2497
|
+
|
|
2498
|
+
def paragraphs(body: str) -> tuple[int, ...]:
|
|
2499
|
+
"""What each paragraph of a body costs, in the same unit :func:`words` charges (RK311).
|
|
2500
|
+
|
|
2501
|
+
The half a refusal was missing. `budget` prices the ceiling before a word exists, which
|
|
2502
|
+
is the right half and the one L1 is about; what had no answer was a draft that already
|
|
2503
|
+
exists — measured over one session of thirteen filings, **fifteen** `body.too-long`
|
|
2504
|
+
refusals, three of them over one or two words, each discarding about 250 words to remove
|
|
2505
|
+
a handful. The overage alone does not shorten the second attempt: it says a cut is needed
|
|
2506
|
+
and leaves the author counting by hand for somewhere to make it, against a number this
|
|
2507
|
+
module has already computed exactly.
|
|
2508
|
+
|
|
2509
|
+
So the refusal says **where**. Paragraphs are blank-line separated, a fenced block is one
|
|
2510
|
+
paragraph however many blanks are inside it, and each is charged by the same reading the
|
|
2511
|
+
limit uses — so the three shapes :func:`words` exempts show as `0` rather than as
|
|
2512
|
+
something a cut could reach. That zero is the answer to the other half of the question: a
|
|
2513
|
+
section over the limit whose longest paragraph is a table is not one to split.
|
|
2514
|
+
"""
|
|
2515
|
+
out: list[int] = []
|
|
2516
|
+
current: list[str] = []
|
|
2517
|
+
fence: str | None = None
|
|
2518
|
+
for raw in body.splitlines():
|
|
2519
|
+
line = raw.lstrip()
|
|
2520
|
+
if fence is not None:
|
|
2521
|
+
current.append(raw)
|
|
2522
|
+
if line.startswith(fence):
|
|
2523
|
+
fence = None
|
|
2524
|
+
continue
|
|
2525
|
+
if line.startswith(_FENCES):
|
|
2526
|
+
# A fence opens *inside* whatever paragraph is being read, so an intro line and
|
|
2527
|
+
# the block under it stay one unit — which is how the author sees them.
|
|
2528
|
+
fence = line[:3]
|
|
2529
|
+
current.append(raw)
|
|
2530
|
+
continue
|
|
2531
|
+
if not line:
|
|
2532
|
+
if current:
|
|
2533
|
+
out.append(words("\n".join(current)))
|
|
2534
|
+
current = []
|
|
2535
|
+
continue
|
|
2536
|
+
current.append(raw)
|
|
2537
|
+
if current:
|
|
2538
|
+
out.append(words("\n".join(current)))
|
|
2539
|
+
return tuple(out)
|
|
2540
|
+
|
|
2541
|
+
|
|
2542
|
+
def _where_the_words_are(body: str) -> str:
|
|
2543
|
+
"""The per-paragraph counts, as the clause a refusal ends with (RK311).
|
|
2544
|
+
|
|
2545
|
+
Named for what it answers rather than for what it formats: the author has been told a cut
|
|
2546
|
+
is needed and this is the sentence that says where one is available. Silent on a
|
|
2547
|
+
single-paragraph body — "¶1 335" restates the total the same message already gave, and a
|
|
2548
|
+
refusal that repeats itself is one an author stops reading.
|
|
2549
|
+
"""
|
|
2550
|
+
counted = paragraphs(body)
|
|
2551
|
+
if len(counted) < 2:
|
|
2552
|
+
return ""
|
|
2553
|
+
listed = ", ".join(f"¶{n} {count}" for n, count in enumerate(counted, 1))
|
|
2554
|
+
# The longest is named because it is the one the author is looking for, and a tie names
|
|
2555
|
+
# the first — the cut has to start somewhere and the file reads top down.
|
|
2556
|
+
fattest = counted.index(max(counted)) + 1
|
|
2557
|
+
return f"; by paragraph {listed} — ¶{fattest} is the longest"
|
|
2558
|
+
|
|
2559
|
+
|
|
2560
|
+
def words(body: str) -> int:
|
|
2561
|
+
"""The words of **argument** in a body — the budget's unit, and never its whole text.
|
|
2562
|
+
|
|
2563
|
+
`len(body.split())` charged every cell of a Markdown table what a word of argument
|
|
2564
|
+
costs. Measured while adopting Claude Tray: its `III` is 269 words of which 230 are the
|
|
2565
|
+
measured-baseline table the file keeps *because it is data, not design*, and its `XVI.3`
|
|
2566
|
+
is 293 of which 72 are a timing table — both under 250 counting prose alone. The remedy
|
|
2567
|
+
the finding offered, "this is two sections, or a paragraph that belongs in the commit",
|
|
2568
|
+
is advice about prose and applied to neither: splitting a six-row measurement in half
|
|
2569
|
+
helps nobody, and the rows are the evidence the design rests on. That adoption ended by
|
|
2570
|
+
declaring `section = 300`, a number describing two tables rather than budgeting anybody's
|
|
2571
|
+
prose, which is the outcome L6 exists to prevent (RK136).
|
|
2572
|
+
|
|
2573
|
+
So three shapes are data and cost nothing: a **table** row, a **fenced** block with
|
|
2574
|
+
everything in it, and a **blockquote**, which is somebody else's words being cited. A
|
|
2575
|
+
list is not among them — a bullet is how an argument is written here, and exempting one
|
|
2576
|
+
would reopen the budget by reformatting. What the limit is for is an agent's attention
|
|
2577
|
+
on an argument, and a row of numbers is not asking for any.
|
|
2578
|
+
"""
|
|
2579
|
+
total = 0
|
|
2580
|
+
fence: str | None = None
|
|
2581
|
+
for raw in body.splitlines():
|
|
2582
|
+
line = raw.lstrip()
|
|
2583
|
+
if fence is not None:
|
|
2584
|
+
fence = None if line.startswith(fence) else fence
|
|
2585
|
+
elif line.startswith(_FENCES):
|
|
2586
|
+
fence = line[:3]
|
|
2587
|
+
elif not (line.startswith(_DATA) or raw.startswith(" ")):
|
|
2588
|
+
total += len(raw.split())
|
|
2589
|
+
return total
|
|
2590
|
+
|
|
2591
|
+
|
|
2592
|
+
# -- validation --------------------------------------------------------------
|
|
2593
|
+
|
|
2594
|
+
|
|
2595
|
+
#: The violations that are an author holding no address, and that `anchors` answers (RK349).
|
|
2596
|
+
#: `ref.missing` is a line with no pointer and `anchor.format` a section written at one that
|
|
2597
|
+
#: is not an address at all; both leave the caller looking for the same free number, and both
|
|
2598
|
+
#: used to state a rule and name nothing that satisfies it.
|
|
2599
|
+
_UNANCHORED = ("ref.missing", "anchor.format")
|
|
2600
|
+
|
|
2601
|
+
|
|
2602
|
+
@dataclass(frozen=True, slots=True)
|
|
2603
|
+
class Namespaced:
|
|
2604
|
+
"""A prose file's addresses moved into a namespace, with its own citations carried (RK1168).
|
|
2605
|
+
|
|
2606
|
+
Declaring `[refs]` re-addresses every heading in a file at once — 48 of them in the run this
|
|
2607
|
+
was measured on — and carried none of that file's own citations: seven dangled and twenty-one
|
|
2608
|
+
kept resolving, into the other file's section of the same address. The first half of this task
|
|
2609
|
+
made the second population a finding (`ref.crossed`); this is the transaction that stops
|
|
2610
|
+
creating it.
|
|
2611
|
+
|
|
2612
|
+
**Why it has to be one act.** At the moment the key is declared, every bare citation in that
|
|
2613
|
+
file *was* local by construction — they resolved to it before the namespace existed, which is
|
|
2614
|
+
what a namespace changes. A minute later the same citation is ambiguous, which is why the
|
|
2615
|
+
finding's remedy is `compose` and this one can be a rewrite: the transaction is what makes the
|
|
2616
|
+
answer knowable, and outside it nobody can say which section was meant.
|
|
2617
|
+
|
|
2618
|
+
An address and never a word of prose (L4): what changes is `§I.2` to `§S:I.2` inside a
|
|
2619
|
+
sentence nobody else touches — the same act `move` performs on the pointers at a section.
|
|
2620
|
+
"""
|
|
2621
|
+
|
|
2622
|
+
role: str
|
|
2623
|
+
namespace: str
|
|
2624
|
+
#: The file, with the citations rewritten. Saved by the caller, so the config write and this
|
|
2625
|
+
#: one land together or not at all.
|
|
2626
|
+
document: Document
|
|
2627
|
+
#: What was re-addressed, as `(anchor, line)`, so the report names every one.
|
|
2628
|
+
carried: tuple[tuple[str, int], ...]
|
|
2629
|
+
#: The configuration as it will read, rendered from the file that is there — a targeted
|
|
2630
|
+
#: insertion and never a serialiser, for `bump_version`'s reason: the rest of somebody's
|
|
2631
|
+
#: `roadkeep.toml` has to come back byte-identical.
|
|
2632
|
+
config_text: str
|
|
2633
|
+
|
|
2634
|
+
def stated(self, config: Config, wrote: Sequence[Path]) -> str:
|
|
2635
|
+
"""The key declared, and every citation carried into it (RK1168).
|
|
2636
|
+
|
|
2637
|
+
Beside :meth:`payload` since RK1170. The config's own path joins the staging line here
|
|
2638
|
+
and not in :attr:`config_text`'s write: it is the file this transaction's *other* half
|
|
2639
|
+
touched, and a commit that staged the prose and left the key is the half-declared state.
|
|
2640
|
+
"""
|
|
2641
|
+
from roadkeep.rendering import _staging_rows # noqa: PLC0415 - RK260
|
|
2642
|
+
|
|
2643
|
+
where = config.relative(config.path(self.role))
|
|
2644
|
+
source = config.relative(config.source)
|
|
2645
|
+
rows = [f'{source} [refs] {self.role} = "{self.namespace}"']
|
|
2646
|
+
# Named and not counted: this is a rewrite inside somebody's prose, and a number alone
|
|
2647
|
+
# is the diff a reviewer has to reconstruct to see what moved.
|
|
2648
|
+
rows += [
|
|
2649
|
+
f" carried §{anchor} → §{self.namespace}:{anchor} ({where}:{line})"
|
|
2650
|
+
for anchor, line in self.carried
|
|
2651
|
+
]
|
|
2652
|
+
if not self.carried:
|
|
2653
|
+
rows.append(f" carried nothing: {where} cites none of its own sections")
|
|
2654
|
+
rows += _staging_rows([where, source])
|
|
2655
|
+
return "\n".join(rows)
|
|
2656
|
+
|
|
2657
|
+
def payload(self, config: Config, wrote: Sequence[Path]) -> dict[str, object]:
|
|
2658
|
+
"""The same answer as data, naming both files the transaction wrote."""
|
|
2659
|
+
from roadkeep.rendering import _wrote_json # noqa: PLC0415 - RK260
|
|
2660
|
+
|
|
2661
|
+
return {
|
|
2662
|
+
"role": self.role,
|
|
2663
|
+
"namespace": self.namespace,
|
|
2664
|
+
"file": config.relative(config.path(self.role)),
|
|
2665
|
+
"config": config.relative(config.source),
|
|
2666
|
+
"carried": [
|
|
2667
|
+
{"anchor": anchor, "line": line} for anchor, line in self.carried
|
|
2668
|
+
],
|
|
2669
|
+
**_wrote_json(config, (*wrote, config.source)),
|
|
2670
|
+
}
|
|
2671
|
+
|
|
2672
|
+
|
|
2673
|
+
def namespaced(config: Config, role: str, prefix: str) -> Namespaced:
|
|
2674
|
+
"""Declare `[refs] <role>` and carry that file's own citations into it (RK1168).
|
|
2675
|
+
|
|
2676
|
+
Refuses rather than guesses in the three states it cannot answer for: a role this project
|
|
2677
|
+
does not declare as prose, a namespace this project already gives that role — where every
|
|
2678
|
+
citation is already qualified and there is nothing to carry — and a *different* namespace,
|
|
2679
|
+
which is a re-addressing whose citations carry the old prefix and whose answer is a different
|
|
2680
|
+
transaction from this one.
|
|
2681
|
+
"""
|
|
2682
|
+
if role not in PROSE_ROLES or not config.has(role):
|
|
2683
|
+
raise ValueError(
|
|
2684
|
+
f"{role} is not a prose file this project declares: `[refs]` names the namespace a "
|
|
2685
|
+
f"prose file's outline lives in, and the roles are {', '.join(sorted(PROSE_ROLES))}"
|
|
2686
|
+
)
|
|
2687
|
+
if not _NAMESPACE_RE.match(prefix):
|
|
2688
|
+
raise ValueError(
|
|
2689
|
+
f"'{prefix}' is not a namespace: one is the letters and digits before the colon of "
|
|
2690
|
+
f"an address like `S:I.2`, and a separator inside it would be a second address"
|
|
2691
|
+
)
|
|
2692
|
+
already = config.refs.get(role)
|
|
2693
|
+
if already == prefix:
|
|
2694
|
+
raise ValueError(
|
|
2695
|
+
f"{role} already lives in `{prefix}:`, so its citations are already qualified and "
|
|
2696
|
+
f"there is nothing to carry"
|
|
2697
|
+
)
|
|
2698
|
+
if already:
|
|
2699
|
+
raise ValueError(
|
|
2700
|
+
f"{role} already lives in `{already}:`, and moving it to `{prefix}:` re-addresses "
|
|
2701
|
+
f"citations that carry the old namespace — a different transaction from declaring one"
|
|
2702
|
+
)
|
|
2703
|
+
document = config.document(role)
|
|
2704
|
+
own = {section.anchor for section in anchored(document)}
|
|
2705
|
+
carried: list[tuple[str, int]] = []
|
|
2706
|
+
for cited in references(document):
|
|
2707
|
+
# The file's **own** addresses and no others, read as they stand *before* the key is
|
|
2708
|
+
# declared — which is the whole reason this is one transaction: right now a bare anchor
|
|
2709
|
+
# this file declares is unambiguously its own, and a citation of the other file's section
|
|
2710
|
+
# is already right and must not be moved into a namespace it has no section in.
|
|
2711
|
+
if cited.anchor not in own:
|
|
2712
|
+
continue
|
|
2713
|
+
at = cited.lineno - 1
|
|
2714
|
+
replaced = document.lines[at].replace(f"§{cited.anchor}", f"§{prefix}:{cited.anchor}")
|
|
2715
|
+
if replaced == document.lines[at]:
|
|
2716
|
+
continue
|
|
2717
|
+
carried.append((cited.anchor, cited.lineno))
|
|
2718
|
+
document = document.replace_line(at, replaced)
|
|
2719
|
+
return Namespaced(
|
|
2720
|
+
role=role,
|
|
2721
|
+
namespace=prefix,
|
|
2722
|
+
document=document,
|
|
2723
|
+
carried=tuple(carried),
|
|
2724
|
+
config_text=_with_namespace(config, role, prefix),
|
|
2725
|
+
)
|
|
2726
|
+
|
|
2727
|
+
|
|
2728
|
+
#: What a namespace may be: the letters and digits before the colon of an address (RK340). A
|
|
2729
|
+
#: separator inside one would make `S:I` two addresses rather than one.
|
|
2730
|
+
_NAMESPACE_RE = re.compile(r"^[A-Za-z0-9]+$")
|
|
2731
|
+
|
|
2732
|
+
|
|
2733
|
+
def _with_namespace(config: Config, role: str, prefix: str) -> str:
|
|
2734
|
+
"""This project's `roadkeep.toml` with one key added, and every other byte as it was.
|
|
2735
|
+
|
|
2736
|
+
A targeted insertion and never a serialiser, which is `bump_version`'s rule about the two
|
|
2737
|
+
files that state a version: a `tomllib` round-trip is not one — it drops the comments a
|
|
2738
|
+
scaffolded config is mostly made of, and rewriting somebody's file to add a line is the
|
|
2739
|
+
destructive formatting L3 refuses one layer down.
|
|
2740
|
+
"""
|
|
2741
|
+
if config.source is None:
|
|
2742
|
+
raise ValueError("this project declares no roadkeep.toml to add a namespace to")
|
|
2743
|
+
text = config.source.read_text(encoding="utf-8")
|
|
2744
|
+
row = f'{role} = "{prefix}"\n'
|
|
2745
|
+
if "\n[refs]\n" in text or text.startswith("[refs]\n"):
|
|
2746
|
+
at = text.index("[refs]\n") + len("[refs]\n")
|
|
2747
|
+
return text[:at] + row + text[at:]
|
|
2748
|
+
# A table of its own, at the end: a key appended under whatever table happens to be last
|
|
2749
|
+
# would belong to that table, which is the one way this write can be silently wrong.
|
|
2750
|
+
joined = "" if text.endswith("\n") else "\n"
|
|
2751
|
+
return f"{text}{joined}\n[refs]\n{row}"
|
|
2752
|
+
|
|
2753
|
+
|
|
2754
|
+
def naming_the_anchor(
|
|
2755
|
+
config: Config,
|
|
2756
|
+
block: str | None,
|
|
2757
|
+
error: SchemaError,
|
|
2758
|
+
*,
|
|
2759
|
+
namespace: str = "",
|
|
2760
|
+
anchor: str = "",
|
|
2761
|
+
) -> SchemaError:
|
|
2762
|
+
"""The same refusal, told which command answers it (RK312, widened by RK349).
|
|
2763
|
+
|
|
2764
|
+
This project's own standard applied to itself. `ref: every task points at its rationale
|
|
2765
|
+
section` states the rule and names nothing that satisfies it — and `--ref` is the one
|
|
2766
|
+
required field of the write path that is neither derived nor guessable, wrong *silently*
|
|
2767
|
+
if the number picked is one some heading already spent. `anchors` answers it exactly, and
|
|
2768
|
+
there was no way to learn that from the refusal; the two reads it replaced were a glob of
|
|
2769
|
+
the pointers per block and a grep of the prose file's headings, done four times by hand.
|
|
2770
|
+
|
|
2771
|
+
Here rather than in `authoring`, which is where RK312 wrote it, because the doors that
|
|
2772
|
+
reach it are on both sides of that import: `place` validates the line `add`, `defer` and
|
|
2773
|
+
`resume` each write, and :func:`add` below validates the anchor `section add` passes.
|
|
2774
|
+
One function, so a fifth door is a call and not a fifth copy of the sentence.
|
|
2775
|
+
|
|
2776
|
+
Every other violation rides through untouched, the error keeps its own class, and the
|
|
2777
|
+
sentence is **appended** rather than replaced: what the rule is has to survive, because
|
|
2778
|
+
a refusal that only says what to type teaches nobody why the field exists.
|
|
2779
|
+
|
|
2780
|
+
``block`` is `None` where the anchor names no live task, and that is not the caller to
|
|
2781
|
+
stay silent for (RK360) — it is the one holding no address at all, since typing a task id
|
|
2782
|
+
is what produces a block to read. What changes is which address is offered, and that is
|
|
2783
|
+
:func:`_where_a_top_level_is`'s to decide from the anchor itself: a family the caller
|
|
2784
|
+
already typed gets its next child, and everything else gets the free top-level. Never a
|
|
2785
|
+
family derived from whichever one happened to be last, which is the guess the two-family
|
|
2786
|
+
branch below also refuses to make.
|
|
2787
|
+
|
|
2788
|
+
Silent where history cannot be searched, which is where the free address cannot be
|
|
2789
|
+
derived: naming a number this could not verify is the failure the whole read exists to
|
|
2790
|
+
prevent, and the command that can say so is still named.
|
|
2791
|
+
"""
|
|
2792
|
+
named = tuple(one for one in error.violations if one.code in _UNANCHORED)
|
|
2793
|
+
if not named:
|
|
2794
|
+
return error
|
|
2795
|
+
clause, free = (
|
|
2796
|
+
_where_a_top_level_is(config, namespace, anchor)
|
|
2797
|
+
if block is None
|
|
2798
|
+
else _where_the_anchor_is(config, block)
|
|
2799
|
+
)
|
|
2800
|
+
refusal = type(error)(
|
|
2801
|
+
tuple(
|
|
2802
|
+
replace(one, message=f"{one.message}{clause}") if one in named else one
|
|
2803
|
+
for one in error.violations
|
|
2804
|
+
)
|
|
2805
|
+
)
|
|
2806
|
+
# The address as **data** on the refusal, for the surface that can turn it into a retry
|
|
2807
|
+
# (RK1149). On the exception and not in a slot somewhere: it is one refusal's fact, it
|
|
2808
|
+
# travels with the object that carries the refusal, and a reader that finds no attribute
|
|
2809
|
+
# gets today's behaviour rather than a stale answer about an earlier call.
|
|
2810
|
+
if free:
|
|
2811
|
+
refusal.offered = free
|
|
2812
|
+
return refusal
|
|
2813
|
+
|
|
2814
|
+
|
|
2815
|
+
def checked(config: Config, task: Task, *, schema: Schema | None = None) -> Task:
|
|
2816
|
+
"""`schema.check`, with the anchor named — the seam a **rewrite** passes (RK379).
|
|
2817
|
+
|
|
2818
|
+
RK312 enriched the refusal an `add` raises and RK349 widened it to the other doors that
|
|
2819
|
+
*insert* a line, by putting the call in :func:`~roadkeep.authoring.place`. Every door that
|
|
2820
|
+
rewrites a line already on the file misses that seam entirely: `amend`, `restate`, `status`
|
|
2821
|
+
and `renumber` each validate the task they composed and none of them goes through `place`.
|
|
2822
|
+
|
|
2823
|
+
So the bare rule survived exactly where an adopting project meets it. `ref.missing` on an
|
|
2824
|
+
insertion is a field the author forgot; on a rewrite it is a line that was **imported
|
|
2825
|
+
without a pointer**, which is the whole population `amend` exists for — the author is
|
|
2826
|
+
correcting that line's `why`, is told a pointer is required, and is told nothing about
|
|
2827
|
+
which address is free. That is the same measured cost RK312 removed, on the door the
|
|
2828
|
+
correction path actually uses.
|
|
2829
|
+
|
|
2830
|
+
Not folded into `place`, which takes a :class:`~roadkeep.kernel.document.Document` and an optional
|
|
2831
|
+
config: these callers hold a :class:`Config` unconditionally, and a rewrite has no
|
|
2832
|
+
insertion to make. The enrichment stays :func:`naming_the_anchor`, so this is a call and
|
|
2833
|
+
still not a copy of the sentence.
|
|
2834
|
+
|
|
2835
|
+
``schema`` is which grammar validates, and it is a parameter because `renumber` moves an
|
|
2836
|
+
id that may be the **ledger's**: a shipped entry is `as_ledger()`, which requires no
|
|
2837
|
+
pointer at all, and validating one against the roadmap's schema would refuse an entry for
|
|
2838
|
+
lacking a field its own file has no column for. The default is this project's roadmap
|
|
2839
|
+
schema, which is every other caller.
|
|
2840
|
+
"""
|
|
2841
|
+
try:
|
|
2842
|
+
return (schema or config.schema).check(task)
|
|
2843
|
+
except SchemaError as error:
|
|
2844
|
+
raise naming_the_anchor(config, task.block, error) from None
|
|
2845
|
+
|
|
2846
|
+
|
|
2847
|
+
def _where_the_anchor_is(config: Config, block: str) -> tuple[str, str]:
|
|
2848
|
+
"""The clause an unanchored refusal ends with, and the address it offers (RK1149).
|
|
2849
|
+
|
|
2850
|
+
A pair, because the sentence and the anchor are read by different surfaces: the clause is
|
|
2851
|
+
what a human reads and the anchor is what a **retry** needs, and until this the second only
|
|
2852
|
+
existed inside the first. `""` where none could be derived — the two cases this already
|
|
2853
|
+
refused to guess in — so a caller has nothing to substitute and says so by having nothing.
|
|
2854
|
+
"""
|
|
2855
|
+
# Deferred for RK260's reason, and because git belongs on no successful write path.
|
|
2856
|
+
from roadkeep.history import ( # noqa: PLC0415
|
|
2857
|
+
HistoryUnavailable,
|
|
2858
|
+
anchors,
|
|
2859
|
+
families_of_block,
|
|
2860
|
+
next_child,
|
|
2861
|
+
)
|
|
2862
|
+
from roadkeep.provenance import invocation # noqa: PLC0415
|
|
2863
|
+
|
|
2864
|
+
spans = families_of_block(config, block)
|
|
2865
|
+
if len(spans) > 1:
|
|
2866
|
+
# A block that reopened under a fresh top-level. Two families is a real answer and the
|
|
2867
|
+
# tool must not pick between them (RK312), so the command that lists both is still the
|
|
2868
|
+
# whole of it — the one case here where the path forks on a judgement, and so the one
|
|
2869
|
+
# RK1198 leaves exactly as it was.
|
|
2870
|
+
return (
|
|
2871
|
+
f" — `{invocation()} anchors --block {block}` says which family this block's "
|
|
2872
|
+
f"prose lives under, and `anchors` alone names the free top-level"
|
|
2873
|
+
), ""
|
|
2874
|
+
if not spans:
|
|
2875
|
+
# And none is a block whose prose has not started, which is not the same question
|
|
2876
|
+
# (RK1198): the two shared a sentence, and the sentence sent an author who was six
|
|
2877
|
+
# calls from a first write to a command that answers one of them.
|
|
2878
|
+
return _the_path_into(config, block)
|
|
2879
|
+
family = spans[0]
|
|
2880
|
+
try:
|
|
2881
|
+
free = next_child(anchors(config), family)
|
|
2882
|
+
except (HistoryUnavailable, OSError):
|
|
2883
|
+
return (
|
|
2884
|
+
f" — Block {block}'s prose is under §{family}, and "
|
|
2885
|
+
f"`{invocation()} anchors --family {family}` says which address is free"
|
|
2886
|
+
), ""
|
|
2887
|
+
return (
|
|
2888
|
+
f" — Block {block}'s prose is under §{family}, where §{free} is free "
|
|
2889
|
+
f"(`{invocation()} anchors --block {block}` lists it)"
|
|
2890
|
+
), free
|
|
2891
|
+
|
|
2892
|
+
|
|
2893
|
+
def _the_path_into(config: Config, block: str) -> tuple[str, str]:
|
|
2894
|
+
"""Every verb between this refusal and the line that lands, with its arguments (RK1198).
|
|
2895
|
+
|
|
2896
|
+
Observed filing three tasks into a project whose `ref_scheme` is `outline`, into blocks
|
|
2897
|
+
whose every line had shipped. Each refusal was individually correct and named the next
|
|
2898
|
+
verb; together they were a staircase, and six calls stood between prose that was ready at
|
|
2899
|
+
call one and the first write. The information was there at the first refusal — it knew the
|
|
2900
|
+
block, whether a heading declared it, that its families were spent and what the next free
|
|
2901
|
+
top-level was, which is everything the remaining five calls established.
|
|
2902
|
+
|
|
2903
|
+
So reporting one step is right when a caller is one step from done and wrong when they are
|
|
2904
|
+
six, because a staircase discovered a stair at a time reads as a tool changing its mind.
|
|
2905
|
+
The refusal carries the path rather than a `--plan` flag doing it, for the reason the
|
|
2906
|
+
whole clause exists: this is the moment the author is actually in, and a flag is one more
|
|
2907
|
+
thing to have learnt first.
|
|
2908
|
+
|
|
2909
|
+
Filled in and not described: the block, the address and the ledger's own spelling are all
|
|
2910
|
+
derived here, so what is left in angle brackets is the title, which is editorial and L4's
|
|
2911
|
+
to leave alone. `""` for the address wherever the outline's numbering does not derive one
|
|
2912
|
+
— the same silence :func:`_where_a_top_level_is` keeps, since a path opening on a number
|
|
2913
|
+
this could not verify is worse than the command that reads it.
|
|
2914
|
+
"""
|
|
2915
|
+
# Deferred for RK260's reason, and because git belongs on no successful write path.
|
|
2916
|
+
from roadkeep.authoring import prose_role # noqa: PLC0415
|
|
2917
|
+
from roadkeep.blocking import BLOCK_ROLES # noqa: PLC0415
|
|
2918
|
+
from roadkeep.history import ( # noqa: PLC0415
|
|
2919
|
+
HistoryUnavailable,
|
|
2920
|
+
anchors,
|
|
2921
|
+
next_child,
|
|
2922
|
+
next_family,
|
|
2923
|
+
)
|
|
2924
|
+
from roadkeep.provenance import invocation # noqa: PLC0415
|
|
2925
|
+
|
|
2926
|
+
role = prose_role(config, on_disk=True)
|
|
2927
|
+
started = f" — Block {block}'s prose has not started"
|
|
2928
|
+
try:
|
|
2929
|
+
taken = () if role is None else anchors(config)
|
|
2930
|
+
except (HistoryUnavailable, OSError):
|
|
2931
|
+
taken = ()
|
|
2932
|
+
family = None if role is None else next_family(taken, config.schema_for(role).ref_prefix)
|
|
2933
|
+
if family is None:
|
|
2934
|
+
# An outline with no family at all, one whose top-levels are not one numbering, or a
|
|
2935
|
+
# history that cannot be read: all three are numbers this could not verify, and a path
|
|
2936
|
+
# opening on a guessed address is worse than the command that reads the real one
|
|
2937
|
+
# (RK340, RK293).
|
|
2938
|
+
return (
|
|
2939
|
+
f"{started}, and `{invocation()} anchors` names the free top-level it opens at"
|
|
2940
|
+
), ""
|
|
2941
|
+
# The task's design is a **child** of that family, through
|
|
2942
|
+
# :func:`~roadkeep.history.next_child` rather than spelled here, so the one writer of a
|
|
2943
|
+
# child address stays the one writer of it.
|
|
2944
|
+
free = next_child(taken, family)
|
|
2945
|
+
steps = [
|
|
2946
|
+
# The family first, and it is the stair nobody sees coming: `section add <free>`
|
|
2947
|
+
# refuses with nothing to extend, and so does an `add --section` naming the same
|
|
2948
|
+
# address, because an anchor states its own place and a fresh top-level has no prose
|
|
2949
|
+
# yet. A free family exists nowhere by construction, so this step is unconditional.
|
|
2950
|
+
f'section add {family} --title "<its title>"',
|
|
2951
|
+
f"add --block {block} --ref {free} …",
|
|
2952
|
+
# Named although the `add` above prints it on success: the whole point is that the
|
|
2953
|
+
# path is legible at call one, and a last step that only appears once the fourth call
|
|
2954
|
+
# lands is the staircase again with one stair left on it.
|
|
2955
|
+
f"section add {free} --title …",
|
|
2956
|
+
]
|
|
2957
|
+
if any(
|
|
2958
|
+
not config.document(one).declaring(block)
|
|
2959
|
+
for one in BLOCK_ROLES
|
|
2960
|
+
if config.has(one) and config.path(one).is_file()
|
|
2961
|
+
):
|
|
2962
|
+
# Ahead of them all, because it is the refusal the retry walks into next: a label no
|
|
2963
|
+
# heading declares is `add`'s own second door, one call further down the stairs.
|
|
2964
|
+
steps.insert(0, f'block add {block} --title "<its title>"')
|
|
2965
|
+
return (
|
|
2966
|
+
f"{started} and §{family} is its free top-level, so filing here is "
|
|
2967
|
+
+ ", then ".join(f"`{invocation()} {one}`" for one in steps)
|
|
2968
|
+
), free
|
|
2969
|
+
|
|
2970
|
+
|
|
2971
|
+
def _where_a_top_level_is(config: Config, namespace: str, anchor: str = "") -> tuple[str, str]:
|
|
2972
|
+
"""The same clause for an anchor belonging to nobody: a free address, or the command.
|
|
2973
|
+
|
|
2974
|
+
A pair for :func:`_where_the_anchor_is`' reason (RK1149): the second half is the address a
|
|
2975
|
+
retry substitutes, and `""` wherever this declines to name one.
|
|
2976
|
+
|
|
2977
|
+
**Which** free address is decided by what the caller typed (RK363). A malformed anchor
|
|
2978
|
+
whose leading segment is a family that exists is a typo inside that family — `XVII-1`
|
|
2979
|
+
is a hyphen where a dot belongs — and answering it with a new top-level says *start a
|
|
2980
|
+
new subtree*, which is the one thing that author was not doing. So the segment is read
|
|
2981
|
+
and, where it names a live family, that family's next child is the answer.
|
|
2982
|
+
|
|
2983
|
+
That is not the guess RK360 refused to make. Deriving a family from whichever one
|
|
2984
|
+
happened to be last is context this cannot verify; reading the front of the address the
|
|
2985
|
+
caller wrote down is the same read :func:`split_ref` already makes, and it answers
|
|
2986
|
+
nothing where the segment names no family.
|
|
2987
|
+
|
|
2988
|
+
The top-level is what remains, per namespace, for :func:`~roadkeep.history.next_family`'s
|
|
2989
|
+
reason (RK340): two prose files each numbering themselves from `I` have two free
|
|
2990
|
+
top-levels, and the taller file's number is not an answer about the shorter one.
|
|
2991
|
+
"""
|
|
2992
|
+
# Deferred for RK260's reason, and because git belongs on no successful write path.
|
|
2993
|
+
from roadkeep.history import ( # noqa: PLC0415
|
|
2994
|
+
HistoryUnavailable,
|
|
2995
|
+
anchors,
|
|
2996
|
+
next_child,
|
|
2997
|
+
next_family,
|
|
2998
|
+
)
|
|
2999
|
+
from roadkeep.provenance import invocation # noqa: PLC0415
|
|
3000
|
+
|
|
3001
|
+
try:
|
|
3002
|
+
taken = anchors(config)
|
|
3003
|
+
except (HistoryUnavailable, OSError):
|
|
3004
|
+
return f" — `{invocation()} anchors` names the addresses this outline has taken", ""
|
|
3005
|
+
family = _family_typed(taken, namespace, anchor)
|
|
3006
|
+
if family is not None:
|
|
3007
|
+
child = next_child(taken, family)
|
|
3008
|
+
return (
|
|
3009
|
+
f" — §{family} is a family that exists, where §{child} is "
|
|
3010
|
+
f"free (`{invocation()} anchors --family {family}` lists it)"
|
|
3011
|
+
), child
|
|
3012
|
+
free = next_family(taken, namespace)
|
|
3013
|
+
if free is None:
|
|
3014
|
+
# None is the honest answer where the top-levels are not one numbering, and a guess
|
|
3015
|
+
# printed beside a rule reads exactly like a fact.
|
|
3016
|
+
return f" — `{invocation()} anchors` names the addresses this outline has taken", ""
|
|
3017
|
+
return (
|
|
3018
|
+
f" — a section belonging to no task takes a top-level, and §{free} is free "
|
|
3019
|
+
f"(`{invocation()} anchors` lists what is taken)"
|
|
3020
|
+
), free
|
|
3021
|
+
|
|
3022
|
+
|
|
3023
|
+
#: What counts as the segment a malformed address opens with: the letters and digits before
|
|
3024
|
+
#: whatever separator was typed wrong. `XVII-1` and `XVII 1` are one mistake (RK363).
|
|
3025
|
+
_LEADING = re.compile(r"[A-Za-z0-9]+")
|
|
3026
|
+
|
|
3027
|
+
|
|
3028
|
+
def _family_typed(taken: Sequence[Anchor], namespace: str, anchor: str) -> str | None:
|
|
3029
|
+
"""The live family this malformed address opens with, spelled as its anchors spell it."""
|
|
3030
|
+
if not anchor:
|
|
3031
|
+
return None
|
|
3032
|
+
head = _LEADING.match(split_ref(anchor)[1])
|
|
3033
|
+
if head is None:
|
|
3034
|
+
return None
|
|
3035
|
+
for one in taken:
|
|
3036
|
+
space, bare = split_ref(one.anchor)
|
|
3037
|
+
if space == namespace and bare.split(".")[0] == head.group():
|
|
3038
|
+
return one.anchor.split(".")[0]
|
|
3039
|
+
return None
|
|
3040
|
+
|
|
3041
|
+
|
|
3042
|
+
def _outline_violation(schema: Schema, anchor: str) -> Violation | None:
|
|
3043
|
+
"""What is wrong with this address under an outline — its namespace, or its shape.
|
|
3044
|
+
|
|
3045
|
+
Namespace first, because it is the question the other one cannot answer: `S:I` fails
|
|
3046
|
+
every reading of `<x.y>` and saying so would send an author to fix a spelling that is
|
|
3047
|
+
correct for the file they meant (RK340).
|
|
3048
|
+
"""
|
|
3049
|
+
here = local(schema, anchor)
|
|
3050
|
+
if here is None:
|
|
3051
|
+
# An address in another role's namespace, written into this file: refused rather
|
|
3052
|
+
# than resolved, because the write was told which role it is for and the anchor
|
|
3053
|
+
# names a different one — and the heading drops the prefix, so the disagreement
|
|
3054
|
+
# would not survive in the file to be seen.
|
|
3055
|
+
return Violation(
|
|
3056
|
+
"anchor.namespace",
|
|
3057
|
+
"anchor",
|
|
3058
|
+
f"{anchor!r} is not an address in this file's namespace ("
|
|
3059
|
+
f"{schema.ref_prefix or 'none'}, per [refs]): a section written here is one "
|
|
3060
|
+
f"every pointer to that address resolves somewhere else",
|
|
3061
|
+
)
|
|
3062
|
+
if not OUTLINE_ANCHOR_RE.match(here):
|
|
3063
|
+
# Refused rather than written, because the heading would be read back by nothing:
|
|
3064
|
+
# under this scheme the number is what announces a section (RK44), so an anchor
|
|
3065
|
+
# that is not one is a section invisible from the moment it reaches the file.
|
|
3066
|
+
return Violation(
|
|
3067
|
+
"anchor.format",
|
|
3068
|
+
"anchor",
|
|
3069
|
+
f"not an <x.y> outline anchor: {anchor!r} — under ref_scheme = outline "
|
|
3070
|
+
f"the heading numbers itself, and a heading with no number is prose",
|
|
3071
|
+
)
|
|
3072
|
+
return None
|
|
3073
|
+
|
|
3074
|
+
|
|
3075
|
+
def addressable(schema: Schema, anchor: str) -> bool:
|
|
3076
|
+
"""Whether this scheme could read the token as a section address at all (RK1025).
|
|
3077
|
+
|
|
3078
|
+
The public half of :func:`_address_violation`, for a reader that has an argument and no
|
|
3079
|
+
section: `show` refuses a token that is not a task id, and whether the token is one this
|
|
3080
|
+
file's outline *numbers* is what decides between "never written" and "you want the other
|
|
3081
|
+
verb". A predicate rather than the violation, because nothing here is being refused —
|
|
3082
|
+
the caller is deciding which sentence to print.
|
|
3083
|
+
|
|
3084
|
+
**Only decidable under an outline**, and it says so by answering `False` everywhere
|
|
3085
|
+
else: under the `id` scheme an anchor is an id, so every token this could be asked about
|
|
3086
|
+
is either already a task or nothing at all, and answering `True` would name a section
|
|
3087
|
+
verb for an argument that is simply a typo.
|
|
3088
|
+
"""
|
|
3089
|
+
if schema.ref_scheme != "outline":
|
|
3090
|
+
return False
|
|
3091
|
+
return _address_violation(schema, anchor) is None
|
|
3092
|
+
|
|
3093
|
+
|
|
3094
|
+
def _address_violation(schema: Schema, anchor: str) -> Violation | None:
|
|
3095
|
+
"""What is wrong with this address as an address, whichever scheme reads it (RK377).
|
|
3096
|
+
|
|
3097
|
+
The half of :func:`_check` a verb that writes no prose still has to make: `move` validates
|
|
3098
|
+
a destination and has no title and no body to be told about, and re-spelling two branches
|
|
3099
|
+
at that call site is the second reader of a rule this module keeps one of.
|
|
3100
|
+
"""
|
|
3101
|
+
if not anchor or anchor.startswith("§"):
|
|
3102
|
+
return Violation("anchor.sigil", "anchor", f"store the anchor without §: {anchor!r}")
|
|
3103
|
+
if schema.ref_scheme == "outline":
|
|
3104
|
+
return _outline_violation(schema, anchor)
|
|
3105
|
+
return None
|
|
3106
|
+
|
|
3107
|
+
|
|
3108
|
+
def _inherited(body: str, standing: int | None) -> bool:
|
|
3109
|
+
"""Whether this overrun was already in the file before the call (RK1263).
|
|
3110
|
+
|
|
3111
|
+
``standing`` is what the prose spent before the edit, and `None` is every caller that
|
|
3112
|
+
composed the whole body — there the overrun is theirs by construction. Where it is a
|
|
3113
|
+
number, an edit that leaves the count where it was or below it is one the file's standing
|
|
3114
|
+
debt refuses, not the caller: `lint` still reports the section, and the finding is about
|
|
3115
|
+
the paragraph rather than about the four characters somebody corrected inside it.
|
|
3116
|
+
|
|
3117
|
+
Not *equal* and not a tolerance: the comparison is `<=`, so shortening an over-long section
|
|
3118
|
+
towards the limit is always allowed and growing it never is.
|
|
3119
|
+
"""
|
|
3120
|
+
return standing is not None and words(body) <= standing
|
|
3121
|
+
|
|
3122
|
+
|
|
3123
|
+
def _check(
|
|
3124
|
+
schema: Schema,
|
|
3125
|
+
anchor: str,
|
|
3126
|
+
title: str,
|
|
3127
|
+
body: str,
|
|
3128
|
+
task: Task | None,
|
|
3129
|
+
*,
|
|
3130
|
+
elsewhere: Whereabouts | None = None,
|
|
3131
|
+
known: frozenset[str] | None = None,
|
|
3132
|
+
resolves: frozenset[str] | None = None,
|
|
3133
|
+
standing: int | None = None,
|
|
3134
|
+
) -> None:
|
|
3135
|
+
"""Every rule a section is refused by, under **this file's** schema (RK147).
|
|
3136
|
+
|
|
3137
|
+
``elsewhere`` is where an id no live role holds actually is, threaded in rather than read
|
|
3138
|
+
here (RK238): this function takes a schema and not a project, which is what keeps it the
|
|
3139
|
+
one place the *rules* live — and the door an unknown anchor should be handed is a fact
|
|
3140
|
+
about the caller's files. `None` is the caller saying there is nothing to say, which
|
|
3141
|
+
`_elsewhere` decides.
|
|
3142
|
+
|
|
3143
|
+
The schema is the one the caller loaded the document under — `config.schema_for(role)`,
|
|
3144
|
+
which is what `[limits.improvements]` declares (RK50) — and never `config.schema`, which
|
|
3145
|
+
is the project's top-level numbers. L1 is the first law: the format is enforced where
|
|
3146
|
+
the text is created, and reading a different limit here than the gate charges is exactly
|
|
3147
|
+
the failure it names. A project declaring a *tighter* rationale budget got it only after
|
|
3148
|
+
the paragraph existed; one declaring a *looser* one had this door refusing prose the gate
|
|
3149
|
+
would accept, which is worse — a refusal on legal text is a refusal an author routes
|
|
3150
|
+
around. Threaded rather than looked up again, so the two readings cannot disagree.
|
|
3151
|
+
|
|
3152
|
+
The **binding** is not refused here and is not checked here at all: :func:`_bound` has
|
|
3153
|
+
already rendered it (RK262), so by the time a title reaches this function it names the
|
|
3154
|
+
task the anchor names, and a violation for the state that cannot arrive is a rule nobody
|
|
3155
|
+
can trip.
|
|
3156
|
+
"""
|
|
3157
|
+
out: list[Violation] = []
|
|
3158
|
+
if (bad := _address_violation(schema, anchor)) is not None:
|
|
3159
|
+
out.append(bad)
|
|
3160
|
+
elif schema.id_pattern().match(anchor) and task is None:
|
|
3161
|
+
# The pointer is the id (RK27), so an id-shaped anchor that names no live task is
|
|
3162
|
+
# a section nothing can ever point at — an orphan the moment it is written. *Live*
|
|
3163
|
+
# and not open (RK231): a paused line keeps its id and its pointer, so its design is
|
|
3164
|
+
# amendable, and the word here is the one `_task_for` reads.
|
|
3165
|
+
out.append(Violation("anchor.unknown", "anchor", _unknown(anchor, elsewhere)))
|
|
3166
|
+
if not title.strip():
|
|
3167
|
+
out.append(Violation("title.empty", "title", "a section is named by its heading"))
|
|
3168
|
+
elif "\n" in title or "\r" in title:
|
|
3169
|
+
out.append(Violation("title.newline", "title", "a heading is one line"))
|
|
3170
|
+
elif title.lstrip().startswith("#"):
|
|
3171
|
+
out.append(
|
|
3172
|
+
Violation("title.markup", "title", "the level is a field, not part of the text")
|
|
3173
|
+
)
|
|
3174
|
+
elif title.strip() == anchor or title.strip() == f"§{anchor}":
|
|
3175
|
+
# The address stated twice with no words in it (RK1329). Measured across one session:
|
|
3176
|
+
# nine sections filed and nine titled with their own anchor, every one by a caller who
|
|
3177
|
+
# had just been thinking in ids and read a bare positional beside `--block` as one.
|
|
3178
|
+
# Nothing refused it, any string being a legal heading, and `show` and `brief` then
|
|
3179
|
+
# print `§RK1320 RK1320` where the title is the line saying what the design argues.
|
|
3180
|
+
#
|
|
3181
|
+
# Knowable at the door, which is where this format puts a limit: the write mints the
|
|
3182
|
+
# id and is handed the title in the same call, so the comparison is free. Not a rule
|
|
3183
|
+
# about the id scheme — under an outline the anchor is passed explicitly and a title
|
|
3184
|
+
# equal to it is the same degenerate heading, so this is checked against whichever
|
|
3185
|
+
# address the caller is writing under.
|
|
3186
|
+
out.append(
|
|
3187
|
+
Violation(
|
|
3188
|
+
"title.is-anchor",
|
|
3189
|
+
"title",
|
|
3190
|
+
f"the heading would read `§{anchor} {title.strip()}`: the anchor is already "
|
|
3191
|
+
f"the address, so this argument is the sentence the design argues",
|
|
3192
|
+
)
|
|
3193
|
+
)
|
|
3194
|
+
out += promised(schema, body, known)
|
|
3195
|
+
# The one thing prose can be wrong about mechanically, asked where the text is created
|
|
3196
|
+
# (RK1227, L1). Found in Shio filing SH763: its rationale cited `§XVII.100`, an anchor a
|
|
3197
|
+
# task had removed when it shipped, and this write took it without complaint — surfacing
|
|
3198
|
+
# two commits later as a **red gate in that project**, on a docs-only commit that had
|
|
3199
|
+
# touched nothing else. Length was checked and paragraph shape was checked; whether the
|
|
3200
|
+
# address resolves was not asked, though the file was open and the answer is a lookup.
|
|
3201
|
+
#
|
|
3202
|
+
# Threaded like `known` and never resolved here (RK238): this function takes a schema and
|
|
3203
|
+
# not a project, which is what keeps it the one place the *rules* live — and which
|
|
3204
|
+
# addresses exist is a fact about the caller's files. `None` is a caller with nothing to
|
|
3205
|
+
# say, which is every call that cannot open them.
|
|
3206
|
+
if resolves is not None:
|
|
3207
|
+
dangling = [one for one in cited_in(body) if one not in resolves]
|
|
3208
|
+
if dangling:
|
|
3209
|
+
out.append(
|
|
3210
|
+
Violation(
|
|
3211
|
+
"ref.dangling",
|
|
3212
|
+
"body",
|
|
3213
|
+
f"cites {', '.join('§' + one for one in dangling)}, which no prose file "
|
|
3214
|
+
f"declares: a citation of an address a ship removed reads as an argument "
|
|
3215
|
+
f"the reader can follow, and the gate finds it in somebody else's commit",
|
|
3216
|
+
)
|
|
3217
|
+
)
|
|
3218
|
+
if not body.strip():
|
|
3219
|
+
out.append(Violation("body.empty", "body", "a section with no prose is a heading"))
|
|
3220
|
+
elif words(body) > schema.section_max and not _inherited(body, standing):
|
|
3221
|
+
out.append(
|
|
3222
|
+
Violation(
|
|
3223
|
+
"body.too-long",
|
|
3224
|
+
"body",
|
|
3225
|
+
f"{over_by(words(body), schema.section_max, unit='word')}; a section "
|
|
3226
|
+
f"this long is two sections, or a paragraph that belongs in the commit"
|
|
3227
|
+
# Where the words are, on the refusal that discards them (RK311): the
|
|
3228
|
+
# overage says a cut is needed, and this says where one is available, so
|
|
3229
|
+
# the second draft is composed once instead of counted by hand.
|
|
3230
|
+
f"{_where_the_words_are(body)}",
|
|
3231
|
+
)
|
|
3232
|
+
)
|
|
3233
|
+
if out:
|
|
3234
|
+
raise SectionError(tuple(out))
|
|
3235
|
+
|
|
3236
|
+
|
|
3237
|
+
def binding(config: Config, role: str, anchor: str) -> tuple[int, int] | None:
|
|
3238
|
+
"""What this address charges anything written **under** it, and against what limit.
|
|
3239
|
+
|
|
3240
|
+
`(words, limit)`, or `None` where nothing written under this anchor is charged to it —
|
|
3241
|
+
which is two states and not one: the address names no section, or it names a container
|
|
3242
|
+
nothing points at. A pointer hands a reader the whole subtree, so a *pointed-at* section
|
|
3243
|
+
is billed with its children and therefore binds them; a container is billed its own
|
|
3244
|
+
prose, and charging its children to it would price a body against a heading the gate does
|
|
3245
|
+
not bill (RK215). Both readers of this — `anchors` offering a child address (RK1024), and
|
|
3246
|
+
`budget` pricing one (RK1029) — want exactly the second question, and asking it here is
|
|
3247
|
+
what keeps them from deriving two answers to it.
|
|
3248
|
+
|
|
3249
|
+
A read, so it decides nothing: `anchors` states the number and still prints the address,
|
|
3250
|
+
because an author about to shorten the parent is holding a plan no count can see.
|
|
3251
|
+
"""
|
|
3252
|
+
if not config.has(role) or not _pointed_at(config, anchor):
|
|
3253
|
+
return None
|
|
3254
|
+
section = find(config.document(role), anchor)
|
|
3255
|
+
if section is None:
|
|
3256
|
+
return None
|
|
3257
|
+
return section.words, config.schema_for(role).section_max
|
|
3258
|
+
|
|
3259
|
+
|
|
3260
|
+
def known(config: Config, anchor: str, task: Task | None) -> frozenset[str]:
|
|
3261
|
+
"""The ids a design may name: every one some file carries, plus this task's own.
|
|
3262
|
+
|
|
3263
|
+
The task's own is added because `add --section` writes the line and the prose in one
|
|
3264
|
+
transaction and the prose is checked first — so at this moment the id it explains is not
|
|
3265
|
+
yet carried by anything, and refusing a design for naming the task it is the design of
|
|
3266
|
+
would be the refusal reading the transaction backwards.
|
|
3267
|
+
"""
|
|
3268
|
+
# Deferred: `ids` reads the documents this module writes into (RK260).
|
|
3269
|
+
from roadkeep.ids import carried # noqa: PLC0415 - RK1002
|
|
3270
|
+
|
|
3271
|
+
own = {anchor} if task is None else {task.id, anchor}
|
|
3272
|
+
return carried(config) | frozenset(own)
|
|
3273
|
+
|
|
3274
|
+
|
|
3275
|
+
def resolvable(config: Config, anchor: str) -> frozenset[str]:
|
|
3276
|
+
"""Every anchor a body may cite: those the prose files declare, plus the one being written.
|
|
3277
|
+
|
|
3278
|
+
Across **every** prose role and never one document's (RK1227, following RK1106's reading):
|
|
3279
|
+
a citation of `§S:I.2` from the improvements file is a reference into the strategy file,
|
|
3280
|
+
and asking one document would refuse the correct half of a project's prose.
|
|
3281
|
+
|
|
3282
|
+
The anchor being written is included for :func:`known`'s reason one field over: `section
|
|
3283
|
+
add` is checked before it writes, so a design citing the address it *is* would be refused
|
|
3284
|
+
by the transaction reading itself backwards.
|
|
3285
|
+
"""
|
|
3286
|
+
out = {anchor}
|
|
3287
|
+
for role in PROSE_ROLES:
|
|
3288
|
+
if not config.has(role) or not config.path(role).is_file():
|
|
3289
|
+
continue
|
|
3290
|
+
out.update(one.anchor for one in anchored(config.document(role)))
|
|
3291
|
+
return frozenset(out)
|
|
3292
|
+
|
|
3293
|
+
|
|
3294
|
+
def promised(schema: Schema, body: str, known: frozenset[str] | None) -> list[Violation]:
|
|
3295
|
+
"""An id-shaped token in a design that no line carries (RK1002).
|
|
3296
|
+
|
|
3297
|
+
RK431 made deriving an id read prose, and that is right: a ledger entry promising *filed
|
|
3298
|
+
as RK499* before the line exists has to reserve the number, or two things carry one id.
|
|
3299
|
+
What deriving cannot do is tell a promise from an illustration — deciding would take the
|
|
3300
|
+
model L4 forbids — so it warns, hedged, in another command's output, two sessions later.
|
|
3301
|
+
|
|
3302
|
+
This is where the same rule is enforceable without judgement. **A design does not promise
|
|
3303
|
+
an id**: it explains a task that already has one, so an id-shaped token in a rationale
|
|
3304
|
+
body either names a line this backlog carries or it is an example, and an example that is
|
|
3305
|
+
spelled in this project's own prefix spends an address. §RK498 was composed with `add
|
|
3306
|
+
--dep RK999` in it, `section add` said nothing, and the next task filed was RK1000.
|
|
3307
|
+
|
|
3308
|
+
The ledger is deliberately not held to this — that is where RK431's promise is legitimate,
|
|
3309
|
+
and refusing it there would refuse the one sentence the mechanism exists for.
|
|
3310
|
+
|
|
3311
|
+
``known`` is the ids some file carries as a line, plus the one this transaction is about
|
|
3312
|
+
to write. ``None`` means the caller had no project to ask, and the check is skipped rather
|
|
3313
|
+
than guessed at.
|
|
3314
|
+
"""
|
|
3315
|
+
if known is None:
|
|
3316
|
+
return []
|
|
3317
|
+
# Deferred beside :func:`known`, and the same one-way edge (RK260).
|
|
3318
|
+
from roadkeep.ids import id_scanner # noqa: PLC0415 - RK1002
|
|
3319
|
+
|
|
3320
|
+
scanner = id_scanner(schema)
|
|
3321
|
+
loose = [
|
|
3322
|
+
match for match in scanner.finditer(body) if match.group(0) not in known
|
|
3323
|
+
]
|
|
3324
|
+
if not loose:
|
|
3325
|
+
return []
|
|
3326
|
+
named = ", ".join(dict.fromkeys(match.group(0) for match in loose))
|
|
3327
|
+
ceiling = _highest_carried(scanner, known)
|
|
3328
|
+
ahead = [
|
|
3329
|
+
match
|
|
3330
|
+
for match in loose
|
|
3331
|
+
if 0
|
|
3332
|
+
< int(match.group("number")) - ceiling.get(match.group("family"), 0)
|
|
3333
|
+
<= _IN_FLIGHT
|
|
3334
|
+
]
|
|
3335
|
+
return [
|
|
3336
|
+
Violation(
|
|
3337
|
+
"body.promise",
|
|
3338
|
+
"body",
|
|
3339
|
+
f"names {named}, which no line carries: an id in this project's own prefix is "
|
|
3340
|
+
f"read as spent, so the next `add` derives past it (RK431) — "
|
|
3341
|
+
+ (
|
|
3342
|
+
# The case both old remedies missed (RK1027). An id past everything a line
|
|
3343
|
+
# carries is not a typo and not a retirement: it is work in flight, and the
|
|
3344
|
+
# caller is authoring two tasks that cite each other in the only order a
|
|
3345
|
+
# shell allows. Told first, because the other two ask them to rename or
|
|
3346
|
+
# delete a cross-reference the backlog wanted.
|
|
3347
|
+
f"{named} is past every id a line carries, so file that task first and "
|
|
3348
|
+
f"write this section after — or spell the example outside "
|
|
3349
|
+
f"{'/'.join(schema.prefixes)}"
|
|
3350
|
+
if len(ahead) == len(loose)
|
|
3351
|
+
else f"spell the example outside {'/'.join(schema.prefixes)}, name the id "
|
|
3352
|
+
f"actually meant, or read `gaps` for where it went"
|
|
3353
|
+
),
|
|
3354
|
+
)
|
|
3355
|
+
]
|
|
3356
|
+
|
|
3357
|
+
|
|
3358
|
+
#: How far past the highest id a line carries a token may sit and still read as work in
|
|
3359
|
+
#: flight (RK1027). Three zones, not two: below the maximum a missing id is a hole `gaps`
|
|
3360
|
+
#: answers; **just** past it is the sibling being authored alongside this one; far past it
|
|
3361
|
+
#: is an illustration, which is the case RK1002 was filed for — §RK498 named `RK999` against
|
|
3362
|
+
#: a backlog whose next id was RK1000, and calling that a forward reference would take the
|
|
3363
|
+
#: refusal RK1002 bought and blunt it.
|
|
3364
|
+
#:
|
|
3365
|
+
#: Not configuration (L6), and the same argument `ranking.NEAREST` makes: a project declares
|
|
3366
|
+
#: how long its lines may be, and this is a property of how a sitting authors — measured on
|
|
3367
|
+
#: this repository's own two batches of cross-citing tasks, which spanned three ids each.
|
|
3368
|
+
_IN_FLIGHT = 8
|
|
3369
|
+
|
|
3370
|
+
|
|
3371
|
+
def _highest_carried(
|
|
3372
|
+
scanner: re.Pattern[str], known: frozenset[str]
|
|
3373
|
+
) -> dict[str, int]:
|
|
3374
|
+
"""The largest number each family holds as a line, read off ``known`` (RK1027).
|
|
3375
|
+
|
|
3376
|
+
The discriminator between a forward reference and a mistake, and it needs no second view
|
|
3377
|
+
of the surface: `known` is already every id some file carries, and the same scanner that
|
|
3378
|
+
found the loose token names the family and the number of each one. A maximum and not
|
|
3379
|
+
`next_id`: this function takes no project, which is what keeps `promised` the one place
|
|
3380
|
+
the *rule* lives — and `next_id` derives past everything a line carries, so the two
|
|
3381
|
+
disagree only about ids that are ahead either way.
|
|
3382
|
+
"""
|
|
3383
|
+
ceiling: dict[str, int] = {}
|
|
3384
|
+
for one in known:
|
|
3385
|
+
match = scanner.fullmatch(one)
|
|
3386
|
+
if match is None:
|
|
3387
|
+
continue
|
|
3388
|
+
family = match.group("family")
|
|
3389
|
+
ceiling[family] = max(ceiling.get(family, 0), int(match.group("number")))
|
|
3390
|
+
return ceiling
|
|
3391
|
+
|
|
3392
|
+
|
|
3393
|
+
def violations(
|
|
3394
|
+
schema: Schema,
|
|
3395
|
+
anchor: str,
|
|
3396
|
+
title: str,
|
|
3397
|
+
body: str,
|
|
3398
|
+
task: Task | None = None,
|
|
3399
|
+
*,
|
|
3400
|
+
elsewhere: Whereabouts | None = None,
|
|
3401
|
+
known: frozenset[str] | None = None,
|
|
3402
|
+
) -> tuple[Violation, ...]:
|
|
3403
|
+
"""The same rules, collected rather than raised (RK426).
|
|
3404
|
+
|
|
3405
|
+
`add --section` refuses the line and the section in two passes, so a call whose `why` is
|
|
3406
|
+
fifteen characters over and whose body is fifty words over costs **two** full
|
|
3407
|
+
resubmissions — the second for a limit the first refusal already knew was breached. That
|
|
3408
|
+
is the cost `--section-body-file` exists to avoid, charged for a field the tool had not
|
|
3409
|
+
looked at, and re-passing the prose is the expensive half.
|
|
3410
|
+
|
|
3411
|
+
So the caller that holds both sets asks for them and raises once. This is the collector
|
|
3412
|
+
and :func:`_check` is the raiser above it, rather than the reverse, because every other
|
|
3413
|
+
caller wants the refusal at the point of the check — a function that returned violations
|
|
3414
|
+
to twelve call sites would put the raise in twelve places, which is the shape L1 exists
|
|
3415
|
+
to avoid one layer up.
|
|
3416
|
+
"""
|
|
3417
|
+
try:
|
|
3418
|
+
_check(schema, anchor, title, body, task, elsewhere=elsewhere, known=known)
|
|
3419
|
+
except SectionError as error:
|
|
3420
|
+
return tuple(error.violations)
|
|
3421
|
+
return ()
|
|
3422
|
+
|
|
3423
|
+
|
|
3424
|
+
def _bound(schema: Schema, anchor: str, title: str, task: Task | None) -> str:
|
|
3425
|
+
"""The heading text with the task named in it, which is what makes it that task's (RK262).
|
|
3426
|
+
|
|
3427
|
+
Under an outline the anchor is an address and the **id in the heading is the binding** —
|
|
3428
|
+
`§XVI.12 A design (SH123)` — so `add --section "A design"` wrote a section belonging to
|
|
3429
|
+
nobody, and every reader afterwards was correct and useless: `ship` reported it *kept*,
|
|
3430
|
+
as prose belonging to none; `lint` declined to call it orphaned on exactly that reading;
|
|
3431
|
+
and the rationale for shipped work stayed in the prose file, which is what RK6 exists to
|
|
3432
|
+
prevent. The recovery was a `section amend --title "<title> (<id>)"` the author had to
|
|
3433
|
+
derive from a field named `kept`.
|
|
3434
|
+
|
|
3435
|
+
**Rendered and not refused**, which is the door the design listed first and the only one
|
|
3436
|
+
`add --section` can take: that command *derives* the id, so an author composing the title
|
|
3437
|
+
does not yet know what to type, and refusing would be the tool telling them the answer and
|
|
3438
|
+
asking them to send it back. Nor is it prose (L4) — the id is the pointer's other end, and
|
|
3439
|
+
rendering a binding into the text that carries it is what `Schema.render` does one file
|
|
3440
|
+
over with `→ §<anchor>`.
|
|
3441
|
+
|
|
3442
|
+
Whose it is, is :func:`owners` and never a second reading of it: that function already
|
|
3443
|
+
answers the question for the gate and for the drop, and a writer that agreed with neither
|
|
3444
|
+
is how a heading passes the door and fails the departure. A throwaway :class:`Section`
|
|
3445
|
+
because that is what it takes — every field but the two it reads is a placeholder. Under
|
|
3446
|
+
`ref_scheme = "id"` the anchor satisfies it, so nothing is ever appended there: no branch
|
|
3447
|
+
on the scheme, because the exemption *is* the reading.
|
|
3448
|
+
"""
|
|
3449
|
+
if task is None or not title.strip():
|
|
3450
|
+
# An empty title stays empty: appending the id would render `§X.1 (CT1)`, a heading
|
|
3451
|
+
# that names its task and nothing else, and would take `title.empty` — the refusal
|
|
3452
|
+
# that is the whole reason nothing composes a heading out of a blank field — with it.
|
|
3453
|
+
return title.strip()
|
|
3454
|
+
probe = Section(anchor=anchor, title=title.strip(), level=0, first=0, last=0)
|
|
3455
|
+
if task.id in owners(probe, schema.id_pattern()):
|
|
3456
|
+
return title.strip()
|
|
3457
|
+
return f"{title.strip()} ({task.id})"
|
|
3458
|
+
|
|
3459
|
+
|
|
3460
|
+
def _unknown(anchor: str, elsewhere: Whereabouts | None) -> str:
|
|
3461
|
+
"""The refusal for an id no live line names, carrying a door the author can take (RK238).
|
|
3462
|
+
|
|
3463
|
+
`add the line first` is the remedy for the one state it fits — an id that never existed.
|
|
3464
|
+
For an id the ledger holds it is the single door RK4 closes: `refuse_reuse` reads every
|
|
3465
|
+
governed file, so the `add` this advises is `IdInUse`, and retired-never-reused is the rule
|
|
3466
|
+
saying so. A finding whose named remedy the tool refuses is worse than one with no remedy,
|
|
3467
|
+
because the author spends the attempt before learning that (RK16).
|
|
3468
|
+
|
|
3469
|
+
So the state is named the way :class:`~roadkeep.deferring.NotSetAside` names it — where the
|
|
3470
|
+
id *is* — and the two doors that do open are the ones offered: `record amend` for the entry
|
|
3471
|
+
sentence, which is what actually needs correcting when a shipped design reads wrong, and an
|
|
3472
|
+
outline anchor for prose belonging to no task, which this message already offered.
|
|
3473
|
+
|
|
3474
|
+
The door is chosen from :class:`~roadkeep.backlog.Where` and not from whether a sentence
|
|
3475
|
+
is empty (RK240): `record amend` is the remedy for an id the **ledger** holds, and a
|
|
3476
|
+
branch that infers that from the truthiness of prose is a branch reading prose.
|
|
3477
|
+
"""
|
|
3478
|
+
if elsewhere is not None and elsewhere.recorded:
|
|
3479
|
+
return (
|
|
3480
|
+
f"no live task {anchor} points at this section: {elsewhere.sentence}, so its "
|
|
3481
|
+
f"design ended at the departure — correct that entry with `record amend`, or use "
|
|
3482
|
+
f"an outline anchor for prose that belongs to no task"
|
|
3483
|
+
)
|
|
3484
|
+
return (
|
|
3485
|
+
f"no live task {anchor} points at this section: add the line first, or "
|
|
3486
|
+
f"use an outline anchor for prose that belongs to no task"
|
|
3487
|
+
)
|
|
3488
|
+
|
|
3489
|
+
|
|
3490
|
+
def _elsewhere(config: Config, schema: Schema, anchor: str, task: Task | None) -> Whereabouts | None:
|
|
3491
|
+
"""Where the id is, read only where the refusal can use the answer (RK240).
|
|
3492
|
+
|
|
3493
|
+
`None` is "nothing to say", and it covers two cases rather than one: a live line already
|
|
3494
|
+
owns this anchor, or the anchor is not an id at all. An outline anchor named a section
|
|
3495
|
+
and never a task, so reading a ledger for it is a parse spent on a question `_unknown`
|
|
3496
|
+
will not ask — the one this used to make before the shape was checked.
|
|
3497
|
+
"""
|
|
3498
|
+
if task is not None or not schema.id_pattern().match(anchor):
|
|
3499
|
+
return None
|
|
3500
|
+
return Whereabouts.of(config, anchor)
|
|
3501
|
+
|
|
3502
|
+
|
|
3503
|
+
def _pointed_at(config: Config, anchor: str) -> bool:
|
|
3504
|
+
"""Does a live task line point at this anchor — the gate's own question (RK215).
|
|
3505
|
+
|
|
3506
|
+
What decides which of the two numbers a section is charged. A pointer hands a reader the
|
|
3507
|
+
whole subtree, so a *pointed-at* section is measured with it; a container nothing points
|
|
3508
|
+
at is measured on its own prose, because counting its children against it would measure
|
|
3509
|
+
the file's shape rather than anybody's paragraph. That is `lint`'s rule, and this asks it
|
|
3510
|
+
the same way so the writer and the gate cannot disagree — the disagreement being the
|
|
3511
|
+
defect, not the limit.
|
|
3512
|
+
|
|
3513
|
+
Both live roles, as the gate reads them: a deferred line keeps its pointer and its
|
|
3514
|
+
section (RK96), so work set aside still claims its rationale. The ledger is not among
|
|
3515
|
+
them — a departure deletes the section in the transaction that writes the entry.
|
|
3516
|
+
|
|
3517
|
+
And **only where one prose role declares the anchor** (RK232), which is the last condition
|
|
3518
|
+
RK215's agreement was missing. An anchor two files declare is charged as pointed at by
|
|
3519
|
+
nobody, because which of the two a line meant is what `ref.ambiguous` asks the author and
|
|
3520
|
+
billing one of them the other's subtree is the silent half of that defect. Counted before
|
|
3521
|
+
it was written: Turing at `f08304fcb1` declares 13 such anchors, one of them — `X.1`,
|
|
3522
|
+
pointed at by T354 — where the gate charges 73 words and this charged 365, so a correction
|
|
3523
|
+
to the intro was refused for 292 words of somebody else's subsections while the gate
|
|
3524
|
+
called that check clean. RK215's finding exactly, in the state RK215 did not reach.
|
|
3525
|
+
"""
|
|
3526
|
+
if len(declaring(config, anchor)) != 1:
|
|
3527
|
+
return False
|
|
3528
|
+
return any(
|
|
3529
|
+
entry.task.ref == anchor
|
|
3530
|
+
for document in _live(config)
|
|
3531
|
+
for entry in document.entries
|
|
3532
|
+
)
|
|
3533
|
+
|
|
3534
|
+
|
|
3535
|
+
def _task_for(config: Config, anchor: str, role: str = "") -> Task | None:
|
|
3536
|
+
"""The live task this anchor names, if it names one at all.
|
|
3537
|
+
|
|
3538
|
+
``role`` is the prose file the section is being written into, and it decides **which**
|
|
3539
|
+
file the owner is looked for in (RK1361). The decisions role is the one that carries both
|
|
3540
|
+
records and prose, so a record there owns a section *in that file* and nowhere else: were
|
|
3541
|
+
the search unconditional, a shipped task with a decision filed under its id would become
|
|
3542
|
+
an id `section add --role improvements` accepts, which is the design a ship deleted coming
|
|
3543
|
+
back under the number that deleted it. Empty is every other caller, and unchanged.
|
|
3544
|
+
|
|
3545
|
+
Both live roles, for the reason `_pointed_at` reads both (RK231) — and this is the half
|
|
3546
|
+
that *refuses*. Reading the roadmap alone, `section amend RK1` on a paused line answered
|
|
3547
|
+
`anchor.unknown`: "no open task RK1 points at this section: add the line first", about a
|
|
3548
|
+
line that exists, in the file `resume` restores from. That closed the last door on a
|
|
3549
|
+
state the tool creates on purpose, RK123's deadlock displaced — `drop` refused while the
|
|
3550
|
+
store's pointer claimed the anchor, `amend` refused because it read a different file than
|
|
3551
|
+
the pointer lived in, and the guard denied the `Edit`.
|
|
3552
|
+
|
|
3553
|
+
Which leaves `anchor.unknown` with nothing to distinguish: a paused task is found here,
|
|
3554
|
+
so the refusal only ever fires for an anchor no live line names. An id the *ledger* holds
|
|
3555
|
+
is one of those, and rightly — a departure deletes the design, so there is no section to
|
|
3556
|
+
amend and no line to add back (RK4).
|
|
3557
|
+
|
|
3558
|
+
**Under an outline the pointer is the answer** (RK262), and until this read it there was
|
|
3559
|
+
none: the anchor is an address, so the id test above matched nothing and every outline
|
|
3560
|
+
section looked ownerless to every caller here — which is why `section add` and `amend`
|
|
3561
|
+
could compose a heading naming no task while `add --section`, the one caller that passes
|
|
3562
|
+
its own, could not. The scan is `_pointed_at`'s and the rule is RK64's: **exactly one**
|
|
3563
|
+
live line, because four of Shio's point at one epic design, and picking one of four would
|
|
3564
|
+
be this function answering a question the format leaves open. Nothing refuses on the None
|
|
3565
|
+
that returns — an outline anchor never reaches `anchor.unknown` — so the cost of the
|
|
3566
|
+
ambiguous case is a heading the author binds by hand, which is where it started.
|
|
3567
|
+
"""
|
|
3568
|
+
owning = _owning(config, role)
|
|
3569
|
+
if config.schema.id_pattern().match(anchor):
|
|
3570
|
+
for document in owning:
|
|
3571
|
+
entry = document.by_id().get(anchor)
|
|
3572
|
+
if entry is not None:
|
|
3573
|
+
return entry.task
|
|
3574
|
+
return None
|
|
3575
|
+
owners_here = [
|
|
3576
|
+
entry.task
|
|
3577
|
+
for document in owning
|
|
3578
|
+
for entry in document.entries
|
|
3579
|
+
if entry.task.ref == anchor
|
|
3580
|
+
]
|
|
3581
|
+
return owners_here[0] if len(owners_here) == 1 else None
|
|
3582
|
+
|
|
3583
|
+
|
|
3584
|
+
def _owning(config: Config, role: str = "") -> list[Document]:
|
|
3585
|
+
"""The files a record owning a section in ``role`` is live in (RK1361).
|
|
3586
|
+
|
|
3587
|
+
Every entry the decisions file holds owns its body, superseded ones included: that is the
|
|
3588
|
+
one departure this role has, and it keeps both entries because the record of what a
|
|
3589
|
+
replacement was needed against is the body of the decision it replaced. So the whole
|
|
3590
|
+
document answers, and there is no marker to filter on.
|
|
3591
|
+
|
|
3592
|
+
Asked *of the destination*, which is what keeps the two doors apart: a decision's body
|
|
3593
|
+
lives in the decisions file, and the design a `ship` deleted stays deleted.
|
|
3594
|
+
"""
|
|
3595
|
+
if role == "decisions":
|
|
3596
|
+
if config.has(role) and config.path(role).is_file():
|
|
3597
|
+
return [config.document(role)]
|
|
3598
|
+
return []
|
|
3599
|
+
return list(_live(config))
|
|
3600
|
+
|
|
3601
|
+
|
|
3602
|
+
def _live(config: Config) -> Iterator[Document]:
|
|
3603
|
+
"""The files a task line is live in, in the order a reader should trust them.
|
|
3604
|
+
|
|
3605
|
+
One place, because the two questions above are the same question about one set of files:
|
|
3606
|
+
a pointer that claims a section and a task that owns one are both facts a ⏸ line still
|
|
3607
|
+
carries (RK96). The changelog is deliberately absent from both.
|
|
3608
|
+
"""
|
|
3609
|
+
for role in ("roadmap", "deferred"):
|
|
3610
|
+
if config.has(role) and config.path(role).is_file():
|
|
3611
|
+
yield config.document(role)
|
|
3612
|
+
|
|
3613
|
+
|
|
3614
|
+
# -- rendering and placement -------------------------------------------------
|
|
3615
|
+
|
|
3616
|
+
|
|
3617
|
+
def _render(
|
|
3618
|
+
schema: Schema, anchor: str, title: str, body: str, level: int
|
|
3619
|
+
) -> tuple[str, ...]:
|
|
3620
|
+
heading = f"{'#' * level} {anchor_text(schema, anchor)} {title.strip()}"
|
|
3621
|
+
return (heading, "", *_body_lines(schema, body))
|
|
3622
|
+
|
|
3623
|
+
|
|
3624
|
+
def _inserted(document: Document, index: int, lines: Sequence[str]) -> Document:
|
|
3625
|
+
"""Put these lines at ``index``, separated from what is already there.
|
|
3626
|
+
|
|
3627
|
+
Factored out for the second writer (RK1258): a family opened in the same transaction is
|
|
3628
|
+
placed exactly as the design under it is, and two copies of the blank-line rule is how one
|
|
3629
|
+
of them comes to write a heading flush against the paragraph above it.
|
|
3630
|
+
"""
|
|
3631
|
+
payload = list(lines)
|
|
3632
|
+
if index > 0 and not blank(document.lines[index - 1]):
|
|
3633
|
+
payload.insert(0, "")
|
|
3634
|
+
if index < len(document.lines):
|
|
3635
|
+
payload.append("")
|
|
3636
|
+
for offset, raw in enumerate(payload):
|
|
3637
|
+
document = document.insert_line(index + offset, raw)
|
|
3638
|
+
return document
|
|
3639
|
+
|
|
3640
|
+
|
|
3641
|
+
def _opening(
|
|
3642
|
+
config: Config, role: str, document: Document, opens: tuple[str, str], where: str
|
|
3643
|
+
) -> Document:
|
|
3644
|
+
"""Declare the family this write's design extends, as a heading and nothing else (RK1258).
|
|
3645
|
+
|
|
3646
|
+
A container and not a section with prose, and the difference is the whole shape: what a
|
|
3647
|
+
reader wants under `## XXXI` is the tasks, and what the tool may not do is compose the
|
|
3648
|
+
paragraph that would otherwise have to sit there (L4). The title is the **block's own**,
|
|
3649
|
+
which is a string the author already wrote — read at the door and passed in, so this
|
|
3650
|
+
function derives no words either.
|
|
3651
|
+
|
|
3652
|
+
The address is asked the three questions every destination is asked, against the document
|
|
3653
|
+
this transaction holds: a family the file, a sibling or history already spent is a refusal
|
|
3654
|
+
here, before the child is placed inside it.
|
|
3655
|
+
"""
|
|
3656
|
+
family, title = opens
|
|
3657
|
+
unspent(config, role, family, document=document, where=where)
|
|
3658
|
+
heading = (
|
|
3659
|
+
f"{'#' * _depth(document, family, None)} "
|
|
3660
|
+
f"{anchor_text(document.schema, family)} {title.strip()}"
|
|
3661
|
+
)
|
|
3662
|
+
return _inserted(document, _placement(document, family, None, where, role), (heading,))
|
|
3663
|
+
|
|
3664
|
+
|
|
3665
|
+
def _body_lines(schema: Schema, body: str) -> tuple[str, ...]:
|
|
3666
|
+
"""The prose as the file carries it: paragraphs filled, structures verbatim.
|
|
3667
|
+
|
|
3668
|
+
Apart from :func:`_render` because `amend` (RK123) writes exactly this and not the
|
|
3669
|
+
heading above it — and a second copy of the reflow rules is the one that would fill a
|
|
3670
|
+
table the day this one learned not to.
|
|
3671
|
+
"""
|
|
3672
|
+
paragraphs = [p for p in _normalize(body).split("\n\n") if p.strip()]
|
|
3673
|
+
out: list[str] = []
|
|
3674
|
+
for position, paragraph in enumerate(paragraphs):
|
|
3675
|
+
if position:
|
|
3676
|
+
out.append("")
|
|
3677
|
+
out.extend(_reflow(paragraph, schema.prose_width).split("\n"))
|
|
3678
|
+
return tuple(out)
|
|
3679
|
+
|
|
3680
|
+
|
|
3681
|
+
def _normalize(body: str) -> str:
|
|
3682
|
+
"""The body arrives from an argument or a pipe, so its endings are not the file's."""
|
|
3683
|
+
return body.replace("\r\n", "\n").replace("\r", "\n").strip("\n")
|
|
3684
|
+
|
|
3685
|
+
|
|
3686
|
+
def structural(lines: Sequence[str]) -> bool:
|
|
3687
|
+
"""Is this paragraph a shape inserted verbatim, rather than prose the tool fills?
|
|
3688
|
+
|
|
3689
|
+
Public because `adopt --sections` measures the width a file's prose is *already*
|
|
3690
|
+
wrapped to (RK99), and that number only means anything over the paragraphs
|
|
3691
|
+
:func:`_reflow` would touch: the widest line in a rationale file is otherwise a table
|
|
3692
|
+
row, a heading or a long link — none of which the tool ever wraps, and all of which an
|
|
3693
|
+
adopter would read `prose` off by mistake. One predicate, so the width that is measured
|
|
3694
|
+
is the width that would be written.
|
|
3695
|
+
"""
|
|
3696
|
+
return any(_shape(line) for line in lines)
|
|
3697
|
+
|
|
3698
|
+
|
|
3699
|
+
def _shape(line: str) -> bool:
|
|
3700
|
+
"""Is this one line a Markdown structure rather than a sentence in a paragraph? (RK397)
|
|
3701
|
+
|
|
3702
|
+
Read as three questions because the prefixes answer to three rules. A pipe, a quote and a
|
|
3703
|
+
fence are shapes on sight. A bullet, a number and a heading are a character **followed by
|
|
3704
|
+
a space** — that is what CommonMark says a marker is, and the space is what tells `* item`
|
|
3705
|
+
from `*emphasis*` and `1. one` from `1.5 seconds`. A run of three or more is a thematic
|
|
3706
|
+
break, which has no space and is a shape anyway.
|
|
3707
|
+
|
|
3708
|
+
Four indented spaces stay a code block. Asked of the raw line and not the stripped one,
|
|
3709
|
+
which is the only place in here where the leading whitespace is the meaning.
|
|
3710
|
+
"""
|
|
3711
|
+
if line.startswith(" "):
|
|
3712
|
+
return True
|
|
3713
|
+
head = line.lstrip()
|
|
3714
|
+
return bool(
|
|
3715
|
+
head.startswith(_VERBATIM) or _BREAK.match(head) or _MARKER.match(head)
|
|
3716
|
+
)
|
|
3717
|
+
|
|
3718
|
+
|
|
3719
|
+
def _reflow(paragraph: str, width: int) -> str:
|
|
3720
|
+
lines = paragraph.split("\n")
|
|
3721
|
+
if structural(lines):
|
|
3722
|
+
return paragraph.rstrip()
|
|
3723
|
+
return textwrap.fill(
|
|
3724
|
+
" ".join(line.strip() for line in lines),
|
|
3725
|
+
width=width,
|
|
3726
|
+
break_long_words=False,
|
|
3727
|
+
break_on_hyphens=False,
|
|
3728
|
+
)
|
|
3729
|
+
|
|
3730
|
+
|
|
3731
|
+
def _placement(
|
|
3732
|
+
document: Document, anchor: str, task: Task | None, where: str = "", role: str = ""
|
|
3733
|
+
) -> int:
|
|
3734
|
+
"""Where the section goes: after the last one under its block, or after what it extends.
|
|
3735
|
+
|
|
3736
|
+
A section for a task belongs under that task's block, so the prose file's order is a
|
|
3737
|
+
consequence of the backlog's rather than a decision made per insertion. Prose that
|
|
3738
|
+
belongs to no task — this project's `§0` preface — has no block to derive it from, and
|
|
3739
|
+
derives it from the anchor instead (RK45): `§0.4` follows `§0.3` and `§RK34.1` belongs
|
|
3740
|
+
inside `§RK34`, so the place is the end of the subtree of the longest anchor this file
|
|
3741
|
+
declares that the new one extends.
|
|
3742
|
+
|
|
3743
|
+
**Under an outline the anchor decides even for a task** (RK166), because there the
|
|
3744
|
+
author chose that anchor and it states a place, while the prose file is organised by the
|
|
3745
|
+
outline and not by blocks — measured on all three outline projects on this machine, whose
|
|
3746
|
+
prose files declare no block heading at all, so the block branch could only ever refuse.
|
|
3747
|
+
Under the id scheme the anchor is the id and carries no place, which is why that scheme
|
|
3748
|
+
is the one that reads the block.
|
|
3749
|
+
|
|
3750
|
+
Neither is ever appended at the end as a fallback. A block the prose file does not
|
|
3751
|
+
declare is refused (RK37) and so is a *nested* anchor extending nothing: a Block A section
|
|
3752
|
+
landing after Block F's reads as Block F's, which is the same mistake `add` refuses one
|
|
3753
|
+
file over, and appending is the one answer that is always plausible and frequently
|
|
3754
|
+
wrong. A task whose line sits under no heading at all is the one case with nothing to
|
|
3755
|
+
derive from either side, and only that one goes last.
|
|
3756
|
+
"""
|
|
3757
|
+
if task is None or document.schema.ref_scheme != "id":
|
|
3758
|
+
return _extended(document, anchor, where, role)
|
|
3759
|
+
if not task.block:
|
|
3760
|
+
return len(document.lines)
|
|
3761
|
+
heading = document.heading(task.block)
|
|
3762
|
+
if heading is None:
|
|
3763
|
+
raise UnknownBlock(
|
|
3764
|
+
task.block,
|
|
3765
|
+
sorted({h.label for h in document.headings if h.label}),
|
|
3766
|
+
where,
|
|
3767
|
+
word=document.schema.heading_word,
|
|
3768
|
+
)
|
|
3769
|
+
return document.subtree_end(heading)
|
|
3770
|
+
|
|
3771
|
+
|
|
3772
|
+
def _extended(
|
|
3773
|
+
document: Document, anchor: str, where: str = "", role: str = ""
|
|
3774
|
+
) -> int:
|
|
3775
|
+
"""The end of the subtree of the section this anchor extends, or a refusal (RK45).
|
|
3776
|
+
|
|
3777
|
+
Or, for a top-level anchor under an outline, the end of the last top-level section
|
|
3778
|
+
(RK166): that is the one place a section extending nothing can go without reading as
|
|
3779
|
+
somebody else's, and until this existed a new block's first design was reachable by no
|
|
3780
|
+
verb at all. The file's *own* order decides it — after the last one, never sorted, since
|
|
3781
|
+
whether `XXII` follows `XXI` is a question about somebody's numbering (L4, L6) and the
|
|
3782
|
+
author is the one who wrote the anchor.
|
|
3783
|
+
|
|
3784
|
+
``role`` reaches the refusal alone, for RK197's reason: the remedy it names is a
|
|
3785
|
+
`section add`, and on a project declaring only a strategy file the default role is one
|
|
3786
|
+
that cannot run. Read here and not resolved from a config this function does not hold.
|
|
3787
|
+
|
|
3788
|
+
**A prefix found is not an address that is well-formed** (RK1208). :func:`_extends`
|
|
3789
|
+
answers the *longest declared* prefix, and reading that as a parent wrote `§I.9.1` into a
|
|
3790
|
+
file holding only `§I` — a `###` at a child's depth, so `I.9.1` reads as a sibling of
|
|
3791
|
+
`I.1`, while `anchors --family I` derives its next child from the `9` inside it and spends
|
|
3792
|
+
a `§I.9` nothing ever claimed. `section add I.1` on that same file is refused, which is
|
|
3793
|
+
the same mistake with the same author and the other answer.
|
|
3794
|
+
"""
|
|
3795
|
+
parent = _extends(document, anchor)
|
|
3796
|
+
if parent is None:
|
|
3797
|
+
if _top_level(document, anchor):
|
|
3798
|
+
tops = [s for s in anchored(document) if _is_top(s.anchor)]
|
|
3799
|
+
if not tops:
|
|
3800
|
+
return len(document.lines)
|
|
3801
|
+
span = _span(document, tops[-1].anchor)
|
|
3802
|
+
assert span is not None # read out of this document a line ago
|
|
3803
|
+
return span[1]
|
|
3804
|
+
raise UnknownParent(
|
|
3805
|
+
anchor,
|
|
3806
|
+
[section.anchor for section in anchored(document)],
|
|
3807
|
+
where,
|
|
3808
|
+
opens=_ancestry(anchor),
|
|
3809
|
+
role=role,
|
|
3810
|
+
)
|
|
3811
|
+
# Every generation between the prefix found and the anchor typed. None of them is declared
|
|
3812
|
+
# by construction — `_extends` returned the longest that is — so this asks *how far* the
|
|
3813
|
+
# prefix falls short and never re-asks what the file holds.
|
|
3814
|
+
missing = _ancestry(anchor)[len(parent.split(".")) :]
|
|
3815
|
+
if missing:
|
|
3816
|
+
raise UnknownParent(
|
|
3817
|
+
anchor,
|
|
3818
|
+
[section.anchor for section in anchored(document)],
|
|
3819
|
+
where,
|
|
3820
|
+
opens=missing,
|
|
3821
|
+
role=role,
|
|
3822
|
+
)
|
|
3823
|
+
span = _span(document, parent)
|
|
3824
|
+
assert span is not None # `_extends` read the anchor out of this document
|
|
3825
|
+
return span[1]
|
|
3826
|
+
|
|
3827
|
+
|
|
3828
|
+
def _ancestry(anchor: str) -> tuple[str, ...]:
|
|
3829
|
+
"""Every ancestor of this anchor, outermost first — the address alone (RK1207, RK1208).
|
|
3830
|
+
|
|
3831
|
+
Not filtered against what the file declares, and the two callers are why that is an
|
|
3832
|
+
invariant rather than an omission: :func:`_extends` answers the **longest declared
|
|
3833
|
+
prefix**, so where it answered None every ancestor is missing, and where it answered one
|
|
3834
|
+
the callers take the tail past it. Either way the set handed to the refusal is undeclared
|
|
3835
|
+
by construction, and a filter here would re-ask what that function already decided.
|
|
3836
|
+
|
|
3837
|
+
Outermost first, because that is the order the calls have to run in: `section add I.1` on
|
|
3838
|
+
a file with no §I is this same refusal, one address down. Empty for a one-segment anchor,
|
|
3839
|
+
which has no ancestor to be missing.
|
|
3840
|
+
"""
|
|
3841
|
+
segments = anchor.split(".")
|
|
3842
|
+
return tuple(".".join(segments[:depth]) for depth in range(1, len(segments)))
|
|
3843
|
+
|
|
3844
|
+
|
|
3845
|
+
#: The depth a section with nothing to derive one from is written at: a one-segment anchor
|
|
3846
|
+
#: under the id scheme, which is a task's own design, and the last resort for anything else.
|
|
3847
|
+
NESTED_LEVEL = 3
|
|
3848
|
+
|
|
3849
|
+
|
|
3850
|
+
def _depth(document: Document, anchor: str, level: int | None) -> int:
|
|
3851
|
+
"""The heading level this section is written at — the caller's, or the file's own (RK166).
|
|
3852
|
+
|
|
3853
|
+
Named, it is used: a project whose outline nests four deep has a depth no rule here
|
|
3854
|
+
knows. Omitted, a **new top level** gets the depth this file already writes one at —
|
|
3855
|
+
falling back to one under its shallowest heading, which is the file's title in every
|
|
3856
|
+
corpus read here — and a **subsection** gets one under the section it extends (RK180).
|
|
3857
|
+
|
|
3858
|
+
That last one was :data:`NESTED_LEVEL` flat, which is the same defect one level down:
|
|
3859
|
+
in a file whose designs are `####` under `###` parts, `section add XXI.6` wrote `###
|
|
3860
|
+
XXI.6`, a *sibling* of `### XXI` that ends the subtree it was meant to be inside — and
|
|
3861
|
+
depth is what says where a section ends (RK115), so `drop XXI` then takes the parent and
|
|
3862
|
+
orphans this one.
|
|
3863
|
+
|
|
3864
|
+
The parent's level and not the depth of the file's other sections at the same number of
|
|
3865
|
+
segments: those are the same answer in a consistently nested file and different in one
|
|
3866
|
+
that mixes schemes, and there the sibling count is wrong in exactly this task's
|
|
3867
|
+
direction — this repository declares `§0.3` at level 3, so a `§RK34.1` read off it would
|
|
3868
|
+
be written level with the `§RK34` it belongs inside.
|
|
3869
|
+
"""
|
|
3870
|
+
if level is not None:
|
|
3871
|
+
return level
|
|
3872
|
+
if _top_level(document, anchor):
|
|
3873
|
+
tops = [s.level for s in anchored(document) if _is_top(s.anchor)]
|
|
3874
|
+
if tops:
|
|
3875
|
+
return tops[0]
|
|
3876
|
+
levels = [h.level for h in document.headings]
|
|
3877
|
+
return min(levels) + 1 if levels else NESTED_LEVEL - 1
|
|
3878
|
+
parent = _extends(document, anchor)
|
|
3879
|
+
if parent is None:
|
|
3880
|
+
# Either a one-segment anchor under the id scheme — a task's design, which has no
|
|
3881
|
+
# parent by construction — or a nested one whose parent this file does not declare,
|
|
3882
|
+
# and that one never reaches a write: `_extended` refuses it by name.
|
|
3883
|
+
return NESTED_LEVEL
|
|
3884
|
+
return next(s.level for s in anchored(document) if s.anchor == parent) + 1
|
|
3885
|
+
|
|
3886
|
+
|
|
3887
|
+
def _descended(
|
|
3888
|
+
anchor: str, claimed: Mapping[str, Sequence[str]]
|
|
3889
|
+
) -> list[tuple[str, tuple[str, ...]]]:
|
|
3890
|
+
"""Every claimed pointer that descends from this anchor, segment by segment (RK169).
|
|
3891
|
+
|
|
3892
|
+
Segment-wise and never as a string, the care :func:`_extends` already takes: `§0.1` is
|
|
3893
|
+
not above `§0.10`, and a guard that read it as one would refuse a drop nobody claimed.
|
|
3894
|
+
The anchor itself is not a descendant of itself — that is :class:`SectionClaimed`, asked
|
|
3895
|
+
first and answered with the message about the pointer that names it exactly.
|
|
3896
|
+
"""
|
|
3897
|
+
segments = anchor.split(".")
|
|
3898
|
+
out: list[tuple[str, tuple[str, ...]]] = []
|
|
3899
|
+
for ref, owners in claimed.items():
|
|
3900
|
+
parts = ref.split(".")
|
|
3901
|
+
if len(parts) > len(segments) and parts[: len(segments)] == segments:
|
|
3902
|
+
out.append((ref, tuple(owners)))
|
|
3903
|
+
return out
|
|
3904
|
+
|
|
3905
|
+
|
|
3906
|
+
def _is_top(anchor: str) -> bool:
|
|
3907
|
+
"""One segment, so there is nothing above it in the outline: `XXII`, `0`, `IX`."""
|
|
3908
|
+
return "." not in anchor
|
|
3909
|
+
|
|
3910
|
+
|
|
3911
|
+
def _top_level(document: Document, anchor: str) -> bool:
|
|
3912
|
+
"""May this anchor open a new top level of the file? (RK166)
|
|
3913
|
+
|
|
3914
|
+
Only under an outline, and only for a one-segment anchor. Under the id scheme the anchor
|
|
3915
|
+
*is* the id, so it carries no place and no level: a `§RK9` that extends nothing is a
|
|
3916
|
+
section for a task, placed under that task's block, and reaching here with one means the
|
|
3917
|
+
id names no open line — which stays the refusal it was.
|
|
3918
|
+
"""
|
|
3919
|
+
return document.schema.ref_scheme != "id" and _is_top(anchor)
|
|
3920
|
+
|
|
3921
|
+
|
|
3922
|
+
def _extends(document: Document, anchor: str) -> str | None:
|
|
3923
|
+
"""The longest anchor this file declares that `anchor` continues: `0.4.2` → `0.4`, `0`.
|
|
3924
|
+
|
|
3925
|
+
Segment by segment rather than by string, which is what keeps `§0.1` from being read as
|
|
3926
|
+
the parent of `§0.10` — the same care :func:`_names` takes about where an anchor ends.
|
|
3927
|
+
"""
|
|
3928
|
+
segments = anchor.split(".")
|
|
3929
|
+
best: list[str] = []
|
|
3930
|
+
for section in anchored(document):
|
|
3931
|
+
candidate = section.anchor.split(".")
|
|
3932
|
+
if len(best) < len(candidate) < len(segments):
|
|
3933
|
+
if candidate == segments[: len(candidate)]:
|
|
3934
|
+
best = candidate
|
|
3935
|
+
return ".".join(best) or None
|
|
3936
|
+
|
|
3937
|
+
|
|
3938
|
+
def untitled(document: Document) -> tuple[Section, ...]:
|
|
3939
|
+
"""Every heading this file carries that declares no anchor, in file order (RK1107).
|
|
3940
|
+
|
|
3941
|
+
The other half of :func:`anchored`, and until this the half no verb could reach. A prose
|
|
3942
|
+
file's opening — the `#` that names it, and the prose under it saying what the file is —
|
|
3943
|
+
declares no address, and neither does a `## Table of contents`; both go stale the instant
|
|
3944
|
+
a `ship` drops a section, and the only door onto either was the hand edit the guard denies.
|
|
3945
|
+
Measured: `section show 'Table of contents'` answered *no §Table of contents section*, which
|
|
3946
|
+
was true and left the caller nowhere to go.
|
|
3947
|
+
|
|
3948
|
+
**The heading's text is the address, and that is not a second addressing scheme.** An
|
|
3949
|
+
anchor is a name the project chose and never reuses; this is the heading a reader already
|
|
3950
|
+
sees, matched as it is written. §RK1107 assumed a positional name (`preamble`, `contents`)
|
|
3951
|
+
would be needed and would have to be declared per project (L6) — measuring the two live
|
|
3952
|
+
files says otherwise: the opening prose is the `#`'s **own** body, which
|
|
3953
|
+
:meth:`~roadkeep.kernel.document.Document.prose_end` already delimits, so the file's title
|
|
3954
|
+
is its address and no new word is invented anywhere.
|
|
3955
|
+
|
|
3956
|
+
Own prose and never the subtree, for :func:`anchored`'s reason: the `#` heading's body is
|
|
3957
|
+
the preamble and stops at the first `##`, so amending it can never reach a section that has
|
|
3958
|
+
an address of its own.
|
|
3959
|
+
"""
|
|
3960
|
+
out: list[Section] = []
|
|
3961
|
+
for heading in document.headings:
|
|
3962
|
+
if anchor_of(heading.text, document.schema) is not None:
|
|
3963
|
+
continue
|
|
3964
|
+
end = document.prose_end(heading)
|
|
3965
|
+
out.append(
|
|
3966
|
+
Section(
|
|
3967
|
+
anchor="",
|
|
3968
|
+
title=heading.text.strip(),
|
|
3969
|
+
level=heading.level,
|
|
3970
|
+
first=heading.lineno,
|
|
3971
|
+
last=end,
|
|
3972
|
+
body="".join(document.lines[heading.lineno : end]).strip("\r\n"),
|
|
3973
|
+
)
|
|
3974
|
+
)
|
|
3975
|
+
return tuple(out)
|
|
3976
|
+
|
|
3977
|
+
|
|
3978
|
+
def titled(document: Document, title: str) -> Heading | None:
|
|
3979
|
+
"""The one unanchored heading whose text is *title*, or None (RK1107).
|
|
3980
|
+
|
|
3981
|
+
Compared on the stripped text and nothing cleverer: the caller has the file open, and a
|
|
3982
|
+
fuzzy match would make *which section did I just edit* a question. Refused rather than
|
|
3983
|
+
guessed where two headings carry one text — :class:`AmbiguousTitle` — because a file whose
|
|
3984
|
+
contents heading is written twice has two regions and no address distinguishes them.
|
|
3985
|
+
|
|
3986
|
+
Asked **only of the unanchored**, so this can never become a second way to reach a section
|
|
3987
|
+
that has an anchor: one address per addressable thing, which is the property every reader
|
|
3988
|
+
downstream of `_span` already depends on.
|
|
3989
|
+
"""
|
|
3990
|
+
wanted = title.strip()
|
|
3991
|
+
found = [
|
|
3992
|
+
heading
|
|
3993
|
+
for heading in document.headings
|
|
3994
|
+
if anchor_of(heading.text, document.schema) is None and heading.text.strip() == wanted
|
|
3995
|
+
]
|
|
3996
|
+
if len(found) > 1:
|
|
3997
|
+
raise AmbiguousTitle(wanted, tuple(heading.lineno for heading in found))
|
|
3998
|
+
return found[0] if found else None
|
|
3999
|
+
|
|
4000
|
+
|
|
4001
|
+
class AmbiguousTitle(ValueError):
|
|
4002
|
+
"""One heading text, two headings — so the text is not an address (RK1107)."""
|
|
4003
|
+
|
|
4004
|
+
def __init__(self, title: str, linenos: tuple[int, ...]) -> None:
|
|
4005
|
+
self.title = title
|
|
4006
|
+
self.linenos = linenos
|
|
4007
|
+
spelled = ", ".join(str(one) for one in linenos)
|
|
4008
|
+
super().__init__(
|
|
4009
|
+
f"{len(linenos)} headings read '{title}' (lines {spelled}): an unanchored section "
|
|
4010
|
+
f"is addressed by its heading, so two with one text have no address between them — "
|
|
4011
|
+
f"give one of them a different heading, or an anchor"
|
|
4012
|
+
)
|
|
4013
|
+
|
|
4014
|
+
|
|
4015
|
+
def _span(document: Document, anchor: str) -> tuple[int, int, Heading] | None:
|
|
4016
|
+
"""The `[start, end)` lines to delete, and the heading that names them.
|
|
4017
|
+
|
|
4018
|
+
A section ends where the next heading of the same or higher level begins — the
|
|
4019
|
+
document's own answer (RK115), because a drop takes the subtree. When it is the last
|
|
4020
|
+
thing in the file, the deletion reaches back over the blank line above it, which
|
|
4021
|
+
otherwise survives as a trailing blank nobody put there.
|
|
4022
|
+
"""
|
|
4023
|
+
for heading in document.headings:
|
|
4024
|
+
if not _names(heading.text, anchor, document.schema):
|
|
4025
|
+
continue
|
|
4026
|
+
start = heading.lineno - 1
|
|
4027
|
+
end = document.subtree_end(heading)
|
|
4028
|
+
if end == len(document.lines):
|
|
4029
|
+
while start > 0 and blank(document.lines[start - 1]):
|
|
4030
|
+
start -= 1
|
|
4031
|
+
return start, end, heading
|
|
4032
|
+
return None
|
|
4033
|
+
|
|
4034
|
+
|
|
4035
|
+
def anchor_text(schema: Schema, anchor: str) -> str:
|
|
4036
|
+
"""The anchor as a *heading* spells it: `§RK9` under `id`, `VIII.1` under `outline`.
|
|
4037
|
+
|
|
4038
|
+
The one place that spelling is decided, so a reader that echoes a heading (`section
|
|
4039
|
+
show`, `brief`) cannot print a file back differently from how it is written. On the
|
|
4040
|
+
pointer the § is unconditional — that is the end of the reference where a sigil is
|
|
4041
|
+
what tells an anchor from a word, in either scheme.
|
|
4042
|
+
|
|
4043
|
+
The **namespace stays on the pointer** (RK340): `[refs]` says which file an address is
|
|
4044
|
+
in, and a heading is already in one, so writing `S:I` above the prose in `STRATEGY.md`
|
|
4045
|
+
would put the answer to "which file" inside the file that is the answer.
|
|
4046
|
+
"""
|
|
4047
|
+
if schema.ref_scheme == "id":
|
|
4048
|
+
return f"§{anchor}"
|
|
4049
|
+
return local(schema, anchor) or anchor
|
|
4050
|
+
|
|
4051
|
+
|
|
4052
|
+
def heading_of(schema: Schema, section: Section) -> str:
|
|
4053
|
+
"""The heading line this section is written as — one spelling, one writer (RK44).
|
|
4054
|
+
|
|
4055
|
+
An empty anchor is the unanchored section (RK1107) and writes its title alone: under the
|
|
4056
|
+
id scheme :func:`anchor_text` would otherwise render the sigil with nothing after it, so a
|
|
4057
|
+
re-titled `## Table of contents` came back as `## § Table of contents`. Answered here
|
|
4058
|
+
because this is the one writer, and a caller composing the exception would be the second.
|
|
4059
|
+
"""
|
|
4060
|
+
if not section.anchor:
|
|
4061
|
+
return f"{'#' * section.level} {section.title}"
|
|
4062
|
+
return f"{'#' * section.level} {anchor_text(schema, section.anchor)} {section.title}"
|
|
4063
|
+
|
|
4064
|
+
|
|
4065
|
+
def anchor_of(text: str, schema: Schema) -> str | None:
|
|
4066
|
+
"""The anchor this heading declares, or None when it declares none (RK27, RK44).
|
|
4067
|
+
|
|
4068
|
+
Public because a heading is read outside a parsed document too (RK247): the anchors a
|
|
4069
|
+
file *used to* declare are in its diffs, and a second reader of this spelling one module
|
|
4070
|
+
over is the drift :func:`anchor_text` refuses at the writing end.
|
|
4071
|
+
|
|
4072
|
+
Read **per scheme**, because the two write it differently and requiring one spelling
|
|
4073
|
+
read the other as prose: measured on Shio, 151 headings yielded 0 sections and
|
|
4074
|
+
therefore 74 pointers reported as resolving to nothing against a file that answers
|
|
4075
|
+
every one of them — RK15's argument inverted, which is how a gate teaches its reader
|
|
4076
|
+
to skip a category.
|
|
4077
|
+
|
|
4078
|
+
* ``id`` — `§RK9 A design` → `RK9`. The anchor is a task id, so the § is what marks
|
|
4079
|
+
it as an anchor rather than a word, and it is required.
|
|
4080
|
+
* ``outline`` — `VIII.1 MCP server host` → `VIII.1`, Shio's `0. Strategy` → `0`, and
|
|
4081
|
+
Turing's lettered fourth level `IX.4.d The pivot` → `IX.4.d` (RK47) and commitclerk's
|
|
4082
|
+
block letters `B.2 Ticket trailers` → `B.2` (RK101), where the bare `B — Context`
|
|
4083
|
+
above it is still a block: the number *is*
|
|
4084
|
+
the announcement, so the sigil belongs on the pointer alone. It is accepted where an
|
|
4085
|
+
author wrote one anyway, because a heading nothing can see is the defect this closes
|
|
4086
|
+
and not a spelling to punish. What a segment may be is
|
|
4087
|
+
:data:`~roadkeep.kernel.schema.OUTLINE_ANCHOR_RE`'s to say, at both ends of the pointer.
|
|
4088
|
+
"""
|
|
4089
|
+
head = text.lstrip()
|
|
4090
|
+
if schema.ref_scheme == "id":
|
|
4091
|
+
if not head.startswith("§"):
|
|
4092
|
+
return None
|
|
4093
|
+
return head[1:].split(" ", 1)[0].strip() or None
|
|
4094
|
+
# The trailing period is Shio's numbering ("## VIII. The Agent Gateway"), not part of
|
|
4095
|
+
# the anchor a pointer writes — the pointer says `§VIII.7`.
|
|
4096
|
+
token = head.split(" ", 1)[0].lstrip("§").rstrip(".")
|
|
4097
|
+
return token if OUTLINE_ANCHOR_RE.match(token) else None
|
|
4098
|
+
|
|
4099
|
+
|
|
4100
|
+
def _title_of(text: str, schema: Schema) -> str:
|
|
4101
|
+
"""`§RK9 A design` → `A design`. The anchor is one token; the rest is the title."""
|
|
4102
|
+
if anchor_of(text, schema) is None:
|
|
4103
|
+
return text
|
|
4104
|
+
return text.lstrip().partition(" ")[2].strip()
|
|
4105
|
+
|
|
4106
|
+
|
|
4107
|
+
def _names(text: str, anchor: str, schema: Schema) -> bool:
|
|
4108
|
+
"""Does this heading declare exactly this anchor?
|
|
4109
|
+
|
|
4110
|
+
Asked of the parsed anchor rather than of the text, which is what keeps `§0` from
|
|
4111
|
+
claiming `§0.1` and `VIII.1` from claiming `VIII.10` without a second opinion about
|
|
4112
|
+
where an anchor ends.
|
|
4113
|
+
|
|
4114
|
+
And asked in **this file's namespace** (RK340): the heading writes the bare address, so
|
|
4115
|
+
an anchor naming another role's is one no heading here declares. One comparison rather
|
|
4116
|
+
than a check at every reader, because this is the comparison every reader already makes.
|
|
4117
|
+
"""
|
|
4118
|
+
here = local(schema, anchor)
|
|
4119
|
+
# Both sides answer None — a heading that declares no anchor, and an address that is
|
|
4120
|
+
# another role's — and the two Nones are not a match.
|
|
4121
|
+
return here is not None and anchor_of(text, schema) == here
|