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
@@ -0,0 +1,503 @@
1
+ """The id two branches spent on different work, moved without a departure (RK97).
2
+
3
+ Measured here: a branch filed five ids while main shipped a different task under the
4
+ first of them, and the merge left both. `lint` named it at once — `id.two-files`, because
5
+ open and recorded-as-gone are not both true — and then no command could act on it. `ship`
6
+ and `retire` are the only doors that take a line out of the roadmap, and each writes a
7
+ *terminal* ledger entry, which is the wrong record for work nobody cancelled; `amend`
8
+ reaches the `why`, the deps and the ref, and deliberately not the id. So the only repair
9
+ was a hand-edit of the line, its pointer and its section heading, in the files the guard
10
+ (RK22) exists to keep hands out of.
11
+
12
+ This is the door that leaves the work open. An id is an address, and a collision is two
13
+ lines claiming one — so the move is an address change and nothing else:
14
+
15
+ * **The whole address, or none of it.** The line, the `§id` heading its pointer resolves
16
+ to, **every `§id.n` nested under that heading**, and every `(deps: …)` naming it change in
17
+ one transaction, validated before any file is touched. A renumber that wrote the line and
18
+ not the section would leave the pointer dangling, which is the state RK93 exists to
19
+ prevent one verb over; one that wrote the heading and not the subtree beneath it leaves a
20
+ `§RK1.1` claiming a task the backlog no longer has, under a heading naming RK9 — half a
21
+ subtree renamed, written, and called clean by the gate (RK113).
22
+ * **The destination is derived unless it is given.** `next_id` in the line's own family
23
+ (RK74) is the answer the repair usually wants, and a given one is refused if *anything*
24
+ mentions it — the same :func:`~roadkeep.authoring.refuse_reuse` `add` calls, because a
25
+ free id is one question with one answer (RK4).
26
+ * **The ledger is never opened.** The id the other branch spent stays spent: it is a
27
+ decision already recorded, and renumbering history is how a `git log -S` starts
28
+ returning two unrelated designs.
29
+
30
+ What it cannot know, and therefore reports: **which line a dep meant**. After the merge
31
+ both RK90s existed, so a `(deps: RK90)` elsewhere in the backlog was written about one of
32
+ them and nothing in the files says which. Every dep on the old id is moved with the line —
33
+ that is what a dependent of *this* task needs — and every line that happened to is named
34
+ in the answer, because the one the author has to reconsider is a line they can only
35
+ reconsider if they are told it changed. Refusing instead would leave the repair a
36
+ hand-edit, which is the defect.
37
+
38
+ Nothing here crosses the id-scheme non-goal. Non-contiguity is a property of real backlogs
39
+ and stays one: the old number is not reclaimed, not filled and not reused — it is left to
40
+ the line that already had it.
41
+ """
42
+
43
+ from __future__ import annotations
44
+
45
+ from collections.abc import Mapping, Sequence
46
+ from dataclasses import dataclass, field, replace
47
+ from pathlib import Path
48
+
49
+ from roadkeep import claiming
50
+ from roadkeep.authoring import refuse_reuse
51
+ from roadkeep.claiming import Held
52
+ from roadkeep.backlog import Backlog, NotOpen, Whereabouts
53
+ from roadkeep.config import Config
54
+ from roadkeep.criteria import readdress
55
+ from roadkeep.kernel.document import Document, Entry, save_all
56
+ from roadkeep.kernel.schema import Task
57
+ from roadkeep.ids import id_scanner, next_id
58
+ from roadkeep.markers import refresh
59
+ from roadkeep.sections import Section, checked, descending, find, heading_of
60
+
61
+ __all__ = ["NotAnId", "Renumbering", "SameId", "family_of", "renumber"]
62
+
63
+ #: The files whose unit is a line, in the order a lookup asks them. The deferred store is
64
+ #: one (RK96): a paused line carries an id like any other, and a collision does not wait.
65
+ LINE_ROLES = ("roadmap", "deferred")
66
+
67
+
68
+ class NotAnId(ValueError):
69
+ """A destination the format cannot read as an id.
70
+
71
+ Refused before anything is written, because an unreadable id is worse than the
72
+ collision it was meant to repair: nothing resolves a dep against it, `next_id` cannot
73
+ see it, and the line is invisible to every scan (RK4).
74
+ """
75
+
76
+ def __init__(self, wanted: str, pattern: str) -> None:
77
+ self.wanted = wanted
78
+ super().__init__(
79
+ f"{wanted!r} is not an id this project can read ({pattern}): the move needs "
80
+ f"an address, and omitting one derives the next in the line's own family"
81
+ )
82
+
83
+
84
+ class SameId(ValueError):
85
+ """A move to the number the line already carries."""
86
+
87
+ def __init__(self, task_id: str) -> None:
88
+ self.task_id = task_id
89
+ super().__init__(
90
+ f"{task_id} already is that id: a renumber that changes nothing would still "
91
+ f"rewrite the file, and an untouched file with a moved mtime reads as an edit"
92
+ )
93
+
94
+
95
+ @dataclass(frozen=True, slots=True)
96
+ class Renumbering:
97
+ """Every edit one line's change of address makes, as data, before it is written."""
98
+
99
+ task_id: str
100
+ to: str
101
+ #: Which line file held it — the roadmap, or the deferred store (RK96).
102
+ role: str
103
+ #: The line as it now reads, under its new id.
104
+ entry: Entry
105
+ #: The governed files this write leaves changed, by role. A mapping and not three
106
+ #: named fields, because *which* files are in it is a property of the project — a
107
+ #: deferred store is optional and a prose file may hold no section for this line.
108
+ documents: Mapping[str, Document] = field(default_factory=dict)
109
+ #: The heading that moved with the line, or None when the pointer had no section.
110
+ section: Section | None = None
111
+ #: The nested anchors re-addressed with it, as they now read (`RK9.1`). A subsection is
112
+ #: the task's own numbering, so it carries the task's address (RK113).
113
+ subsections: tuple[str, ...] = ()
114
+ #: Whether this line's own `## Done when` heading moved with it (RK1317). A flag and not
115
+ #: the leads, unlike a departure's `unmet`: nothing was deleted, so what the author needs
116
+ #: is that the address moved — the bullets are still there and are still theirs.
117
+ criteria: bool = False
118
+ #: Every line whose `(deps: …)` now names the new id. Named and never silent: which
119
+ #: of two collided ids a dep meant is the one thing this transaction cannot read.
120
+ moved: tuple[str, ...] = ()
121
+ #: Lines whose annotation this write made true again (RK8).
122
+ refreshed: tuple[str, ...] = ()
123
+ #: The live claim this move carries to the new id, where there is one (RK156). Reported,
124
+ #: because a worker whose line changed number will next ask for it by an id that no longer
125
+ #: exists, and that it is still theirs is the half of the answer the files do not hold.
126
+ claim: Held | None = None
127
+ #: The checkout, because one thing this move carries is *not* a governed file: the claim
128
+ #: registry lives outside the repository (L2) and is keyed by the address that just moved.
129
+ root: Path | None = None
130
+
131
+ @property
132
+ def rendered(self) -> str:
133
+ return self.entry.raw
134
+
135
+ @property
136
+ def lineno(self) -> int:
137
+ return self.entry.lineno
138
+
139
+ def save(self) -> tuple[Path, ...]:
140
+ """Write the files, and answer every path that took (RK1130).
141
+
142
+ The claim goes last and never conditions the write: it is transient state whose worst
143
+ failure is a claim lost, which is the behaviour before claims existed — and putting it
144
+ before the files would move an address the files had not moved yet.
145
+ """
146
+ wrote = save_all(*self.documents.values())
147
+ if self.root is not None and self.claim is not None:
148
+ claiming.rename(self.root, self.task_id, self.to)
149
+ return wrote
150
+
151
+ def event(self, config: Config) -> dict[str, object]:
152
+ """What the move did to the block it lands in (RK38).
153
+
154
+ The roadmap is read back where this write did not touch it: a line moved in the
155
+ deferred store owes the same event line, and the file is already saved.
156
+ """
157
+ from roadkeep.rendering import _event # noqa: PLC0415 - RK260
158
+
159
+ return _event(
160
+ self.to,
161
+ self.entry.task.block,
162
+ self.documents.get("roadmap") or config.document("roadmap"),
163
+ config,
164
+ )
165
+
166
+ def stated(self, config: Config, wrote: Sequence[Path]) -> str:
167
+ """Where the line went and what followed it (RK74, RK113, RK156).
168
+
169
+ Beside :meth:`payload` since RK1170. `wrote` is the caller's, because :meth:`save` is
170
+ a step this record does not take.
171
+ """
172
+ from roadkeep.rendering import ( # noqa: PLC0415 - RK260
173
+ _event_rows,
174
+ _staging_rows,
175
+ )
176
+
177
+ where = config.relative(config.path(self.role))
178
+ prose = (
179
+ config.relative(config.path("improvements")) if config.has("improvements") else ""
180
+ )
181
+ rows = [
182
+ f"{self.task_id} → {self.to} {where}:{self.lineno}",
183
+ f" {self.rendered}",
184
+ ]
185
+ if self.section is not None:
186
+ # The section's **own** anchor and not `to` (RK1231): where the ref is the id the
187
+ # two are the same string, and under an outline they are not — the address stayed
188
+ # and the binding moved, so printing the id would name a heading that is not there.
189
+ rows.append(f" section §{self.section.anchor} → {prose}:{self.section.first}")
190
+ if self.subsections:
191
+ rows.append(
192
+ f" nested {', '.join('§' + a for a in self.subsections)} "
193
+ f"(the id's own numbering)"
194
+ )
195
+ if self.criteria:
196
+ # Said and never silent (RK1317), which is `_unmet_rows`' rule pointed the other
197
+ # way: a departure names the list it spends, and this names the list it moved —
198
+ # a heading rewritten on the author's behalf is one they cannot otherwise see.
199
+ rows.append(
200
+ f" finished ## Done when — {self.to}, re-addressed with the line"
201
+ )
202
+ if self.moved:
203
+ rows.append(
204
+ f" deps {', '.join(self.moved)} now name {self.to} — "
205
+ f"confirm each meant this line"
206
+ )
207
+ if self.refreshed:
208
+ rows.append(f" derived {', '.join(self.refreshed)} (dep annotations re-derived)")
209
+ if self.claim is not None:
210
+ # The half the files do not hold (RK156): the worker holding this will next ask for
211
+ # it by a number that no longer exists, and that it is still theirs is what to say.
212
+ rows.append(f" claimed the claim taken {self.claim.since} ago moved with it")
213
+ rows += _staging_rows(config.relative(one) for one in wrote)
214
+ rows += _event_rows(self.event(config), " ")
215
+ return "\n".join(rows)
216
+
217
+ def payload(self, config: Config, wrote: Sequence[Path]) -> dict[str, object]:
218
+ """The same answer as data, with every file the new address reached."""
219
+ from roadkeep.rendering import _held_json, _wrote_json # noqa: PLC0415 - RK260
220
+
221
+ prose = (
222
+ config.relative(config.path("improvements")) if config.has("improvements") else ""
223
+ )
224
+ return {
225
+ "id": self.task_id,
226
+ "to": self.to,
227
+ "role": self.role,
228
+ "file": config.relative(config.path(self.role)),
229
+ "line": self.lineno,
230
+ "rendered": self.rendered,
231
+ "section": None if self.section is None else self.section.payload(prose),
232
+ # The nested headings that carried the old address, as they now read.
233
+ "subsections": list(self.subsections),
234
+ # Whether this line's own criteria heading moved with it (RK1317). False and never
235
+ # omitted: a task that declared no list is the ordinary renumbering, and a key that
236
+ # appears only when it is set is one a reader learns to stop looking for.
237
+ "criteria": self.criteria,
238
+ # The lines this write changed on the author's behalf, because which of two
239
+ # collided ids a dep meant is not a fact any file holds.
240
+ "moved": list(self.moved),
241
+ "refreshed": list(self.refreshed),
242
+ "files": sorted(config.relative(config.path(role)) for role in self.documents),
243
+ "claimed": _held_json(self.claim),
244
+ **_wrote_json(config, wrote),
245
+ "event": self.event(config),
246
+ }
247
+
248
+
249
+ def renumber(config: Config, task_id: str, to: str | None = None) -> Renumbering:
250
+ """Move one open line to a free id, with its section and its dependents.
251
+
252
+ `to` is derived when it is not given: one past the highest id in this line's own
253
+ family (RK74), which is the address a collision repair almost always wants. Given, it
254
+ is held to the same rule every minted id is — refused if any configured source
255
+ mentions it, including prose, because a number a document already names is a number
256
+ two designs would share in the history.
257
+
258
+ Refuses before writing anything: an id in neither line file, a destination the format
259
+ cannot read, a destination already spent, and any line the move would render over the
260
+ limit — a longer number is two more characters, and the cap is the cap.
261
+ """
262
+ schema = config.schema
263
+ documents = _line_documents(config)
264
+ role, entry = _locate(config, documents, task_id)
265
+ if to is None:
266
+ to = next_id(config, family_of(config, task_id))
267
+ if to == task_id:
268
+ raise SameId(task_id)
269
+ if not schema.id_pattern().match(to):
270
+ raise NotAnId(to, schema.id_pattern().pattern)
271
+ # `--to` and not `--id`, which is this verb's own spelling (RK1212): the rule is shared
272
+ # and the argument carrying the number is not.
273
+ refuse_reuse(config, to, flag="--to")
274
+
275
+ changed: dict[str, Document] = {}
276
+ # The pointer is the id under `ref_scheme = "id"` (RK27), so it moves with it; under
277
+ # an outline it names a heading this line does not own, and is left exactly as typed.
278
+ pointer = to if schema.ref_scheme == "id" and entry.task.ref else entry.task.ref
279
+ documents[role] = documents[role].replace_task(
280
+ entry,
281
+ checked(
282
+ config,
283
+ replace(entry.task, id=to, ref=pointer),
284
+ schema=documents[role].schema,
285
+ ),
286
+ )
287
+ changed[role] = documents[role]
288
+
289
+ moved = _move_deps(documents, task_id, to)
290
+ changed.update({name: documents[name] for name in moved})
291
+
292
+ section = None
293
+ subsections: tuple[str, ...] = ()
294
+ prose = _section_document(config, task_id, to) if entry.task.ref == task_id else None
295
+ if prose is not None:
296
+ changed["improvements"], section, subsections = prose
297
+ elif entry.task.ref:
298
+ # The **binding**, where the anchor is not the id (RK1231). Under an outline the ref is
299
+ # an address like `XXVI.14`, so the branch above is skipped and the heading keeps the
300
+ # number the task no longer has — `### XXVI.14 … (SH9001)` after `renumber SH9001
301
+ # SH789`, a heading naming a task that does not exist. The comment above is right that
302
+ # an outline heading is not this line's to move; the trailing `(<id>)` is a different
303
+ # question, and one this tool answered when it *wrote* the id there (RK262).
304
+ #
305
+ # Reported through the same `section` field, because it is the same fact — this write
306
+ # touched the design — and `section: null` was what an author had to read as a signal.
307
+ rebound = _rebound(config, entry.task.ref, entry.task, to)
308
+ if rebound is not None:
309
+ changed["improvements"], section = rebound
310
+
311
+ # And the list addressed by the id this write is spending (RK1317), **re-addressed** and
312
+ # never removed: a renumbering is not a departure, so RK1316's rule at the block's label
313
+ # and RK1268's at a departing line both point the other way here. Before the annotations
314
+ # are refreshed, because that read parses the roadmap and a heading it did not expect is
315
+ # not a state to hand it.
316
+ criteria_moved = False
317
+ derived = ()
318
+ if "roadmap" in documents:
319
+ documents["roadmap"], criteria_moved = readdress(documents["roadmap"], task_id, to)
320
+ if criteria_moved:
321
+ changed["roadmap"] = documents["roadmap"]
322
+
323
+ # Derived against the state this write creates, for the reason every other door
324
+ # does it (RK8): a dep that now names a different id is a dep whose cached marker
325
+ # was answered by the line that used to carry it.
326
+ refreshed = refresh(replace(Backlog.load(config), roadmap=documents["roadmap"]))
327
+ documents["roadmap"] = refreshed.document
328
+ derived = refreshed.changed
329
+ if derived:
330
+ changed["roadmap"] = refreshed.document
331
+
332
+ dependents = tuple(name for names in moved.values() for name in names)
333
+ # Read against the line as it was *before* the move, which is the only state the registry's
334
+ # key still matches (RK156).
335
+ held = claiming.live(config, [entry])
336
+ return Renumbering(
337
+ task_id=task_id,
338
+ to=to,
339
+ role=role,
340
+ entry=next(e for e in documents[role].entries if e.task.id == to),
341
+ documents=changed,
342
+ section=section,
343
+ subsections=subsections,
344
+ criteria=criteria_moved,
345
+ moved=dependents,
346
+ refreshed=tuple(n for n in derived if n != to and n not in dependents),
347
+ claim=held[0] if held else None,
348
+ root=config.root,
349
+ )
350
+
351
+
352
+ def _move_deps(
353
+ documents: dict[str, Document], task_id: str, to: str
354
+ ) -> dict[str, tuple[str, ...]]:
355
+ """Rewrite every `(deps: <old>)` to the new id, in place, by file. Refuses first.
356
+
357
+ Which lines those are is read once, before any of them is rewritten: `replace_task`
358
+ re-parses, so an entry held across an edit is one whose line number may already have
359
+ moved — the same care every mutator in :mod:`roadkeep.kernel.document` takes.
360
+ """
361
+ out: dict[str, tuple[str, ...]] = {}
362
+ for name, document in documents.items():
363
+ dependents = tuple(
364
+ e.task.id for e in document.entries if task_id in e.task.dep_ids
365
+ )
366
+ for dependent in dependents:
367
+ current = next(e for e in documents[name].entries if e.task.id == dependent)
368
+ rewritten = replace(
369
+ current.task,
370
+ deps=tuple(
371
+ replace(dep, id=to) if dep.id == task_id else dep
372
+ for dep in current.task.deps
373
+ ),
374
+ )
375
+ documents[name] = documents[name].replace_task(
376
+ current, documents[name].schema.check(rewritten)
377
+ )
378
+ if dependents:
379
+ out[name] = dependents
380
+ return out
381
+
382
+
383
+ def _line_documents(config: Config) -> dict[str, Document]:
384
+ """Every governed file whose unit is a line, loaded once and mutated in memory."""
385
+ return {
386
+ role: config.document(role)
387
+ for role in LINE_ROLES
388
+ if config.has(role) and config.path(role).is_file()
389
+ }
390
+
391
+
392
+ def _locate(
393
+ config: Config, documents: Mapping[str, Document], task_id: str
394
+ ) -> tuple[str, Entry]:
395
+ """Which line file holds this id, and the line — the roadmap, or the store (RK96).
396
+
397
+ A paused line is still a line, so it is renumbered by the same door; the ledger is not
398
+ asked, because an id it records is a decision and not an address to move.
399
+ """
400
+ for role, document in documents.items():
401
+ entry = document.by_id().get(task_id)
402
+ if entry is not None:
403
+ return role, entry
404
+ raise NotOpen(
405
+ task_id,
406
+ ", ".join(config.relative(config.path(role)) for role in documents),
407
+ Whereabouts.of(config, task_id),
408
+ )
409
+
410
+
411
+ def _rebound(
412
+ config: Config, anchor: str, task: Task, to: str
413
+ ) -> tuple[Document, Section] | None:
414
+ """This section's heading with the id it names moved, the address untouched (RK1231).
415
+
416
+ The half `_section_document` cannot do, and the two are deliberately not one function: that
417
+ one rewrites an **address**, which is only this line's to move where the anchor *is* the id;
418
+ this rewrites a **binding**, which is the tool's own writing wherever it appears. Under an
419
+ outline both facts are true of one heading and only the second travels with the id.
420
+
421
+ The binding is composed by :func:`~roadkeep.sections._bound` and never spelled here — a
422
+ second place that knew the `(<id>)` shape is exactly what drifts from the writer. Applied
423
+ to the document directly, the way its sibling applies an address, and **not** through
424
+ `amend`: that verb re-binds from the roadmap *on disk*, which at this moment still carries
425
+ the old id, so it would render `A design (SH789) (SH9001)`.
426
+
427
+ `None` where there is nothing to do: no prose file, no section at that anchor, or a heading
428
+ that never carried this id — an author's own title mentioning it is not a binding, which is
429
+ :func:`~roadkeep.sections.owners`' reading and not a second one.
430
+ """
431
+ from roadkeep.sections import _bound, owners # noqa: PLC0415 - RK260
432
+
433
+ if not config.has("improvements") or not config.path("improvements").is_file():
434
+ return None
435
+ document = config.document("improvements")
436
+ section = find(document, anchor)
437
+ if section is None or task.id not in owners(section, document.schema.id_pattern()):
438
+ return None
439
+ bare = section.title.replace(f"({task.id})", "").strip()
440
+ rebound = replace(
441
+ section,
442
+ title=_bound(document.schema, anchor, bare, replace(task, id=to)),
443
+ )
444
+ return document.replace_line(
445
+ section.first - 1, heading_of(document.schema, rebound)
446
+ ), rebound
447
+
448
+
449
+ def _section_document(
450
+ config: Config, anchor: str, to: str
451
+ ) -> tuple[Document, Section, tuple[str, ...]] | None:
452
+ """The prose file with this section's whole address re-written, or None if it has none.
453
+
454
+ Every heading and no prose. The paragraphs under them are the author's (L4) — but a
455
+ `§<id>.1` is not prose, it is the same address one segment longer, and leaving it behind
456
+ is what RK113 measured: `renumber RK1 --to RK9` moved the line, moved the pointer, moved
457
+ `§RK1` to `§RK9`, and left `§RK1.1` nested under it naming a task the backlog no longer
458
+ has. `find` deliberately returns the subtree and this function rewrote one line of it;
459
+ that asymmetry was the whole defect.
460
+
461
+ Only the anchors this one owns, which is :func:`~roadkeep.sections.descending`'s reading
462
+ and not a second one: a nested heading is renamed when it *extends* the id segment by
463
+ segment, so a `§RK1.1` travels and a `§RK50` someone filed inside the subtree keeps the
464
+ address of the task that owns it — the same question :func:`_move_deps` cannot answer
465
+ about a dep, answered by the anchor itself rather than by depth. The destination cannot
466
+ already carry one of these: `refuse_reuse` refused `to` if anything in any configured
467
+ source so much as mentions it, and `§RK9.1` mentions RK9.
468
+ """
469
+ if not config.has("improvements") or not config.path("improvements").is_file():
470
+ return None
471
+ document = config.document("improvements")
472
+ section = find(document, anchor)
473
+ if section is None:
474
+ return None
475
+ moved = replace(section, anchor=to)
476
+ # Read before any of them is written, and applied by line number: `replace_line` is one
477
+ # line for one line, so no heading below the first edit moves under the edits above it.
478
+ edits = [(section.first - 1, heading_of(document.schema, moved))]
479
+ renamed: list[str] = []
480
+ for child in descending(document, anchor):
481
+ under = replace(child, anchor=f"{to}{child.anchor[len(anchor) :]}")
482
+ edits.append((child.first - 1, heading_of(document.schema, under)))
483
+ renamed.append(under.anchor)
484
+ for index, raw in edits:
485
+ document = document.replace_line(index, raw)
486
+ return document, moved, tuple(renamed)
487
+
488
+
489
+ def family_of(config: Config, task_id: str) -> str:
490
+ """Which track this id belongs to, read off the id itself (RK74).
491
+
492
+ Off the id and never off the block: a track is not a block, and the destination of a
493
+ move has to stay in the family the line was numbered in or the repair is a second
494
+ collision waiting for the next `next_id`.
495
+
496
+ Public because the ledger's own re-addressing (RK127) asks the same question about the
497
+ same string, and two answers to "which family is this id in" is how one door mints a
498
+ destination the other would have refused.
499
+ """
500
+ match = id_scanner(config.schema).match(task_id)
501
+ return match.group(1) if match else config.schema.prefix
502
+
503
+