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/renumbering.py
ADDED
|
@@ -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
|
+
|