roadkeep 0.2.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- roadkeep/__init__.py +79 -0
- roadkeep/adopting.py +2347 -0
- roadkeep/attesting.py +293 -0
- roadkeep/authoring.py +2117 -0
- roadkeep/backlog.py +767 -0
- roadkeep/blocking.py +1622 -0
- roadkeep/briefing.py +970 -0
- roadkeep/budgeting.py +2056 -0
- roadkeep/capturing.py +1699 -0
- roadkeep/claiming.py +1019 -0
- roadkeep/cli.py +638 -0
- roadkeep/commanding.py +487 -0
- roadkeep/config.py +1832 -0
- roadkeep/counting.py +376 -0
- roadkeep/criteria.py +933 -0
- roadkeep/deferring.py +708 -0
- roadkeep/describing.py +568 -0
- roadkeep/exporting.py +808 -0
- roadkeep/fixing.py +629 -0
- roadkeep/governing.py +934 -0
- roadkeep/graph.py +395 -0
- roadkeep/guarding.py +1028 -0
- roadkeep/history.py +2403 -0
- roadkeep/ids.py +301 -0
- roadkeep/installing.py +2145 -0
- roadkeep/kernel/__init__.py +24 -0
- roadkeep/kernel/document.py +1719 -0
- roadkeep/kernel/schema.py +2308 -0
- roadkeep/linting.py +4420 -0
- roadkeep/locking.py +209 -0
- roadkeep/markers.py +172 -0
- roadkeep/merging.py +1159 -0
- roadkeep/picking.py +772 -0
- roadkeep/provenance.py +789 -0
- roadkeep/queueing.py +752 -0
- roadkeep/ranking.py +139 -0
- roadkeep/referring.py +231 -0
- roadkeep/remaining.py +336 -0
- roadkeep/remedying.py +1989 -0
- roadkeep/rendering.py +1601 -0
- roadkeep/renumbering.py +503 -0
- roadkeep/repairing.py +295 -0
- roadkeep/reverting.py +144 -0
- roadkeep/scoping.py +708 -0
- roadkeep/screening.py +196 -0
- roadkeep/sections.py +4121 -0
- roadkeep/serving.py +2909 -0
- roadkeep/shipping.py +3993 -0
- roadkeep/showing.py +613 -0
- roadkeep/storing.py +224 -0
- roadkeep/verbs/__init__.py +26 -0
- roadkeep/verbs/adopting.py +974 -0
- roadkeep/verbs/authoring.py +566 -0
- roadkeep/verbs/declaring.py +335 -0
- roadkeep/verbs/linting.py +645 -0
- roadkeep/verbs/querying.py +2138 -0
- roadkeep/verbs/reading.py +307 -0
- roadkeep/verbs/refusing.py +146 -0
- roadkeep/verbs/sections.py +1433 -0
- roadkeep/verbs/shipping.py +819 -0
- roadkeep/weighing.py +380 -0
- roadkeep-0.2.0.dist-info/METADATA +453 -0
- roadkeep-0.2.0.dist-info/RECORD +67 -0
- roadkeep-0.2.0.dist-info/WHEEL +5 -0
- roadkeep-0.2.0.dist-info/entry_points.txt +2 -0
- roadkeep-0.2.0.dist-info/licenses/LICENSE +202 -0
- roadkeep-0.2.0.dist-info/top_level.txt +1 -0
roadkeep/scoping.py
ADDED
|
@@ -0,0 +1,708 @@
|
|
|
1
|
+
"""The one bullet in the roadmap that is not a task line (RK70).
|
|
2
|
+
|
|
3
|
+
RK22's value is that a denied edit *names the command to call instead*. For the non-goals it
|
|
4
|
+
named five commands that all write task lines, so the only content of the roadmap that is not
|
|
5
|
+
a task line was also the only content nothing governed: `Edit` denied, `lint` silent — a
|
|
6
|
+
bullet carrying no marker is prose — and `sed` through `Bash` the route left, which the
|
|
7
|
+
barrier deliberately does not match. L1 held everywhere except on the list that binds what
|
|
8
|
+
`add` may be called for at all.
|
|
9
|
+
|
|
10
|
+
A non-goal is structurally what `add` already governs, a lead and a reason, so this needs no
|
|
11
|
+
new law: one renderer, and the fields refused at input. Three decisions are narrower than
|
|
12
|
+
they could be, and each is the reason this module is small:
|
|
13
|
+
|
|
14
|
+
* **No ids.** An id buys a lifecycle — retire, rename, a second file to disagree with — for a
|
|
15
|
+
list of eight lines that changes once a year. The **lead is the address**, so it is unique
|
|
16
|
+
and checked. The trigger that would change that answer is already visible: Turing's backlog
|
|
17
|
+
says "which the Non-goals say is not the path", a reference resolving to nothing, which is
|
|
18
|
+
the defect RK15 catches for `→ §`.
|
|
19
|
+
* **Opt-in under `[non_goals]`** (L6), for RK66's reason: Shio and Turing wrote theirs before
|
|
20
|
+
the schema existed, and a default that reports fifteen findings on adoption is a gate that
|
|
21
|
+
gets bypassed rather than adopted. This repository opts in and is the fixture.
|
|
22
|
+
* **The wrap is not judged, only written.** A bullet is filled to `prose` at insertion (L1),
|
|
23
|
+
and a hand-wrapped one already in the file is whitespace inside prose — mechanical, so
|
|
24
|
+
reporting it where `--fix` cannot repair it would be a finding with no door (RK16).
|
|
25
|
+
|
|
26
|
+
The lead is kept **verbatim**, including a trailing stop when the author wrote one inside the
|
|
27
|
+
bold: the corpus writes both `**No web UI and no server.** Files and a CLI.` and `**No
|
|
28
|
+
issue-tracker sync** (Jira, …).`, and a renderer that normalized either would be rewriting
|
|
29
|
+
the author's punctuation to satisfy a rule nobody stated (L4).
|
|
30
|
+
"""
|
|
31
|
+
|
|
32
|
+
from __future__ import annotations
|
|
33
|
+
|
|
34
|
+
import re
|
|
35
|
+
import textwrap
|
|
36
|
+
from collections.abc import Sequence
|
|
37
|
+
from dataclasses import dataclass, replace
|
|
38
|
+
from pathlib import Path
|
|
39
|
+
|
|
40
|
+
from roadkeep.config import Config, Scope
|
|
41
|
+
from roadkeep.kernel.document import Document, blank
|
|
42
|
+
from roadkeep.kernel.schema import SchemaError, Violation, over_by, width
|
|
43
|
+
|
|
44
|
+
__all__ = [
|
|
45
|
+
"HEADING",
|
|
46
|
+
"LEAD",
|
|
47
|
+
"SHAPE",
|
|
48
|
+
"WHY",
|
|
49
|
+
"Amended",
|
|
50
|
+
"DuplicateLead",
|
|
51
|
+
"Dropped",
|
|
52
|
+
"NoNonGoals",
|
|
53
|
+
"NoSuchNonGoal",
|
|
54
|
+
"NonGoal",
|
|
55
|
+
"NotGoverned",
|
|
56
|
+
"Unshaped",
|
|
57
|
+
"Written",
|
|
58
|
+
"add",
|
|
59
|
+
"address",
|
|
60
|
+
"amend",
|
|
61
|
+
"check",
|
|
62
|
+
"drop",
|
|
63
|
+
"leads",
|
|
64
|
+
"read",
|
|
65
|
+
"render",
|
|
66
|
+
"validate",
|
|
67
|
+
]
|
|
68
|
+
|
|
69
|
+
#: Any heading whose text starts like this holds the non-goals. A prefix match rather than a
|
|
70
|
+
#: config key, because both live corpora already write it and neither writes it exactly: this
|
|
71
|
+
#: repository has "## Non-goals", Shio has "## Non-goals (do NOT add as tasks)".
|
|
72
|
+
HEADING = re.compile(r"^non-goals?\b", re.IGNORECASE)
|
|
73
|
+
|
|
74
|
+
#: `- **<lead>** <why>`, at column zero. The lead is bold and the why is everything after it,
|
|
75
|
+
#: which is what lets a parenthetical or a second sentence stay exactly as it was written.
|
|
76
|
+
_BULLET = re.compile(r"^- \*\*(?P<lead>[^*]+)\*\*(?P<why> .*)?$")
|
|
77
|
+
#: A bullet that is one, without the shape this governs — reported, never guessed at.
|
|
78
|
+
_ANY_BULLET = re.compile(r"^[-*+] (?P<rest>.*)$")
|
|
79
|
+
#: What a wrapped bullet's continuation looks like: indented, and not a bullet of its own.
|
|
80
|
+
_CONTINUATION = " "
|
|
81
|
+
#: Where a lead ends in a bullet that carries no bold head. A stop *and a space*, so an
|
|
82
|
+
#: abbreviation or a version number inside the sentence is not read as its end.
|
|
83
|
+
_SENTENCE = ". "
|
|
84
|
+
|
|
85
|
+
#: The two codes this format can be violated by, and the one a bullet's *shape* is. Named
|
|
86
|
+
#: here because `lint` reports them and a code spelled twice is a code that drifts once.
|
|
87
|
+
LEAD = "non-goal.lead"
|
|
88
|
+
WHY = "non-goal.why"
|
|
89
|
+
SHAPE = "non-goal.shape"
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
class NotGoverned(KeyError):
|
|
93
|
+
"""A write to a list this project has not declared governed (RK70).
|
|
94
|
+
|
|
95
|
+
Refused rather than defaulted: a project whose non-goals are free prose would have every
|
|
96
|
+
existing bullet judged by the first `add`, which is the adoption gate RK66 measures.
|
|
97
|
+
"""
|
|
98
|
+
|
|
99
|
+
def __init__(self, where: str) -> None:
|
|
100
|
+
super().__init__(
|
|
101
|
+
# The command and no longer the edit (RK1328), which is `criteria`'s twin.
|
|
102
|
+
f"{where} declares no [non_goals]: `declare non_goals` opens the table, which is "
|
|
103
|
+
f"what governs the list — a schema applied to prose nobody wrote to it reports "
|
|
104
|
+
f"on adoption, so it is opted into and never assumed"
|
|
105
|
+
)
|
|
106
|
+
|
|
107
|
+
|
|
108
|
+
class NoNonGoals(KeyError):
|
|
109
|
+
"""No heading holds a list to write to. A heading is the only thing that declares one."""
|
|
110
|
+
|
|
111
|
+
def __init__(self, where: str) -> None:
|
|
112
|
+
super().__init__(
|
|
113
|
+
f"no non-goals heading in {where}: the heading declares the list, exactly as a "
|
|
114
|
+
f"block heading declares a block (RK37)"
|
|
115
|
+
)
|
|
116
|
+
|
|
117
|
+
|
|
118
|
+
class DuplicateLead(ValueError):
|
|
119
|
+
"""The lead is the address, so a second bullet claiming one is two answers to a scope."""
|
|
120
|
+
|
|
121
|
+
def __init__(self, lead: str, where: str, lineno: int) -> None:
|
|
122
|
+
self.lead = lead
|
|
123
|
+
self.lineno = lineno
|
|
124
|
+
super().__init__(
|
|
125
|
+
f"{where}:{lineno} already leads with {lead!r}: the lead is how a non-goal is "
|
|
126
|
+
f"addressed, so a second one carrying it is two answers about the same scope"
|
|
127
|
+
)
|
|
128
|
+
|
|
129
|
+
|
|
130
|
+
class NoSuchNonGoal(KeyError):
|
|
131
|
+
"""A lead that addresses nothing. The leads that exist are named, because a constraint
|
|
132
|
+
is looked up by the words a reader remembers and the stop inside the bold is invisible."""
|
|
133
|
+
|
|
134
|
+
def __init__(self, lead: str, where: str, leads: tuple[str, ...]) -> None:
|
|
135
|
+
self.lead = lead
|
|
136
|
+
known = ", ".join(repr(one) for one in leads) or "none"
|
|
137
|
+
super().__init__(
|
|
138
|
+
f"no non-goal in {where} leads with {lead!r}: the list carries {known}"
|
|
139
|
+
)
|
|
140
|
+
|
|
141
|
+
|
|
142
|
+
class Unshaped(ValueError):
|
|
143
|
+
"""A correction to a bullet this module could not have written (RK368).
|
|
144
|
+
|
|
145
|
+
:func:`read` accepts a bullet with no bold head so that every constraint has an address
|
|
146
|
+
(RK233), and that is safe precisely because nothing renders one back: `drop` removes the
|
|
147
|
+
source span and :func:`render` writes only what `add` composed. An `amend` is the first
|
|
148
|
+
verb that would render over lines it did not write, and on an unshaped bullet the render
|
|
149
|
+
imposes the shape — which moves the lead, and the lead is the address.
|
|
150
|
+
|
|
151
|
+
So the gate's `non-goal.shape` keeps the door it already had, and this refusal names it: a
|
|
152
|
+
bullet whose head is its first sentence is repaired by `drop` and `add`, the pair that is
|
|
153
|
+
honest about a changed address.
|
|
154
|
+
"""
|
|
155
|
+
|
|
156
|
+
def __init__(self, lead: str, where: str, lineno: int) -> None:
|
|
157
|
+
self.lead = lead
|
|
158
|
+
self.lineno = lineno
|
|
159
|
+
super().__init__(
|
|
160
|
+
f"the bullet at {where}:{lineno} carries no bold lead, so {lead!r} is its first "
|
|
161
|
+
f"sentence rather than an address this verb can write around — `non-goal drop` "
|
|
162
|
+
f"then `non-goal add` is the repair, and it is honest about the lead changing"
|
|
163
|
+
)
|
|
164
|
+
|
|
165
|
+
|
|
166
|
+
@dataclass(frozen=True, slots=True)
|
|
167
|
+
class NonGoal:
|
|
168
|
+
"""One bullet under the non-goals heading, as data and as the file spells it."""
|
|
169
|
+
|
|
170
|
+
lead: str
|
|
171
|
+
why: str
|
|
172
|
+
#: 1-based, and a span because a filled bullet wraps: `first` is the line the `- ` is on.
|
|
173
|
+
first: int
|
|
174
|
+
last: int
|
|
175
|
+
#: The source lines, verbatim and without their endings — the round-trip's evidence.
|
|
176
|
+
lines: tuple[str, ...] = ()
|
|
177
|
+
#: Did the bold shape hold? False where the lead is the bullet's first sentence instead
|
|
178
|
+
#: (RK233). Carried rather than answered by a second parse, because every caller that
|
|
179
|
+
#: needs the distinction — the gate's `non-goal.shape`, `adopt`'s unread count — is
|
|
180
|
+
#: asking about a bullet this reader already read.
|
|
181
|
+
shaped: bool = True
|
|
182
|
+
|
|
183
|
+
def __str__(self) -> str:
|
|
184
|
+
# Only what the file spells: a bullet that carries no bold head is not given one here,
|
|
185
|
+
# because a rendering that invented the shape would read as prose the tool wrote (L4).
|
|
186
|
+
return f"**{self.lead}** {self.why}" if self.shaped else " ".join(self.lines).strip()
|
|
187
|
+
|
|
188
|
+
|
|
189
|
+
@dataclass(frozen=True, slots=True)
|
|
190
|
+
class Written:
|
|
191
|
+
"""A non-goal inserted, and the document it went into. Save writes one file."""
|
|
192
|
+
|
|
193
|
+
document: Document
|
|
194
|
+
non_goal: NonGoal
|
|
195
|
+
|
|
196
|
+
@property
|
|
197
|
+
def lineno(self) -> int:
|
|
198
|
+
return self.non_goal.first
|
|
199
|
+
|
|
200
|
+
@property
|
|
201
|
+
def rendered(self) -> tuple[str, ...]:
|
|
202
|
+
return self.non_goal.lines
|
|
203
|
+
|
|
204
|
+
def save(self) -> tuple[Path, ...]:
|
|
205
|
+
return self.document.save()
|
|
206
|
+
|
|
207
|
+
def stated(self, config: Config, wrote: Sequence[Path]) -> str:
|
|
208
|
+
"""The bullet, as many lines as it took (RK69).
|
|
209
|
+
|
|
210
|
+
Beside :meth:`payload` since RK1170. **No event line** (RK38): the payload a hook reads
|
|
211
|
+
is an id and its block's open state, and a non-goal has neither — it is the constraint
|
|
212
|
+
on what a block may hold, not a member.
|
|
213
|
+
"""
|
|
214
|
+
from roadkeep.rendering import _staging_rows # noqa: PLC0415 - RK260
|
|
215
|
+
|
|
216
|
+
where = config.relative(config.path("roadmap"))
|
|
217
|
+
rows = [
|
|
218
|
+
f"{where}:{self.lineno} {len(self.rendered)} line(s)",
|
|
219
|
+
*(f" {line}" for line in self.rendered),
|
|
220
|
+
]
|
|
221
|
+
rows += _staging_rows(config.relative(one) for one in wrote)
|
|
222
|
+
return "\n".join(rows)
|
|
223
|
+
|
|
224
|
+
def payload(self, config: Config, wrote: Sequence[Path]) -> dict[str, object]:
|
|
225
|
+
from roadkeep.rendering import _wrote_json # noqa: PLC0415 - RK260
|
|
226
|
+
|
|
227
|
+
return {
|
|
228
|
+
"lead": self.non_goal.lead,
|
|
229
|
+
"why": self.non_goal.why,
|
|
230
|
+
"file": config.relative(config.path("roadmap")),
|
|
231
|
+
"line": self.lineno,
|
|
232
|
+
"rendered": list(self.rendered),
|
|
233
|
+
**_wrote_json(config, wrote),
|
|
234
|
+
}
|
|
235
|
+
|
|
236
|
+
|
|
237
|
+
@dataclass(frozen=True, slots=True)
|
|
238
|
+
class Amended:
|
|
239
|
+
"""A non-goal's reason rewritten where it already sat. Save writes one file."""
|
|
240
|
+
|
|
241
|
+
document: Document
|
|
242
|
+
non_goal: NonGoal
|
|
243
|
+
#: The reason as the file read it. Both readings, because what makes a correction
|
|
244
|
+
#: reviewable is that a word changed and the bullet did not move.
|
|
245
|
+
before: str = ""
|
|
246
|
+
|
|
247
|
+
@property
|
|
248
|
+
def changed(self) -> bool:
|
|
249
|
+
return self.before != self.non_goal.why
|
|
250
|
+
|
|
251
|
+
@property
|
|
252
|
+
def lineno(self) -> int:
|
|
253
|
+
return self.non_goal.first
|
|
254
|
+
|
|
255
|
+
@property
|
|
256
|
+
def rendered(self) -> tuple[str, ...]:
|
|
257
|
+
return self.non_goal.lines
|
|
258
|
+
|
|
259
|
+
def save(self) -> tuple[Path, ...]:
|
|
260
|
+
return self.document.save()
|
|
261
|
+
|
|
262
|
+
def stated(self, config: Config, wrote: Sequence[Path]) -> str:
|
|
263
|
+
"""What the correction rewrote, or that nothing moved (RK368).
|
|
264
|
+
|
|
265
|
+
Beside :meth:`payload` since RK1170.
|
|
266
|
+
"""
|
|
267
|
+
from roadkeep.rendering import _staging_rows # noqa: PLC0415 - RK260
|
|
268
|
+
|
|
269
|
+
if not self.changed:
|
|
270
|
+
return f"{self.non_goal.lead} unchanged: the bullet already reads that way"
|
|
271
|
+
where = config.relative(config.path("roadmap"))
|
|
272
|
+
rows = [
|
|
273
|
+
f"{where}:{self.lineno} amended {len(self.rendered)} line(s)",
|
|
274
|
+
*(f" {line}" for line in self.rendered),
|
|
275
|
+
]
|
|
276
|
+
rows += _staging_rows(config.relative(one) for one in wrote)
|
|
277
|
+
return "\n".join(rows)
|
|
278
|
+
|
|
279
|
+
def payload(self, config: Config, wrote: Sequence[Path]) -> dict[str, object]:
|
|
280
|
+
from roadkeep.rendering import _wrote_json # noqa: PLC0415 - RK260
|
|
281
|
+
|
|
282
|
+
return {
|
|
283
|
+
"lead": self.non_goal.lead,
|
|
284
|
+
# Both readings, which is what makes this reviewable as a correction rather than
|
|
285
|
+
# as a move: the word changed and the bullet did not.
|
|
286
|
+
"was": self.before,
|
|
287
|
+
"now": self.non_goal.why,
|
|
288
|
+
"changed": self.changed,
|
|
289
|
+
"file": config.relative(config.path("roadmap")),
|
|
290
|
+
"line": self.lineno,
|
|
291
|
+
"rendered": list(self.rendered),
|
|
292
|
+
**_wrote_json(config, wrote),
|
|
293
|
+
}
|
|
294
|
+
|
|
295
|
+
|
|
296
|
+
@dataclass(frozen=True, slots=True)
|
|
297
|
+
class Dropped:
|
|
298
|
+
"""A non-goal removed, whole. Save writes the roadmap and nothing else."""
|
|
299
|
+
|
|
300
|
+
document: Document
|
|
301
|
+
non_goal: NonGoal
|
|
302
|
+
#: How many bullets carried this address before the removal — 2 or more means the drop
|
|
303
|
+
#: was also the repair for `lint`'s `non-goal.duplicate`, and the report says so.
|
|
304
|
+
carried: int = 1
|
|
305
|
+
|
|
306
|
+
@property
|
|
307
|
+
def lines(self) -> tuple[str, ...]:
|
|
308
|
+
return self.non_goal.lines
|
|
309
|
+
|
|
310
|
+
def save(self) -> tuple[Path, ...]:
|
|
311
|
+
return self.document.save()
|
|
312
|
+
|
|
313
|
+
def stated(self, config: Config, wrote: Sequence[Path]) -> str:
|
|
314
|
+
"""The span that went, and whether the drop was also a repair (RK144).
|
|
315
|
+
|
|
316
|
+
Beside :meth:`payload` since RK1170.
|
|
317
|
+
"""
|
|
318
|
+
from roadkeep.rendering import _staging_rows # noqa: PLC0415 - RK260
|
|
319
|
+
|
|
320
|
+
where = config.relative(config.path("roadmap"))
|
|
321
|
+
span = self.non_goal
|
|
322
|
+
rows = [f"{where}:{span.first}-{span.last} dropped **{span.lead}**"]
|
|
323
|
+
if self.carried > 1:
|
|
324
|
+
# Two bullets for one address is `lint`'s non-goal.duplicate, and this call repaired
|
|
325
|
+
# it rather than removing the list's only statement of a constraint.
|
|
326
|
+
rows.append(
|
|
327
|
+
f" duplicate {self.carried} bullets carried this lead: the later one went, "
|
|
328
|
+
f"the first is where the reader already found it"
|
|
329
|
+
)
|
|
330
|
+
rows += _staging_rows(config.relative(one) for one in wrote)
|
|
331
|
+
return "\n".join(rows)
|
|
332
|
+
|
|
333
|
+
def payload(self, config: Config, wrote: Sequence[Path]) -> dict[str, object]:
|
|
334
|
+
from roadkeep.rendering import _wrote_json # noqa: PLC0415 - RK260
|
|
335
|
+
|
|
336
|
+
span = self.non_goal
|
|
337
|
+
return {
|
|
338
|
+
"lead": span.lead,
|
|
339
|
+
"why": span.why,
|
|
340
|
+
"file": config.relative(config.path("roadmap")),
|
|
341
|
+
"removed": [span.first, span.last],
|
|
342
|
+
"carried": self.carried,
|
|
343
|
+
"rendered": list(self.lines),
|
|
344
|
+
**_wrote_json(config, wrote),
|
|
345
|
+
}
|
|
346
|
+
|
|
347
|
+
|
|
348
|
+
def read(document: Document) -> tuple[NonGoal, ...]:
|
|
349
|
+
"""Every non-goal under the heading, in file order, with its continuations joined.
|
|
350
|
+
|
|
351
|
+
**Every bullet, including the ones the shape does not hold** (RK233). Skipping those made
|
|
352
|
+
two readers of one list: `leads` gave them an address on purpose (RK68) so `brief` prints
|
|
353
|
+
the whole scope, this one dropped them, and `drop` resolves against this one — so a
|
|
354
|
+
constraint printed by one command answered to no address in the other. On an opted-in
|
|
355
|
+
project that closed the last door: the gate reports `non-goal.shape` and names the
|
|
356
|
+
rewrite, `Edit` is denied (RK22), and the pair that would do it — `drop` then `add` —
|
|
357
|
+
could not reach the bullet. A finding whose remedy the tool refuses (RK16).
|
|
358
|
+
|
|
359
|
+
The **round-trip question that decided it** (L3): nothing renders a parsed non-goal back
|
|
360
|
+
into the file. :attr:`NonGoal.lines` is the source verbatim, `drop` removes that span, and
|
|
361
|
+
:func:`render` writes only what `add` composed — so accepting a bullet this module could
|
|
362
|
+
not have written costs no rendering it cannot do. What the shape *does* still decide is
|
|
363
|
+
what the gate says about the bullet, which is :attr:`NonGoal.shaped` and not this filter.
|
|
364
|
+
"""
|
|
365
|
+
return _bullets(document)
|
|
366
|
+
|
|
367
|
+
|
|
368
|
+
def rejects(document: Document) -> tuple[tuple[int, str], ...]:
|
|
369
|
+
"""The bullets under the heading whose shape the format does not hold, with their line.
|
|
370
|
+
|
|
371
|
+
Still the gate's own answer and still counted apart (RK139): being addressable is not
|
|
372
|
+
being in the format, and a count that omitted these would read as a complete one. What
|
|
373
|
+
changed is that they are no longer *unread* — :func:`read` returns them, so the finding
|
|
374
|
+
reported here has the door the finding is asking for.
|
|
375
|
+
"""
|
|
376
|
+
return tuple(
|
|
377
|
+
(goal.first, goal.lines[0]) for goal in _bullets(document) if not goal.shaped
|
|
378
|
+
)
|
|
379
|
+
|
|
380
|
+
|
|
381
|
+
def leads(document: Document) -> tuple[str, ...]:
|
|
382
|
+
"""The lead of every bullet under the heading, in file order — what `brief` prints.
|
|
383
|
+
|
|
384
|
+
Here rather than at the reader's call site so that the reader and the writer cannot
|
|
385
|
+
disagree about what a lead *is*, exactly as :data:`HEADING` settles where the list is
|
|
386
|
+
(RK68). One line now, because :func:`read` reads what this reads (RK233) — the agreement
|
|
387
|
+
is the reader rather than two functions applying the same rule.
|
|
388
|
+
|
|
389
|
+
Where the shape holds a lead is the bold run and only that. Where it does not, it is the
|
|
390
|
+
first sentence of the bullet **joined across its continuations** — never a bold run found
|
|
391
|
+
mid-sentence, which is emphasis and not an address: Turing writes ``is **not** a path``,
|
|
392
|
+
whose middle bold made the printed non-goal the word ``not``.
|
|
393
|
+
"""
|
|
394
|
+
return tuple(goal.lead for goal in _bullets(document))
|
|
395
|
+
|
|
396
|
+
|
|
397
|
+
def address(lead: str) -> str:
|
|
398
|
+
"""The lead as an address: case-folded, and without the stop the bold may carry.
|
|
399
|
+
|
|
400
|
+
One function, because `add` refuses a duplicate and `lint` reports one — two spellings of
|
|
401
|
+
"the same lead" would mean a bullet the write path accepted and the gate then failed on,
|
|
402
|
+
which is the split L1 exists to prevent.
|
|
403
|
+
"""
|
|
404
|
+
return lead.strip().rstrip(".").casefold()
|
|
405
|
+
|
|
406
|
+
|
|
407
|
+
def render(config: Config, lead: str, why: str) -> tuple[str, ...]:
|
|
408
|
+
"""The bullet as the schema writes it: one line, filled to `prose`, continuations by two.
|
|
409
|
+
|
|
410
|
+
The only writer of the format, exactly as `Schema.render` is for a task line — a bullet
|
|
411
|
+
composed at a call site is the drift this module exists to make impossible.
|
|
412
|
+
"""
|
|
413
|
+
return tuple(
|
|
414
|
+
textwrap.fill(
|
|
415
|
+
f"- **{lead.strip()}** {' '.join(why.split())}",
|
|
416
|
+
width=config.schema.prose_width,
|
|
417
|
+
subsequent_indent=_CONTINUATION,
|
|
418
|
+
break_long_words=False,
|
|
419
|
+
break_on_hyphens=False,
|
|
420
|
+
).split("\n")
|
|
421
|
+
)
|
|
422
|
+
|
|
423
|
+
|
|
424
|
+
def validate(config: Config, lead: str, why: str) -> tuple[Violation, ...]:
|
|
425
|
+
"""Every rule a schema can check about a non-goal, and no rule it cannot.
|
|
426
|
+
|
|
427
|
+
Length and shape only. That the lead states a *constraint* rather than a task is the
|
|
428
|
+
author's claim, the same way a symptom's falsifiability is (L4).
|
|
429
|
+
"""
|
|
430
|
+
scope = config.non_goals or Scope()
|
|
431
|
+
out: list[Violation] = []
|
|
432
|
+
head, reason = lead.strip(), " ".join(why.split())
|
|
433
|
+
if not head:
|
|
434
|
+
out.append(Violation(LEAD, "lead", "a non-goal is addressed by its lead"))
|
|
435
|
+
if "*" in head:
|
|
436
|
+
out.append(
|
|
437
|
+
Violation(
|
|
438
|
+
LEAD,
|
|
439
|
+
"lead",
|
|
440
|
+
"the lead is bolded by the renderer, so it may not carry '*' itself",
|
|
441
|
+
)
|
|
442
|
+
)
|
|
443
|
+
if width(head) > scope.lead:
|
|
444
|
+
out.append(
|
|
445
|
+
Violation(
|
|
446
|
+
LEAD,
|
|
447
|
+
"lead",
|
|
448
|
+
over_by(width(head), scope.lead, measured=head),
|
|
449
|
+
)
|
|
450
|
+
)
|
|
451
|
+
if not reason:
|
|
452
|
+
out.append(Violation(WHY, "why", "a constraint nobody argued is a rule"))
|
|
453
|
+
if width(reason) > scope.why:
|
|
454
|
+
out.append(
|
|
455
|
+
Violation(WHY, "why", over_by(width(reason), scope.why, measured=reason))
|
|
456
|
+
)
|
|
457
|
+
return tuple(out)
|
|
458
|
+
|
|
459
|
+
|
|
460
|
+
def check(config: Config, lead: str, why: str) -> None:
|
|
461
|
+
"""Validate or raise, so a refusal reports every problem at once (as `Schema.check`)."""
|
|
462
|
+
violations = validate(config, lead, why)
|
|
463
|
+
if violations:
|
|
464
|
+
raise SchemaError(violations)
|
|
465
|
+
|
|
466
|
+
|
|
467
|
+
def add(config: Config, lead: str, why: str) -> Written:
|
|
468
|
+
"""Insert one non-goal under the heading, after the last one there. Validated first.
|
|
469
|
+
|
|
470
|
+
Refused, and nothing written, when the project has not opted in, when no heading declares
|
|
471
|
+
the list, when a field is over its limit, or when the lead is already taken — the four
|
|
472
|
+
refusals being what makes this a door rather than an `Edit` with extra steps.
|
|
473
|
+
"""
|
|
474
|
+
if config.non_goals is None:
|
|
475
|
+
raise NotGoverned(config.relative(config.source or config.root))
|
|
476
|
+
document = config.document("roadmap")
|
|
477
|
+
where = config.relative(config.path("roadmap"))
|
|
478
|
+
heading = _heading_index(document)
|
|
479
|
+
if heading is None:
|
|
480
|
+
raise NoNonGoals(where)
|
|
481
|
+
check(config, lead, why)
|
|
482
|
+
|
|
483
|
+
head = lead.strip()
|
|
484
|
+
existing = read(document)
|
|
485
|
+
twin = next((n for n in existing if address(n.lead) == address(head)), None)
|
|
486
|
+
if twin is not None:
|
|
487
|
+
raise DuplicateLead(head, where, twin.first)
|
|
488
|
+
|
|
489
|
+
lines = render(config, head, why)
|
|
490
|
+
at, separate = _placement(document, heading, existing)
|
|
491
|
+
updated = document
|
|
492
|
+
if separate:
|
|
493
|
+
# The line above is the heading or its prose, and a bullet glued to either reads as
|
|
494
|
+
# part of it — so the blank that separates them is part of this insertion.
|
|
495
|
+
updated = updated.insert_line(at, "")
|
|
496
|
+
at += 1
|
|
497
|
+
for offset, line in enumerate(lines):
|
|
498
|
+
updated = updated.insert_line(at + offset, line)
|
|
499
|
+
return Written(
|
|
500
|
+
document=updated,
|
|
501
|
+
non_goal=NonGoal(
|
|
502
|
+
lead=head,
|
|
503
|
+
why=" ".join(why.split()),
|
|
504
|
+
first=at + 1,
|
|
505
|
+
last=at + len(lines),
|
|
506
|
+
lines=lines,
|
|
507
|
+
),
|
|
508
|
+
)
|
|
509
|
+
|
|
510
|
+
|
|
511
|
+
def amend(config: Config, lead: str, why: str) -> Amended:
|
|
512
|
+
"""Rewrite one non-goal's reason where it already sits, keeping its place (RK368).
|
|
513
|
+
|
|
514
|
+
The door the other two bullet grammars have and this one did not. `record amend` exists so
|
|
515
|
+
a ledger correction is not a move — never drop-and-re-add, which shows a reviewer a
|
|
516
|
+
deletion where a word changed — and `section amend` is the same door for a live design.
|
|
517
|
+
The non-goals had only `drop` plus `add`, and `add` inserts after the last bullet: measured
|
|
518
|
+
at RK367, a constraint that sat fifth of eight moved to eighth for a reason no commit was
|
|
519
|
+
about, and the order a reader takes for the shape of the list changed with it.
|
|
520
|
+
|
|
521
|
+
**The lead is not a field**, exactly as a task's `symptom` is not `amend`'s: it is the
|
|
522
|
+
address, so a constraint whose lead changes is one retired and one written, which is what
|
|
523
|
+
`drop` already says and what the skill already tells an author. The asymmetry needs no
|
|
524
|
+
refusal of its own — there is no argument to pass — and this sentence is where it is stated.
|
|
525
|
+
|
|
526
|
+
Where two bullets carry one address the **first** is corrected, which is the other half of
|
|
527
|
+
`drop`'s rule (RK67): that verb removes the later copy because the first is where the
|
|
528
|
+
reader already found it, so the one that stays is the one a correction is about.
|
|
529
|
+
|
|
530
|
+
Nothing is written when nothing differs, as at every other door: rewriting the same bytes
|
|
531
|
+
makes a no-op look like an edit to every hook watching the file.
|
|
532
|
+
"""
|
|
533
|
+
if config.non_goals is None:
|
|
534
|
+
raise NotGoverned(config.relative(config.source or config.root))
|
|
535
|
+
document = config.document("roadmap")
|
|
536
|
+
where = config.relative(config.path("roadmap"))
|
|
537
|
+
if _heading_index(document) is None:
|
|
538
|
+
raise NoNonGoals(where)
|
|
539
|
+
|
|
540
|
+
existing = read(document)
|
|
541
|
+
wanted = address(lead)
|
|
542
|
+
matches = tuple(one for one in existing if address(one.lead) == wanted)
|
|
543
|
+
if not matches:
|
|
544
|
+
raise NoSuchNonGoal(lead.strip(), where, tuple(one.lead for one in existing))
|
|
545
|
+
standing = matches[0]
|
|
546
|
+
if not standing.shaped:
|
|
547
|
+
raise Unshaped(standing.lead, where, standing.first)
|
|
548
|
+
|
|
549
|
+
# Its own lead and not the address the caller typed: `address` folds case and drops the
|
|
550
|
+
# stop, so composing from the argument would rewrite the head this verb promises not to.
|
|
551
|
+
check(config, standing.lead, why)
|
|
552
|
+
reason = " ".join(why.split())
|
|
553
|
+
if reason == standing.why:
|
|
554
|
+
return Amended(document=document, non_goal=standing, before=standing.why)
|
|
555
|
+
|
|
556
|
+
lines = render(config, standing.lead, reason)
|
|
557
|
+
start = standing.first - 1
|
|
558
|
+
updated = document.remove_lines(start, standing.last)
|
|
559
|
+
for offset, line in enumerate(lines):
|
|
560
|
+
updated = updated.insert_line(start + offset, line)
|
|
561
|
+
return Amended(
|
|
562
|
+
document=updated,
|
|
563
|
+
non_goal=replace(
|
|
564
|
+
standing, why=reason, last=start + len(lines), lines=lines
|
|
565
|
+
),
|
|
566
|
+
before=standing.why,
|
|
567
|
+
)
|
|
568
|
+
|
|
569
|
+
|
|
570
|
+
def drop(config: Config, lead: str) -> Dropped:
|
|
571
|
+
"""Remove the non-goal a lead addresses, whole, wrapped lines included.
|
|
572
|
+
|
|
573
|
+
The other half of the door, and the half a *correction* needs: a lead is the address, so a
|
|
574
|
+
constraint whose lead changes is a different constraint — `- **No dates, quarters or
|
|
575
|
+
estimates**` becoming `- **No dates or quarters**` is one retired and one written, which
|
|
576
|
+
is honest in a way an in-place edit of the address would not be.
|
|
577
|
+
|
|
578
|
+
Where two bullets carry one address — `lint`'s `non-goal.duplicate` — the later one goes,
|
|
579
|
+
for `record drop`'s reason (RK67): the first is where the reader already found it. So this
|
|
580
|
+
is also that finding's door, and a second call is what a third copy takes.
|
|
581
|
+
"""
|
|
582
|
+
if config.non_goals is None:
|
|
583
|
+
raise NotGoverned(config.relative(config.source or config.root))
|
|
584
|
+
document = config.document("roadmap")
|
|
585
|
+
where = config.relative(config.path("roadmap"))
|
|
586
|
+
if _heading_index(document) is None:
|
|
587
|
+
raise NoNonGoals(where)
|
|
588
|
+
|
|
589
|
+
existing = read(document)
|
|
590
|
+
wanted = address(lead)
|
|
591
|
+
matches = tuple(one for one in existing if address(one.lead) == wanted)
|
|
592
|
+
if not matches:
|
|
593
|
+
raise NoSuchNonGoal(lead.strip(), where, tuple(one.lead for one in existing))
|
|
594
|
+
going = matches[-1]
|
|
595
|
+
return Dropped(
|
|
596
|
+
document=_remove_span(document, going),
|
|
597
|
+
non_goal=going,
|
|
598
|
+
carried=len(matches),
|
|
599
|
+
)
|
|
600
|
+
|
|
601
|
+
|
|
602
|
+
def _remove_span(document: Document, going: NonGoal) -> Document:
|
|
603
|
+
"""Take the bullet out, and the blank line the removal doubled.
|
|
604
|
+
|
|
605
|
+
A list of one sits between blanks, so removing it leaves a paragraph break the file never
|
|
606
|
+
had — and both spellings round-trip, which is exactly why nothing downstream would catch
|
|
607
|
+
it (the same care `ship` takes with a task line, RK6).
|
|
608
|
+
"""
|
|
609
|
+
start = going.first - 1
|
|
610
|
+
updated = document.remove_lines(start, going.last)
|
|
611
|
+
lines = updated.lines
|
|
612
|
+
if start > 0 and start < len(lines) and blank(lines[start - 1]) and blank(lines[start]):
|
|
613
|
+
return updated.remove_line(start)
|
|
614
|
+
if start >= len(lines) and start > 0 and blank(lines[start - 1]):
|
|
615
|
+
# The list was last in the file: its trailing blank has nothing left to separate.
|
|
616
|
+
return updated.remove_line(start - 1)
|
|
617
|
+
return updated
|
|
618
|
+
|
|
619
|
+
|
|
620
|
+
def _heading_index(document: Document) -> int | None:
|
|
621
|
+
"""The 0-based index of the non-goals heading line, or None when there is no list."""
|
|
622
|
+
heading = next((h for h in document.headings if HEADING.match(h.text)), None)
|
|
623
|
+
return None if heading is None else heading.lineno - 1
|
|
624
|
+
|
|
625
|
+
|
|
626
|
+
def _bullets(document: Document) -> tuple[NonGoal, ...]:
|
|
627
|
+
"""Every bullet under the heading, spans joined, each one addressable (RK233).
|
|
628
|
+
|
|
629
|
+
The continuation lines are folded in before a lead is taken, which is what lets it come
|
|
630
|
+
from the whole bullet instead of from its first physical line (RK68) — the difference
|
|
631
|
+
between Turing's first non-goal forbidding ten things and appearing to forbid three.
|
|
632
|
+
|
|
633
|
+
Where the bold shape does not hold, the lead is the first sentence and the `why` is what
|
|
634
|
+
follows it. Both **verbatim**, stop included where the sentence is the whole bullet,
|
|
635
|
+
exactly as the bold lead is kept: normalizing an author's punctuation to satisfy a rule
|
|
636
|
+
nobody stated is the rewrite this refuses to be (L4).
|
|
637
|
+
"""
|
|
638
|
+
start = _heading_index(document)
|
|
639
|
+
if start is None:
|
|
640
|
+
return ()
|
|
641
|
+
# A line the task grammar already read is that reader's and never this one's (RK1355).
|
|
642
|
+
# Both claimed it: a well-formed task line appended under this heading answered
|
|
643
|
+
# `block.missing` — *a task line lives under a block heading*, which is what happened —
|
|
644
|
+
# and `non-goal.shape` at the same time, whose door is `non-goal drop '<the whole line>'`.
|
|
645
|
+
# Run as printed, that door removed the id, the symptom, the why and the pointer, and
|
|
646
|
+
# reported a bullet taken out of a list it never belonged to. So the specific reading
|
|
647
|
+
# wins, as a codepoint finding already replaces every other on its line.
|
|
648
|
+
#
|
|
649
|
+
# Parsed entries only. A bullet the grammar *rejected* is an ordinary malformed non-goal,
|
|
650
|
+
# which is the population this section exists to measure — excluding those would hide the
|
|
651
|
+
# thing being looked for.
|
|
652
|
+
entries = {entry.lineno for entry in document.entries}
|
|
653
|
+
spans: list[tuple[int, list[str]]] = []
|
|
654
|
+
for offset, raw in enumerate(document.lines[start + 1 :], start=start + 2):
|
|
655
|
+
body = raw.rstrip("\r\n")
|
|
656
|
+
if body.startswith("#"):
|
|
657
|
+
break # the next heading ends the section, whatever its level
|
|
658
|
+
if offset in entries:
|
|
659
|
+
continue
|
|
660
|
+
if _ANY_BULLET.match(body):
|
|
661
|
+
spans.append((offset, [body]))
|
|
662
|
+
elif spans and body.startswith(_CONTINUATION) and not blank(body):
|
|
663
|
+
spans[-1][1].append(body)
|
|
664
|
+
out: list[NonGoal] = []
|
|
665
|
+
for first, span in spans:
|
|
666
|
+
joined = " ".join(line.strip() for line in span)
|
|
667
|
+
where = {"first": first, "last": first + len(span) - 1, "lines": tuple(span)}
|
|
668
|
+
match = _BULLET.match(joined)
|
|
669
|
+
if match is not None:
|
|
670
|
+
out.append(
|
|
671
|
+
NonGoal(
|
|
672
|
+
lead=match.group("lead").strip(),
|
|
673
|
+
why=(match.group("why") or "").strip(),
|
|
674
|
+
**where,
|
|
675
|
+
)
|
|
676
|
+
)
|
|
677
|
+
continue
|
|
678
|
+
marker = _ANY_BULLET.match(joined)
|
|
679
|
+
rest = marker.group("rest") if marker is not None else joined
|
|
680
|
+
head, _, tail = rest.partition(_SENTENCE)
|
|
681
|
+
out.append(NonGoal(lead=head.strip(), why=tail.strip(), shaped=False, **where))
|
|
682
|
+
return tuple(out)
|
|
683
|
+
|
|
684
|
+
|
|
685
|
+
def _placement(
|
|
686
|
+
document: Document, heading: int, existing: tuple[NonGoal, ...]
|
|
687
|
+
) -> tuple[int, bool]:
|
|
688
|
+
"""Where the bullet goes, and whether a blank line has to go in front of it.
|
|
689
|
+
|
|
690
|
+
After the last non-goal, so the list stays in the order it was written — and after the
|
|
691
|
+
section's *prose* when there is no bullet yet, never straight under the heading: this
|
|
692
|
+
repository's list opens with a sentence telling a reader to check it, and a bullet above
|
|
693
|
+
that sentence would make the instruction read as a footnote to the first non-goal.
|
|
694
|
+
|
|
695
|
+
Whatever blank lines follow the section stay where they are, which is what keeps the
|
|
696
|
+
separation from the next heading (or the file's end) exactly as the author left it.
|
|
697
|
+
"""
|
|
698
|
+
if existing:
|
|
699
|
+
# `last` is 1-based, so it is already the 0-based index of the line after it.
|
|
700
|
+
return existing[-1].last, False
|
|
701
|
+
end = len(document.lines)
|
|
702
|
+
for offset, raw in enumerate(document.lines[heading + 1 :], start=heading + 1):
|
|
703
|
+
if raw.lstrip().startswith("#"):
|
|
704
|
+
end = offset
|
|
705
|
+
break
|
|
706
|
+
while end > heading + 1 and blank(document.lines[end - 1]):
|
|
707
|
+
end -= 1
|
|
708
|
+
return end, True
|