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.
Files changed (67) hide show
  1. roadkeep/__init__.py +79 -0
  2. roadkeep/adopting.py +2347 -0
  3. roadkeep/attesting.py +293 -0
  4. roadkeep/authoring.py +2117 -0
  5. roadkeep/backlog.py +767 -0
  6. roadkeep/blocking.py +1622 -0
  7. roadkeep/briefing.py +970 -0
  8. roadkeep/budgeting.py +2056 -0
  9. roadkeep/capturing.py +1699 -0
  10. roadkeep/claiming.py +1019 -0
  11. roadkeep/cli.py +638 -0
  12. roadkeep/commanding.py +487 -0
  13. roadkeep/config.py +1832 -0
  14. roadkeep/counting.py +376 -0
  15. roadkeep/criteria.py +933 -0
  16. roadkeep/deferring.py +708 -0
  17. roadkeep/describing.py +568 -0
  18. roadkeep/exporting.py +808 -0
  19. roadkeep/fixing.py +629 -0
  20. roadkeep/governing.py +934 -0
  21. roadkeep/graph.py +395 -0
  22. roadkeep/guarding.py +1028 -0
  23. roadkeep/history.py +2403 -0
  24. roadkeep/ids.py +301 -0
  25. roadkeep/installing.py +2145 -0
  26. roadkeep/kernel/__init__.py +24 -0
  27. roadkeep/kernel/document.py +1719 -0
  28. roadkeep/kernel/schema.py +2308 -0
  29. roadkeep/linting.py +4420 -0
  30. roadkeep/locking.py +209 -0
  31. roadkeep/markers.py +172 -0
  32. roadkeep/merging.py +1159 -0
  33. roadkeep/picking.py +772 -0
  34. roadkeep/provenance.py +789 -0
  35. roadkeep/queueing.py +752 -0
  36. roadkeep/ranking.py +139 -0
  37. roadkeep/referring.py +231 -0
  38. roadkeep/remaining.py +336 -0
  39. roadkeep/remedying.py +1989 -0
  40. roadkeep/rendering.py +1601 -0
  41. roadkeep/renumbering.py +503 -0
  42. roadkeep/repairing.py +295 -0
  43. roadkeep/reverting.py +144 -0
  44. roadkeep/scoping.py +708 -0
  45. roadkeep/screening.py +196 -0
  46. roadkeep/sections.py +4121 -0
  47. roadkeep/serving.py +2909 -0
  48. roadkeep/shipping.py +3993 -0
  49. roadkeep/showing.py +613 -0
  50. roadkeep/storing.py +224 -0
  51. roadkeep/verbs/__init__.py +26 -0
  52. roadkeep/verbs/adopting.py +974 -0
  53. roadkeep/verbs/authoring.py +566 -0
  54. roadkeep/verbs/declaring.py +335 -0
  55. roadkeep/verbs/linting.py +645 -0
  56. roadkeep/verbs/querying.py +2138 -0
  57. roadkeep/verbs/reading.py +307 -0
  58. roadkeep/verbs/refusing.py +146 -0
  59. roadkeep/verbs/sections.py +1433 -0
  60. roadkeep/verbs/shipping.py +819 -0
  61. roadkeep/weighing.py +380 -0
  62. roadkeep-0.2.0.dist-info/METADATA +453 -0
  63. roadkeep-0.2.0.dist-info/RECORD +67 -0
  64. roadkeep-0.2.0.dist-info/WHEEL +5 -0
  65. roadkeep-0.2.0.dist-info/entry_points.txt +2 -0
  66. roadkeep-0.2.0.dist-info/licenses/LICENSE +202 -0
  67. 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