roadkeep 0.2.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- roadkeep/__init__.py +79 -0
- roadkeep/adopting.py +2347 -0
- roadkeep/attesting.py +293 -0
- roadkeep/authoring.py +2117 -0
- roadkeep/backlog.py +767 -0
- roadkeep/blocking.py +1622 -0
- roadkeep/briefing.py +970 -0
- roadkeep/budgeting.py +2056 -0
- roadkeep/capturing.py +1699 -0
- roadkeep/claiming.py +1019 -0
- roadkeep/cli.py +638 -0
- roadkeep/commanding.py +487 -0
- roadkeep/config.py +1832 -0
- roadkeep/counting.py +376 -0
- roadkeep/criteria.py +933 -0
- roadkeep/deferring.py +708 -0
- roadkeep/describing.py +568 -0
- roadkeep/exporting.py +808 -0
- roadkeep/fixing.py +629 -0
- roadkeep/governing.py +934 -0
- roadkeep/graph.py +395 -0
- roadkeep/guarding.py +1028 -0
- roadkeep/history.py +2403 -0
- roadkeep/ids.py +301 -0
- roadkeep/installing.py +2145 -0
- roadkeep/kernel/__init__.py +24 -0
- roadkeep/kernel/document.py +1719 -0
- roadkeep/kernel/schema.py +2308 -0
- roadkeep/linting.py +4420 -0
- roadkeep/locking.py +209 -0
- roadkeep/markers.py +172 -0
- roadkeep/merging.py +1159 -0
- roadkeep/picking.py +772 -0
- roadkeep/provenance.py +789 -0
- roadkeep/queueing.py +752 -0
- roadkeep/ranking.py +139 -0
- roadkeep/referring.py +231 -0
- roadkeep/remaining.py +336 -0
- roadkeep/remedying.py +1989 -0
- roadkeep/rendering.py +1601 -0
- roadkeep/renumbering.py +503 -0
- roadkeep/repairing.py +295 -0
- roadkeep/reverting.py +144 -0
- roadkeep/scoping.py +708 -0
- roadkeep/screening.py +196 -0
- roadkeep/sections.py +4121 -0
- roadkeep/serving.py +2909 -0
- roadkeep/shipping.py +3993 -0
- roadkeep/showing.py +613 -0
- roadkeep/storing.py +224 -0
- roadkeep/verbs/__init__.py +26 -0
- roadkeep/verbs/adopting.py +974 -0
- roadkeep/verbs/authoring.py +566 -0
- roadkeep/verbs/declaring.py +335 -0
- roadkeep/verbs/linting.py +645 -0
- roadkeep/verbs/querying.py +2138 -0
- roadkeep/verbs/reading.py +307 -0
- roadkeep/verbs/refusing.py +146 -0
- roadkeep/verbs/sections.py +1433 -0
- roadkeep/verbs/shipping.py +819 -0
- roadkeep/weighing.py +380 -0
- roadkeep-0.2.0.dist-info/METADATA +453 -0
- roadkeep-0.2.0.dist-info/RECORD +67 -0
- roadkeep-0.2.0.dist-info/WHEEL +5 -0
- roadkeep-0.2.0.dist-info/entry_points.txt +2 -0
- roadkeep-0.2.0.dist-info/licenses/LICENSE +202 -0
- roadkeep-0.2.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,1719 @@
|
|
|
1
|
+
"""Reading a governed file, and the invariant that lets the tool write one (RK2).
|
|
2
|
+
|
|
3
|
+
A tool that edits a file a human also edits has to prove it understood that file
|
|
4
|
+
before it is allowed to replace it, so the ownership test is mechanical: parse →
|
|
5
|
+
render → byte-identical, or refuse (L3). Two independent halves of that:
|
|
6
|
+
|
|
7
|
+
* **The file** round-trips because a :class:`Document` keeps every source line
|
|
8
|
+
verbatim, endings included, and :meth:`Document.render` is a join. Interpretation
|
|
9
|
+
is a layer over the lines, never a replacement for them — so a document can be
|
|
10
|
+
written back untouched even where the parser understood nothing.
|
|
11
|
+
* **The line** round-trips only if ``schema.render(parsed) == raw``. Where it does
|
|
12
|
+
not, the entry is *non-canonical* and every mutator refuses the whole file
|
|
13
|
+
(:class:`RoundTripError`) rather than normalizing what it may have misread. A
|
|
14
|
+
formatter that "fixes" what it misunderstood destroys work no diff review catches.
|
|
15
|
+
|
|
16
|
+
The parser is written to be lossless: every branch either keeps the text in a field
|
|
17
|
+
or rejects the line, so no file it accepts comes back changed — 144 lines across
|
|
18
|
+
this repository, Shio and Turing, none of them non-canonical. That makes the guard
|
|
19
|
+
look redundant until the configuration moves: a file written under one
|
|
20
|
+
`roadkeep.toml` and rendered under another (a different marker set, a ledger's
|
|
21
|
+
missing deps field) comes back reformatted, and **a configuration change is not a
|
|
22
|
+
licence to rewrite the files written before it.** The guard is also what keeps any
|
|
23
|
+
future normalizing parser honest, because it fails the corpus instead of a review.
|
|
24
|
+
|
|
25
|
+
Nothing here silently drops a line it failed to read: a bullet that carries a status
|
|
26
|
+
marker but does not match the grammar becomes a :class:`Reject` with a reason, and so
|
|
27
|
+
does one that puts an *undeclared* marker where the marker goes, **no marker at all**
|
|
28
|
+
where a bold id leads (RK43), or GitHub's **task-list checkbox** there (RK103) — otherwise
|
|
29
|
+
it reads as prose and leaves no trace. That is
|
|
30
|
+
the data `audit` (RK10) prints, because a count whose misses are invisible is the failure
|
|
31
|
+
mode the grep it replaces already had. Measured: Shio's changelog is 920 bullets and
|
|
32
|
+
parsed as 0 entries *and* 0 rejects, the one shape that made the miss silent twice.
|
|
33
|
+
|
|
34
|
+
The marker slot is also the one part of the grammar a file may not have. Both live
|
|
35
|
+
ledgers write `- **T1** — …`, so `[ledger] marker = false` (L6) says the status is the
|
|
36
|
+
file's rather than the line's — every entry in it shipped — and there a marker on a line
|
|
37
|
+
is the reject instead, with one exception the file's own claim creates: a **departure** is
|
|
38
|
+
what such a ledger does not say about itself, so the retired line is the one that carries a
|
|
39
|
+
marker (RK125), and whether a line fills the slot is decided per line by
|
|
40
|
+
:meth:`Schema.marks` — the same answer `render` writes from.
|
|
41
|
+
"""
|
|
42
|
+
|
|
43
|
+
from __future__ import annotations
|
|
44
|
+
|
|
45
|
+
import contextlib
|
|
46
|
+
import functools
|
|
47
|
+
import os
|
|
48
|
+
import re
|
|
49
|
+
import time
|
|
50
|
+
from collections.abc import Callable, Sequence
|
|
51
|
+
from dataclasses import dataclass, replace
|
|
52
|
+
from functools import lru_cache
|
|
53
|
+
from pathlib import Path
|
|
54
|
+
from typing import TYPE_CHECKING
|
|
55
|
+
|
|
56
|
+
from roadkeep.kernel.schema import (
|
|
57
|
+
ARROW,
|
|
58
|
+
EM_DASH,
|
|
59
|
+
ID_SHAPE,
|
|
60
|
+
NO_DEPS,
|
|
61
|
+
Dep,
|
|
62
|
+
Schema,
|
|
63
|
+
Task,
|
|
64
|
+
grammar,
|
|
65
|
+
)
|
|
66
|
+
|
|
67
|
+
if TYPE_CHECKING: # a name for the annotation only: `config` reads this module, not back
|
|
68
|
+
from roadkeep.config import Config
|
|
69
|
+
|
|
70
|
+
#: Everything after the marker slot, up to the symptom. `deps` is optional because the
|
|
71
|
+
#: ledger has none; the trailing pointer is stripped before this runs (see `_split_ref`).
|
|
72
|
+
#: How many times :func:`write_atomically` retries the rename, and how long it pauses
|
|
73
|
+
#: between them. Small: the case this covers is a Windows indexer holding the target open
|
|
74
|
+
#: for a moment, and anything longer than that is a file somebody means to be holding.
|
|
75
|
+
_REPLACE_TRIES = 5
|
|
76
|
+
_REPLACE_PAUSE = 0.05
|
|
77
|
+
|
|
78
|
+
#: How many distinct (text, schema) parses :func:`_parsed` keeps (RK211). Enough for the
|
|
79
|
+
#: four governed roles a transaction reads plus the state each is about to become; a bigger
|
|
80
|
+
#: number would hold megabytes of somebody else's ledger for no further hit.
|
|
81
|
+
_PARSE_CACHE = 12
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
@functools.lru_cache(maxsize=None)
|
|
85
|
+
def _task_re(marker: bool, symptom: bool) -> re.Pattern[str]:
|
|
86
|
+
"""The task-line grammar for one file's shape, anchored at both ends.
|
|
87
|
+
|
|
88
|
+
Cached because it is rebuilt per line otherwise, and the four combinations are the
|
|
89
|
+
whole domain: with a marker or without, with a symptom slot or without.
|
|
90
|
+
|
|
91
|
+
Composed from :func:`~roadkeep.kernel.schema.grammar` since RK1063, which is the same
|
|
92
|
+
:data:`~roadkeep.kernel.schema.TEMPLATE` `Schema.render` writes from. The fragments used to
|
|
93
|
+
live here, beside the parser that consumed them and a file away from the writer that
|
|
94
|
+
had to agree with them — so the two were one statement made twice, and L3's property
|
|
95
|
+
test over three corpora was what held them level. It still runs; what it no longer
|
|
96
|
+
carries is the drift case, that having stopped being expressible.
|
|
97
|
+
"""
|
|
98
|
+
return re.compile(rf"^- {grammar(marker, symptom)}")
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
_HEADING_RE = re.compile(r"^(?P<hashes>#{1,6}) (?P<text>.*)$")
|
|
102
|
+
_BULLET_RE = re.compile(r"^(?P<indent>\s*)[-*+] (?P<rest>.*)$")
|
|
103
|
+
#: A fenced code block's delimiter, indented or not — a fence inside a list item is (RK53).
|
|
104
|
+
_FENCE_RE = re.compile(r"^\s*(?P<marks>`{3,}|~{3,})")
|
|
105
|
+
#: A bullet that puts *something* where a marker goes and a bold id after it — how an
|
|
106
|
+
#: undeclared marker is caught instead of read as prose (see `_wears_the_marker_slot`).
|
|
107
|
+
#: The qualifier as it appears inside the bold, for the two shape tests below (RK121).
|
|
108
|
+
#: They decide whether a bullet *claims* the task line's shape, and a claim they declined
|
|
109
|
+
#: is prose — which is how Shio's seven partial entries came to be read as no line at all.
|
|
110
|
+
_PART = r"(?: \([^)]+\))?"
|
|
111
|
+
_MARKER_SLOT_RE = re.compile(rf"^\S+ \*\*[A-Za-z0-9]+{_PART}\*\*")
|
|
112
|
+
#: A line that is nothing but pipe-delimited cells, and the `|---|` rule that makes a run
|
|
113
|
+
#: of them a table rather than prose that happens to use pipes. Two shapes and no grammar:
|
|
114
|
+
#: what is *inside* the cells is deliberately never read (RK98).
|
|
115
|
+
_ROW_RE = re.compile(r"^\s*\|.*\|\s*$")
|
|
116
|
+
_RULE_RE = re.compile(r"^\s*\|(?:\s*:?-+:?\s*\|)+\s*$")
|
|
117
|
+
#: A **top-level** list item of any Markdown flavour — `-`, `*`, `+` or `1.` / `1)` (RK279).
|
|
118
|
+
#: Where a task would be, in the shape an unadopted backlog is actually in. Unindented on
|
|
119
|
+
#: purpose: a nested bullet is detail of the item above it, and counting it would price one
|
|
120
|
+
#: task as several. What is inside is never read, for the reason :data:`_ROW_RE` gives.
|
|
121
|
+
_ITEM_RE = re.compile(r"^(?:[-*+]|\d+[.)]) +\S")
|
|
122
|
+
#: A bullet whose first token *is* the bold id, so the marker slot is empty rather than
|
|
123
|
+
#: wrong (see `_leads_with_the_id`). Id-shaped and nothing else: the shape is what tells
|
|
124
|
+
#: `- **T1** — …` from `- **Delete** the 3 old files`.
|
|
125
|
+
_BOLD_ID_RE = re.compile(rf"^\*\*{ID_SHAPE}{_PART}\*\*(?=\s|$)")
|
|
126
|
+
#: GitHub's task-list checkbox where the marker goes, with a bold id after it — the shape
|
|
127
|
+
#: neither test above catches, because `[ ]` is two tokens where a marker is one and `[x]`
|
|
128
|
+
#: carries a letter (see `checkbox`).
|
|
129
|
+
_CHECKBOX_RE = re.compile(rf"^(?P<box>\[[ xX]?\]) \*\*{ID_SHAPE}{_PART}\*\*(?=\s|$)")
|
|
130
|
+
_POINTER = f" {ARROW} §"
|
|
131
|
+
|
|
132
|
+
|
|
133
|
+
def shading(label: str, declared: Sequence[str]) -> str:
|
|
134
|
+
"""The clause that makes an undeclared-block refusal actionable, or "" (RK216).
|
|
135
|
+
|
|
136
|
+
A label sharing a prefix with a declared one turns *no heading declares Block A
|
|
137
|
+
(declares: … AJ …)* into a sentence nobody can act on: the only thing it asks for is a
|
|
138
|
+
heading already there under a letter the caller never typed. Measured in Claude Code
|
|
139
|
+
Tray, on a `ship` whose task was in AJ.
|
|
140
|
+
|
|
141
|
+
One function and not one sentence per raiser, because four places compose this refusal —
|
|
142
|
+
this module's write refusal, `Census.select`, `pick` and `delivered` — and their *other*
|
|
143
|
+
clauses legitimately differ: a write may not invent a heading, a read is simply asking
|
|
144
|
+
about a block that is not there, and `delivered` has to say the ledger went unread
|
|
145
|
+
because its empty answer is consumed as evidence (RK433). The confusion is the same in
|
|
146
|
+
all four, so it is written once and the tails stay their own.
|
|
147
|
+
|
|
148
|
+
Both directions, `A` against a declared `AJ` and `AJ` against a declared `A` being one
|
|
149
|
+
mistake seen from two ends.
|
|
150
|
+
"""
|
|
151
|
+
shades = tuple(
|
|
152
|
+
other
|
|
153
|
+
for other in declared
|
|
154
|
+
if other != label and (other.startswith(label) or label.startswith(other))
|
|
155
|
+
)
|
|
156
|
+
if not shades:
|
|
157
|
+
return ""
|
|
158
|
+
verb = "share" if len(shades) > 1 else "shares"
|
|
159
|
+
return (
|
|
160
|
+
f" — but {', '.join(shades)} {verb} a prefix with {label}, so check that the label "
|
|
161
|
+
f"reached this command whole"
|
|
162
|
+
)
|
|
163
|
+
|
|
164
|
+
|
|
165
|
+
def declares(declared: Sequence[str], *, named: bool = False) -> str:
|
|
166
|
+
"""What an undeclared-block refusal says about the labels that *are* declared (RK296).
|
|
167
|
+
|
|
168
|
+
Which is **nothing**, unless there are none. RK216 put the whole list in the sentence and
|
|
169
|
+
RK257 named the file it came from, and what was left is a project with 90 blocks answering
|
|
170
|
+
a question nobody asked: the two clauses that are the remedy — which file, and `block add`
|
|
171
|
+
— arrive after a line of labels the reader has to scan past.
|
|
172
|
+
|
|
173
|
+
The list is load-bearing exactly once, when the label really was mangled, and there the
|
|
174
|
+
neighbours are what makes the mistake visible. That case is :func:`shading`'s, and it
|
|
175
|
+
already answers it *by name* — the labels sharing a prefix are the subset a confused
|
|
176
|
+
author needs. Where nothing shades, the rest are a set the author is not choosing from:
|
|
177
|
+
they typed a label, they are not picking from a menu.
|
|
178
|
+
|
|
179
|
+
Not a cap on the list, which is the answer that reads well and helps nobody: an elision
|
|
180
|
+
(`A, AA, AB, … and 87 more`) keeps the length and loses the one label that would have
|
|
181
|
+
settled it — RK68's argument about a bounded list read as the whole one.
|
|
182
|
+
|
|
183
|
+
What survives is the empty case, because "this file declares no blocks at all" is a
|
|
184
|
+
different diagnosis rather than a shorter list: there is no label to have mistyped, and
|
|
185
|
+
`block add` is the whole answer. `named` says the refusal already spelled the file, so the
|
|
186
|
+
clause says *it* rather than repeating the path.
|
|
187
|
+
"""
|
|
188
|
+
if declared:
|
|
189
|
+
return ""
|
|
190
|
+
return " (it declares none)" if named else " (nothing declares any block)"
|
|
191
|
+
|
|
192
|
+
|
|
193
|
+
class UnknownBlock(ValueError):
|
|
194
|
+
"""A block is declared by a heading and by nothing else (RK37).
|
|
195
|
+
|
|
196
|
+
Raised by every write that files something under a block — a task line (RK5) and a
|
|
197
|
+
rationale section (RK9) — because a heading invented by a write puts the text where
|
|
198
|
+
nothing looks for it, and one that is merely missing is a heading the author can add.
|
|
199
|
+
|
|
200
|
+
Which is the advice that stops being safe when the label **shares a prefix with a
|
|
201
|
+
declared one** (RK216). Measured in Claude Code Tray: a `ship` on a task in Block AJ
|
|
202
|
+
refused with *no heading declares Block A (declares: AG, AE, AB, AC, AI, AJ, …)*, from a
|
|
203
|
+
list containing AJ — a sentence nobody can act on, because the only thing it asks for is
|
|
204
|
+
a heading that is already there under a letter the caller never typed, and taking it at
|
|
205
|
+
its word opens a second heading over the first one's work.
|
|
206
|
+
|
|
207
|
+
So the confusion is named here rather than at a caller. Every write that files under a
|
|
208
|
+
block raises this one exception, and the two things needed to spot it — the label asked
|
|
209
|
+
for and the labels declared — are the two it already carries. Whatever mangled the input
|
|
210
|
+
(that incident was PowerShell 5.1 and a long inline argument), the file is untouched and
|
|
211
|
+
the message is the only thing the author has to go on.
|
|
212
|
+
|
|
213
|
+
And the **recovery is one command**, so the refusal spells it (RK257). Measured on a
|
|
214
|
+
`ship` whose roadmap plainly declared the block: the labels listed are the ledger's, not
|
|
215
|
+
the roadmap's, so an author reading a list that omits a heading they can see in front of
|
|
216
|
+
them concludes the label is wrong — the one thing it is not. Naming the file the list
|
|
217
|
+
came from and naming `block add`, which opens the heading in every governed file still
|
|
218
|
+
missing it, turns a refusal that had to be researched into one that can be acted on.
|
|
219
|
+
``where`` is the caller's to render (RK181), and every write that has a
|
|
220
|
+
:class:`~roadkeep.config.Config` passes it.
|
|
221
|
+
|
|
222
|
+
The labels themselves are **not** listed (RK296), which is the half of RK257 that was
|
|
223
|
+
left: the file and the verb are the remedy, and a line of labels in front of them is a
|
|
224
|
+
question nobody asked. :func:`declares` is where that decision is written, and
|
|
225
|
+
:attr:`declared` still carries them for a caller that wants them.
|
|
226
|
+
|
|
227
|
+
``into`` is the file the line was going into, said only when it is **not** the file the
|
|
228
|
+
labels came from (RK404). One raiser is in that position: `add` asks the ledger for the
|
|
229
|
+
heading the first `ship` will need (RK380), and the sentence it reuses was written for a
|
|
230
|
+
write into the file it names — so an author adding a line to a roadmap whose `## Block A`
|
|
231
|
+
is on the screen in front of them reads a refusal about `CHANGELOG.md` as *your label is
|
|
232
|
+
wrong*, which is the one thing it is not. The same confusion RK257 measured one surface
|
|
233
|
+
over. Absent where the two are one file, which is every other raiser: there the clause
|
|
234
|
+
would say the thing the sentence already said.
|
|
235
|
+
|
|
236
|
+
``organise`` is the role the remedy needs when the file declares **no** block at all
|
|
237
|
+
(RK405). `block add` skips such a file, so the bare command this sentence names is one
|
|
238
|
+
more refusal — measured on a project whose ledger was prose, where `ship`, `block add
|
|
239
|
+
<its label>` and `block add <a fresh label>` all declined and the guard denied the edit.
|
|
240
|
+
Said only in that state, because where the file declares blocks the argument is spent.
|
|
241
|
+
"""
|
|
242
|
+
|
|
243
|
+
def __init__(
|
|
244
|
+
self,
|
|
245
|
+
label: str,
|
|
246
|
+
declared: Sequence[str],
|
|
247
|
+
where: str = "",
|
|
248
|
+
word: str = "Block",
|
|
249
|
+
*,
|
|
250
|
+
into: str = "",
|
|
251
|
+
organise: str = "",
|
|
252
|
+
) -> None:
|
|
253
|
+
self.label = label
|
|
254
|
+
self.declared = tuple(declared)
|
|
255
|
+
self.into = into
|
|
256
|
+
self.organise = organise
|
|
257
|
+
file = f" in {where}" if where else ""
|
|
258
|
+
# The remedy that works on *this* file (RK405). `block add` skips a file organised
|
|
259
|
+
# by nothing, so where the labels came back empty the bare command is one more
|
|
260
|
+
# refusal, and the argument that opens the first heading is the whole answer.
|
|
261
|
+
starting = f" --organise {organise}" if organise and not self.declared else ""
|
|
262
|
+
elsewhere = (
|
|
263
|
+
f", though {into} (where this line goes) declares it"
|
|
264
|
+
if into and into != where
|
|
265
|
+
else ""
|
|
266
|
+
)
|
|
267
|
+
# The tail this refusal adds to the shared diagnosis: at a *write* the danger is
|
|
268
|
+
# taking "add the heading" at its word and opening a second one over the first's work.
|
|
269
|
+
shades = shading(label, self.declared)
|
|
270
|
+
if shades:
|
|
271
|
+
shades += (
|
|
272
|
+
" before declaring a second heading over the first one's work — and if it "
|
|
273
|
+
"did, the verb is"
|
|
274
|
+
)
|
|
275
|
+
else:
|
|
276
|
+
shades = "; the verb that opens it wherever it is missing is"
|
|
277
|
+
super().__init__(
|
|
278
|
+
f"no heading declares {word} {label}{file}"
|
|
279
|
+
f"{declares(self.declared, named=bool(where))}{elsewhere}: a heading "
|
|
280
|
+
f"invented by a write files the text where nothing looks for it{shades} "
|
|
281
|
+
f'`block add {label} --title "<its title>"{starting}`'
|
|
282
|
+
)
|
|
283
|
+
|
|
284
|
+
|
|
285
|
+
class RepeatedHeading(ValueError):
|
|
286
|
+
"""One label, two headings — refused at every write that files under it (RK391).
|
|
287
|
+
|
|
288
|
+
RK390 shut this door at `init`, which was one of four ways in: a roadmap edited by hand,
|
|
289
|
+
brought under the tool by `adopt`, or merged from two branches arrives at the same file,
|
|
290
|
+
and there `add --block A` filed under the **last** of them. That was never a decision —
|
|
291
|
+
it is what scanning to the end leaves — and a verb resolving an ambiguity by position is
|
|
292
|
+
the part that may not survive whatever the gate does about the state.
|
|
293
|
+
|
|
294
|
+
Refused rather than defaulted to the first, which is the same act one line earlier: both
|
|
295
|
+
headings are somebody's, the entries under each are already filed, and a tool that picks
|
|
296
|
+
one files the next line where half the readers are not looking. The **line numbers of
|
|
297
|
+
both** are named, because the fold keeps the first heading and a reader has to see which
|
|
298
|
+
that is — and the remedy is `block merge` (RK403), which does exactly that fold: it is
|
|
299
|
+
the tool's own merge of the two regions, not the hand-edit the guard denies.
|
|
300
|
+
|
|
301
|
+
`block.repeated` is the other end, and this is not it: the gate reports the state and
|
|
302
|
+
this stops a write from adding to it.
|
|
303
|
+
"""
|
|
304
|
+
|
|
305
|
+
def __init__(
|
|
306
|
+
self, label: str, linenos: Sequence[int], where: str = "", word: str = "Block"
|
|
307
|
+
) -> None:
|
|
308
|
+
self.label = label
|
|
309
|
+
self.linenos = tuple(linenos)
|
|
310
|
+
self.where = where
|
|
311
|
+
file = f"{where}:" if where else "line "
|
|
312
|
+
lines = ", ".join(f"{file}{lineno}" for lineno in self.linenos)
|
|
313
|
+
super().__init__(
|
|
314
|
+
f"{len(self.linenos)} headings declare {word} {label} ({lines}): one label is "
|
|
315
|
+
f"one heading, and a write that chose between them would file this line where "
|
|
316
|
+
f"half the readers are not looking — `block merge {label}` folds them into the first"
|
|
317
|
+
)
|
|
318
|
+
|
|
319
|
+
|
|
320
|
+
class RoundTripError(RuntimeError):
|
|
321
|
+
"""The tool may not write a file whose lines it cannot reproduce.
|
|
322
|
+
|
|
323
|
+
Refusal is the whole point: the alternative is a rewrite that silently
|
|
324
|
+
normalizes a line the parser misread.
|
|
325
|
+
"""
|
|
326
|
+
|
|
327
|
+
def __init__(self, offenders: tuple[Entry, ...], path: Path | None = None) -> None:
|
|
328
|
+
self.offenders = offenders
|
|
329
|
+
self.path = path
|
|
330
|
+
where = f"{path}: " if path else ""
|
|
331
|
+
detail = ", ".join(f"{e.task.id} (line {e.lineno})" for e in offenders)
|
|
332
|
+
super().__init__(
|
|
333
|
+
f"{where}{len(offenders)} line(s) do not round-trip and this file will "
|
|
334
|
+
f"not be rewritten: {detail}"
|
|
335
|
+
)
|
|
336
|
+
|
|
337
|
+
|
|
338
|
+
class Wrapped(ValueError):
|
|
339
|
+
"""A sentence rewrite on an entry the parse holds only the first line of (RK179).
|
|
340
|
+
|
|
341
|
+
A ledger written before this tool existed wraps its bullets, and a wrapped entry's `why`
|
|
342
|
+
is only as much of the sentence as fits on line one. Rewriting that line — which is all
|
|
343
|
+
:meth:`Document.replace_task` can reproduce — left the tail of the old sentence beneath
|
|
344
|
+
the new one, and the command printed the first line and called it amended.
|
|
345
|
+
|
|
346
|
+
Refused rather than defaulted either way, because both defaults are wrong: rewriting the
|
|
347
|
+
line alone is the entry that states an outcome followed by half a problem, and deleting
|
|
348
|
+
the span silently is prose no field of this task holds, removed by a command that was
|
|
349
|
+
asked to change a word. So the caller says how many lines the rewrite replaces — the
|
|
350
|
+
idiom `record drop --line` already uses, where naming what you read *is* the door — and
|
|
351
|
+
a count that does not match the span is refused too, an off-by-one here being the
|
|
352
|
+
deletion of somebody's paragraph.
|
|
353
|
+
|
|
354
|
+
`verb` is what the other doors reaching it asked for. `ship <id>` completing a partial
|
|
355
|
+
replaces that entry with a *different sentence* (RK193), and the roadmap's own `amend`
|
|
356
|
+
and `restate` are the same write one file over (RK195) — same rule, different word for
|
|
357
|
+
what the caller called it.
|
|
358
|
+
|
|
359
|
+
`keeps_tail` is whether passing the count *also* permits the span to be written back
|
|
360
|
+
(RK1057), which is true on the ledger and false on the roadmap. Carried rather than
|
|
361
|
+
derived from `verb`: the word is what the caller called the act and this is what the
|
|
362
|
+
file allows, and joining them would make a fifth door's message depend on which verb
|
|
363
|
+
it happened to spell.
|
|
364
|
+
"""
|
|
365
|
+
|
|
366
|
+
def __init__(
|
|
367
|
+
self,
|
|
368
|
+
task_id: str,
|
|
369
|
+
where: str,
|
|
370
|
+
entry: Entry,
|
|
371
|
+
*,
|
|
372
|
+
given: int | None,
|
|
373
|
+
verb: str = "correcting it",
|
|
374
|
+
keeps_tail: bool = False,
|
|
375
|
+
) -> None:
|
|
376
|
+
self.task_id = task_id
|
|
377
|
+
self.lineno = entry.lineno
|
|
378
|
+
self.owned = entry.stop - entry.index
|
|
379
|
+
self.given = given
|
|
380
|
+
self.keeps_tail = keeps_tail
|
|
381
|
+
span = (
|
|
382
|
+
f"lines {entry.lineno}-{entry.stop}"
|
|
383
|
+
if self.owned > 1
|
|
384
|
+
else f"line {entry.lineno}"
|
|
385
|
+
)
|
|
386
|
+
# The second half of what the count does, said only where it is true (RK1057). On
|
|
387
|
+
# the ledger `--lines` is two permissions in one flag — the span may be replaced,
|
|
388
|
+
# and `--why` may carry it back — and a message naming the first alone teaches
|
|
389
|
+
# exactly the loss it is reporting. On the roadmap it is one permission and the
|
|
390
|
+
# sentence is already whole: no multi-line task line is a non-goal, so the wrapped
|
|
391
|
+
# line is a hand-written note the format is asserting over.
|
|
392
|
+
instead = (
|
|
393
|
+
(
|
|
394
|
+
f", or a --why that carries those {self.owned} lines writes them back "
|
|
395
|
+
f"instead of collapsing them: its first line is the sentence and the rest "
|
|
396
|
+
f"is the tail, kept verbatim"
|
|
397
|
+
)
|
|
398
|
+
if keeps_tail
|
|
399
|
+
else ""
|
|
400
|
+
)
|
|
401
|
+
said = (
|
|
402
|
+
(
|
|
403
|
+
f"the parse holds only as much of its sentence as fits on line "
|
|
404
|
+
f"{entry.lineno}, so {verb} replaces all {self.owned} — read them "
|
|
405
|
+
f"with `show {task_id}`, which prints them, and pass --lines {self.owned}, "
|
|
406
|
+
f"which is you saying the text below the first line is the rest of the "
|
|
407
|
+
f"sentence being replaced{instead}"
|
|
408
|
+
)
|
|
409
|
+
if given is None
|
|
410
|
+
else (
|
|
411
|
+
f"--lines {given} is not that count: pass --lines {self.owned}, or check "
|
|
412
|
+
f"that this is the entry you read"
|
|
413
|
+
)
|
|
414
|
+
)
|
|
415
|
+
super().__init__(f"{where}:{entry.lineno}: {task_id} is written over {span} and {said}")
|
|
416
|
+
|
|
417
|
+
|
|
418
|
+
class Continuation(ValueError):
|
|
419
|
+
"""A line offered as an entry's tail that would not come back as one (RK1049).
|
|
420
|
+
|
|
421
|
+
The guard on the half of :meth:`Document.rewrite_entry` that writes text this schema
|
|
422
|
+
never renders. A continuation is defined by what the parser does with it — non-blank,
|
|
423
|
+
and read as neither a bullet, a heading, a table row nor a fence — so a tail carrying a
|
|
424
|
+
blank line splits the entry in two, and one starting `- ` files a second task under an
|
|
425
|
+
id nobody added. Both round-trip, which is exactly why L3 cannot catch either.
|
|
426
|
+
|
|
427
|
+
Refused against the **re-parse** rather than against a copy of the parser's rules: the
|
|
428
|
+
rules are :meth:`Document.parse`'s, and a second statement of them here is the one that
|
|
429
|
+
goes stale. `offered` is what the caller passed and `held` what came back, so the
|
|
430
|
+
message can name the line that stopped being a tail instead of the count that changed.
|
|
431
|
+
"""
|
|
432
|
+
|
|
433
|
+
def __init__(self, task_id: str, offered: int, held: int, line: str = "") -> None:
|
|
434
|
+
self.task_id = task_id
|
|
435
|
+
self.offered = offered
|
|
436
|
+
self.held = held
|
|
437
|
+
self.line = line
|
|
438
|
+
names = (
|
|
439
|
+
f" — {line.strip()!r} is read as a bullet, a heading, a row or a blank"
|
|
440
|
+
if line.strip()
|
|
441
|
+
else " — a blank line ends the entry, so the lines under it belong to the block"
|
|
442
|
+
)
|
|
443
|
+
super().__init__(
|
|
444
|
+
f"{task_id}: {offered} continuation line(s) were offered and {held} came back "
|
|
445
|
+
f"as this entry's{names}; a tail is prose under the bullet and nothing else"
|
|
446
|
+
)
|
|
447
|
+
|
|
448
|
+
|
|
449
|
+
def counted(
|
|
450
|
+
task_id: str,
|
|
451
|
+
where: str,
|
|
452
|
+
entry: Entry,
|
|
453
|
+
lines: int | None,
|
|
454
|
+
*,
|
|
455
|
+
verb: str,
|
|
456
|
+
keeps_tail: bool = False,
|
|
457
|
+
) -> None:
|
|
458
|
+
"""Refuse a :meth:`Document.rewrite_entry` the caller has not said they read.
|
|
459
|
+
|
|
460
|
+
Beside the write it guards rather than inside any one caller, because the invariant is
|
|
461
|
+
that method's — *no caller reaches it without having said how many lines the write
|
|
462
|
+
replaces* — and three doors do: `record amend` (RK179), the `ship` that completes a
|
|
463
|
+
partial (RK193), and the roadmap's own `amend` and `restate` (RK195). A rule restated
|
|
464
|
+
once per caller is a rule the fourth caller does not get.
|
|
465
|
+
|
|
466
|
+
What the count authorises is no longer one thing, and the split is worth naming (RK1053).
|
|
467
|
+
On the **ledger** it opens the span in both directions: the two doors there may write the
|
|
468
|
+
tail back rather than only delete it, so the caller who says they read three lines may
|
|
469
|
+
return three. On the **roadmap** it can only collapse — no multi-line task line is a
|
|
470
|
+
non-goal, so a wrapped line there is a hand-written note the format is asserting over,
|
|
471
|
+
and that deletion is the whole reason the count is asked for. The fourth caller this
|
|
472
|
+
guarded, the `--supersedes` forward pointer, no longer reaches it at all: that write
|
|
473
|
+
turned out to need only the first line.
|
|
474
|
+
|
|
475
|
+
A count that matches is silence.
|
|
476
|
+
"""
|
|
477
|
+
if lines is None:
|
|
478
|
+
if entry.wrapped:
|
|
479
|
+
raise Wrapped(
|
|
480
|
+
task_id, where, entry, given=None, verb=verb, keeps_tail=keeps_tail
|
|
481
|
+
)
|
|
482
|
+
elif lines != entry.stop - entry.index:
|
|
483
|
+
raise Wrapped(
|
|
484
|
+
task_id, where, entry, given=lines, verb=verb, keeps_tail=keeps_tail
|
|
485
|
+
)
|
|
486
|
+
|
|
487
|
+
|
|
488
|
+
class StaleFile(RuntimeError):
|
|
489
|
+
"""The file moved between the read and the write, so the write is abandoned (RK116).
|
|
490
|
+
|
|
491
|
+
The second half of L3's question. :class:`RoundTripError` asks whether this document
|
|
492
|
+
is one the tool understood; this asks whether it is still the document that was read —
|
|
493
|
+
and `save` truncating a file it last saw seconds ago is how one agent's line disappears
|
|
494
|
+
while both commands exit 0.
|
|
495
|
+
|
|
496
|
+
Deliberately blind to *what* changed: a write that lands on top of a file somebody else
|
|
497
|
+
already rewrote is refused whether the other writer was a second roadkeep process, a
|
|
498
|
+
hand edit the hook missed, or a `git checkout` mid-session. Merging is the caller's
|
|
499
|
+
business, and the caller here is asked to re-run the command against the file as it now
|
|
500
|
+
is — which costs one command and loses nothing.
|
|
501
|
+
"""
|
|
502
|
+
|
|
503
|
+
def __init__(self, path: Path | None = None, *, missing: bool = False) -> None:
|
|
504
|
+
self.path = path
|
|
505
|
+
self.missing = missing
|
|
506
|
+
where = f"{path}: " if path else ""
|
|
507
|
+
became = "no longer exists" if missing else "changed since it was read"
|
|
508
|
+
super().__init__(
|
|
509
|
+
f"{where}the file {became}, so this write was abandoned rather than "
|
|
510
|
+
f"applied on top of it — re-run the command"
|
|
511
|
+
)
|
|
512
|
+
|
|
513
|
+
|
|
514
|
+
@dataclass(frozen=True, slots=True)
|
|
515
|
+
class Entry:
|
|
516
|
+
"""A parsed task line, with the provenance needed to refuse or replace it."""
|
|
517
|
+
|
|
518
|
+
task: Task
|
|
519
|
+
raw: str
|
|
520
|
+
lineno: int # 1-based, as an editor counts
|
|
521
|
+
#: The last line this entry owns — its own, unless the bullet wraps (RK157). A ledger
|
|
522
|
+
#: written before this tool existed wraps at the median, and the lines under a bullet
|
|
523
|
+
#: parse as nothing at all, so an entry's *end* was a fact no reader held: `place`
|
|
524
|
+
#: answered "the line after the last entry" with the line after that entry's **first**
|
|
525
|
+
#: line, and every continuation below it was re-attributed to whatever shipped next.
|
|
526
|
+
#: 0 means the entry is one line, which is every line of a governed roadmap (the
|
|
527
|
+
#: format has no multi-line task line) — read through :attr:`stop`, never directly.
|
|
528
|
+
last: int = 0
|
|
529
|
+
|
|
530
|
+
@property
|
|
531
|
+
def index(self) -> int:
|
|
532
|
+
"""0-based index into :attr:`Document.lines`."""
|
|
533
|
+
return self.lineno - 1
|
|
534
|
+
|
|
535
|
+
@property
|
|
536
|
+
def stop(self) -> int:
|
|
537
|
+
"""0-based index one past the last line this entry owns — where the next one starts.
|
|
538
|
+
|
|
539
|
+
What an insertion inserts at and a removal removes up to. The two writes wanted the
|
|
540
|
+
same answer and each had its own arithmetic for it, which is the whole reason this is
|
|
541
|
+
a field: a span computed twice is a span two writes can disagree about.
|
|
542
|
+
"""
|
|
543
|
+
return max(self.last, self.lineno)
|
|
544
|
+
|
|
545
|
+
@property
|
|
546
|
+
def wrapped(self) -> bool:
|
|
547
|
+
"""Does this entry own lines the parse read nothing from?
|
|
548
|
+
|
|
549
|
+
The commonest source is a project turning the one-sentence and terminator rules off
|
|
550
|
+
for a role (RK52), which is what a ledger of history written by hand needs. It is
|
|
551
|
+
**not** the only one, and reading it that way is what left RK195 unmeasured: the
|
|
552
|
+
rules bound the bullet, and a wrapped entry is a fact about the *line beneath* it. A
|
|
553
|
+
first line that satisfies every rule and carries a hand-written note underneath is
|
|
554
|
+
wrapped, parses without a reject, and lints clean — on a roadmap, under the default
|
|
555
|
+
schema, with nothing turned off. `add` refuses to write one, which is why every
|
|
556
|
+
governed roadmap reads as zero and why adoption is the whole population.
|
|
557
|
+
"""
|
|
558
|
+
return self.last > self.lineno
|
|
559
|
+
|
|
560
|
+
|
|
561
|
+
@dataclass(frozen=True, slots=True)
|
|
562
|
+
class Reject:
|
|
563
|
+
"""A marker-bearing bullet the grammar did not accept, and why.
|
|
564
|
+
|
|
565
|
+
``block`` is the heading it sits under, known at parse time and kept because a
|
|
566
|
+
count reported per block has to report its misses per block too (RK10) — a
|
|
567
|
+
total that is honest and a column that is not is the same failure, narrower.
|
|
568
|
+
"""
|
|
569
|
+
|
|
570
|
+
raw: str
|
|
571
|
+
lineno: int
|
|
572
|
+
reason: str
|
|
573
|
+
block: str = ""
|
|
574
|
+
|
|
575
|
+
|
|
576
|
+
@dataclass(frozen=True, slots=True)
|
|
577
|
+
class Row:
|
|
578
|
+
"""A table row under a block heading — a task in a shape this format has no reader for.
|
|
579
|
+
|
|
580
|
+
A backlog kept as `| ID | Status | Task |` rows parses as **nothing**: not an entry,
|
|
581
|
+
and not a :class:`Reject` either, because a reject is a bullet that claimed the task
|
|
582
|
+
line's shape and a row never claims it. So the file reads exactly as an empty one does,
|
|
583
|
+
which is the single answer an adoption estimate may not give (RK98).
|
|
584
|
+
|
|
585
|
+
Never parsed, only counted. Reading the shape is what tells a table from an empty file;
|
|
586
|
+
reading the cells would be a second line format, and one is what L3 keeps singular.
|
|
587
|
+
"""
|
|
588
|
+
|
|
589
|
+
raw: str
|
|
590
|
+
lineno: int
|
|
591
|
+
block: str
|
|
592
|
+
|
|
593
|
+
|
|
594
|
+
@dataclass(frozen=True, slots=True)
|
|
595
|
+
class Item:
|
|
596
|
+
"""A plain list item under a block heading — the other shape with no reader (RK279).
|
|
597
|
+
|
|
598
|
+
:class:`Row` caught a backlog kept as a table. This catches the one almost every
|
|
599
|
+
unadopted roadmap is actually in: `- [ ] fix login`, `- fix login`, `1. fix login`. It
|
|
600
|
+
claims none of the task line's shape, so it is not a :class:`Reject`; it holds no pipes,
|
|
601
|
+
so it is not a :class:`Row` — and the file therefore read exactly as an empty one does,
|
|
602
|
+
which is the single answer an adoption estimate may not give (RK98).
|
|
603
|
+
|
|
604
|
+
Counted under a **declared block** and nowhere else, which is what keeps the frame out of
|
|
605
|
+
the number: a roadmap's preamble is bullets, its non-goals are bullets, and a prose aside
|
|
606
|
+
is a bullet. None of those sit under a block heading, and a task does.
|
|
607
|
+
|
|
608
|
+
Never parsed, only counted — the line :class:`Row` draws, for the same reason.
|
|
609
|
+
"""
|
|
610
|
+
|
|
611
|
+
raw: str
|
|
612
|
+
lineno: int
|
|
613
|
+
block: str
|
|
614
|
+
|
|
615
|
+
|
|
616
|
+
@dataclass(frozen=True, slots=True)
|
|
617
|
+
class Heading:
|
|
618
|
+
"""A Markdown heading. ``label`` is set when it names a block."""
|
|
619
|
+
|
|
620
|
+
level: int
|
|
621
|
+
text: str
|
|
622
|
+
lineno: int
|
|
623
|
+
label: str | None = None
|
|
624
|
+
|
|
625
|
+
|
|
626
|
+
@dataclass(frozen=True, slots=True)
|
|
627
|
+
class Document:
|
|
628
|
+
"""A governed Markdown file: verbatim lines, plus what was understood of them."""
|
|
629
|
+
|
|
630
|
+
schema: Schema
|
|
631
|
+
lines: tuple[str, ...] # with their endings, so render() is a join
|
|
632
|
+
entries: tuple[Entry, ...] = ()
|
|
633
|
+
rejects: tuple[Reject, ...] = ()
|
|
634
|
+
headings: tuple[Heading, ...] = ()
|
|
635
|
+
#: Rows of a Markdown table filed under a block heading (RK98). Read here and nowhere
|
|
636
|
+
#: else, because this is the only reader of a file — and a count taken by a second
|
|
637
|
+
#: scanner would be a second fence state machine to keep in step with this one.
|
|
638
|
+
tabular: tuple[Row, ...] = ()
|
|
639
|
+
#: Plain list items filed under a block heading (RK279) — the same contract as
|
|
640
|
+
#: :attr:`tabular`, for the shape that is not a table. Read here for the same reason:
|
|
641
|
+
#: this is the only reader of a file, and the block a line sits under is state only
|
|
642
|
+
#: this pass has.
|
|
643
|
+
listed: tuple[Item, ...] = ()
|
|
644
|
+
path: Path | None = None
|
|
645
|
+
#: The bytes :meth:`load` read, kept so :meth:`save` can ask whether the target is
|
|
646
|
+
#: still them (RK116). Carried through every mutation — the point is what was on disk
|
|
647
|
+
#: when this document was *read*, not what it holds now — and None for a document
|
|
648
|
+
#: parsed from a string, which has no disk state to have moved.
|
|
649
|
+
source: str | None = None
|
|
650
|
+
#: The project this file was read for, set by :meth:`config.Config.document` and by
|
|
651
|
+
#: nothing else — what a transaction needs to re-derive the projections its own write
|
|
652
|
+
#: stales (RK188). None for a document parsed from a string or loaded by path alone:
|
|
653
|
+
#: there is no project to project, and a save then writes exactly one file.
|
|
654
|
+
config: Config | None = None
|
|
655
|
+
|
|
656
|
+
# -- reading -----------------------------------------------------------
|
|
657
|
+
|
|
658
|
+
@classmethod
|
|
659
|
+
def parse(
|
|
660
|
+
cls, text: str, schema: Schema | None = None, path: Path | None = None
|
|
661
|
+
) -> Document:
|
|
662
|
+
schema = schema or Schema()
|
|
663
|
+
lines = tuple(text.splitlines(keepends=True))
|
|
664
|
+
entries: list[Entry] = []
|
|
665
|
+
rejects: list[Reject] = []
|
|
666
|
+
headings: list[Heading] = []
|
|
667
|
+
pipes: list[Row] = []
|
|
668
|
+
items: list[Item] = []
|
|
669
|
+
loose: set[int] = set()
|
|
670
|
+
block: str | None = None
|
|
671
|
+
|
|
672
|
+
fence: str | None = None
|
|
673
|
+
for number, raw in enumerate(lines, start=1):
|
|
674
|
+
body = raw.rstrip("\r\n")
|
|
675
|
+
opened = _FENCE_RE.match(body)
|
|
676
|
+
if opened is not None:
|
|
677
|
+
fence = _fenced(fence, opened.group("marks"))
|
|
678
|
+
continue
|
|
679
|
+
if fence is not None:
|
|
680
|
+
# Inside a fence nothing is a list item and nothing is a heading. A quoted
|
|
681
|
+
# example is what a rationale section is for, and reading it as a task gave
|
|
682
|
+
# the file an id nothing wrote and a line that could not round-trip.
|
|
683
|
+
continue
|
|
684
|
+
heading = _HEADING_RE.match(body)
|
|
685
|
+
if heading:
|
|
686
|
+
label = _block_label(heading.group("text"), schema)
|
|
687
|
+
headings.append(
|
|
688
|
+
Heading(
|
|
689
|
+
level=len(heading.group("hashes")),
|
|
690
|
+
text=heading.group("text"),
|
|
691
|
+
lineno=number,
|
|
692
|
+
label=label,
|
|
693
|
+
)
|
|
694
|
+
)
|
|
695
|
+
# A non-block heading ends the block it followed: a task under
|
|
696
|
+
# "## Priority queue" belongs to no block, and guessing one would
|
|
697
|
+
# put it in the wrong place on the next write.
|
|
698
|
+
block = label
|
|
699
|
+
continue
|
|
700
|
+
|
|
701
|
+
if _ROW_RE.match(body):
|
|
702
|
+
# Collected raw and resolved after the loop: whether a run of pipe lines is
|
|
703
|
+
# a table is decided by a rule row further down, which a single pass over
|
|
704
|
+
# the file cannot know at the line it is looking at.
|
|
705
|
+
pipes.append(Row(raw=body, lineno=number, block=block or ""))
|
|
706
|
+
continue
|
|
707
|
+
|
|
708
|
+
outcome = _read_bullet(body, schema, block or "")
|
|
709
|
+
if outcome is None:
|
|
710
|
+
if block and _ITEM_RE.match(body):
|
|
711
|
+
# A task in a shape this format has no reader for (RK279). Counted *as
|
|
712
|
+
# well as* left loose below, not instead: `loose` decides where an entry's
|
|
713
|
+
# span ends and this decides what an estimate saw, and one line can
|
|
714
|
+
# honestly be both — a continuation of the bullet above, and a bullet.
|
|
715
|
+
items.append(Item(raw=body, lineno=number, block=block))
|
|
716
|
+
if body.strip():
|
|
717
|
+
# A non-blank line this pass read nothing from: the continuation of the
|
|
718
|
+
# bullet above it, or a paragraph. Which of the two is decided after the
|
|
719
|
+
# loop, by whether anything is directly above — and it has to be decided,
|
|
720
|
+
# because until RK157 an entry's end was nobody's fact (see `Entry.last`).
|
|
721
|
+
loose.add(number)
|
|
722
|
+
continue
|
|
723
|
+
if isinstance(outcome, str):
|
|
724
|
+
rejects.append(
|
|
725
|
+
Reject(
|
|
726
|
+
raw=body, lineno=number, reason=outcome, block=block or ""
|
|
727
|
+
)
|
|
728
|
+
)
|
|
729
|
+
else:
|
|
730
|
+
entries.append(Entry(task=outcome, raw=body, lineno=number))
|
|
731
|
+
|
|
732
|
+
return cls(
|
|
733
|
+
schema=schema,
|
|
734
|
+
lines=lines,
|
|
735
|
+
entries=_spanned(entries, loose),
|
|
736
|
+
rejects=tuple(rejects),
|
|
737
|
+
headings=tuple(headings),
|
|
738
|
+
tabular=_tables(pipes),
|
|
739
|
+
listed=tuple(items),
|
|
740
|
+
path=path,
|
|
741
|
+
)
|
|
742
|
+
|
|
743
|
+
@classmethod
|
|
744
|
+
def load(cls, path: str | Path, schema: Schema | None = None) -> Document:
|
|
745
|
+
path = Path(path)
|
|
746
|
+
# newline="" keeps the file's endings intact; the default would translate
|
|
747
|
+
# CRLF to LF on read and the tool would "own" a file it silently rewrote.
|
|
748
|
+
# (open(), not read_text(newline=…) — that keyword is 3.13+, and this
|
|
749
|
+
# package supports 3.11.)
|
|
750
|
+
with path.open("r", encoding="utf-8", newline="") as handle:
|
|
751
|
+
text = handle.read()
|
|
752
|
+
# `source` is set here and nowhere else: a document that was read from disk is the
|
|
753
|
+
# only one that can find the disk changed under it (RK116).
|
|
754
|
+
return replace(_parsed(text, schema), path=path, source=text)
|
|
755
|
+
|
|
756
|
+
def render(self) -> str:
|
|
757
|
+
"""The source, exactly. This is what makes L3 a fact rather than a hope."""
|
|
758
|
+
return "".join(self.lines)
|
|
759
|
+
|
|
760
|
+
@property
|
|
761
|
+
def newline(self) -> str:
|
|
762
|
+
"""The file's dominant ending, so an inserted line matches its neighbours."""
|
|
763
|
+
for line in self.lines:
|
|
764
|
+
if line.endswith("\r\n"):
|
|
765
|
+
return "\r\n"
|
|
766
|
+
if line.endswith("\n"):
|
|
767
|
+
return "\n"
|
|
768
|
+
return "\n"
|
|
769
|
+
|
|
770
|
+
def by_id(self) -> dict[str, Entry]:
|
|
771
|
+
"""First entry per id. A duplicate id is a lint error (RK14), not a merge."""
|
|
772
|
+
out: dict[str, Entry] = {}
|
|
773
|
+
for entry in self.entries:
|
|
774
|
+
out.setdefault(entry.task.id, entry)
|
|
775
|
+
return out
|
|
776
|
+
|
|
777
|
+
def block(self, label: str) -> tuple[Entry, ...]:
|
|
778
|
+
return tuple(e for e in self.entries if e.task.block == label)
|
|
779
|
+
|
|
780
|
+
def holds(self, label: str) -> bool:
|
|
781
|
+
"""Whether any line in **this** file is filed under ``label`` (RK300).
|
|
782
|
+
|
|
783
|
+
The one reader of "is that block still occupied", and it exists because there were
|
|
784
|
+
two: `ship`'s event line and the transition `lint --since` notes (RK269) were one
|
|
785
|
+
expression written twice in modules that never call each other. That is the shape
|
|
786
|
+
this project removes everywhere else — one `GUARDED_TOOLS`, one `Schema.validate`,
|
|
787
|
+
`_only_reads` reading the parser's own declaration — and a test holding two outputs
|
|
788
|
+
level is weaker than one caller, because it does not stop a third reader from
|
|
789
|
+
spelling it a fourth way.
|
|
790
|
+
|
|
791
|
+
The event has since moved **up** rather than away (RK438): a boolean about this file
|
|
792
|
+
could not tell a finished block from a paused one, so the write path asks
|
|
793
|
+
:meth:`~roadkeep.backlog.Standing.of` for the four-state answer instead. That reader
|
|
794
|
+
is this one plus the ledger and the store, so the question is unchanged and only its
|
|
795
|
+
scope grew. `lint --since` still asks *this* file, because a transition inside one
|
|
796
|
+
document is what it reports.
|
|
797
|
+
|
|
798
|
+
Deliberately **not** named for openness. "Open" is not a property of a label, it is a
|
|
799
|
+
property of the file being asked: the roadmap is the active backlog, so
|
|
800
|
+
`roadmap.holds(label)` *is* the open question, while the deferred store answers about
|
|
801
|
+
paused work and the ledger about shipped (RK92). A name carrying the word would make
|
|
802
|
+
the wrong one of those three read as a bug rather than as a different question.
|
|
803
|
+
|
|
804
|
+
`any` and not `len(self.block(label))`: the answer is a boolean, so the walk stops at
|
|
805
|
+
the first line instead of building a tuple to measure — which is what the gate wants,
|
|
806
|
+
asking this once per declared heading per tree.
|
|
807
|
+
"""
|
|
808
|
+
return any(entry.task.block == label for entry in self.entries)
|
|
809
|
+
|
|
810
|
+
def heading(self, label: str) -> Heading | None:
|
|
811
|
+
"""The first heading naming ``label`` — where `add` inserts (RK5).
|
|
812
|
+
|
|
813
|
+
A **read**, and it keeps the first of two because every question asked of a broken
|
|
814
|
+
file has to have an answer. What may not resolve by position is a *write*, which is
|
|
815
|
+
:func:`~roadkeep.authoring.place`'s refusal off :meth:`declaring` (RK391).
|
|
816
|
+
"""
|
|
817
|
+
return next((h for h in self.headings if h.label == label), None)
|
|
818
|
+
|
|
819
|
+
def declaring(self, label: str) -> tuple[Heading, ...]:
|
|
820
|
+
"""Every heading **declaring** ``label`` — one, in a file any verb can address (RK391).
|
|
821
|
+
|
|
822
|
+
The distinction :meth:`heading` cannot make, and the reason it is a method rather
|
|
823
|
+
than a comprehension at the one call site: two headings under one label is a state
|
|
824
|
+
the gate reports and the write path refuses, and both ends have to be reading the
|
|
825
|
+
same thing. A file with none is :class:`UnknownBlock`'s case and returns empty here.
|
|
826
|
+
|
|
827
|
+
**A heading inside another's region is not a second address for it** (RK439). Shio's
|
|
828
|
+
ledger nests eight `### Block K follow-ups` under their own `## Block K`, and reading
|
|
829
|
+
every matching heading whatever its level made each one a second declaration: `lint`
|
|
830
|
+
fired `block.repeated` at all eight and every write through `place` refused, so
|
|
831
|
+
nothing could be shipped into the block at all. Neither remedy the finding names fits
|
|
832
|
+
that shape — `block drop` wants a region holding nothing and these hold 91 entries,
|
|
833
|
+
`block merge` deletes an organisation the author chose, and renaming so only the `##`
|
|
834
|
+
declares the label was measured there: 91 entries moved to `block.missing` and it was
|
|
835
|
+
reverted.
|
|
836
|
+
|
|
837
|
+
What RK391 refuses is two headings that are two *addresses* for one label — the state
|
|
838
|
+
where a write cannot know which region it files under. A heading inside another's
|
|
839
|
+
subtree is not that state: its position already says which region owns it. So the
|
|
840
|
+
test is :meth:`subtree_end`, which is where that ownership is already drawn, and it
|
|
841
|
+
is read here rather than per caller, which is what keeps the gate and the write path
|
|
842
|
+
one expression.
|
|
843
|
+
|
|
844
|
+
A nested heading naming a *different* label still declares it, and is still refused
|
|
845
|
+
where something else declares that label too: one label under two headings that are
|
|
846
|
+
not one inside the other is a genuine second address wherever it is written.
|
|
847
|
+
"""
|
|
848
|
+
kept: list[Heading] = []
|
|
849
|
+
for heading in self.headings:
|
|
850
|
+
if heading.label != label:
|
|
851
|
+
continue
|
|
852
|
+
# `lineno` is 1-based and `subtree_end` is a 0-based index one past the last line
|
|
853
|
+
# the region owns, so a heading at line L is inside it exactly while L <= that.
|
|
854
|
+
if kept and heading.lineno <= self.subtree_end(kept[-1]):
|
|
855
|
+
continue
|
|
856
|
+
kept.append(heading)
|
|
857
|
+
return tuple(kept)
|
|
858
|
+
|
|
859
|
+
def subtree_end(self, heading: Heading) -> int:
|
|
860
|
+
"""Where a heading's whole region ends: the next heading of the **same or higher**
|
|
861
|
+
level, as a 0-based index one past the last line it owns (RK115).
|
|
862
|
+
|
|
863
|
+
What a deletion takes and what an insertion may not cross. A nested heading is
|
|
864
|
+
*inside* this region — `drop` removes the subsection with the section, and a task
|
|
865
|
+
appended to a block goes after everything filed under it.
|
|
866
|
+
"""
|
|
867
|
+
return self._ends_before(heading, lambda later: later.level <= heading.level)
|
|
868
|
+
|
|
869
|
+
def prose_end(self, heading: Heading) -> int:
|
|
870
|
+
"""Where a heading's **own** prose ends: the next heading of *any* level, as a
|
|
871
|
+
0-based index one past the last line (RK115).
|
|
872
|
+
|
|
873
|
+
The other of the two answers, and the narrower one: a paragraph under a nested
|
|
874
|
+
heading belongs to that heading, so a budget charging this one may not count it and
|
|
875
|
+
a line placed past it would read as the nested heading's.
|
|
876
|
+
"""
|
|
877
|
+
return self._ends_before(heading, lambda later: True)
|
|
878
|
+
|
|
879
|
+
def _ends_before(self, heading: Heading, stops: Callable[[Heading], bool]) -> int:
|
|
880
|
+
"""The one loop the two rules above differ only in the predicate of.
|
|
881
|
+
|
|
882
|
+
Four call sites used to walk :attr:`headings` themselves — two under each rule —
|
|
883
|
+
which is the id's defect (RK109) one structure over: a question answered where it is
|
|
884
|
+
asked rather than by the thing that read the file. No boolean, because a flag passed
|
|
885
|
+
by hand is what that fix removed: the two rules are two names.
|
|
886
|
+
"""
|
|
887
|
+
for later in self.headings:
|
|
888
|
+
if later.lineno > heading.lineno and stops(later):
|
|
889
|
+
return later.lineno - 1
|
|
890
|
+
return len(self.lines)
|
|
891
|
+
|
|
892
|
+
# -- the ownership test ------------------------------------------------
|
|
893
|
+
|
|
894
|
+
@property
|
|
895
|
+
def non_canonical(self) -> tuple[Entry, ...]:
|
|
896
|
+
"""Entries the schema would render differently from how they are written."""
|
|
897
|
+
return tuple(e for e in self.entries if self.schema.render(e.task) != e.raw)
|
|
898
|
+
|
|
899
|
+
def ensure_writable(self) -> None:
|
|
900
|
+
offenders = self.non_canonical
|
|
901
|
+
if offenders:
|
|
902
|
+
raise RoundTripError(offenders, self.path)
|
|
903
|
+
|
|
904
|
+
# -- writing (every mutator refuses first) -----------------------------
|
|
905
|
+
|
|
906
|
+
def replace_line(self, index: int, raw: str) -> Document:
|
|
907
|
+
self.ensure_writable()
|
|
908
|
+
lines = list(self.lines)
|
|
909
|
+
lines[index] = raw + ending(lines[index])
|
|
910
|
+
return self._reparse(lines)
|
|
911
|
+
|
|
912
|
+
def insert_line(self, index: int, raw: str) -> Document:
|
|
913
|
+
"""Insert before ``index``; ``len(lines)`` appends."""
|
|
914
|
+
self.ensure_writable()
|
|
915
|
+
lines = list(self.lines)
|
|
916
|
+
# A file whose last line has no ending would otherwise get the new line
|
|
917
|
+
# glued onto it — the exact corruption this module exists to prevent.
|
|
918
|
+
if lines and index >= len(lines) and not ending(lines[-1]):
|
|
919
|
+
lines[-1] += self.newline
|
|
920
|
+
lines.insert(index, raw + self.newline)
|
|
921
|
+
return self._reparse(lines)
|
|
922
|
+
|
|
923
|
+
def remove_line(self, index: int) -> Document:
|
|
924
|
+
return self.remove_lines(index, index + 1)
|
|
925
|
+
|
|
926
|
+
def remove_lines(self, start: int, stop: int) -> Document:
|
|
927
|
+
"""Delete ``[start, stop)`` in one edit — validated once, re-parsed once (RK54).
|
|
928
|
+
|
|
929
|
+
One edit and not a loop, because every intermediate state of a loop is validated as
|
|
930
|
+
if it were the finished file: deleting a section whose prose quotes a fenced example
|
|
931
|
+
removes the fence's opening line first, and the quoted task line inside it is then
|
|
932
|
+
briefly outside any fence, parses, and refuses the rest of the deletion.
|
|
933
|
+
"""
|
|
934
|
+
self.ensure_writable()
|
|
935
|
+
lines = list(self.lines)
|
|
936
|
+
del lines[start:stop]
|
|
937
|
+
return self._reparse(lines)
|
|
938
|
+
|
|
939
|
+
def replace_task(self, entry: Entry, task: Task) -> Document:
|
|
940
|
+
"""Re-render one entry from its data — the only way a task line changes.
|
|
941
|
+
|
|
942
|
+
The **first** line, and deliberately not the span (RK157): every field the schema
|
|
943
|
+
renders was read off that line, so rewriting it is lossless, while replacing the
|
|
944
|
+
whole span with one rendered line would delete continuation lines whose text this
|
|
945
|
+
task never held — somebody's paragraph, removed by a command that was asked to
|
|
946
|
+
change an id. The span is what an insertion and a removal need; a rewrite needs the
|
|
947
|
+
line it can actually reproduce.
|
|
948
|
+
"""
|
|
949
|
+
return self.replace_line(entry.index, self.schema.render(task))
|
|
950
|
+
|
|
951
|
+
def rewrite_entry(
|
|
952
|
+
self, entry: Entry, task: Task, below: Sequence[str] = ()
|
|
953
|
+
) -> Document:
|
|
954
|
+
"""Re-render one entry over its **whole span**, collapsing a wrap to one line.
|
|
955
|
+
|
|
956
|
+
The other half of :meth:`replace_task`'s split (RK179). That one is right where the
|
|
957
|
+
rewrite cannot contradict the lines beneath it — an id, a marker — and wrong the
|
|
958
|
+
moment the *sentence* changes, because a wrapped entry's `why` is only as much of
|
|
959
|
+
the sentence as fits on the first line: rewriting that line alone leaves the tail of
|
|
960
|
+
the old one underneath the new one, in an entry the command just called amended.
|
|
961
|
+
|
|
962
|
+
So this one really does delete prose, which is why no caller reaches it without
|
|
963
|
+
having said how many lines the write replaces. What goes is text no field of this
|
|
964
|
+
task holds, and the only reader who can call it the old sentence's tail is the one
|
|
965
|
+
who read it.
|
|
966
|
+
|
|
967
|
+
`below` is the tail put back (RK1049) — the shape the parser accepts and this method
|
|
968
|
+
could not produce, so the only writable outcome for a five-line entry was one line.
|
|
969
|
+
Written **verbatim**, because no field of this task holds it: the schema renders the
|
|
970
|
+
first line and these are the author's bytes, checked by re-parsing rather than by
|
|
971
|
+
restating the parser's rules (:class:`Continuation`). Empty is the collapse this
|
|
972
|
+
method always did, and stays the default.
|
|
973
|
+
"""
|
|
974
|
+
self.ensure_writable()
|
|
975
|
+
lines = list(self.lines)
|
|
976
|
+
# One edit and not a replace-then-delete, for `remove_lines`'s reason (RK54): each
|
|
977
|
+
# intermediate state of a loop is validated as if it were the finished file. The
|
|
978
|
+
# ending is the *last* line's, so a file that ends without one still does.
|
|
979
|
+
# The span's own ending goes on the *last* line written, so a file that ends
|
|
980
|
+
# without one still does; the lines above it get the file's, which is the only
|
|
981
|
+
# ending a line that did not exist a moment ago could be given.
|
|
982
|
+
tail = ending(lines[entry.stop - 1])
|
|
983
|
+
written = [self.schema.render(task), *below]
|
|
984
|
+
lines[entry.index : entry.stop] = [
|
|
985
|
+
raw + (tail if index == len(written) - 1 else self.newline)
|
|
986
|
+
for index, raw in enumerate(written)
|
|
987
|
+
]
|
|
988
|
+
document = self._reparse(lines)
|
|
989
|
+
if below:
|
|
990
|
+
# The one check, and made after the fact on purpose: a tail is whatever the
|
|
991
|
+
# parser reads as one, so the question "did these come back as this entry's?"
|
|
992
|
+
# is answerable only by the parse that answers it for every other line.
|
|
993
|
+
rewritten = document.by_id().get(task.id)
|
|
994
|
+
held = 0 if rewritten is None else rewritten.stop - rewritten.index - 1
|
|
995
|
+
if held != len(below):
|
|
996
|
+
raise Continuation(task.id, len(below), held, below[min(held, len(below) - 1)])
|
|
997
|
+
return document
|
|
998
|
+
|
|
999
|
+
def assert_current(self, path: str | Path | None = None) -> None:
|
|
1000
|
+
"""Refuse if the target is no longer the file this document was read from (RK116).
|
|
1001
|
+
|
|
1002
|
+
The check `save` makes, callable on its own so a transaction that writes several
|
|
1003
|
+
files can ask about all of them before it writes any (RK6): a refusal raised
|
|
1004
|
+
halfway through leaves the state the all-or-nothing rule exists to prevent.
|
|
1005
|
+
|
|
1006
|
+
Silent in the two cases where there is nothing to compare: a document parsed from a
|
|
1007
|
+
string, which never had disk state, and a save to a path other than the one it was
|
|
1008
|
+
read from, where the target is a different file and not a changed one.
|
|
1009
|
+
"""
|
|
1010
|
+
target = Path(path) if path is not None else self.path
|
|
1011
|
+
if self.source is None or target is None or target != self.path:
|
|
1012
|
+
return
|
|
1013
|
+
if not target.is_file():
|
|
1014
|
+
raise StaleFile(target, missing=True)
|
|
1015
|
+
with target.open("r", encoding="utf-8", newline="") as handle:
|
|
1016
|
+
if handle.read() != self.source:
|
|
1017
|
+
raise StaleFile(target)
|
|
1018
|
+
|
|
1019
|
+
def save(self, path: str | Path | None = None) -> tuple[Path, ...]:
|
|
1020
|
+
"""Write this file, and answer **every** path that took, projections included.
|
|
1021
|
+
|
|
1022
|
+
The whole list and not this file's own (RK1130). A one-document transaction refreshes
|
|
1023
|
+
the derived block exactly as a three-document one does — that is what routing through
|
|
1024
|
+
:func:`save_all` below says — and answering only the target left every caller composing
|
|
1025
|
+
a commit with no way to name the file it had just refreshed. Measured: four of the
|
|
1026
|
+
thirty-two write commands printed a `git add --` line, and the other twenty-eight had
|
|
1027
|
+
nothing to print it from.
|
|
1028
|
+
|
|
1029
|
+
A path **argument** is the one case that writes alone: it is a copy to somewhere the
|
|
1030
|
+
project does not govern, so it stales no projection and the answer is that one file.
|
|
1031
|
+
"""
|
|
1032
|
+
target = Path(path) if path is not None else self.path
|
|
1033
|
+
if target is None:
|
|
1034
|
+
raise ValueError("no path to save to")
|
|
1035
|
+
if target == self.path:
|
|
1036
|
+
# The one-document transaction, and not a shorter path around one: a write that
|
|
1037
|
+
# stales a derived block owes the refresh whether it touched one file or three
|
|
1038
|
+
# (RK188), and `save_all` is where that is stated once.
|
|
1039
|
+
return save_all(self)
|
|
1040
|
+
self.ensure_writable()
|
|
1041
|
+
# Both halves of "may this file be rewritten": one the tool understood, and one
|
|
1042
|
+
# nobody else has touched since (RK116). Re-read and not stat'd — a modification
|
|
1043
|
+
# time is a second source of truth about the bytes, and the coarser one.
|
|
1044
|
+
self.assert_current(target)
|
|
1045
|
+
write_atomically(target, self.render())
|
|
1046
|
+
return (target,)
|
|
1047
|
+
|
|
1048
|
+
def _reparse(self, lines: list[str]) -> Document:
|
|
1049
|
+
# Reparse rather than patch the entry tuples: line numbers shift, and a
|
|
1050
|
+
# document that reports stale ones is worse than one that costs a reparse.
|
|
1051
|
+
parsed = Document.parse("".join(lines), schema=self.schema, path=self.path)
|
|
1052
|
+
# `source` survives the edit: it is what the file held when it was *read*, and an
|
|
1053
|
+
# edited document is exactly the one that needs to know that (RK116). So does
|
|
1054
|
+
# `config`, for the same reason — an edited document is the one about to be saved.
|
|
1055
|
+
return replace(parsed, path=self.path, source=self.source, config=self.config)
|
|
1056
|
+
|
|
1057
|
+
|
|
1058
|
+
@lru_cache(maxsize=_PARSE_CACHE)
|
|
1059
|
+
def _parsed(text: str, schema: Schema) -> Document:
|
|
1060
|
+
"""One parse per distinct (bytes, schema), because a command reads a file more than once.
|
|
1061
|
+
|
|
1062
|
+
Measured for RK211, on the write that motivated it: a `status` change parses the three
|
|
1063
|
+
counted roles through `Backlog.load`, and the projection RK188 put in the same
|
|
1064
|
+
transaction parses them again — 9.1 ms of Turing's 17.1 ms refresh, on a file the
|
|
1065
|
+
command had already read a millisecond earlier. `pick`, `budget` and `lint` each read
|
|
1066
|
+
the same file two or three ways for the same reason.
|
|
1067
|
+
|
|
1068
|
+
Keyed by the **text**, so the bytes are still read from disk every single time. That is
|
|
1069
|
+
what makes it a memo rather than a cache: a file somebody else changed produces a
|
|
1070
|
+
different key and a fresh parse, so there is no state to invalidate and no window where
|
|
1071
|
+
this answers about a file that has moved (RK116's question is asked of the disk either
|
|
1072
|
+
way). What it costs is hashing the text — 0.1 ms on Turing's 800 KB ledger against the
|
|
1073
|
+
7.3 ms parse it skips.
|
|
1074
|
+
|
|
1075
|
+
Small on purpose. The entries are immutable and shared, which is safe because every
|
|
1076
|
+
mutator returns a new document (L3), but a long-lived process — the MCP server — would
|
|
1077
|
+
otherwise hold every revision of a ledger it ever read.
|
|
1078
|
+
"""
|
|
1079
|
+
return Document.parse(text, schema=schema)
|
|
1080
|
+
|
|
1081
|
+
|
|
1082
|
+
def write_atomically(target: Path, text: str) -> None:
|
|
1083
|
+
"""Replace a file's whole content in one step, so no reader ever sees half of it (RK118).
|
|
1084
|
+
|
|
1085
|
+
`write_text` truncates the target and then fills it, and a reader arriving between those
|
|
1086
|
+
two moments does not get an old file or a new one — it gets a **shorter** file that
|
|
1087
|
+
parses, because every line still in it is a line the schema accepts. The roadmap simply
|
|
1088
|
+
has fewer tasks, and nothing about that is loud enough to notice.
|
|
1089
|
+
|
|
1090
|
+
So the content is written to a temporary file in the target's **own directory** — same
|
|
1091
|
+
filesystem, or the rename would be a copy — and :func:`os.replace` puts it in place,
|
|
1092
|
+
which is one step on both platforms this runs on. What that buys is not an atomic
|
|
1093
|
+
transaction across the three files a `ship` writes: it is that every state a reader can
|
|
1094
|
+
catch is a *whole* file, which is the state the tool already knows how to read.
|
|
1095
|
+
|
|
1096
|
+
The two halves are :func:`stage` and :func:`commit` because a transaction needs them
|
|
1097
|
+
apart (RK131); a single-file write is the pair called back to back.
|
|
1098
|
+
"""
|
|
1099
|
+
scratch = stage(target, text)
|
|
1100
|
+
try:
|
|
1101
|
+
commit(scratch, target)
|
|
1102
|
+
finally:
|
|
1103
|
+
discard(scratch)
|
|
1104
|
+
|
|
1105
|
+
|
|
1106
|
+
def stage(target: Path, text: str) -> Path:
|
|
1107
|
+
"""Write the new content beside its target, under a name only this process uses.
|
|
1108
|
+
|
|
1109
|
+
The target's **own directory**, or the rename that follows would be a copy across
|
|
1110
|
+
filesystems and no longer one step. Nothing about the target is touched here, which is
|
|
1111
|
+
what lets a transaction stage every file it writes before it commits any of them.
|
|
1112
|
+
|
|
1113
|
+
**And the bytes are on the disk before this returns** (RK450). `write_text` returns once
|
|
1114
|
+
they are in the page cache, and :func:`commit` renames immediately after — so the
|
|
1115
|
+
filesystem journals the rename's *metadata*, the directory entry lands, and the data
|
|
1116
|
+
blocks behind it were never written. A crash there leaves the target at its **new size
|
|
1117
|
+
and entirely NUL**, which is the one state RK118 says a reader cannot catch: it is not a
|
|
1118
|
+
whole file, and it is not the old one either. Measured on this repository, from a hard
|
|
1119
|
+
reboot mid-session: `ROADMAP.md`, `CHANGELOG.md`, `IMPROVEMENTS.md` and `README.md` at
|
|
1120
|
+
2,980, 121,337, 4,333 and 24,068 bytes, every byte NUL, recoverable only because git had
|
|
1121
|
+
them. `os.replace` is atomic with respect to two versions of a file and says nothing
|
|
1122
|
+
about the durability of either.
|
|
1123
|
+
|
|
1124
|
+
So the handle is flushed out of Python's buffer and :func:`os.fsync` puts it on the
|
|
1125
|
+
device. One syscall per governed file per write, which is what every editor and every
|
|
1126
|
+
database does between these two steps.
|
|
1127
|
+
|
|
1128
|
+
**The directory entry is deliberately not synced**, which is the question §RK450 left
|
|
1129
|
+
open. On POSIX a rename is durable only once the *directory* is synced too, and losing
|
|
1130
|
+
that sync loses the rename — leaving the previous whole file, which is a state this tool
|
|
1131
|
+
already knows how to read and a reader can act on. That is a lost write, not a corrupt
|
|
1132
|
+
one, and the two are worth different prices: Windows exposes no handle to sync a
|
|
1133
|
+
directory with, so buying it would mean a platform-conditional path for the failure mode
|
|
1134
|
+
that is already safe.
|
|
1135
|
+
"""
|
|
1136
|
+
scratch = target.with_name(f".{target.name}.roadkeep-{os.getpid()}.tmp")
|
|
1137
|
+
with scratch.open("w", encoding="utf-8", newline="") as handle:
|
|
1138
|
+
handle.write(text)
|
|
1139
|
+
handle.flush()
|
|
1140
|
+
os.fsync(handle.fileno())
|
|
1141
|
+
return scratch
|
|
1142
|
+
|
|
1143
|
+
|
|
1144
|
+
def commit(scratch: Path, target: Path) -> None:
|
|
1145
|
+
"""Put a staged file in place with :func:`os.replace`, which is one step on both platforms.
|
|
1146
|
+
|
|
1147
|
+
The retry is Windows: a rename over a file another process has open can fail while an
|
|
1148
|
+
indexer or a virus scanner holds it for a moment. A failure that outlasts the retries is
|
|
1149
|
+
raised as the :class:`OSError` it is, and every writing command already refuses on one.
|
|
1150
|
+
"""
|
|
1151
|
+
for remaining in reversed(range(_REPLACE_TRIES)):
|
|
1152
|
+
try:
|
|
1153
|
+
os.replace(scratch, target)
|
|
1154
|
+
return
|
|
1155
|
+
except PermissionError:
|
|
1156
|
+
if not remaining:
|
|
1157
|
+
raise
|
|
1158
|
+
time.sleep(_REPLACE_PAUSE)
|
|
1159
|
+
|
|
1160
|
+
|
|
1161
|
+
def discard(scratch: Path) -> None:
|
|
1162
|
+
# The scratch file is this process's own and named after it, so removing it can never
|
|
1163
|
+
# take somebody else's — and a temporary file left behind by a failed write is litter
|
|
1164
|
+
# in a directory the tool asked to be trusted with.
|
|
1165
|
+
with contextlib.suppress(OSError):
|
|
1166
|
+
scratch.unlink()
|
|
1167
|
+
|
|
1168
|
+
|
|
1169
|
+
@dataclass(frozen=True, slots=True)
|
|
1170
|
+
class Write:
|
|
1171
|
+
"""One file a transaction will replace, as :func:`write_all` needs it (RK187).
|
|
1172
|
+
|
|
1173
|
+
Three things and no document: where the bytes go, what they are, and the question that
|
|
1174
|
+
still has to be true when they land. The third is a callable rather than a source
|
|
1175
|
+
string because what "unchanged" means is the caller's — a governed file compares the
|
|
1176
|
+
text it parsed (RK116), and a README this tool does not own compares the bytes it read
|
|
1177
|
+
(RK132), which is the same question asked of a file with no format to parse.
|
|
1178
|
+
"""
|
|
1179
|
+
|
|
1180
|
+
target: Path
|
|
1181
|
+
text: str
|
|
1182
|
+
#: Raises :class:`StaleFile` where the target stopped being the file that was read.
|
|
1183
|
+
assert_current: Callable[[], None]
|
|
1184
|
+
|
|
1185
|
+
|
|
1186
|
+
def write_all(*writes: Write) -> tuple[Path, ...]:
|
|
1187
|
+
"""Stage every file, ask every target, then rename in order (RK131, RK187, RK6).
|
|
1188
|
+
|
|
1189
|
+
The obvious arrangement — ask every target first, then write each in turn — leaves the
|
|
1190
|
+
rendering and the writing of file *n-1* inside the window between the question and file
|
|
1191
|
+
*n*'s write, and a writer landing in it is refused on the second file after the first
|
|
1192
|
+
has already been written. That is the half-applied state the question was asked to
|
|
1193
|
+
prevent, made rarer rather than impossible.
|
|
1194
|
+
|
|
1195
|
+
So the order is inverted: every file is rendered to its scratch name first, where it
|
|
1196
|
+
costs nothing and is visible to nobody, *then* every target is asked whether it is still
|
|
1197
|
+
the file that was read, and only then are the renames made. What is left between the
|
|
1198
|
+
question and the last write is the renames themselves — no rendering, no I/O on any
|
|
1199
|
+
source, nothing that can raise for a reason of its own — which is as close to one step
|
|
1200
|
+
as three files on a filesystem get.
|
|
1201
|
+
|
|
1202
|
+
The argument order is the rename order, and every caller's ordering rationale is about
|
|
1203
|
+
which halfway state a crash leaves (see :meth:`shipping.Departure.save`).
|
|
1204
|
+
|
|
1205
|
+
One function for the rule, because the two callers are two kinds of file and one
|
|
1206
|
+
guarantee: `ship` writes three documents it parsed, `export` splices two projections
|
|
1207
|
+
into files it does not own, and a second phrasing of "all or none" is a second thing to
|
|
1208
|
+
keep true.
|
|
1209
|
+
"""
|
|
1210
|
+
staged: list[tuple[Path, Write]] = []
|
|
1211
|
+
try:
|
|
1212
|
+
for write in writes:
|
|
1213
|
+
staged.append((stage(write.target, write.text), write))
|
|
1214
|
+
for _, write in staged:
|
|
1215
|
+
write.assert_current()
|
|
1216
|
+
for scratch, write in staged:
|
|
1217
|
+
commit(scratch, write.target)
|
|
1218
|
+
finally:
|
|
1219
|
+
for scratch, _ in staged:
|
|
1220
|
+
discard(scratch)
|
|
1221
|
+
return tuple(write.target for _, write in staged)
|
|
1222
|
+
|
|
1223
|
+
|
|
1224
|
+
def save_all(*documents: Document | None) -> tuple[Path, ...]:
|
|
1225
|
+
""":func:`write_all` for the files this tool parsed, plus what they derive (RK188).
|
|
1226
|
+
|
|
1227
|
+
A None is skipped, because a transaction's optional file is absent and not stale.
|
|
1228
|
+
"""
|
|
1229
|
+
writes: list[Write] = []
|
|
1230
|
+
for document in documents:
|
|
1231
|
+
if document is None:
|
|
1232
|
+
continue
|
|
1233
|
+
target = document.path
|
|
1234
|
+
if target is None:
|
|
1235
|
+
raise ValueError("no path to save to")
|
|
1236
|
+
# Before anything is staged: a document that would not round-trip is refused for
|
|
1237
|
+
# the whole transaction, not for the file it happened to be discovered on (L3).
|
|
1238
|
+
document.ensure_writable()
|
|
1239
|
+
writes.append(Write(target, document.render(), document.assert_current))
|
|
1240
|
+
# Derived last, so the rename order leaves the recoverable halfway state: a crash after
|
|
1241
|
+
# the governed files land is a block `lint` names and one command repairs, where the
|
|
1242
|
+
# reverse would be a README stating counts no file holds.
|
|
1243
|
+
return write_all(*writes, *_projected(documents))
|
|
1244
|
+
|
|
1245
|
+
|
|
1246
|
+
def _projected(documents: Sequence[Document | None]) -> tuple[Write, ...]:
|
|
1247
|
+
"""The derived blocks this transaction stales, refreshed *inside* it (RK188).
|
|
1248
|
+
|
|
1249
|
+
Every governed write changes what a README or a landing page would render, and RK104
|
|
1250
|
+
put the gate over that block without giving any verb the job of writing it — so ten
|
|
1251
|
+
claims and ten ships each left this repository failing its own conformance run on a
|
|
1252
|
+
file the task never touched. The block is derived wholly from documents this call
|
|
1253
|
+
already holds, which makes it the same kind of thing as a dep annotation or a pointer:
|
|
1254
|
+
the write that invalidates it is the write that owes it.
|
|
1255
|
+
|
|
1256
|
+
Imported inside the function because the dependency runs the other way — a projection
|
|
1257
|
+
reads documents, so `exporting` imports this module and a module-level import here
|
|
1258
|
+
would be a cycle. It belongs here anyway: this is where a transaction is assembled,
|
|
1259
|
+
and a refresh planned anywhere else would land outside `write_all`'s all-or-nothing
|
|
1260
|
+
rule (RK187), which is the one thing that keeps a half-refreshed pair impossible.
|
|
1261
|
+
"""
|
|
1262
|
+
held = [document for document in documents if document is not None]
|
|
1263
|
+
config = next((document.config for document in held if document.config), None)
|
|
1264
|
+
if config is None:
|
|
1265
|
+
return ()
|
|
1266
|
+
from roadkeep.exporting import refreshes
|
|
1267
|
+
|
|
1268
|
+
return refreshes(config, held)
|
|
1269
|
+
|
|
1270
|
+
|
|
1271
|
+
def _spanned(entries: list[Entry], loose: set[int]) -> tuple[Entry, ...]:
|
|
1272
|
+
"""Give every entry its end: the run of non-blank unparsed lines directly beneath it.
|
|
1273
|
+
|
|
1274
|
+
The rule §RK157 names, and the reason it is the parser's to state rather than a writer's
|
|
1275
|
+
guess: an entry ends at the line before the next bullet, heading, table row or blank. A
|
|
1276
|
+
blank breaks the run because a paragraph one line down belongs to the block, not to the
|
|
1277
|
+
bullet above it — which is also what keeps a block's own introduction (RK108) out of the
|
|
1278
|
+
last entry of the block before it.
|
|
1279
|
+
"""
|
|
1280
|
+
return tuple(
|
|
1281
|
+
replace(entry, last=_run(entry.lineno, loose)) for entry in entries
|
|
1282
|
+
)
|
|
1283
|
+
|
|
1284
|
+
|
|
1285
|
+
def _run(lineno: int, loose: set[int]) -> int:
|
|
1286
|
+
last = lineno
|
|
1287
|
+
while last + 1 in loose:
|
|
1288
|
+
last += 1
|
|
1289
|
+
return last
|
|
1290
|
+
|
|
1291
|
+
|
|
1292
|
+
def blank(line: str) -> bool:
|
|
1293
|
+
"""A line with no content — what separates a heading from what belongs to it.
|
|
1294
|
+
|
|
1295
|
+
Public because every writer has to reason about it: a task glued to a heading, or a
|
|
1296
|
+
doubled blank left where a line was removed, is a change to the file's shape that
|
|
1297
|
+
the round-trip cannot catch because both spellings round-trip.
|
|
1298
|
+
"""
|
|
1299
|
+
return not line.strip()
|
|
1300
|
+
|
|
1301
|
+
|
|
1302
|
+
def ending(line: str) -> str:
|
|
1303
|
+
"""The line's own terminator, or empty at a file that ends without one.
|
|
1304
|
+
|
|
1305
|
+
Public for the same reason as :func:`blank`: a writer that replaces a line has to put
|
|
1306
|
+
back the ending that line had, and a second implementation of this would be the one
|
|
1307
|
+
that turns a CRLF file into a mixed one on the first fix (RK16).
|
|
1308
|
+
"""
|
|
1309
|
+
for candidate in ("\r\n", "\n", "\r"):
|
|
1310
|
+
if line.endswith(candidate):
|
|
1311
|
+
return candidate
|
|
1312
|
+
return ""
|
|
1313
|
+
|
|
1314
|
+
|
|
1315
|
+
def _looks_like_marker(token: str, schema: Schema) -> bool:
|
|
1316
|
+
"""Is this token *meant* to be a status marker?
|
|
1317
|
+
|
|
1318
|
+
Deliberately looser than the schema: a marker followed by U+FE0F renders
|
|
1319
|
+
identically in an editor, so a line carrying one would otherwise be skipped in
|
|
1320
|
+
silence — invisible drift, uncounted and unreported. Read it instead, and let
|
|
1321
|
+
the round-trip refuse the write and lint name the character.
|
|
1322
|
+
"""
|
|
1323
|
+
stripped = _bare(token)
|
|
1324
|
+
return any(
|
|
1325
|
+
token == marker or stripped == marker
|
|
1326
|
+
for marker in (*schema.markers, schema.shipped_marker)
|
|
1327
|
+
)
|
|
1328
|
+
|
|
1329
|
+
|
|
1330
|
+
def _bare(token: str) -> str:
|
|
1331
|
+
"""A marker token without the codepoints that render as nothing.
|
|
1332
|
+
|
|
1333
|
+
One function because two tests read a marker off a line \u2014 is this one at all, and is it
|
|
1334
|
+
the departure a markerless ledger may carry (RK125) \u2014 and a second copy of the pair is a
|
|
1335
|
+
second answer to "does a trash marker with a variation selector count".
|
|
1336
|
+
"""
|
|
1337
|
+
return token.rstrip("\ufe0f\u200d") # variation selector, ZWJ
|
|
1338
|
+
|
|
1339
|
+
|
|
1340
|
+
def _wears_the_marker_slot(rest: str, token: str) -> bool:
|
|
1341
|
+
"""A bullet whose first token sits where a marker sits and is not one.
|
|
1342
|
+
|
|
1343
|
+
The silent miss :mod:`roadkeep.counting` exists to end: a line written with a
|
|
1344
|
+
marker this project does not declare — a ✨ from another repository's set, a ✅
|
|
1345
|
+
in the roadmap — matches no marker, so it is read as prose and disappears from
|
|
1346
|
+
every count without being rejected either.
|
|
1347
|
+
|
|
1348
|
+
The token must carry no letter or digit, which is what separates it from prose:
|
|
1349
|
+
``- See **RK5** for the design.`` also puts a bold id second, and reporting it
|
|
1350
|
+
would make the audit the noise its own symptom names.
|
|
1351
|
+
"""
|
|
1352
|
+
return bool(token) and not any(c.isalnum() for c in token) and bool(
|
|
1353
|
+
_MARKER_SLOT_RE.match(rest)
|
|
1354
|
+
)
|
|
1355
|
+
|
|
1356
|
+
|
|
1357
|
+
def _retirement(token: str, schema: Schema) -> bool:
|
|
1358
|
+
"""The one marker a line in a markerless ledger may carry: a departure (RK125).
|
|
1359
|
+
|
|
1360
|
+
Asked of :meth:`Schema.marks`, so the grammar and the renderer cannot disagree about
|
|
1361
|
+
which line writes the slot — the parser reads a marker exactly where `render` would put
|
|
1362
|
+
one, which is what keeps the round-trip (L3) an identity rather than a hope.
|
|
1363
|
+
|
|
1364
|
+
Tolerant of the variation selector for the same reason :func:`_looks_like_marker` is: a
|
|
1365
|
+
🗑️ renders identically in an editor, so reading it as prose would hide the line from
|
|
1366
|
+
every count instead of letting `lint --fix` name the codepoint.
|
|
1367
|
+
"""
|
|
1368
|
+
if schema.marker_field or not schema.marks(schema.retired_marker):
|
|
1369
|
+
return False
|
|
1370
|
+
return schema.retired_marker in (token, _bare(token))
|
|
1371
|
+
|
|
1372
|
+
|
|
1373
|
+
def _leads_with_the_id(rest: str) -> bool:
|
|
1374
|
+
"""A bullet whose first token *is* the bold id: the slot is empty, not wrong (RK43).
|
|
1375
|
+
|
|
1376
|
+
The wider half of the same silent miss, and the one that was measured: Shio's
|
|
1377
|
+
changelog is 920 bullets, and it parsed as **0 entries and 0 rejects** — every line
|
|
1378
|
+
writes ``- **SH125** — …`` with no marker at all, so none of them wears the slot
|
|
1379
|
+
wrongly, they leave it out, and :func:`_wears_the_marker_slot` declines them because
|
|
1380
|
+
the first token carries alphanumerics. Turing's writes 755 of the same.
|
|
1381
|
+
|
|
1382
|
+
Id-shaped and nothing after the bold, which is what keeps this off prose that also
|
|
1383
|
+
leads with bold: ``- **Delete** the 3 old files`` carries no digit and
|
|
1384
|
+
``- **SH239**: a benchmark …`` puts a colon where the grammar has a space.
|
|
1385
|
+
"""
|
|
1386
|
+
return bool(_BOLD_ID_RE.match(rest))
|
|
1387
|
+
|
|
1388
|
+
|
|
1389
|
+
def checkbox(rest: str) -> str | None:
|
|
1390
|
+
"""The task-list checkbox this bullet puts where the status goes, or None (RK103).
|
|
1391
|
+
|
|
1392
|
+
``- [ ] **C40** · …`` is GitHub's task-list syntax, which is what a Markdown backlog
|
|
1393
|
+
looks like when nobody chose a format — and it was the last shape read as prose by
|
|
1394
|
+
everything. The first whitespace-delimited token is ``[`` and never ``[ ]``, so it
|
|
1395
|
+
matches no marker; :func:`_wears_the_marker_slot` wants the bold id second and this
|
|
1396
|
+
puts it third; :func:`_leads_with_the_id` wants the bullet to open with the bold.
|
|
1397
|
+
Measured on cursarei: 16 such lines, **0 entries and 0 rejects**, the silent miss the
|
|
1398
|
+
reject list exists to end, one shape further out than Shio's 920.
|
|
1399
|
+
|
|
1400
|
+
A reject and not a reading, and not `[markers]` either: the slot is one token by
|
|
1401
|
+
construction, so declaring ``[ ]`` would widen it to two and make every two-word prose
|
|
1402
|
+
bullet a candidate. The bold id after the box is what keeps this off a prose checklist,
|
|
1403
|
+
and ``[x]`` is here beside ``[ ]`` because a checked box is the same convention and was
|
|
1404
|
+
missed by the same three tests.
|
|
1405
|
+
|
|
1406
|
+
Public because :mod:`roadkeep.adopting` reads it: a box is not a marker anybody has to
|
|
1407
|
+
declare, so the `[markers]` delta an estimate prints has to leave this one out.
|
|
1408
|
+
"""
|
|
1409
|
+
match = _CHECKBOX_RE.match(rest)
|
|
1410
|
+
return match.group("box") if match else None
|
|
1411
|
+
|
|
1412
|
+
|
|
1413
|
+
def _marker_slot(rest: str, token: str, schema: Schema) -> tuple[bool, str | None]:
|
|
1414
|
+
"""Whether this bullet claims a task line's shape, and the reason if its slot is not.
|
|
1415
|
+
|
|
1416
|
+
A pair because there are three answers and skipping is one of them: ``(False, None)``
|
|
1417
|
+
is prose, ``(True, None)`` is a line to go on parsing, and ``(False, reason)`` is a
|
|
1418
|
+
claim whose marker slot is wrong — which is the only one that becomes a
|
|
1419
|
+
:class:`Reject`, because rejecting prose is what makes a report unread.
|
|
1420
|
+
|
|
1421
|
+
Which slot is right is a fact about the file, not the format (RK43): where the ledger
|
|
1422
|
+
declares no marker the slot is absent, so a bold id leads and a marker is the error.
|
|
1423
|
+
A checkbox is judged before either, because it is another convention's whole line and
|
|
1424
|
+
is one whether this file's slot holds a marker or nothing (RK103).
|
|
1425
|
+
"""
|
|
1426
|
+
box = checkbox(rest)
|
|
1427
|
+
if box is not None:
|
|
1428
|
+
return False, (
|
|
1429
|
+
f"{box} is a task-list checkbox where the status goes: the line is a task in "
|
|
1430
|
+
f"another convention, so it reads as prose and no count sees it"
|
|
1431
|
+
)
|
|
1432
|
+
if not schema.marker_field:
|
|
1433
|
+
if _retirement(token, schema):
|
|
1434
|
+
# The one line such a file writes a marker on (RK125): a departure is the status
|
|
1435
|
+
# the file does not state about itself, so the line has to.
|
|
1436
|
+
return True, None
|
|
1437
|
+
if _looks_like_marker(token, schema):
|
|
1438
|
+
return False, (
|
|
1439
|
+
f"{token} is a status marker, in a file whose lines carry none "
|
|
1440
|
+
f"([ledger] marker = false): there the marker is the file's, not the "
|
|
1441
|
+
f"line's — {schema.retired_marker} alone carries one, a departure not "
|
|
1442
|
+
f"being a shipment"
|
|
1443
|
+
)
|
|
1444
|
+
return _leads_with_the_id(rest), None
|
|
1445
|
+
if _looks_like_marker(token, schema):
|
|
1446
|
+
return True, None
|
|
1447
|
+
if _wears_the_marker_slot(rest, token):
|
|
1448
|
+
declared = " ".join((*schema.markers, schema.shipped_marker))
|
|
1449
|
+
return False, (
|
|
1450
|
+
f"{token} is not a marker this project declares ({declared}): the line "
|
|
1451
|
+
f"reads as prose and no count sees it"
|
|
1452
|
+
)
|
|
1453
|
+
if _leads_with_the_id(rest):
|
|
1454
|
+
# The id is deliberately left out of the reason: a `Reject` already carries the
|
|
1455
|
+
# line number, and 755 reasons differing only by an id group into 755 rows of one,
|
|
1456
|
+
# which is the report `adopt` (RK18) prints instead of a number worth reading.
|
|
1457
|
+
reason = (
|
|
1458
|
+
"no marker where the status goes: the slot is empty, so the line reads as "
|
|
1459
|
+
"prose and no count sees it"
|
|
1460
|
+
)
|
|
1461
|
+
if schema.is_ledger:
|
|
1462
|
+
# The declaration(s) that make these into entries. Said here because this reason
|
|
1463
|
+
# is the only place a reader of that file will be looking — and **both** slots are
|
|
1464
|
+
# named where both are needed (RK286): Turing's ledger was told `marker = false`
|
|
1465
|
+
# alone, and taking exactly that advice left `827 would change` unmoved because
|
|
1466
|
+
# its lines carry no symptom slot either. Which of the two shapes the line lacks
|
|
1467
|
+
# is a fact this pass has, so it is stated rather than guessed at by the reader.
|
|
1468
|
+
reason += f" — a ledger of these lines declares {_ledger_slots(rest)}"
|
|
1469
|
+
return False, reason
|
|
1470
|
+
return False, None
|
|
1471
|
+
|
|
1472
|
+
|
|
1473
|
+
#: The four shapes a ledger line can be declared into, and the `[ledger]` slots each gives up.
|
|
1474
|
+
#: Ordered by how much they give up, so the first that reads a line is the smallest that does.
|
|
1475
|
+
LEDGER_SHAPES: tuple[tuple[bool, bool, tuple[str, ...]], ...] = (
|
|
1476
|
+
(True, True, ()),
|
|
1477
|
+
(False, True, ("marker = false",)),
|
|
1478
|
+
(True, False, ("symptom = false",)),
|
|
1479
|
+
(False, False, ("marker = false", "symptom = false")),
|
|
1480
|
+
)
|
|
1481
|
+
|
|
1482
|
+
|
|
1483
|
+
def reads_as_entry(line: str, marker: bool, symptom: bool) -> bool:
|
|
1484
|
+
"""Whether this line is a task line under a `[ledger]` declared with these two slots.
|
|
1485
|
+
|
|
1486
|
+
The shape test on its own, so an estimate can ask what a *whole* declaration would read
|
|
1487
|
+
(RK286) rather than adding up what each line separately wants — the two slots are not
|
|
1488
|
+
independent, and a project declares one `[ledger]`.
|
|
1489
|
+
"""
|
|
1490
|
+
return _task_re(marker, symptom).match(line) is not None
|
|
1491
|
+
|
|
1492
|
+
|
|
1493
|
+
def ledger_slots(line: str) -> tuple[str, ...]:
|
|
1494
|
+
"""Which `[ledger]` slots this line needs declared before it parses (RK286).
|
|
1495
|
+
|
|
1496
|
+
Asked of the line and never assumed: `- **T1** — because.` needs `marker = false` alone,
|
|
1497
|
+
`- **T1** because.` needs `symptom = false` as well, and `- ✅ **T1** because.` needs only
|
|
1498
|
+
`symptom = false`. Naming one where two are wanted is advice that does not survive being
|
|
1499
|
+
taken — measured on Turing, where declaring exactly what the reason said left the count
|
|
1500
|
+
where it was.
|
|
1501
|
+
|
|
1502
|
+
The **fewest** slots that read it, so the declaration reported is the smallest one that
|
|
1503
|
+
works: each shape is tried in order of how much it gives up. Empty when none reads the
|
|
1504
|
+
line, which is a line no declaration reaches and so is not evidence about one.
|
|
1505
|
+
"""
|
|
1506
|
+
for marker, symptom, slots in LEDGER_SHAPES:
|
|
1507
|
+
if reads_as_entry(line, marker, symptom):
|
|
1508
|
+
return slots
|
|
1509
|
+
return ()
|
|
1510
|
+
|
|
1511
|
+
|
|
1512
|
+
def _ledger_slots(rest: str) -> str:
|
|
1513
|
+
""":func:`ledger_slots` as the reject reason spells it, from the bullet's body."""
|
|
1514
|
+
slots = ledger_slots(f"- {rest}")
|
|
1515
|
+
if not slots:
|
|
1516
|
+
return "no [ledger] shape this line reads under"
|
|
1517
|
+
return "[ledger] " + ", ".join(slots)
|
|
1518
|
+
|
|
1519
|
+
|
|
1520
|
+
def _fenced(open_marks: str | None, marks: str) -> str | None:
|
|
1521
|
+
"""The fence still open after this delimiter line, or None (RK53).
|
|
1522
|
+
|
|
1523
|
+
A fence is closed only by its own character and at least as many of them, so ``` inside
|
|
1524
|
+
a ~~~ block is text — which is how a renderer reads it, and the only way a section that
|
|
1525
|
+
quotes one fence inside another can be read at all.
|
|
1526
|
+
"""
|
|
1527
|
+
if open_marks is None:
|
|
1528
|
+
return marks
|
|
1529
|
+
if marks[0] == open_marks[0] and len(marks) >= len(open_marks):
|
|
1530
|
+
return None
|
|
1531
|
+
return open_marks
|
|
1532
|
+
|
|
1533
|
+
|
|
1534
|
+
def _tables(pipes: Sequence[Row]) -> tuple[Row, ...]:
|
|
1535
|
+
"""The data rows of every table in the file, from the pipe lines it collected (RK98).
|
|
1536
|
+
|
|
1537
|
+
Split into runs of adjacent lines first, because two tables in one file are two
|
|
1538
|
+
questions about where the rule row is, and a run interrupted by prose is two runs.
|
|
1539
|
+
"""
|
|
1540
|
+
out: list[Row] = []
|
|
1541
|
+
run: list[Row] = []
|
|
1542
|
+
for row in pipes:
|
|
1543
|
+
if run and row.lineno != run[-1].lineno + 1:
|
|
1544
|
+
out += _below_the_rule(run)
|
|
1545
|
+
run = []
|
|
1546
|
+
run.append(row)
|
|
1547
|
+
out += _below_the_rule(run)
|
|
1548
|
+
return tuple(out)
|
|
1549
|
+
|
|
1550
|
+
|
|
1551
|
+
def _below_the_rule(run: Sequence[Row]) -> list[Row]:
|
|
1552
|
+
"""One run's task rows: what sits under the `|---|`, filed under a block.
|
|
1553
|
+
|
|
1554
|
+
Two filters, and each drops a whole class of false report. **Without a rule row** a run
|
|
1555
|
+
of pipes is prose that uses them — a leading `|` is not a table, and counting one would
|
|
1556
|
+
make this report name itself. **Outside a block** a table is documentation: the legend
|
|
1557
|
+
in a roadmap's preamble is not 6 tasks, and a heading is the only thing that says a line
|
|
1558
|
+
is filed work (RK37).
|
|
1559
|
+
"""
|
|
1560
|
+
for index, row in enumerate(run):
|
|
1561
|
+
if _RULE_RE.match(row.raw):
|
|
1562
|
+
return [below for below in run[index + 1 :] if below.block]
|
|
1563
|
+
return []
|
|
1564
|
+
|
|
1565
|
+
|
|
1566
|
+
def _block_label(text: str, schema: Schema) -> str | None:
|
|
1567
|
+
"""The label a heading declares, under this project's own word (RK75).
|
|
1568
|
+
|
|
1569
|
+
Read from the schema and not from a constant here, so the heading and the dep that
|
|
1570
|
+
names it cannot disagree about either the word or the label's shape.
|
|
1571
|
+
"""
|
|
1572
|
+
match = schema.heading_pattern().match(text)
|
|
1573
|
+
return match.group("label") if match else None
|
|
1574
|
+
|
|
1575
|
+
|
|
1576
|
+
def _split_ref(body: str) -> tuple[str, str | None]:
|
|
1577
|
+
"""Take the pointer off the end, last occurrence first.
|
|
1578
|
+
|
|
1579
|
+
Matching the pointer with a regex over the whole line would find the one
|
|
1580
|
+
RK15's own `why` quotes as an example and truncate the sentence at it.
|
|
1581
|
+
"""
|
|
1582
|
+
head, sep, tail = body.rpartition(_POINTER)
|
|
1583
|
+
if sep and tail and not any(c.isspace() for c in tail):
|
|
1584
|
+
return head, tail
|
|
1585
|
+
return body, None
|
|
1586
|
+
|
|
1587
|
+
|
|
1588
|
+
def _read_bullet(body: str, schema: Schema, block: str) -> Task | str | None:
|
|
1589
|
+
"""A task, a reason it was rejected, or None when the line is not a task at all.
|
|
1590
|
+
|
|
1591
|
+
Only a bullet that claims the task line's own shape can be rejected: every other one
|
|
1592
|
+
is prose, and reporting the non-goals list as malformed would make the report
|
|
1593
|
+
worthless. Which shape that is depends on the file — in a markerless ledger (RK43)
|
|
1594
|
+
the claim is a leading bold id, and a marker there is the mistake instead, 🗑 excepted
|
|
1595
|
+
(RK125).
|
|
1596
|
+
|
|
1597
|
+
So whether *this line* fills the marker slot is a question per line and not per file:
|
|
1598
|
+
the grammar is chosen from the same answer `render` writes from, which is what keeps
|
|
1599
|
+
the retirement a markerless ledger carries byte-identical through the round trip.
|
|
1600
|
+
"""
|
|
1601
|
+
bullet = _BULLET_RE.match(body)
|
|
1602
|
+
if not bullet:
|
|
1603
|
+
return None
|
|
1604
|
+
rest = bullet.group("rest").lstrip()
|
|
1605
|
+
token = rest.split(" ", 1)[0]
|
|
1606
|
+
marked = schema.marker_field or _retirement(token, schema)
|
|
1607
|
+
claimed, wrong = _marker_slot(rest, token, schema)
|
|
1608
|
+
if wrong is not None:
|
|
1609
|
+
return wrong
|
|
1610
|
+
if not claimed:
|
|
1611
|
+
return None
|
|
1612
|
+
indent = bullet.group("indent")
|
|
1613
|
+
if not body.lstrip().startswith("- "):
|
|
1614
|
+
return "bullet must be '- ': a task line is one dash and one space"
|
|
1615
|
+
|
|
1616
|
+
# Judged exactly as it would be at column zero (RK49), and the indentation is carried
|
|
1617
|
+
# on the task so `render` puts it back: Shio nests four live tasks under a shipped
|
|
1618
|
+
# parent, and rejecting them made 4 ids invisible to every count and to `next-id`.
|
|
1619
|
+
head, ref = _split_ref(body[len(indent) :])
|
|
1620
|
+
match = _task_re(marked, schema.symptom_field).match(head)
|
|
1621
|
+
if not match:
|
|
1622
|
+
return _diagnose(head, schema, marked)
|
|
1623
|
+
|
|
1624
|
+
raw_deps = match.group("deps")
|
|
1625
|
+
if schema.deps_field and raw_deps is None:
|
|
1626
|
+
return "no (deps: …) field"
|
|
1627
|
+
if not schema.deps_field and raw_deps is not None:
|
|
1628
|
+
return "a deps field, in a file that carries none"
|
|
1629
|
+
|
|
1630
|
+
deps: tuple[Dep, ...] = ()
|
|
1631
|
+
if raw_deps is not None and raw_deps != NO_DEPS:
|
|
1632
|
+
deps = read_deps(raw_deps, schema)
|
|
1633
|
+
|
|
1634
|
+
# Read wherever the grammar finds one and judged by the schema, which is the split every
|
|
1635
|
+
# other slot takes (RK1297): a token no `[requirements]` declares still round-trips and
|
|
1636
|
+
# is reported as `requires.unknown`, because dropping the line instead would take an
|
|
1637
|
+
# otherwise perfect task out of every count — `read_deps`' rule, one group over.
|
|
1638
|
+
raw_requires = match.group("requires")
|
|
1639
|
+
requires = read_requires(raw_requires) if raw_requires is not None else ()
|
|
1640
|
+
|
|
1641
|
+
return Task(
|
|
1642
|
+
id=match.group("id"),
|
|
1643
|
+
# The qualifier a partial entry carries (RK121). Read wherever the grammar finds
|
|
1644
|
+
# one and refused by the schema where it is not legal, which is the split every
|
|
1645
|
+
# other slot takes: the parser's job is to lose nothing, the schema's is to judge.
|
|
1646
|
+
part=match.group("part"),
|
|
1647
|
+
# Where the file declares no marker, the status is the file's own: every entry in
|
|
1648
|
+
# a ledger that carries none shipped, which is the whole content of the claim.
|
|
1649
|
+
status=match.group("status") if marked else schema.shipped_marker,
|
|
1650
|
+
block=block,
|
|
1651
|
+
# Absent where the file has no such slot (RK48): the whole tail is the `why`, and
|
|
1652
|
+
# an empty string is what `render` then reproduces by omitting the bold entirely.
|
|
1653
|
+
symptom=match.group("symptom") if schema.symptom_field else "",
|
|
1654
|
+
why=match.group("why"),
|
|
1655
|
+
deps=deps,
|
|
1656
|
+
requires=requires,
|
|
1657
|
+
ref=ref,
|
|
1658
|
+
indent=indent,
|
|
1659
|
+
)
|
|
1660
|
+
|
|
1661
|
+
|
|
1662
|
+
def read_deps(raw: str, schema: Schema) -> tuple[Dep, ...]:
|
|
1663
|
+
"""Split the field; never reject the line over it.
|
|
1664
|
+
|
|
1665
|
+
Public because `add` (RK5) reads the deps an author types with the same code that
|
|
1666
|
+
reads the ones already in the file — a `(deps: …)` field the writer and the reader
|
|
1667
|
+
parse differently is a field that stops round-tripping on the next write.
|
|
1668
|
+
|
|
1669
|
+
A dep token the schema will not accept — Shio's ``Block P``, Turing's ``real
|
|
1670
|
+
design partners`` — still round-trips, so it is read as an id and reported by
|
|
1671
|
+
`lint` as `deps.format`. Rejecting the whole line instead would drop an
|
|
1672
|
+
otherwise perfect task out of every count, which is the silent-miss failure
|
|
1673
|
+
the reject list exists to prevent.
|
|
1674
|
+
"""
|
|
1675
|
+
markers = schema.dep_markers
|
|
1676
|
+
out: list[Dep] = []
|
|
1677
|
+
for token in raw.split(", "):
|
|
1678
|
+
head, _, last = token.rpartition(" ")
|
|
1679
|
+
if head and last in markers:
|
|
1680
|
+
out.append(Dep(head, marker=last))
|
|
1681
|
+
else:
|
|
1682
|
+
out.append(Dep(token))
|
|
1683
|
+
return tuple(out)
|
|
1684
|
+
|
|
1685
|
+
|
|
1686
|
+
def read_requires(raw: str) -> tuple[str, ...]:
|
|
1687
|
+
"""Split the requirement group; never reject the line over it (RK1297).
|
|
1688
|
+
|
|
1689
|
+
Public for `read_deps`' reason: `add` reads the requirements an author types with the
|
|
1690
|
+
code that reads the ones already in a file, and a group the writer and the reader split
|
|
1691
|
+
differently is a group that stops round-tripping on the next write.
|
|
1692
|
+
|
|
1693
|
+
It takes no schema, which is the one difference from its neighbour and is the point: a
|
|
1694
|
+
requirement is a word, not a reference, so there is nothing to classify here — whether
|
|
1695
|
+
the project declared it is :meth:`Schema._check_needs`' question and is asked of a line
|
|
1696
|
+
that already parsed.
|
|
1697
|
+
"""
|
|
1698
|
+
return tuple(token for token in raw.split(", ") if token)
|
|
1699
|
+
|
|
1700
|
+
|
|
1701
|
+
def _diagnose(head: str, schema: Schema, marked: bool) -> str:
|
|
1702
|
+
"""Name the missing piece. A reason is what makes a reject actionable.
|
|
1703
|
+
|
|
1704
|
+
``marked`` is whether *this line* filled the marker slot rather than whether the file's
|
|
1705
|
+
lines do, so a retirement in a markerless ledger (RK125) is told where the id is missing
|
|
1706
|
+
from and not sent to look at the start of a line that begins with 🗑.
|
|
1707
|
+
"""
|
|
1708
|
+
if not re.search(r"\*\*[A-Za-z0-9]+\*\*", head):
|
|
1709
|
+
where = "after the marker" if marked else "where the line starts"
|
|
1710
|
+
return f"no bold **<id>** {where}"
|
|
1711
|
+
if schema.deps_field and "(deps:" not in head:
|
|
1712
|
+
return "no (deps: …) field"
|
|
1713
|
+
if not schema.deps_field and "(deps:" in head:
|
|
1714
|
+
return "a deps field, in a file that carries none"
|
|
1715
|
+
if f" {EM_DASH} " not in head:
|
|
1716
|
+
return f"no ' {EM_DASH} ' between the symptom and the why"
|
|
1717
|
+
if head.count("**") < 4:
|
|
1718
|
+
return "symptom is not delimited by **"
|
|
1719
|
+
return "does not match the task-line grammar"
|