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/blocking.py
ADDED
|
@@ -0,0 +1,1622 @@
|
|
|
1
|
+
"""Declaring a block, which every other write refuses to do for you (RK141).
|
|
2
|
+
|
|
3
|
+
Measured in Claude Code Tray, shipping the first task of a new block. `ship T179` refused —
|
|
4
|
+
*"no heading declares Block AE: a heading invented by a write files the text where nothing
|
|
5
|
+
looks for it"* — and wrote nothing, which is right: naming a block is editorial, and a
|
|
6
|
+
heading the tool guesses is a heading nobody looks under. The remedy is one line in the
|
|
7
|
+
changelog, and the guard denies that `Edit`, listing every verb that may write there —
|
|
8
|
+
`ship`, `record add`, `record drop`, `retire` — none of which adds a heading.
|
|
9
|
+
|
|
10
|
+
Both refusals are right alone and the pair is a deadlock, so neither is weakened. This is the
|
|
11
|
+
missing key: a verb that declares a block and takes the title as the argument it is, symmetric
|
|
12
|
+
with `non-goal` (RK70), which already writes the roadmap's other non-task line.
|
|
13
|
+
|
|
14
|
+
What the author gives is the **label and the title**, which is the whole editorial content.
|
|
15
|
+
Everything else is derived, and derived **per file** rather than decided here:
|
|
16
|
+
|
|
17
|
+
* **Which files.** Every governed file that is *already organised by blocks*, because a
|
|
18
|
+
heading is only wanted where something looks for one — the roadmap for `add`, the ledger
|
|
19
|
+
for `ship`, the rationale file for `section add`. A file that declares no block at all is
|
|
20
|
+
not one this verb starts organising; it is named in the answer and left alone.
|
|
21
|
+
* **Where.** After the last block's subtree, which is what opening a *new* block means and
|
|
22
|
+
which is also the only placement that cannot land inside another's work. Never at the end
|
|
23
|
+
of the file: the roadmap's `## Non-goals` follows the blocks, and appending would file the
|
|
24
|
+
first task of the new block under it. **Or after a block the author names** (RK145), because
|
|
25
|
+
appended is *a* placement and it was the only one: block order is not decoration — `list`
|
|
26
|
+
reports blocks in the headings' own order, `brief --block <x>` is scoped by it, and a reader
|
|
27
|
+
takes the sequence for the shape of the plan, so a phase belonging between two existing ones
|
|
28
|
+
had no route but reordering three files by hand. `--after <label>` names a **neighbour**
|
|
29
|
+
rather than a position, which is what lets one argument stay honest across files that
|
|
30
|
+
order blocks differently: each file places the heading after the end of *its* `<label>`
|
|
31
|
+
subtree, and a file declaring no such label is a refusal rather than a guess.
|
|
32
|
+
* **How it is spelled.** The level and the separator are read off the file's own first block
|
|
33
|
+
heading, so a project writing `## Block A — The model` gets one more of those and one
|
|
34
|
+
writing `### Fase 2 - Execução` gets one more of those. The word is `[headings] word`
|
|
35
|
+
already (RK75), and the label shape is the one a dep resolves against (RK28).
|
|
36
|
+
|
|
37
|
+
All of the files or none of them. A block declared in the roadmap and not the ledger is a
|
|
38
|
+
project where `add` works and `ship` fails on the same label, which is the deadlock again
|
|
39
|
+
with one more step in it.
|
|
40
|
+
|
|
41
|
+
**And the key that could not close the door** (RK144). This verb was the only one that writes a
|
|
42
|
+
heading, and nothing took one back out — so a label typed wrongly, or a block whose every line
|
|
43
|
+
has left, was three headings only the edit the guard denies could remove: RK138's asymmetry one
|
|
44
|
+
surface over. :func:`drop_block` is the inverse, and it is narrow in the one way that matters:
|
|
45
|
+
**a heading over work is not an empty heading.** It removes a heading only where its whole
|
|
46
|
+
subtree is blank, and where anything is filed under the label it refuses by name — the
|
|
47
|
+
roadmap's open lines, the store's paused ones, the rationale file's sections — because
|
|
48
|
+
deleting the heading would orphan every one of them.
|
|
49
|
+
|
|
50
|
+
The **ledger is the exception, and not an inconsistency**: history is filed under its headings
|
|
51
|
+
for ever, so entries there are never something to refuse over and never something to remove.
|
|
52
|
+
That file is left alone and said so, which is also what keeps the removal from re-opening the
|
|
53
|
+
deadlock — the only asymmetry it can leave is a ledger declaring a label the roadmap does not,
|
|
54
|
+
where nothing plans and history still reads. The reverse, which would make `add` work and
|
|
55
|
+
`ship` fail, is exactly what refusing over open lines prevents.
|
|
56
|
+
|
|
57
|
+
**And the question all four of them assume has been answered** (RK1188). `add --block <x>` is
|
|
58
|
+
the first flag on the first write of any new task, and until :func:`catalogue` nothing said
|
|
59
|
+
what `<x>` could be: `stats` prints letters and counts and never a title, `list --block` and
|
|
60
|
+
`delivered <block>` both demand the letter as an argument and refuse one nothing declares, so
|
|
61
|
+
neither can discover it. The author read `docs/ROADMAP.md` with grep — the file the hook exists
|
|
62
|
+
to keep hands off, and the habit every other refusal here is spent unteaching.
|
|
63
|
+
|
|
64
|
+
A read under this noun rather than a column on `stats`, for the reason `non-goal list` is not
|
|
65
|
+
a column on anything: that verb is a report *about a file*, and this is the question asked
|
|
66
|
+
before writing *to* one. What it answers with is the label, the title as the file spells it,
|
|
67
|
+
and what became of the block — from the same reader `list` and `brief` answer an empty count
|
|
68
|
+
with, so the two cannot come to disagree about a block being finished.
|
|
69
|
+
"""
|
|
70
|
+
|
|
71
|
+
from __future__ import annotations
|
|
72
|
+
|
|
73
|
+
from collections.abc import Callable, Mapping, Sequence
|
|
74
|
+
from dataclasses import dataclass, field
|
|
75
|
+
from pathlib import Path
|
|
76
|
+
|
|
77
|
+
from roadkeep.authoring import _after_preamble, remove_entry
|
|
78
|
+
from roadkeep.backlog import Backlog, Standing as Became
|
|
79
|
+
from roadkeep.config import Config
|
|
80
|
+
from roadkeep.criteria import without as criteria_without
|
|
81
|
+
from roadkeep.kernel.document import (
|
|
82
|
+
Document,
|
|
83
|
+
Heading,
|
|
84
|
+
RepeatedHeading,
|
|
85
|
+
blank,
|
|
86
|
+
save_all,
|
|
87
|
+
)
|
|
88
|
+
from roadkeep.kernel.schema import Schema
|
|
89
|
+
from roadkeep.provenance import invocation
|
|
90
|
+
|
|
91
|
+
__all__ = [
|
|
92
|
+
"BlockExists",
|
|
93
|
+
"BlockOccupied",
|
|
94
|
+
"Catalogue",
|
|
95
|
+
"Closed",
|
|
96
|
+
"Declared",
|
|
97
|
+
"Merged",
|
|
98
|
+
"NoSuchBlock",
|
|
99
|
+
"NoSuchNeighbour",
|
|
100
|
+
"NotALabel",
|
|
101
|
+
"NotOrganisable",
|
|
102
|
+
"NotRepeated",
|
|
103
|
+
|
|
104
|
+
"NothingToDrop",
|
|
105
|
+
"Opened",
|
|
106
|
+
"RegionOccupied",
|
|
107
|
+
"catalogue",
|
|
108
|
+
"drop_block",
|
|
109
|
+
"merge_block",
|
|
110
|
+
"open_block",
|
|
111
|
+
]
|
|
112
|
+
|
|
113
|
+
#: The governed files a block heading can belong in, in the order the answer reports them.
|
|
114
|
+
#: A role is only written when its file already declares one — see the module docstring.
|
|
115
|
+
BLOCK_ROLES = (
|
|
116
|
+
"roadmap",
|
|
117
|
+
"changelog",
|
|
118
|
+
"deferred",
|
|
119
|
+
"improvements",
|
|
120
|
+
"strategy",
|
|
121
|
+
"decisions",
|
|
122
|
+
)
|
|
123
|
+
|
|
124
|
+
#: What separates the label from the title where a file declares no separator of its own.
|
|
125
|
+
#: Only reachable when the first block heading is the label alone, which no corpus writes.
|
|
126
|
+
DEFAULT_SEPARATOR = " \N{EM DASH} "
|
|
127
|
+
|
|
128
|
+
|
|
129
|
+
class NotALabel(ValueError):
|
|
130
|
+
"""A label the format cannot read, refused before anything is written.
|
|
131
|
+
|
|
132
|
+
The same shape a dep resolves against (RK28): a heading declaring something else would
|
|
133
|
+
make `pick --block <x>` an answer about a block nothing declares, and the disagreement
|
|
134
|
+
would be invisible because both halves parse.
|
|
135
|
+
"""
|
|
136
|
+
|
|
137
|
+
def __init__(self, label: str, pattern: str) -> None:
|
|
138
|
+
self.label = label
|
|
139
|
+
super().__init__(
|
|
140
|
+
f"{label!r} is not a label this project can read ({pattern}): a heading "
|
|
141
|
+
f"declares exactly one, and a dep resolves against that same list"
|
|
142
|
+
)
|
|
143
|
+
|
|
144
|
+
|
|
145
|
+
class NoSuchNeighbour(KeyError):
|
|
146
|
+
"""A `--after` label a file that wants the new heading does not declare (RK145).
|
|
147
|
+
|
|
148
|
+
Refused rather than fallen back on, and that is the whole of the decision: appending in
|
|
149
|
+
the one file that cannot resolve the neighbour would order that file by a rule the others
|
|
150
|
+
did not use, which is a disagreement about the plan's shape that both halves round-trip.
|
|
151
|
+
The labels the file *does* declare are named, because the commonest cause is a neighbour
|
|
152
|
+
that exists in the roadmap and not yet in the file being written beside it.
|
|
153
|
+
"""
|
|
154
|
+
|
|
155
|
+
def __init__(
|
|
156
|
+
self,
|
|
157
|
+
after: str,
|
|
158
|
+
label: str,
|
|
159
|
+
where: str,
|
|
160
|
+
declared: Sequence[str],
|
|
161
|
+
word: str = "Block",
|
|
162
|
+
) -> None:
|
|
163
|
+
self.after = after
|
|
164
|
+
self.label = label
|
|
165
|
+
self.where = where
|
|
166
|
+
self.declared = tuple(declared)
|
|
167
|
+
known = ", ".join(self.declared) or "none"
|
|
168
|
+
super().__init__(
|
|
169
|
+
f"{where} declares no {word} {after} to open {word} {label} after (declares: "
|
|
170
|
+
f"{known}): --after names a neighbour, and a file that cannot find it would be "
|
|
171
|
+
f"the one file ordered by a different rule"
|
|
172
|
+
)
|
|
173
|
+
|
|
174
|
+
|
|
175
|
+
class NotOrganisable(ValueError):
|
|
176
|
+
"""An `--organise` this project cannot honour, refused before anything is written (RK405).
|
|
177
|
+
|
|
178
|
+
Two ways to be that, and the sentence says which. A role the project does not declare, or
|
|
179
|
+
whose file is not on disk, is nothing this verb can write into at all — and the roles it
|
|
180
|
+
*can* are named, because the commonest cause is the role's own spelling.
|
|
181
|
+
|
|
182
|
+
The other is subtler and is the rule this argument does not weaken: with **no** governed
|
|
183
|
+
file declaring a block, there is no level and no separator to read, and a heading composed
|
|
184
|
+
out of this module's own punctuation would write a second convention into a project that
|
|
185
|
+
has one (see :func:`_heading`). That project is one `init` scaffolds, not one this verb
|
|
186
|
+
guesses the shape of.
|
|
187
|
+
"""
|
|
188
|
+
|
|
189
|
+
def __init__(self, role: str, roles: Sequence[str], *, spelling: bool = False) -> None:
|
|
190
|
+
self.role = role
|
|
191
|
+
self.roles = tuple(roles)
|
|
192
|
+
if spelling:
|
|
193
|
+
super().__init__(
|
|
194
|
+
f"--organise {role}: no file this project declares carries a block heading "
|
|
195
|
+
f"to read the level and the separator off, so the first one is not this "
|
|
196
|
+
f"verb's to compose — `init` scaffolds a project that has none"
|
|
197
|
+
)
|
|
198
|
+
return
|
|
199
|
+
known = ", ".join(self.roles) or "none"
|
|
200
|
+
super().__init__(
|
|
201
|
+
f"--organise {role}: this project declares no such file on disk (it declares: "
|
|
202
|
+
f"{known}) — the argument names a role, which is how [files] names one"
|
|
203
|
+
)
|
|
204
|
+
|
|
205
|
+
|
|
206
|
+
class BlockExists(ValueError):
|
|
207
|
+
"""A label every file that files work under blocks already declares.
|
|
208
|
+
|
|
209
|
+
Reported as a refusal rather than a silent success, because a caller reaching for this
|
|
210
|
+
verb believes the block is missing — and a command that exits 0 having written nothing
|
|
211
|
+
teaches that it wrote something.
|
|
212
|
+
|
|
213
|
+
**And the files that lack it are named, with the flag that reaches them** (RK1223).
|
|
214
|
+
Reopening a shipped block is ordinary: a follow-up is filed under the block it belongs to,
|
|
215
|
+
and that block's heading survives only in the ledger, because `drop_block` leaves history
|
|
216
|
+
the heading it was filed under. So `block add J --title "…"` is the obvious move, and on a
|
|
217
|
+
roadmap whose own blocks have all been withdrawn it answered *`J is already declared in
|
|
218
|
+
docs/CHANGELOG.md: nothing to open`* — true of the changelog, false of the request, and
|
|
219
|
+
reading as *you are done here* about the one file the new line was about to go into.
|
|
220
|
+
|
|
221
|
+
The reason was already computed and thrown away: this verb skips a file that declares no
|
|
222
|
+
block at all, and records why — `--organise <role> writes the first one`. That row went
|
|
223
|
+
into :attr:`Opened.skipped` on the success path and nowhere on this one, so the caller
|
|
224
|
+
learned it from the *next* command's refusal instead, which is a second failure to reach a
|
|
225
|
+
door this verb owns.
|
|
226
|
+
|
|
227
|
+
Named rather than opened, which is RK405's rule and is not weakened here: whether a file is
|
|
228
|
+
to be organised by blocks is a statement only the author can make, and a heading composed
|
|
229
|
+
into a file that has none would be this tool inventing a convention (see
|
|
230
|
+
:func:`open_block`). What changes is that the statement is *asked for* here rather than
|
|
231
|
+
somewhere else.
|
|
232
|
+
"""
|
|
233
|
+
|
|
234
|
+
def __init__(
|
|
235
|
+
self, label: str, where: Sequence[str], lacking: Sequence[tuple[str, str]] = ()
|
|
236
|
+
) -> None:
|
|
237
|
+
self.label = label
|
|
238
|
+
self.where = tuple(where)
|
|
239
|
+
#: `(file, role)` per governed file that would take the heading and declares no block.
|
|
240
|
+
self.lacking = tuple(lacking)
|
|
241
|
+
said = f"{label} is already declared in {', '.join(self.where)}"
|
|
242
|
+
if not self.lacking:
|
|
243
|
+
super().__init__(f"{said}: nothing to open")
|
|
244
|
+
return
|
|
245
|
+
files = ", ".join(one for one, _ in self.lacking)
|
|
246
|
+
flags = " ".join(f"--organise {role}" for _, role in self.lacking)
|
|
247
|
+
super().__init__(
|
|
248
|
+
f"{said}, and {files} declares no block at all: that file is where the work "
|
|
249
|
+
f"goes, so this is a heading to open rather than nothing — "
|
|
250
|
+
f"`{invocation()} block add {label} --title \"<its title>\" {flags}`"
|
|
251
|
+
)
|
|
252
|
+
|
|
253
|
+
|
|
254
|
+
class NoSuchBlock(KeyError):
|
|
255
|
+
"""A label no governed file declares, at the door that removes a declaration (RK144).
|
|
256
|
+
|
|
257
|
+
Distinct from :class:`~roadkeep.kernel.document.UnknownBlock`, which every *write* raises and
|
|
258
|
+
whose sentence is about a heading a write may not invent. Here nothing was going to be
|
|
259
|
+
written, and what the caller needs is the list — a label that is merely spelled
|
|
260
|
+
differently from the file's is the commonest reason this door is reached at all.
|
|
261
|
+
"""
|
|
262
|
+
|
|
263
|
+
def __init__(
|
|
264
|
+
self,
|
|
265
|
+
label: str,
|
|
266
|
+
declared: Sequence[str],
|
|
267
|
+
word: str = "Block",
|
|
268
|
+
*,
|
|
269
|
+
doing: str = "remove",
|
|
270
|
+
) -> None:
|
|
271
|
+
self.label = label
|
|
272
|
+
self.declared = tuple(declared)
|
|
273
|
+
known = ", ".join(self.declared) or "none"
|
|
274
|
+
super().__init__(
|
|
275
|
+
f"no governed file declares {word} {label} (declares: {known}): there is no "
|
|
276
|
+
f"heading to {doing}"
|
|
277
|
+
)
|
|
278
|
+
|
|
279
|
+
|
|
280
|
+
class BlockOccupied(ValueError):
|
|
281
|
+
"""A heading with something filed under it, which is not an empty heading (RK144).
|
|
282
|
+
|
|
283
|
+
The whole safety of the door, and the reason it is worth having at all: removing this
|
|
284
|
+
heading would leave every line beneath it filed under the block above, silently and in a
|
|
285
|
+
way that round-trips. So the occupants are **named** rather than counted — an author who
|
|
286
|
+
typed the wrong label needs to see immediately that they are looking at somebody else's
|
|
287
|
+
work, and a count cannot show that.
|
|
288
|
+
|
|
289
|
+
Never raised for the ledger: entries there are history filed under a heading that stays
|
|
290
|
+
for ever, so that file is skipped and reported instead.
|
|
291
|
+
|
|
292
|
+
``prose`` says everything held is a **note**, and then the refusal names the flag that
|
|
293
|
+
takes it (RK237): a door whose existence the author learns from the refusal is the shape
|
|
294
|
+
RK93 argued for, and until it existed this message was the whole exit from the corner.
|
|
295
|
+
"""
|
|
296
|
+
|
|
297
|
+
def __init__(
|
|
298
|
+
self,
|
|
299
|
+
label: str,
|
|
300
|
+
where: str,
|
|
301
|
+
named: Sequence[str],
|
|
302
|
+
word: str = "Block",
|
|
303
|
+
*,
|
|
304
|
+
prose: bool = False,
|
|
305
|
+
) -> None:
|
|
306
|
+
self.label = label
|
|
307
|
+
self.where = where
|
|
308
|
+
self.named = tuple(named)
|
|
309
|
+
holds = ", ".join(self.named)
|
|
310
|
+
if prose:
|
|
311
|
+
super().__init__(
|
|
312
|
+
f"{where} files {holds} under {word} {label}, which is loose prose and not "
|
|
313
|
+
f"work: pass --prose to take the note with the heading, or keep both"
|
|
314
|
+
)
|
|
315
|
+
return
|
|
316
|
+
super().__init__(
|
|
317
|
+
f"{where} files {holds} under {word} {label}: a heading over work is not an "
|
|
318
|
+
f"empty heading, and removing it would file all of it under the block above"
|
|
319
|
+
)
|
|
320
|
+
|
|
321
|
+
|
|
322
|
+
class NothingToDrop(ValueError):
|
|
323
|
+
"""A label the ledger declares and no other file does (RK144).
|
|
324
|
+
|
|
325
|
+
The terminal shape of the ledger exception: its heading holds history and stays for ever,
|
|
326
|
+
so there is nothing this verb may remove — and nothing it is right to refuse over either.
|
|
327
|
+
A refusal all the same, because the alternative is exit 0 over an untouched tree.
|
|
328
|
+
"""
|
|
329
|
+
|
|
330
|
+
def __init__(self, label: str, where: Sequence[str], word: str = "Block") -> None:
|
|
331
|
+
self.label = label
|
|
332
|
+
self.where = tuple(where)
|
|
333
|
+
super().__init__(
|
|
334
|
+
f"{word} {label} is declared only in {', '.join(self.where)}, whose heading "
|
|
335
|
+
f"holds the history filed under it: there is nothing to remove"
|
|
336
|
+
)
|
|
337
|
+
|
|
338
|
+
|
|
339
|
+
class NotRepeated(ValueError):
|
|
340
|
+
"""A label no file declares more than once — there is nothing to consolidate (RK403).
|
|
341
|
+
|
|
342
|
+
The door `merge` exists to close is a **doubled** heading, so a label that is declared
|
|
343
|
+
once (or not at all) is refused rather than exited 0 over, for the reason
|
|
344
|
+
:class:`BlockExists` is: a command that writes nothing and reports success teaches that
|
|
345
|
+
it wrote something. The linenos it does declare are named, because the commonest cause
|
|
346
|
+
is a label spelled differently from the file's — the same help :class:`NoSuchBlock` gives.
|
|
347
|
+
"""
|
|
348
|
+
|
|
349
|
+
def __init__(self, label: str, where: Sequence[str], word: str = "Block") -> None:
|
|
350
|
+
self.label = label
|
|
351
|
+
self.where = tuple(where)
|
|
352
|
+
listed = ", ".join(self.where) if self.where else "no governed file"
|
|
353
|
+
super().__init__(
|
|
354
|
+
f"{word} {label} is declared once, in {listed}: one heading is not two, and "
|
|
355
|
+
f"there is nothing to merge"
|
|
356
|
+
)
|
|
357
|
+
|
|
358
|
+
|
|
359
|
+
class RegionOccupied(ValueError):
|
|
360
|
+
"""A duplicate heading standing over something a mechanical fold may not move (RK403).
|
|
361
|
+
|
|
362
|
+
`merge` relocates **entries** — a task line or a ledger entry is keyed by its id and
|
|
363
|
+
filed under a label, so moving it under the surviving heading of the same label changes
|
|
364
|
+
no field and round-trips by construction (L3, L4). Two kinds are not that, and each is
|
|
365
|
+
refused by name rather than folded:
|
|
366
|
+
|
|
367
|
+
* A **nested heading** — a rationale section, a sub-block — is a subtree whose placement
|
|
368
|
+
is editorial, and `section move` is its door. Folding it would guess an order the tool
|
|
369
|
+
has no opinion about (L4), which is the same reason :func:`open_block` refuses to invent
|
|
370
|
+
a heading at all.
|
|
371
|
+
* **Loose prose** is carried only under ``--prose``, the flag :class:`BlockOccupied`
|
|
372
|
+
already names (RK237): a paragraph under one of two duplicate headings is a note the
|
|
373
|
+
merge drops, and dropping it silently is the misfiling RK144 refused over.
|
|
374
|
+
|
|
375
|
+
Named and not counted, for :class:`BlockOccupied`'s reason: an author who reached this
|
|
376
|
+
door needs to see *what* is in the way, not how much.
|
|
377
|
+
"""
|
|
378
|
+
|
|
379
|
+
def __init__(
|
|
380
|
+
self,
|
|
381
|
+
label: str,
|
|
382
|
+
where: str,
|
|
383
|
+
named: Sequence[str],
|
|
384
|
+
word: str = "Block",
|
|
385
|
+
*,
|
|
386
|
+
nested: bool,
|
|
387
|
+
) -> None:
|
|
388
|
+
self.label = label
|
|
389
|
+
self.where = where
|
|
390
|
+
self.named = tuple(named)
|
|
391
|
+
holds = ", ".join(self.named)
|
|
392
|
+
if nested:
|
|
393
|
+
super().__init__(
|
|
394
|
+
f"{where} nests {holds} under a second {word} {label}: a section is not an "
|
|
395
|
+
f"entry, and `section move` places it — `merge` folds entries alone"
|
|
396
|
+
)
|
|
397
|
+
return
|
|
398
|
+
super().__init__(
|
|
399
|
+
f"{where} files loose prose ({holds}) under a second {word} {label}: pass "
|
|
400
|
+
f"--prose to drop the note as the duplicate heading is folded, or move it first"
|
|
401
|
+
)
|
|
402
|
+
|
|
403
|
+
|
|
404
|
+
@dataclass(frozen=True, slots=True)
|
|
405
|
+
class Retitled:
|
|
406
|
+
"""The words one block's heading is given, in every file that declares it (RK1204).
|
|
407
|
+
|
|
408
|
+
A fourth shape and not :class:`Opened` with a flag, for the reason :class:`Closed` is not
|
|
409
|
+
that either: what this one has to carry is the heading **as it read** beside the heading it
|
|
410
|
+
now reads, because the whole answer is a title changing and a reader has to see both. The
|
|
411
|
+
label is on neither side of that pair — it is the identity, and a verb that could move it
|
|
412
|
+
would be `merge` and `add` at once.
|
|
413
|
+
"""
|
|
414
|
+
|
|
415
|
+
label: str
|
|
416
|
+
title: str
|
|
417
|
+
#: The files this write changes, by role. Written together or not at all.
|
|
418
|
+
documents: Mapping[str, Document] = field(default_factory=dict)
|
|
419
|
+
#: Where the heading is, by role — 1-based, as an editor counts. Unmoved by this write,
|
|
420
|
+
#: which is the point: the subtree is untouched and so is the placement.
|
|
421
|
+
placed: Mapping[str, int] = field(default_factory=dict)
|
|
422
|
+
#: The heading each file held before this write, by role, verbatim.
|
|
423
|
+
was: Mapping[str, str] = field(default_factory=dict)
|
|
424
|
+
#: The heading each file holds after it. Two files can differ in level and in separator,
|
|
425
|
+
#: and each keeps its own: nobody asked for a restyle, and re-rendering from the project's
|
|
426
|
+
#: convention would take a file's own spacing as the silent price of a retitle (RK388).
|
|
427
|
+
rendered: Mapping[str, str] = field(default_factory=dict)
|
|
428
|
+
#: Roles left alone, each with the reason — a file that declares the label with this title
|
|
429
|
+
#: already above all, which is neither a refusal nor a write.
|
|
430
|
+
skipped: tuple[tuple[str, str], ...] = ()
|
|
431
|
+
|
|
432
|
+
def save(self) -> tuple[Path, ...]:
|
|
433
|
+
"""Write every file, having asked all of them first (RK116, RK6)."""
|
|
434
|
+
return save_all(*self.documents.values())
|
|
435
|
+
|
|
436
|
+
def stated(self, config: Config, wrote: Sequence[Path]) -> str:
|
|
437
|
+
"""Both readings of the heading, and every file that took the new one (RK1204).
|
|
438
|
+
|
|
439
|
+
Through the same row producer its three siblings use, so the four block verbs answer
|
|
440
|
+
in one table shape and none of them pads to a column of its own.
|
|
441
|
+
"""
|
|
442
|
+
from roadkeep.rendering import _staging_rows # noqa: PLC0415 - RK260
|
|
443
|
+
|
|
444
|
+
rows = [
|
|
445
|
+
f"{config.schema.block_named(self.label)} retitled: {self.title}",
|
|
446
|
+
*_role_rows(
|
|
447
|
+
config,
|
|
448
|
+
self.documents,
|
|
449
|
+
# Two rows per file, and the second is a left-aligned `was` rather than a
|
|
450
|
+
# column under the first: `restate` prints both readings of a claim that way,
|
|
451
|
+
# and a heading is long enough that an indented pair wraps in a terminal.
|
|
452
|
+
lambda role, where: [
|
|
453
|
+
f" {where}:{self.placed[role]} {self.rendered[role]}",
|
|
454
|
+
f" was {self.was[role]}",
|
|
455
|
+
],
|
|
456
|
+
),
|
|
457
|
+
*(f" not {where}: {reason}" for where, reason in self.skipped),
|
|
458
|
+
# Said out loud, because it is the whole argument for the verb being narrow: a
|
|
459
|
+
# retitle that moved work would be a merge nobody asked for.
|
|
460
|
+
" kept the label, the placement and everything filed under it",
|
|
461
|
+
]
|
|
462
|
+
rows += _staging_rows(config.relative(one) for one in wrote)
|
|
463
|
+
return "\n".join(rows)
|
|
464
|
+
|
|
465
|
+
def payload(self, config: Config, wrote: Sequence[Path]) -> dict[str, object]:
|
|
466
|
+
"""The same answer as data, with both readings of every heading it rewrote."""
|
|
467
|
+
from roadkeep.rendering import _wrote_json # noqa: PLC0415 - RK260
|
|
468
|
+
|
|
469
|
+
return {
|
|
470
|
+
"label": self.label,
|
|
471
|
+
"title": self.title,
|
|
472
|
+
"written": [
|
|
473
|
+
{
|
|
474
|
+
"role": role,
|
|
475
|
+
"file": config.relative(config.path(role)),
|
|
476
|
+
"line": self.placed[role],
|
|
477
|
+
# Both readings, which is what makes the write reviewable: a payload with
|
|
478
|
+
# only the new heading says a title is right and not that one changed.
|
|
479
|
+
"was": self.was[role],
|
|
480
|
+
"rendered": self.rendered[role],
|
|
481
|
+
}
|
|
482
|
+
for role in self.documents
|
|
483
|
+
],
|
|
484
|
+
"skipped": [
|
|
485
|
+
{"file": where, "reason": reason} for where, reason in self.skipped
|
|
486
|
+
],
|
|
487
|
+
**_wrote_json(config, wrote),
|
|
488
|
+
}
|
|
489
|
+
|
|
490
|
+
|
|
491
|
+
def amend_block(config: Config, label: str, title: str) -> Retitled:
|
|
492
|
+
"""Give one block's heading new words, in every governed file that declares it (RK1204).
|
|
493
|
+
|
|
494
|
+
The door the other three left shut. `add` takes a title, `drop` removes a heading and
|
|
495
|
+
`merge` folds a duplicate; none of them changes the words of a heading that exists, and
|
|
496
|
+
`section amend --title` — the verb that does exactly this one file over — had no block
|
|
497
|
+
counterpart. So a title was write-once, and the only repair was `drop` plus `add`, which
|
|
498
|
+
:class:`BlockOccupied` refuses the moment anything is filed under the label. The window
|
|
499
|
+
closed on the first `add`, and after it the hand edit the guard denies was the whole exit.
|
|
500
|
+
|
|
501
|
+
Measured in Turing: the ledger's `Analytics & observability gaps` was reopened through a
|
|
502
|
+
layer that escaped the ampersand, and the roadmap took `Analytics & observability
|
|
503
|
+
gaps`. One heading, two spellings, and the skill's own rule is that they stay identical.
|
|
504
|
+
|
|
505
|
+
**Narrow, and every part of that is deliberate.** The label is the identity and does not
|
|
506
|
+
move — `merge` is the verb for a label, and a retitle that could change one would be two
|
|
507
|
+
acts wearing one name. The subtree is not touched: this rewrites a heading line and
|
|
508
|
+
nothing beneath it, which is why it is safe over work where `drop` is rightly not. Each
|
|
509
|
+
file keeps its **own** level and separator, read off the heading being rewritten rather
|
|
510
|
+
than off the project's first block, because nobody asked for a restyle and RK388 settled
|
|
511
|
+
that a body-only edit leaves the bytes it was not asked about alone.
|
|
512
|
+
|
|
513
|
+
All of the files or none of them, as its three siblings write: a title corrected in the
|
|
514
|
+
roadmap and left standing in the ledger is the exact two-spellings defect this closes.
|
|
515
|
+
|
|
516
|
+
A file already holding this title is skipped and said so, and a label where **every** file
|
|
517
|
+
holds it writes nothing: rewriting the same bytes makes a no-op look like an edit to every
|
|
518
|
+
hook watching the file, which is the rule the doors in `authoring` keep.
|
|
519
|
+
"""
|
|
520
|
+
schema = config.schema
|
|
521
|
+
if not schema.block_dep_pattern().match(schema.block_named(label)):
|
|
522
|
+
raise NotALabel(label, schema.block_dep_pattern().pattern)
|
|
523
|
+
if not title.strip():
|
|
524
|
+
raise NotALabel(label, "a block is named by its title, and this one is blank")
|
|
525
|
+
|
|
526
|
+
wanted = title.strip()
|
|
527
|
+
changed: dict[str, Document] = {}
|
|
528
|
+
placed: dict[str, int] = {}
|
|
529
|
+
was: dict[str, str] = {}
|
|
530
|
+
rendered: dict[str, str] = {}
|
|
531
|
+
skipped: list[tuple[str, str]] = []
|
|
532
|
+
declared: list[str] = []
|
|
533
|
+
|
|
534
|
+
for role, (where, document, blocks) in _readable(config).items():
|
|
535
|
+
holding = [one for one in blocks if one.label == label]
|
|
536
|
+
if not holding:
|
|
537
|
+
continue
|
|
538
|
+
declared.append(where)
|
|
539
|
+
if len(holding) > 1:
|
|
540
|
+
# Two headings under one label is `merge`'s state, and picking one to rewrite
|
|
541
|
+
# would leave the other saying the old thing — which is this defect again, inside
|
|
542
|
+
# one file. The refusal names the verb that resolves it (RK391, RK403).
|
|
543
|
+
raise RepeatedHeading(
|
|
544
|
+
label,
|
|
545
|
+
[one.lineno for one in holding],
|
|
546
|
+
where,
|
|
547
|
+
word=schema.heading_word,
|
|
548
|
+
)
|
|
549
|
+
(heading,) = holding
|
|
550
|
+
raw = _heading((heading,), schema.block_named(label), wanted)
|
|
551
|
+
before = document.lines[heading.lineno - 1].rstrip("\r\n")
|
|
552
|
+
if before == raw:
|
|
553
|
+
skipped.append((where, "already reads that"))
|
|
554
|
+
continue
|
|
555
|
+
changed[role] = document.replace_line(heading.lineno - 1, raw)
|
|
556
|
+
was[role] = before
|
|
557
|
+
rendered[role] = raw
|
|
558
|
+
placed[role] = heading.lineno
|
|
559
|
+
|
|
560
|
+
if not declared:
|
|
561
|
+
raise NoSuchBlock(label, _labels(config), word=schema.heading_word, doing="retitle")
|
|
562
|
+
if not changed:
|
|
563
|
+
# Every file already reads that, which is success and not a write. A refusal here
|
|
564
|
+
# would be a rule against running the same correction twice.
|
|
565
|
+
return Retitled(label=label, title=wanted, skipped=tuple(skipped))
|
|
566
|
+
return Retitled(
|
|
567
|
+
label=label,
|
|
568
|
+
title=wanted,
|
|
569
|
+
documents=changed,
|
|
570
|
+
placed=placed,
|
|
571
|
+
was=was,
|
|
572
|
+
rendered=rendered,
|
|
573
|
+
skipped=tuple(skipped),
|
|
574
|
+
)
|
|
575
|
+
|
|
576
|
+
|
|
577
|
+
@dataclass(frozen=True, slots=True)
|
|
578
|
+
class Merged:
|
|
579
|
+
"""What consolidating one label's duplicate headings changes, before it is written (RK403).
|
|
580
|
+
|
|
581
|
+
The inverse shape of neither :class:`Opened` nor :class:`Closed`: a merge keeps a heading
|
|
582
|
+
**and** removes one or more, and moves the entries the removed ones stood over into the
|
|
583
|
+
one that stays. So it carries the surviving heading's line, every folded heading's line
|
|
584
|
+
verbatim — the file will not hold them to read afterwards — and the ids that moved, per
|
|
585
|
+
role, because the whole answer is *what went where*.
|
|
586
|
+
"""
|
|
587
|
+
|
|
588
|
+
label: str
|
|
589
|
+
#: The files this write changes, by role. Written together or not at all.
|
|
590
|
+
documents: Mapping[str, Document] = field(default_factory=dict)
|
|
591
|
+
#: Where the surviving heading is, by role — 1-based, as an editor counts.
|
|
592
|
+
kept: Mapping[str, int] = field(default_factory=dict)
|
|
593
|
+
#: The folded headings, verbatim and by role: the answer's only record of the titles this
|
|
594
|
+
#: removed, since the file no longer holds them.
|
|
595
|
+
folded: Mapping[str, tuple[str, ...]] = field(default_factory=dict)
|
|
596
|
+
#: The ids relocated into the surviving region, by role and in the order they moved.
|
|
597
|
+
moved: Mapping[str, tuple[str, ...]] = field(default_factory=dict)
|
|
598
|
+
#: Lines of loose prose dropped with a folded heading, by role (RK237). Absent where a
|
|
599
|
+
#: heading stood over entries alone, so the report tells "folded" from "folded the note too".
|
|
600
|
+
notes: Mapping[str, int] = field(default_factory=dict)
|
|
601
|
+
|
|
602
|
+
def save(self) -> tuple[Path, ...]:
|
|
603
|
+
"""Write every file, having asked all of them first (RK116, RK6)."""
|
|
604
|
+
return save_all(*self.documents.values())
|
|
605
|
+
|
|
606
|
+
def stated(self, config: Config, wrote: Sequence[Path]) -> str:
|
|
607
|
+
"""What went where, per file (RK403).
|
|
608
|
+
|
|
609
|
+
Beside :meth:`payload` since RK1170, through the same row producer its two siblings use.
|
|
610
|
+
"""
|
|
611
|
+
from roadkeep.rendering import _staging_rows # noqa: PLC0415 - RK260
|
|
612
|
+
|
|
613
|
+
rows = [
|
|
614
|
+
f"{config.schema.block_named(self.label)} consolidated",
|
|
615
|
+
*_role_rows(config, self.documents, self._rows),
|
|
616
|
+
]
|
|
617
|
+
rows += _staging_rows(config.relative(one) for one in wrote)
|
|
618
|
+
return "\n".join(rows)
|
|
619
|
+
|
|
620
|
+
def _rows(self, role: str, where: str) -> list[str]:
|
|
621
|
+
moved = ", ".join(self.moved[role]) or "nothing"
|
|
622
|
+
rows = [
|
|
623
|
+
f" {where}:{self.kept[role]} "
|
|
624
|
+
f"folded {len(self.folded[role])}, moved {moved}"
|
|
625
|
+
]
|
|
626
|
+
if role in self.notes:
|
|
627
|
+
rows.append(f" note {self.notes[role]} line(s) of prose dropped with a heading")
|
|
628
|
+
return rows
|
|
629
|
+
|
|
630
|
+
def payload(self, config: Config, wrote: Sequence[Path]) -> dict[str, object]:
|
|
631
|
+
"""The same answer as data, carrying the headings no file holds any more."""
|
|
632
|
+
from roadkeep.rendering import _wrote_json # noqa: PLC0415 - RK260
|
|
633
|
+
|
|
634
|
+
return {
|
|
635
|
+
"label": self.label,
|
|
636
|
+
"merged": [
|
|
637
|
+
{
|
|
638
|
+
"role": role,
|
|
639
|
+
"file": config.relative(config.path(role)),
|
|
640
|
+
# Where the surviving heading is, the ids that moved under it, and the
|
|
641
|
+
# headings folded — verbatim, since the file no longer holds them and this
|
|
642
|
+
# answer is their only record.
|
|
643
|
+
"kept": self.kept[role],
|
|
644
|
+
"moved": list(self.moved[role]),
|
|
645
|
+
"folded": list(self.folded[role]),
|
|
646
|
+
# Null where a folded heading stood over entries alone (RK237).
|
|
647
|
+
"note": self.notes.get(role),
|
|
648
|
+
}
|
|
649
|
+
for role in self.documents
|
|
650
|
+
],
|
|
651
|
+
**_wrote_json(config, wrote),
|
|
652
|
+
}
|
|
653
|
+
|
|
654
|
+
|
|
655
|
+
@dataclass(frozen=True, slots=True)
|
|
656
|
+
class Closed:
|
|
657
|
+
"""The heading one block's removal takes out of every file, before it is written.
|
|
658
|
+
|
|
659
|
+
The inverse shape of :class:`Opened` and deliberately not that class with a flag: what
|
|
660
|
+
this one has to carry is the heading **as it read**, because after the write there is no
|
|
661
|
+
file left to read it off — and what it does not carry is a title, which is the one thing
|
|
662
|
+
a removal has no opinion about.
|
|
663
|
+
"""
|
|
664
|
+
|
|
665
|
+
label: str
|
|
666
|
+
#: The files this write changes, by role. Written together or not at all.
|
|
667
|
+
documents: Mapping[str, Document] = field(default_factory=dict)
|
|
668
|
+
#: Where the heading was, by role — 1-based, as an editor counts.
|
|
669
|
+
removed: Mapping[str, int] = field(default_factory=dict)
|
|
670
|
+
#: The heading each file held, by role, verbatim: the answer's only record of the title
|
|
671
|
+
#: this took out, since the file it was read from no longer holds it.
|
|
672
|
+
rendered: Mapping[str, str] = field(default_factory=dict)
|
|
673
|
+
#: How many lines of loose prose went with the heading, by role (RK237). Absent where the
|
|
674
|
+
#: heading stood over nothing, so the report can tell "removed" from "removed the note
|
|
675
|
+
#: too" — which is the one thing `--prose` did that the author has to be able to see.
|
|
676
|
+
notes: Mapping[str, int] = field(default_factory=dict)
|
|
677
|
+
#: Roles left alone, each with the reason — the ledger's entries above all, which are
|
|
678
|
+
#: neither a refusal nor a removal and would otherwise be an unexplained silence.
|
|
679
|
+
skipped: tuple[tuple[str, str], ...] = ()
|
|
680
|
+
#: The leads of the block's own criteria, which left with the label (RK1316). Named for
|
|
681
|
+
#: `Departure.unmet`'s reason one address over: a definition of done that disappeared with
|
|
682
|
+
#: no line about it is a deletion nobody reviewing the diff was told to look for.
|
|
683
|
+
unmet: tuple[str, ...] = ()
|
|
684
|
+
|
|
685
|
+
def save(self) -> tuple[Path, ...]:
|
|
686
|
+
"""Write every file, having asked all of them first (RK116, RK6)."""
|
|
687
|
+
return save_all(*self.documents.values())
|
|
688
|
+
|
|
689
|
+
def stated(self, config: Config, wrote: Sequence[Path]) -> str:
|
|
690
|
+
"""The heading as it read, and the files it came out of (RK144, RK237).
|
|
691
|
+
|
|
692
|
+
Beside :meth:`payload` since RK1170, through the same row producer its two siblings use.
|
|
693
|
+
"""
|
|
694
|
+
from roadkeep.rendering import _staging_rows # noqa: PLC0415 - RK260
|
|
695
|
+
|
|
696
|
+
from roadkeep.rendering import _unmet_rows # noqa: PLC0415 - RK260
|
|
697
|
+
|
|
698
|
+
rows = [
|
|
699
|
+
f"{config.schema.block_named(self.label)} withdrawn",
|
|
700
|
+
*_role_rows(config, self.documents, self._rows),
|
|
701
|
+
*(f" kept {where}: {reason}" for where, reason in self.skipped),
|
|
702
|
+
# The same sentence a departure prints for a task's list (RK1268, RK1316), with
|
|
703
|
+
# the address this write spends: a definition of done that went with no line
|
|
704
|
+
# about it is the deletion that task was filed against, one address up.
|
|
705
|
+
*_unmet_rows(self.unmet, "the label"),
|
|
706
|
+
]
|
|
707
|
+
rows += _staging_rows(config.relative(one) for one in wrote)
|
|
708
|
+
return "\n".join(rows)
|
|
709
|
+
|
|
710
|
+
def _rows(self, role: str, where: str) -> list[str]:
|
|
711
|
+
rows = [f" {where}:{self.removed[role]} {self.rendered[role]}"]
|
|
712
|
+
if role in self.notes:
|
|
713
|
+
# Said, because this is the one line of the removal that took prose with it and
|
|
714
|
+
# the file no longer holds it to be compared against (RK237).
|
|
715
|
+
rows.append(
|
|
716
|
+
f" note {self.notes[role]} line(s) of prose taken with the heading"
|
|
717
|
+
)
|
|
718
|
+
return rows
|
|
719
|
+
|
|
720
|
+
def payload(self, config: Config, wrote: Sequence[Path]) -> dict[str, object]:
|
|
721
|
+
"""The same answer as data, carrying the heading no file holds any more."""
|
|
722
|
+
from roadkeep.rendering import _wrote_json # noqa: PLC0415 - RK260
|
|
723
|
+
|
|
724
|
+
return {
|
|
725
|
+
"label": self.label,
|
|
726
|
+
"removed": [
|
|
727
|
+
{
|
|
728
|
+
"role": role,
|
|
729
|
+
"file": config.relative(config.path(role)),
|
|
730
|
+
# The line it was on and the heading it was, because after this write no
|
|
731
|
+
# file holds either and the answer is the only record.
|
|
732
|
+
"line": self.removed[role],
|
|
733
|
+
"rendered": self.rendered[role],
|
|
734
|
+
# Null where the heading stood over nothing, so a caller reads "the note
|
|
735
|
+
# went too" off a field rather than off a count (RK237).
|
|
736
|
+
"note": self.notes.get(role),
|
|
737
|
+
}
|
|
738
|
+
for role in self.documents
|
|
739
|
+
],
|
|
740
|
+
"skipped": [
|
|
741
|
+
{"file": where, "reason": reason} for where, reason in self.skipped
|
|
742
|
+
],
|
|
743
|
+
# The block's own criteria, which left with the label (RK1316). `[]` and never
|
|
744
|
+
# omitted, as a departure's is: a plan that quietly got shorter is a change with
|
|
745
|
+
# no sentence about it.
|
|
746
|
+
"unmet": list(self.unmet),
|
|
747
|
+
**_wrote_json(config, wrote),
|
|
748
|
+
}
|
|
749
|
+
|
|
750
|
+
|
|
751
|
+
def drop_block(config: Config, label: str, *, prose: bool = False) -> Closed:
|
|
752
|
+
"""Remove one block's heading from every governed file where it stands over nothing.
|
|
753
|
+
|
|
754
|
+
Validates everything before touching anything, as :func:`open_block` does: a label no
|
|
755
|
+
file declares, and a heading with work under it, are refusals that leave the whole tree
|
|
756
|
+
exactly as it was — including the files whose heading *was* removable, because a partial
|
|
757
|
+
removal is the split declaration RK141's last paragraph is about.
|
|
758
|
+
|
|
759
|
+
The ledger is skipped rather than refused over (see the module docstring): its headings
|
|
760
|
+
hold history for ever, so entries under one are not an obstacle to clear.
|
|
761
|
+
|
|
762
|
+
``prose`` takes the heading's **loose prose** with it (RK237), and it is the door a corner
|
|
763
|
+
had none of. An adopted roadmap carries a blockquote under each block heading — what the
|
|
764
|
+
block is, often a "fully shipped, see the changelog" paragraph — because that is what a
|
|
765
|
+
hand-written backlog looks like; Turing's had ten, four of them over blocks with no open
|
|
766
|
+
line left. RK144 is right to count that prose, but no verb wrote or removed a note, so the
|
|
767
|
+
only exits were an `Edit` the guard denies and a `Bash` write RK175 then reports as
|
|
768
|
+
unattested. The block that most needs withdrawing is exactly the one whose note says so.
|
|
769
|
+
|
|
770
|
+
**Opt-in, and never over work.** A task line or a nested heading under the label is
|
|
771
|
+
somebody's, and no flag makes a removal the right verb for it — so the refusal stands
|
|
772
|
+
whenever :attr:`Standing.work` is non-empty, and it names the flag only when prose is all
|
|
773
|
+
that is left. Nothing here reads what the note *says*: "loose prose under a heading" is
|
|
774
|
+
what the document model already resolves, and a tool with an opinion about the paragraph
|
|
775
|
+
would be writing prose (L4).
|
|
776
|
+
"""
|
|
777
|
+
word = config.schema.heading_word
|
|
778
|
+
declaring = _declaring(config, label)
|
|
779
|
+
if not declaring:
|
|
780
|
+
raise NoSuchBlock(label, _labels(config), word=word)
|
|
781
|
+
|
|
782
|
+
changed: dict[str, Document] = {}
|
|
783
|
+
removed: dict[str, int] = {}
|
|
784
|
+
rendered: dict[str, str] = {}
|
|
785
|
+
notes: dict[str, int] = {}
|
|
786
|
+
skipped: list[tuple[str, str]] = []
|
|
787
|
+
|
|
788
|
+
for role, where, document, heading in declaring:
|
|
789
|
+
held = _held(document, heading)
|
|
790
|
+
takeable = bool(held) and not held.work and prose
|
|
791
|
+
if not held or takeable:
|
|
792
|
+
rendered[role] = document.lines[heading.lineno - 1].rstrip("\r\n")
|
|
793
|
+
removed[role] = heading.lineno
|
|
794
|
+
changed[role] = _excise(document, heading)
|
|
795
|
+
if takeable:
|
|
796
|
+
notes[role] = len(held.prose)
|
|
797
|
+
continue
|
|
798
|
+
if role != "changelog":
|
|
799
|
+
raise BlockOccupied(
|
|
800
|
+
label, where, held.names, word=word, prose=not held.work
|
|
801
|
+
)
|
|
802
|
+
skipped.append((where, _kept(held)))
|
|
803
|
+
|
|
804
|
+
if not changed:
|
|
805
|
+
# Every file declaring it kept it, which can only be the ledger. A refusal rather
|
|
806
|
+
# than an exit 0, for the reason `BlockExists` is one: a command that writes nothing
|
|
807
|
+
# and reports success teaches that it wrote something.
|
|
808
|
+
raise NothingToDrop(label, [where for _, where, _, _ in declaring], word=word)
|
|
809
|
+
# And the list that asked what would finish it (RK1316), inside the same transaction —
|
|
810
|
+
# which is RK1268's rule at the block's own address. RK1265 is right that a block's list
|
|
811
|
+
# outlives its *lines*: an emptied block is a question somebody answered, and RK1300 prints
|
|
812
|
+
# it at the ship that finishes one. Neither is about the **label** leaving. Observed on a
|
|
813
|
+
# fresh tree, 2026-08-23: after `block drop A` the heading was gone from the roadmap and
|
|
814
|
+
# the improvements file, and `## Done when — Block A` stood behind it — reported by
|
|
815
|
+
# `criterion list` under a label `block list` does not carry, and refused by `criterion add
|
|
816
|
+
# --block A` with `no block 'A'`, so what was left had no door but `criterion drop`.
|
|
817
|
+
if "roadmap" in changed:
|
|
818
|
+
without_list, unmet = criteria_without(changed["roadmap"], label)
|
|
819
|
+
changed["roadmap"] = without_list
|
|
820
|
+
else:
|
|
821
|
+
unmet = ()
|
|
822
|
+
return Closed(
|
|
823
|
+
label=label,
|
|
824
|
+
documents=changed,
|
|
825
|
+
removed=removed,
|
|
826
|
+
rendered=rendered,
|
|
827
|
+
notes=notes,
|
|
828
|
+
skipped=tuple(skipped),
|
|
829
|
+
unmet=unmet,
|
|
830
|
+
)
|
|
831
|
+
|
|
832
|
+
|
|
833
|
+
def _kept(held: Standing) -> str:
|
|
834
|
+
"""Why the ledger's heading stayed, saying what it actually holds.
|
|
835
|
+
|
|
836
|
+
Counted by kind (RK237): "3 entries filed under it" about three lines of prose is a reason
|
|
837
|
+
that names the wrong thing, and the ledger is the one role where the answer is never a
|
|
838
|
+
refusal the author can read the difference off.
|
|
839
|
+
"""
|
|
840
|
+
if held.ids:
|
|
841
|
+
plural = "entry" if len(held.ids) == 1 else "entries"
|
|
842
|
+
return (
|
|
843
|
+
f"{len(held.ids)} {plural} filed under it: history keeps the heading it "
|
|
844
|
+
f"was filed under"
|
|
845
|
+
)
|
|
846
|
+
kind = "prose" if held.prose else "heading(s)"
|
|
847
|
+
return f"{len(held.names)} line(s) of {kind} under it: the ledger's heading is not moved"
|
|
848
|
+
|
|
849
|
+
|
|
850
|
+
def _readable(config: Config) -> dict[str, tuple[str, Document, tuple[Heading, ...]]]:
|
|
851
|
+
"""Every governed file a block heading can belong in that is on disk, in report order.
|
|
852
|
+
|
|
853
|
+
Read once and in one place because :func:`open_block` now asks two questions of the set
|
|
854
|
+
rather than one (RK405): *which files want the heading* and *how does this project spell
|
|
855
|
+
one* — and the second is answered by a file the first may skip.
|
|
856
|
+
"""
|
|
857
|
+
found: dict[str, tuple[str, Document, tuple[Heading, ...]]] = {}
|
|
858
|
+
for role in BLOCK_ROLES:
|
|
859
|
+
if not config.has(role) or not config.path(role).is_file():
|
|
860
|
+
continue
|
|
861
|
+
document = config.document(role)
|
|
862
|
+
found[role] = (
|
|
863
|
+
config.relative(config.path(role)),
|
|
864
|
+
document,
|
|
865
|
+
tuple(h for h in document.headings if h.label),
|
|
866
|
+
)
|
|
867
|
+
return found
|
|
868
|
+
|
|
869
|
+
|
|
870
|
+
def removable(document: Document, label: str) -> Heading | None:
|
|
871
|
+
"""The heading :func:`drop_block` would take out of this file for ``label``, or None.
|
|
872
|
+
|
|
873
|
+
One expression, read by the verb that removes and by the gate that reports a label two
|
|
874
|
+
headings declare (RK391, RK417): a finding naming a command that then refuses is worse
|
|
875
|
+
than one naming none, and the only thing that keeps those two level is asking the same
|
|
876
|
+
function rather than each spelling the rule.
|
|
877
|
+
|
|
878
|
+
**The empty one, wherever in the file it is**, which is what makes a duplicate repairable
|
|
879
|
+
at all. Reading the first heading alone was right while a label had one; on a file that
|
|
880
|
+
declares it twice it would refuse over an occupied first while an empty one sat below —
|
|
881
|
+
measured on a real corpus, where the removable heading happened to come first and the
|
|
882
|
+
reverse order would have had no exit at all. A heading over work is still never removed:
|
|
883
|
+
that rule is per *heading* here, which is how it was always written.
|
|
884
|
+
|
|
885
|
+
Prose is not empty. `--prose` is a decision the caller makes at the door, and a reader
|
|
886
|
+
asking whether a heading is removable without it must not be told yes.
|
|
887
|
+
"""
|
|
888
|
+
return next((h for h in document.declaring(label) if not _held(document, h)), None)
|
|
889
|
+
|
|
890
|
+
|
|
891
|
+
def _declaring(
|
|
892
|
+
config: Config, label: str
|
|
893
|
+
) -> tuple[tuple[str, str, Document, Heading], ...]:
|
|
894
|
+
"""Every governed file that declares this label, with the heading that does it."""
|
|
895
|
+
found: list[tuple[str, str, Document, Heading]] = []
|
|
896
|
+
for role in BLOCK_ROLES:
|
|
897
|
+
if not config.has(role) or not config.path(role).is_file():
|
|
898
|
+
continue
|
|
899
|
+
document = config.document(role)
|
|
900
|
+
declared = document.declaring(label)
|
|
901
|
+
if declared:
|
|
902
|
+
# The removable one where there is one, and otherwise the first — which is then
|
|
903
|
+
# the heading the refusal is rightly about (RK417).
|
|
904
|
+
heading = removable(document, label) or declared[0]
|
|
905
|
+
found.append((role, config.relative(config.path(role)), document, heading))
|
|
906
|
+
return tuple(found)
|
|
907
|
+
|
|
908
|
+
|
|
909
|
+
@dataclass(frozen=True, slots=True)
|
|
910
|
+
class Standing:
|
|
911
|
+
"""What one heading stands over, by kind (RK237).
|
|
912
|
+
|
|
913
|
+
The three kinds were always read; what they were not was told apart. A count of names is
|
|
914
|
+
all a refusal needs, and it is not enough for the *door*: prose is the one kind a removal
|
|
915
|
+
can honestly take with the heading, because the block above it is where it silently lands
|
|
916
|
+
otherwise — while a task line or a rationale section under this label is work, and moving
|
|
917
|
+
that is not a removal's business.
|
|
918
|
+
"""
|
|
919
|
+
|
|
920
|
+
#: Task lines or ledger entries, by id.
|
|
921
|
+
ids: tuple[str, ...] = ()
|
|
922
|
+
#: Nested headings, by their text — a rationale section, or a sub-block.
|
|
923
|
+
headings: tuple[str, ...] = ()
|
|
924
|
+
#: Loose prose, by line number: the only address a paragraph has.
|
|
925
|
+
prose: tuple[int, ...] = ()
|
|
926
|
+
|
|
927
|
+
def __bool__(self) -> bool:
|
|
928
|
+
return bool(self.ids or self.headings or self.prose)
|
|
929
|
+
|
|
930
|
+
@property
|
|
931
|
+
def names(self) -> tuple[str, ...]:
|
|
932
|
+
"""Everything, named as a reader has to see it — the order a refusal reports."""
|
|
933
|
+
return (
|
|
934
|
+
*self.ids,
|
|
935
|
+
*(f"{text!r}" for text in self.headings),
|
|
936
|
+
*(f"line {lineno}" for lineno in self.prose),
|
|
937
|
+
)
|
|
938
|
+
|
|
939
|
+
@property
|
|
940
|
+
def work(self) -> tuple[str, ...]:
|
|
941
|
+
"""What no flag may take: the kinds that are somebody's, rather than the heading's."""
|
|
942
|
+
return (*self.ids, *(f"{text!r}" for text in self.headings))
|
|
943
|
+
|
|
944
|
+
|
|
945
|
+
def _held(document: Document, heading: Heading) -> Standing:
|
|
946
|
+
"""What this heading stands over — empty when nothing.
|
|
947
|
+
|
|
948
|
+
Anything non-blank counts: a paragraph left behind by a removed heading is filed under the
|
|
949
|
+
block above it, which is the same silent misfiling as an orphaned task line (RK144).
|
|
950
|
+
"""
|
|
951
|
+
start, end = heading.lineno, document.subtree_end(heading)
|
|
952
|
+
ids: list[str] = []
|
|
953
|
+
nested: list[str] = []
|
|
954
|
+
loose: list[int] = []
|
|
955
|
+
seen: set[int] = set()
|
|
956
|
+
for entry in document.entries:
|
|
957
|
+
if start < entry.lineno <= end:
|
|
958
|
+
ids.append(entry.task.id)
|
|
959
|
+
seen.add(entry.lineno)
|
|
960
|
+
for below in document.headings:
|
|
961
|
+
if start < below.lineno <= end:
|
|
962
|
+
nested.append(below.text)
|
|
963
|
+
seen.add(below.lineno)
|
|
964
|
+
for offset in range(start, end):
|
|
965
|
+
if offset + 1 not in seen and not blank(document.lines[offset]):
|
|
966
|
+
loose.append(offset + 1)
|
|
967
|
+
return Standing(ids=tuple(ids), headings=tuple(nested), prose=tuple(loose))
|
|
968
|
+
|
|
969
|
+
|
|
970
|
+
def _labels(config: Config) -> tuple[str, ...]:
|
|
971
|
+
"""Every label any governed file declares, in file order and without repeats."""
|
|
972
|
+
found: list[str] = []
|
|
973
|
+
for role in BLOCK_ROLES:
|
|
974
|
+
if not config.has(role) or not config.path(role).is_file():
|
|
975
|
+
continue
|
|
976
|
+
for heading in config.document(role).headings:
|
|
977
|
+
if heading.label and heading.label not in found:
|
|
978
|
+
found.append(heading.label)
|
|
979
|
+
return tuple(found)
|
|
980
|
+
|
|
981
|
+
|
|
982
|
+
@dataclass(frozen=True, slots=True)
|
|
983
|
+
class Declared:
|
|
984
|
+
"""One block, as the question before an `add` needs it answered (RK1188)."""
|
|
985
|
+
|
|
986
|
+
label: str
|
|
987
|
+
#: `Block C`, or whatever `[headings] word` spells — the same rendering every refusal
|
|
988
|
+
#: about a label uses, so a project writing `Fase` never reads `Block` back.
|
|
989
|
+
named: str
|
|
990
|
+
#: The words after the label, **read** off the heading and never composed here. The
|
|
991
|
+
#: first file that declares it wins, which is the roadmap wherever the roadmap has it:
|
|
992
|
+
#: two files may legitimately title one block differently (this repository's do), and a
|
|
993
|
+
#: verb that reported both would be answering a question about drift instead of place.
|
|
994
|
+
title: str
|
|
995
|
+
#: What became of it — :class:`roadkeep.backlog.Standing`, so this row and the sentence
|
|
996
|
+
#: `list --block` prints over an empty count are one read and cannot disagree.
|
|
997
|
+
became: Became
|
|
998
|
+
#: The roles declaring it, in :data:`BLOCK_ROLES` order. Roles and not paths, because
|
|
999
|
+
#: :attr:`plannable` is a question about *which* file and a path cannot be asked it.
|
|
1000
|
+
roles: tuple[str, ...] = ()
|
|
1001
|
+
|
|
1002
|
+
@property
|
|
1003
|
+
def plannable(self) -> bool:
|
|
1004
|
+
"""Whether an `add --block` could land here — which is the roadmap's heading alone.
|
|
1005
|
+
|
|
1006
|
+
A block whose last line shipped keeps its ledger heading and may have lost the
|
|
1007
|
+
roadmap's, and that row is the one whose absence turns an `add` into
|
|
1008
|
+
:class:`~roadkeep.kernel.document.UnknownBlock`. Reported rather than filtered out:
|
|
1009
|
+
the label exists, and hiding it would answer "no such block" to a caller who can see
|
|
1010
|
+
the heading in the changelog.
|
|
1011
|
+
"""
|
|
1012
|
+
return "roadmap" in self.roles
|
|
1013
|
+
|
|
1014
|
+
|
|
1015
|
+
@dataclass(frozen=True, slots=True)
|
|
1016
|
+
class Catalogue:
|
|
1017
|
+
"""Where a task may go, in the order the files declare it (RK1188).
|
|
1018
|
+
|
|
1019
|
+
Order is content here, for the reason `--after` exists (RK145): `list` reports blocks in
|
|
1020
|
+
the headings' own order and a reader takes the sequence for the shape of the plan, so a
|
|
1021
|
+
catalogue sorted alphabetically would be a second opinion about that shape.
|
|
1022
|
+
"""
|
|
1023
|
+
|
|
1024
|
+
blocks: tuple[Declared, ...] = ()
|
|
1025
|
+
|
|
1026
|
+
def __bool__(self) -> bool:
|
|
1027
|
+
return bool(self.blocks)
|
|
1028
|
+
|
|
1029
|
+
def stated(self, config: Config) -> str:
|
|
1030
|
+
"""The rows, and the labels an `add` would still refuse (RK1188)."""
|
|
1031
|
+
where = config.relative(config.path("roadmap"))
|
|
1032
|
+
if not self.blocks:
|
|
1033
|
+
return (
|
|
1034
|
+
f"{where}: no block is declared — `block add <label> --title …` writes the "
|
|
1035
|
+
f"first heading, and every other write refuses until one exists"
|
|
1036
|
+
)
|
|
1037
|
+
pad = max(len(one.named) for one in self.blocks)
|
|
1038
|
+
titles = max(len(one.title) for one in self.blocks)
|
|
1039
|
+
rows = [f"{len(self.blocks)} block(s), in file order"]
|
|
1040
|
+
rows += [
|
|
1041
|
+
f" {one.named:<{pad}} {one.title:<{titles}} "
|
|
1042
|
+
f"{one.became.open:>4} open {one.became.stage}".rstrip()
|
|
1043
|
+
for one in self.blocks
|
|
1044
|
+
]
|
|
1045
|
+
elsewhere = [one.label for one in self.blocks if not one.plannable]
|
|
1046
|
+
if elsewhere:
|
|
1047
|
+
# The one row an author has to act on before typing `add --block`, said once
|
|
1048
|
+
# rather than as a column that is empty on every other line.
|
|
1049
|
+
rows.append(
|
|
1050
|
+
f" not in {where}: {', '.join(elsewhere)} — `block add <label> --title …` "
|
|
1051
|
+
f"re-declares the heading a task can be filed under"
|
|
1052
|
+
)
|
|
1053
|
+
return "\n".join(rows)
|
|
1054
|
+
|
|
1055
|
+
def payload(self, config: Config) -> dict[str, object]:
|
|
1056
|
+
"""The same answer as data, with every file each label is declared in."""
|
|
1057
|
+
return {
|
|
1058
|
+
"file": config.relative(config.path("roadmap")),
|
|
1059
|
+
"blocks": [
|
|
1060
|
+
{
|
|
1061
|
+
# The state and its counts first and whole, because they are one record
|
|
1062
|
+
# (RK1170): a payload that spelled `block` a second time here would be the
|
|
1063
|
+
# two-readers defect this row exists to keep out of `stats`.
|
|
1064
|
+
**one.became.payload(),
|
|
1065
|
+
"named": one.named,
|
|
1066
|
+
"title": one.title,
|
|
1067
|
+
# Whether `add --block` resolves, which is the roadmap's heading and not
|
|
1068
|
+
# the label existing — the distinction the ledger's own headings create.
|
|
1069
|
+
"plannable": one.plannable,
|
|
1070
|
+
"declared_in": [
|
|
1071
|
+
config.relative(config.path(role)) for role in one.roles
|
|
1072
|
+
],
|
|
1073
|
+
}
|
|
1074
|
+
for one in self.blocks
|
|
1075
|
+
],
|
|
1076
|
+
}
|
|
1077
|
+
|
|
1078
|
+
|
|
1079
|
+
def catalogue(config: Config) -> Catalogue:
|
|
1080
|
+
"""Every block this project declares, titled and counted (RK1188).
|
|
1081
|
+
|
|
1082
|
+
Read-only, and reading is never refused: a project with no block at all answers with the
|
|
1083
|
+
empty catalogue and the command that opens the first heading, because the caller who most
|
|
1084
|
+
needs this verb is the one who has nothing to grep for.
|
|
1085
|
+
|
|
1086
|
+
The walk is :func:`_labels`', so the order and the membership are the ones the three
|
|
1087
|
+
writes in this module already resolve against, and the counts are
|
|
1088
|
+
:meth:`roadkeep.backlog.Backlog.standing`'s — one read of the roadmap, the ledger and the
|
|
1089
|
+
store, which is what keeps this from being a fourth opinion about a finished block.
|
|
1090
|
+
"""
|
|
1091
|
+
backlog = Backlog.load(config)
|
|
1092
|
+
readable = _readable(config)
|
|
1093
|
+
schema = config.schema
|
|
1094
|
+
found: list[Declared] = []
|
|
1095
|
+
for label in _labels(config):
|
|
1096
|
+
roles = tuple(
|
|
1097
|
+
role for role, (_, _, blocks) in readable.items()
|
|
1098
|
+
if any(one.label == label for one in blocks)
|
|
1099
|
+
)
|
|
1100
|
+
heading = next(
|
|
1101
|
+
one
|
|
1102
|
+
for role in roles
|
|
1103
|
+
for one in readable[role][2]
|
|
1104
|
+
if one.label == label
|
|
1105
|
+
)
|
|
1106
|
+
found.append(
|
|
1107
|
+
Declared(
|
|
1108
|
+
label=label,
|
|
1109
|
+
named=schema.block_named(label),
|
|
1110
|
+
title=_title(heading),
|
|
1111
|
+
became=backlog.standing(label),
|
|
1112
|
+
roles=roles,
|
|
1113
|
+
)
|
|
1114
|
+
)
|
|
1115
|
+
return Catalogue(blocks=tuple(found))
|
|
1116
|
+
|
|
1117
|
+
|
|
1118
|
+
def _title(heading: Heading) -> str:
|
|
1119
|
+
"""The words this heading gives its block, with the separator it spelled them after.
|
|
1120
|
+
|
|
1121
|
+
The inverse of :func:`_heading`, and it reads the same two facts that one writes: what
|
|
1122
|
+
follows the label, minus whatever :func:`_separator` says this file puts between them. A
|
|
1123
|
+
heading that is the label alone has no title, and the empty string is that answer — not
|
|
1124
|
+
an invention this module would then have to keep out of `amend`.
|
|
1125
|
+
"""
|
|
1126
|
+
tail = heading.text[_label_end(heading.text) :]
|
|
1127
|
+
separator = _separator(heading)
|
|
1128
|
+
if tail.startswith(separator):
|
|
1129
|
+
return tail[len(separator) :].strip()
|
|
1130
|
+
return tail.strip()
|
|
1131
|
+
|
|
1132
|
+
|
|
1133
|
+
def _excise(document: Document, heading: Heading) -> Document:
|
|
1134
|
+
"""Take the heading out, with the blanks it owned — the inverse of :func:`_insert`.
|
|
1135
|
+
|
|
1136
|
+
The whole subtree in one edit, which by the time this is reached is the heading, blank
|
|
1137
|
+
lines, and — under `--prose` — the note (RK237): the deletion is refused above where it is
|
|
1138
|
+
anything a task or a section owns. The trailing blank goes
|
|
1139
|
+
with it, and where the block was last in the file the *leading* one does too — a
|
|
1140
|
+
paragraph break the file never had is still a change, and both spellings round-trip,
|
|
1141
|
+
which is exactly why nothing downstream would catch it (RK54).
|
|
1142
|
+
"""
|
|
1143
|
+
start = heading.lineno - 1
|
|
1144
|
+
updated = document.remove_lines(start, document.subtree_end(heading))
|
|
1145
|
+
if start >= len(updated.lines) and start > 0 and blank(updated.lines[start - 1]):
|
|
1146
|
+
return updated.remove_line(start - 1)
|
|
1147
|
+
return updated
|
|
1148
|
+
|
|
1149
|
+
|
|
1150
|
+
@dataclass(frozen=True, slots=True)
|
|
1151
|
+
class Opened:
|
|
1152
|
+
"""The heading one block costs, in every file that wanted it, before it is written."""
|
|
1153
|
+
|
|
1154
|
+
label: str
|
|
1155
|
+
title: str
|
|
1156
|
+
#: The block this one was opened after, where the author named one (RK145). None is the
|
|
1157
|
+
#: derived answer — the last block — and it is reported as such rather than resolved to a
|
|
1158
|
+
#: label, because "appended" and "after the last one" are the same placement said twice.
|
|
1159
|
+
after: str | None = None
|
|
1160
|
+
#: The files this write changes, by role. Written together or not at all.
|
|
1161
|
+
documents: Mapping[str, Document] = field(default_factory=dict)
|
|
1162
|
+
#: Where the heading landed, by role — 1-based, as an editor counts.
|
|
1163
|
+
placed: Mapping[str, int] = field(default_factory=dict)
|
|
1164
|
+
#: The heading as each file spells it, by role. Two files can differ in level and in
|
|
1165
|
+
#: separator, because each is read off its own first block heading.
|
|
1166
|
+
rendered: Mapping[str, str] = field(default_factory=dict)
|
|
1167
|
+
#: Roles left alone, each with the reason. A file skipped in silence is one the author
|
|
1168
|
+
#: discovers was skipped by the next command that refuses on it.
|
|
1169
|
+
skipped: tuple[tuple[str, str], ...] = ()
|
|
1170
|
+
|
|
1171
|
+
def save(self) -> tuple[Path, ...]:
|
|
1172
|
+
"""Write every file, having asked all of them first (RK116, RK6)."""
|
|
1173
|
+
return save_all(*self.documents.values())
|
|
1174
|
+
|
|
1175
|
+
def stated(self, config: Config, wrote: Sequence[Path]) -> str:
|
|
1176
|
+
"""The heading, and every file that took it (RK145).
|
|
1177
|
+
|
|
1178
|
+
Beside :meth:`payload` since RK1170. The three block verbs answer in one table shape —
|
|
1179
|
+
role, file, line — and :func:`_role_rows` is where that column width is decided once.
|
|
1180
|
+
"""
|
|
1181
|
+
from roadkeep.rendering import _staging_rows # noqa: PLC0415 - RK260
|
|
1182
|
+
|
|
1183
|
+
beside = f" (after {config.schema.block_named(self.after)})" if self.after else ""
|
|
1184
|
+
rows = [
|
|
1185
|
+
f"{config.schema.block_named(self.label)} declared{beside}: {self.title}",
|
|
1186
|
+
*_role_rows(
|
|
1187
|
+
config,
|
|
1188
|
+
self.documents,
|
|
1189
|
+
lambda role, where: [
|
|
1190
|
+
f" {where}:{self.placed[role]} {self.rendered[role]}"
|
|
1191
|
+
],
|
|
1192
|
+
),
|
|
1193
|
+
*(f" not {where}: {reason}" for where, reason in self.skipped),
|
|
1194
|
+
]
|
|
1195
|
+
rows += _staging_rows(config.relative(one) for one in wrote)
|
|
1196
|
+
return "\n".join(rows)
|
|
1197
|
+
|
|
1198
|
+
def payload(self, config: Config, wrote: Sequence[Path]) -> dict[str, object]:
|
|
1199
|
+
"""The same answer as data, with the files this write left alone."""
|
|
1200
|
+
from roadkeep.rendering import _wrote_json # noqa: PLC0415 - RK260
|
|
1201
|
+
|
|
1202
|
+
return {
|
|
1203
|
+
"label": self.label,
|
|
1204
|
+
"title": self.title,
|
|
1205
|
+
# The neighbour as it was asked for, null where it was derived: "after the last
|
|
1206
|
+
# block" and "appended" are the same placement said twice.
|
|
1207
|
+
"after": self.after,
|
|
1208
|
+
"written": [
|
|
1209
|
+
{
|
|
1210
|
+
"role": role,
|
|
1211
|
+
"file": config.relative(config.path(role)),
|
|
1212
|
+
"line": self.placed[role],
|
|
1213
|
+
"rendered": self.rendered[role],
|
|
1214
|
+
}
|
|
1215
|
+
for role in self.documents
|
|
1216
|
+
],
|
|
1217
|
+
# Named, never silent: a file skipped in silence is one the author discovers was
|
|
1218
|
+
# skipped by the next command that refuses on it.
|
|
1219
|
+
"skipped": [
|
|
1220
|
+
{"file": where, "reason": reason} for where, reason in self.skipped
|
|
1221
|
+
],
|
|
1222
|
+
**_wrote_json(config, wrote),
|
|
1223
|
+
}
|
|
1224
|
+
|
|
1225
|
+
|
|
1226
|
+
def _role_rows(
|
|
1227
|
+
config: Config,
|
|
1228
|
+
documents: Mapping[str, Document],
|
|
1229
|
+
rows: Callable[[str, str], list[str]],
|
|
1230
|
+
) -> list[str]:
|
|
1231
|
+
"""Every role's rows, with the paths padded to one column (RK1170).
|
|
1232
|
+
|
|
1233
|
+
The shape all three block verbs answer in, and the reason this is a function rather than
|
|
1234
|
+
three loops: the width is a property of *the set of files*, so a verb computing it beside
|
|
1235
|
+
its own loop is a verb that can quietly pad to a different column than its siblings.
|
|
1236
|
+
|
|
1237
|
+
The callback is handed the role and its already-padded path, and answers with that role's
|
|
1238
|
+
rows — one for the heading and, where the write took prose with it, a second (RK237).
|
|
1239
|
+
"""
|
|
1240
|
+
files = {role: config.relative(config.path(role)) for role in documents}
|
|
1241
|
+
width = max((len(one) for one in files.values()), default=0)
|
|
1242
|
+
return [row for role in documents for row in rows(role, f"{files[role]:<{width}}")]
|
|
1243
|
+
|
|
1244
|
+
|
|
1245
|
+
def open_block(
|
|
1246
|
+
config: Config,
|
|
1247
|
+
label: str,
|
|
1248
|
+
title: str,
|
|
1249
|
+
*,
|
|
1250
|
+
after: str | None = None,
|
|
1251
|
+
organise: Sequence[str] = (),
|
|
1252
|
+
) -> Opened:
|
|
1253
|
+
"""Declare one block in every governed file already organised by blocks.
|
|
1254
|
+
|
|
1255
|
+
Validates everything before touching anything: an unreadable label, an empty title, a
|
|
1256
|
+
label every candidate file already declares, and a neighbour a file that wants the
|
|
1257
|
+
heading does not declare are all refusals that leave the tree exactly as it was.
|
|
1258
|
+
|
|
1259
|
+
``after`` is the neighbour, not an index (RK145): each file places the heading at the end
|
|
1260
|
+
of *its own* `<label>` subtree, so the argument stays honest where two files order their
|
|
1261
|
+
blocks differently. Omitted, the neighbour is the last block, which is what opening a new
|
|
1262
|
+
one means and what every call before this argument existed got.
|
|
1263
|
+
|
|
1264
|
+
``organise`` names the roles this verb may write the **first** block heading into (RK405),
|
|
1265
|
+
and it is the key to the one deadlock the rest of this module left. Measured on a project
|
|
1266
|
+
whose `CHANGELOG.md` was prose: `ship` refused, naming this verb; this verb skipped that
|
|
1267
|
+
file, because a file declaring no block is not one it starts organising; and `block add`
|
|
1268
|
+
on a label nothing declares anywhere skipped it too — so no argument to any command put a
|
|
1269
|
+
heading there, and the guard denies the `Edit`. Plan freely, ship never.
|
|
1270
|
+
|
|
1271
|
+
The rule being defended is real and is not weakened: the level, the separator and the
|
|
1272
|
+
placement are the file's own, and a file with no blocks holds none of them. What this
|
|
1273
|
+
argument supplies is the missing **statement** — *this file is to be organised by blocks*
|
|
1274
|
+
— which is the author's to make and never the tool's to infer, exactly as the title is.
|
|
1275
|
+
Given it, the spelling is derived from a file that does declare one, because the project's
|
|
1276
|
+
convention is a project fact and a second punctuation invented here would be the thing
|
|
1277
|
+
:func:`_heading` exists to avoid; and the placement is the end of the file, which is the
|
|
1278
|
+
only honest answer where there is no block subtree to follow and no `--after` to resolve.
|
|
1279
|
+
|
|
1280
|
+
Refused where the role is not declared, where its file is absent, and where **no** file
|
|
1281
|
+
declares a block to read the spelling off — that last one being `init`'s job and not a
|
|
1282
|
+
heading this verb may compose out of nothing. A role that already declares blocks is
|
|
1283
|
+
written the ordinary way and the argument is simply spent: it says what is already true.
|
|
1284
|
+
"""
|
|
1285
|
+
schema = config.schema
|
|
1286
|
+
# The dep's pattern rather than the heading's, because that one is anchored at both
|
|
1287
|
+
# ends: a heading stops at the first space, so "a label with spaces" declares `a` and
|
|
1288
|
+
# the title would silently absorb the rest.
|
|
1289
|
+
if not schema.block_dep_pattern().match(schema.block_named(label)):
|
|
1290
|
+
raise NotALabel(label, schema.block_dep_pattern().pattern)
|
|
1291
|
+
if not title.strip():
|
|
1292
|
+
raise NotALabel(label, "a block is named by its title, and this one is blank")
|
|
1293
|
+
if after is not None and after == label:
|
|
1294
|
+
raise NotALabel(label, "a block cannot be opened after itself")
|
|
1295
|
+
|
|
1296
|
+
changed: dict[str, Document] = {}
|
|
1297
|
+
placed: dict[str, int] = {}
|
|
1298
|
+
rendered: dict[str, str] = {}
|
|
1299
|
+
skipped: list[tuple[str, str]] = []
|
|
1300
|
+
#: `(file, role)` per file that declares no block and was therefore passed over. Kept
|
|
1301
|
+
#: apart from `skipped` because the refusal needs the **role** to name the flag (RK1223),
|
|
1302
|
+
#: and that row's prose is a sentence for a reader rather than an argument for a command.
|
|
1303
|
+
lacking: list[tuple[str, str]] = []
|
|
1304
|
+
declared: list[str] = []
|
|
1305
|
+
|
|
1306
|
+
readable = _readable(config)
|
|
1307
|
+
asked = tuple(dict.fromkeys(organise))
|
|
1308
|
+
for role in asked:
|
|
1309
|
+
if role not in readable:
|
|
1310
|
+
raise NotOrganisable(role, sorted(readable))
|
|
1311
|
+
# The project's own convention, read before anything is written and off the first file
|
|
1312
|
+
# that has one — `BLOCK_ROLES` order, so it is the roadmap wherever the roadmap has
|
|
1313
|
+
# blocks. A file being organised for the first time has no heading of its own to copy.
|
|
1314
|
+
convention = next((blocks for _, _, blocks in readable.values() if blocks), ())
|
|
1315
|
+
|
|
1316
|
+
for role, (where, document, blocks) in readable.items():
|
|
1317
|
+
if not blocks:
|
|
1318
|
+
if role not in asked:
|
|
1319
|
+
# Not a file this verb starts organising unless told to: a heading here
|
|
1320
|
+
# would be the first of its kind, which is a decision about the file's
|
|
1321
|
+
# shape and not about a block (RK405 names the argument that makes it).
|
|
1322
|
+
skipped.append(
|
|
1323
|
+
(where, f"declares no block; --organise {role} writes the first one")
|
|
1324
|
+
)
|
|
1325
|
+
lacking.append((where, role))
|
|
1326
|
+
continue
|
|
1327
|
+
if not convention:
|
|
1328
|
+
raise NotOrganisable(role, sorted(readable), spelling=True)
|
|
1329
|
+
raw = _heading(convention, schema.block_named(label), title.strip())
|
|
1330
|
+
index = _region_end(document, convention[0].level)
|
|
1331
|
+
changed[role] = _insert(document, index, raw)
|
|
1332
|
+
rendered[role] = raw
|
|
1333
|
+
placed[role] = _lineno(changed[role], raw)
|
|
1334
|
+
continue
|
|
1335
|
+
if any(h.label == label for h in blocks):
|
|
1336
|
+
declared.append(where)
|
|
1337
|
+
continue
|
|
1338
|
+
|
|
1339
|
+
raw = _heading(blocks, schema.block_named(label), title.strip())
|
|
1340
|
+
index = document.subtree_end(_neighbour(blocks, after, where, label, schema))
|
|
1341
|
+
changed[role] = _insert(document, index, raw)
|
|
1342
|
+
rendered[role] = raw
|
|
1343
|
+
placed[role] = _lineno(changed[role], raw)
|
|
1344
|
+
|
|
1345
|
+
if not changed:
|
|
1346
|
+
if declared:
|
|
1347
|
+
# The skipped rows go with it (RK1223): a file that declares no block is not a
|
|
1348
|
+
# file with nothing to open, it is the one file the work is about to go into.
|
|
1349
|
+
raise BlockExists(label, declared, lacking)
|
|
1350
|
+
raise BlockExists(label, ["no file this project declares is organised by blocks"])
|
|
1351
|
+
return Opened(
|
|
1352
|
+
label=label,
|
|
1353
|
+
title=title.strip(),
|
|
1354
|
+
after=after,
|
|
1355
|
+
documents=changed,
|
|
1356
|
+
placed=placed,
|
|
1357
|
+
rendered=rendered,
|
|
1358
|
+
skipped=tuple(skipped)
|
|
1359
|
+
+ tuple((where, "already declares it") for where in declared),
|
|
1360
|
+
)
|
|
1361
|
+
|
|
1362
|
+
|
|
1363
|
+
def _neighbour(
|
|
1364
|
+
blocks: tuple[Heading, ...], after: str | None, where: str, label: str, schema: Schema
|
|
1365
|
+
) -> Heading:
|
|
1366
|
+
"""The heading this file places the new one after — the last block, or the named one.
|
|
1367
|
+
|
|
1368
|
+
Read per file on purpose (RK145): `--after C` means *after this file's Block C*, so two
|
|
1369
|
+
files that order their blocks differently each keep their own sequence. A file that wants
|
|
1370
|
+
the heading and declares no such neighbour is a refusal, because the alternative is
|
|
1371
|
+
falling back to the end and leaving one file ordered by an argument the others ignored.
|
|
1372
|
+
"""
|
|
1373
|
+
if after is None:
|
|
1374
|
+
return blocks[-1]
|
|
1375
|
+
found = next((h for h in blocks if h.label == after), None)
|
|
1376
|
+
if found is None:
|
|
1377
|
+
raise NoSuchNeighbour(
|
|
1378
|
+
after,
|
|
1379
|
+
label,
|
|
1380
|
+
where,
|
|
1381
|
+
[h.label for h in blocks if h.label],
|
|
1382
|
+
word=schema.heading_word,
|
|
1383
|
+
)
|
|
1384
|
+
return found
|
|
1385
|
+
|
|
1386
|
+
|
|
1387
|
+
def _region_end(document: Document, level: int) -> int:
|
|
1388
|
+
"""Where a file with no blocks yet keeps its block region, as a 0-based index (RK413).
|
|
1389
|
+
|
|
1390
|
+
The end of the file is what the first version of `--organise` used, and it is the one
|
|
1391
|
+
placement :func:`open_block` refuses by name everywhere else: a roadmap's `## Non-goals`
|
|
1392
|
+
follows its blocks, so appending filed the first task of the new block under it —
|
|
1393
|
+
measured, and `lint` called the result clean, because which sections a project puts after
|
|
1394
|
+
its blocks is not a rule this format holds.
|
|
1395
|
+
|
|
1396
|
+
So the file is asked instead. A heading at the level the new one is being written at is
|
|
1397
|
+
where the next section begins, and the block region stops in front of it. The **level**
|
|
1398
|
+
and not any heading, which is what keeps the file's own title out of the answer, and
|
|
1399
|
+
`==` rather than `<=` for the same reason: a `# Roadmap` on line 1 is not a section the
|
|
1400
|
+
blocks come after.
|
|
1401
|
+
|
|
1402
|
+
None of them is the flat ledger this door was built for, and there the end of the file is
|
|
1403
|
+
right after all — one rule for both shapes, read off the file rather than assumed.
|
|
1404
|
+
"""
|
|
1405
|
+
section = next((h for h in document.headings if h.level == level), None)
|
|
1406
|
+
return len(document.lines) if section is None else section.lineno - 1
|
|
1407
|
+
|
|
1408
|
+
|
|
1409
|
+
def _heading(blocks: tuple[Heading, ...], named: str, title: str) -> str:
|
|
1410
|
+
"""The heading line, spelled the way this file already spells one.
|
|
1411
|
+
|
|
1412
|
+
The level and the separator are the file's, never this module's: a project writing
|
|
1413
|
+
`### Fase 2 - Execução` gets one more of those, and a tool that answered with its own
|
|
1414
|
+
punctuation would be writing a second convention into a file that has one.
|
|
1415
|
+
"""
|
|
1416
|
+
first = blocks[0]
|
|
1417
|
+
return f"{'#' * first.level} {named}{_separator(first)}{title}"
|
|
1418
|
+
|
|
1419
|
+
|
|
1420
|
+
def _separator(heading: Heading) -> str:
|
|
1421
|
+
"""What this file puts between the label and the title — read, never assumed.
|
|
1422
|
+
|
|
1423
|
+
`Block A — The model` → `" — "`, `Fase 2 - Execução` → `" - "`, `Track C notes` →
|
|
1424
|
+
`" "`. A heading that is the label alone has no separator to read, and only then is
|
|
1425
|
+
:data:`DEFAULT_SEPARATOR` the answer.
|
|
1426
|
+
"""
|
|
1427
|
+
tail = heading.text[_label_end(heading.text) :]
|
|
1428
|
+
if not tail.strip():
|
|
1429
|
+
return DEFAULT_SEPARATOR
|
|
1430
|
+
stripped = tail.lstrip()
|
|
1431
|
+
lead = tail[: len(tail) - len(stripped)]
|
|
1432
|
+
token, space, rest = stripped.partition(" ")
|
|
1433
|
+
if token and not token[0].isalnum() and rest:
|
|
1434
|
+
return f"{lead}{token}{space}"
|
|
1435
|
+
return lead
|
|
1436
|
+
|
|
1437
|
+
|
|
1438
|
+
def _label_end(text: str) -> int:
|
|
1439
|
+
"""Where the `<word> <label>` part of this heading stops."""
|
|
1440
|
+
head, _, _ = text.partition(" ")
|
|
1441
|
+
rest = text[len(head) + 1 :]
|
|
1442
|
+
label, _, _ = rest.partition(" ")
|
|
1443
|
+
return len(head) + 1 + len(label)
|
|
1444
|
+
|
|
1445
|
+
|
|
1446
|
+
def _insert(document: Document, index: int, raw: str) -> Document:
|
|
1447
|
+
"""Put the heading in, with the blank lines a heading needs on either side.
|
|
1448
|
+
|
|
1449
|
+
The same care every writer in this package takes about blanks (RK5): a heading glued to
|
|
1450
|
+
the block above it reads as that block's text, and a doubled blank is a paragraph break
|
|
1451
|
+
the file never had — both of which round-trip, which is exactly why nothing else catches
|
|
1452
|
+
them.
|
|
1453
|
+
"""
|
|
1454
|
+
payload: list[str] = []
|
|
1455
|
+
if index > 0 and not blank(document.lines[index - 1]):
|
|
1456
|
+
payload.append("")
|
|
1457
|
+
payload.append(raw)
|
|
1458
|
+
if index >= len(document.lines) or not blank(document.lines[index]):
|
|
1459
|
+
payload.append("")
|
|
1460
|
+
updated = document
|
|
1461
|
+
for offset, line in enumerate(payload):
|
|
1462
|
+
updated = updated.insert_line(index + offset, line)
|
|
1463
|
+
return updated
|
|
1464
|
+
|
|
1465
|
+
|
|
1466
|
+
def _lineno(document: Document, raw: str) -> int:
|
|
1467
|
+
"""Where the heading this write just rendered ended up, read back off the parse."""
|
|
1468
|
+
text = raw.partition(" ")[2]
|
|
1469
|
+
return next(h.lineno for h in document.headings if h.text == text)
|
|
1470
|
+
|
|
1471
|
+
|
|
1472
|
+
def merge_block(config: Config, label: str, *, prose: bool = False) -> Merged:
|
|
1473
|
+
"""Fold every duplicate heading for one label into the first, moving the entries (RK403).
|
|
1474
|
+
|
|
1475
|
+
The key RK391 named and RK141/RK144's pair never cut. Two headings under one label is a
|
|
1476
|
+
state the gate reports (`block.repeated`) and every write refuses
|
|
1477
|
+
(:class:`~roadkeep.kernel.document.RepeatedHeading`), and the only remedy it could offer was
|
|
1478
|
+
*merge the two regions by hand* — which the guard (RK22) denies and the gate (RK14)
|
|
1479
|
+
refuses. `drop_block` cannot help: it **skips the ledger**, whose headings hold history
|
|
1480
|
+
for ever, so an empty duplicate ledger heading is :class:`NothingToDrop` rather than
|
|
1481
|
+
removable; `--fix` (RK16) repairs only derived data. So a doubled changelog heading — the
|
|
1482
|
+
shape a textual git merge, an `adopt`, or a hand edit leaves — was the one deadlock with
|
|
1483
|
+
no door.
|
|
1484
|
+
|
|
1485
|
+
This is that door, and it is mechanical, not editorial. The surviving heading is the
|
|
1486
|
+
**first** one — the same choice `block.repeated` reports and `add` files under by position
|
|
1487
|
+
— and every later duplicate's entries move under it. Because both regions share the label,
|
|
1488
|
+
an entry's every field is byte-identical before and after, so the relocation round-trips
|
|
1489
|
+
by construction (L3) and writes no prose (L4); the move is `record move`'s (RK143) without
|
|
1490
|
+
the block changing.
|
|
1491
|
+
|
|
1492
|
+
**The ledger is included, not skipped**, which is the difference from `drop_block` and the
|
|
1493
|
+
reason this exists: consolidating two headings of *one* label keeps history under a heading
|
|
1494
|
+
of that label, so nothing is orphaned — the danger that made `drop_block` skip the ledger
|
|
1495
|
+
does not arise here.
|
|
1496
|
+
|
|
1497
|
+
Validates everything before touching anything, as :func:`open_block` and :func:`drop_block`
|
|
1498
|
+
do — all of the files, or none of them. A later duplicate standing over a **nested heading**
|
|
1499
|
+
(a rationale section, a sub-block) is :class:`RegionOccupied`, because placing a subtree is
|
|
1500
|
+
`section move`'s editorial call and not a fold's; **loose prose** is dropped only under
|
|
1501
|
+
``prose`` and refused by name otherwise (RK237). A label declared once or nowhere is
|
|
1502
|
+
:class:`NotRepeated`.
|
|
1503
|
+
"""
|
|
1504
|
+
word = config.schema.heading_word
|
|
1505
|
+
declaring = _declaring(config, label)
|
|
1506
|
+
if not declaring:
|
|
1507
|
+
raise NoSuchBlock(label, _labels(config), word=word)
|
|
1508
|
+
|
|
1509
|
+
doubled = [(role, where, document) for role, where, document, _ in declaring
|
|
1510
|
+
if len(document.declaring(label)) > 1]
|
|
1511
|
+
if not doubled:
|
|
1512
|
+
raise NotRepeated(label, [where for _, where, _, _ in declaring], word=word)
|
|
1513
|
+
|
|
1514
|
+
# Every refusal before any write (RK6): a nested heading or an un-flagged note under a
|
|
1515
|
+
# duplicate leaves the whole tree untouched, including the files whose fold was clean.
|
|
1516
|
+
for role, where, document in doubled:
|
|
1517
|
+
for later in document.declaring(label)[1:]:
|
|
1518
|
+
held = _held(document, later)
|
|
1519
|
+
if held.headings:
|
|
1520
|
+
raise RegionOccupied(label, where, held.headings, word=word, nested=True)
|
|
1521
|
+
if held.prose and not prose:
|
|
1522
|
+
raise RegionOccupied(
|
|
1523
|
+
label, where, [f"line {n}" for n in held.prose], word=word, nested=False
|
|
1524
|
+
)
|
|
1525
|
+
|
|
1526
|
+
changed: dict[str, Document] = {}
|
|
1527
|
+
kept: dict[str, int] = {}
|
|
1528
|
+
folded: dict[str, tuple[str, ...]] = {}
|
|
1529
|
+
moved: dict[str, tuple[str, ...]] = {}
|
|
1530
|
+
notes: dict[str, int] = {}
|
|
1531
|
+
for role, _, document in doubled:
|
|
1532
|
+
result, moved_ids, folded_headings, dropped = _fold(document, label)
|
|
1533
|
+
changed[role] = result
|
|
1534
|
+
kept[role] = result.declaring(label)[0].lineno
|
|
1535
|
+
moved[role] = moved_ids
|
|
1536
|
+
folded[role] = folded_headings
|
|
1537
|
+
if dropped:
|
|
1538
|
+
notes[role] = dropped
|
|
1539
|
+
return Merged(
|
|
1540
|
+
label=label,
|
|
1541
|
+
documents=changed,
|
|
1542
|
+
kept=kept,
|
|
1543
|
+
folded=folded,
|
|
1544
|
+
moved=moved,
|
|
1545
|
+
notes=notes,
|
|
1546
|
+
)
|
|
1547
|
+
|
|
1548
|
+
|
|
1549
|
+
def _fold(document: Document, label: str) -> tuple[Document, tuple[str, ...], tuple[str, ...], int]:
|
|
1550
|
+
"""Fold every later heading for ``label`` into the first, entry by entry.
|
|
1551
|
+
|
|
1552
|
+
Re-reads the parse each step (RK54): moving one entry re-numbers every line below it, and
|
|
1553
|
+
a heading held across the edit is a heading at a line that has moved. So the loop asks
|
|
1554
|
+
:meth:`~roadkeep.kernel.document.Document.declaring` again each time and acts on the first
|
|
1555
|
+
remaining duplicate — moving its next entry under the survivor, or, once it holds none,
|
|
1556
|
+
excising the emptied heading. It ends when one heading is left, which the entry moves and
|
|
1557
|
+
the excises both drive toward.
|
|
1558
|
+
"""
|
|
1559
|
+
result = document
|
|
1560
|
+
moved: list[str] = []
|
|
1561
|
+
folded: list[str] = []
|
|
1562
|
+
notes = 0
|
|
1563
|
+
while len(result.declaring(label)) > 1:
|
|
1564
|
+
keep, later = result.declaring(label)[:2]
|
|
1565
|
+
entries = [
|
|
1566
|
+
entry
|
|
1567
|
+
for entry in result.entries
|
|
1568
|
+
if later.lineno < entry.lineno <= result.subtree_end(later)
|
|
1569
|
+
]
|
|
1570
|
+
if entries:
|
|
1571
|
+
entry = entries[0]
|
|
1572
|
+
# The whole entry, continuation lines included (RK157): a wrapped ledger entry's
|
|
1573
|
+
# tail is prose no task holds, so a fold that re-rendered alone would take the
|
|
1574
|
+
# paragraph out of the file in the name of moving the bullet.
|
|
1575
|
+
carrying = tuple(
|
|
1576
|
+
line.rstrip("\r\n") for line in result.lines[entry.lineno : entry.stop]
|
|
1577
|
+
)
|
|
1578
|
+
moved.append(entry.task.id)
|
|
1579
|
+
result = remove_entry(result, entry)
|
|
1580
|
+
result = _append_under(result, result.declaring(label)[0], entry.raw, carrying)
|
|
1581
|
+
else:
|
|
1582
|
+
# Emptied: the heading now stands over blanks alone (a note went with `--prose`
|
|
1583
|
+
# to `_held` above, which is why the count is read before the excise removes it).
|
|
1584
|
+
held = _held(result, later)
|
|
1585
|
+
notes += len(held.prose)
|
|
1586
|
+
folded.append(result.lines[later.lineno - 1].rstrip("\r\n"))
|
|
1587
|
+
result = _excise(result, later)
|
|
1588
|
+
return result, tuple(moved), tuple(folded), notes
|
|
1589
|
+
|
|
1590
|
+
|
|
1591
|
+
def _append_under(
|
|
1592
|
+
document: Document, heading: Heading, raw: str, carrying: tuple[str, ...]
|
|
1593
|
+
) -> Document:
|
|
1594
|
+
"""Place one entry (and its continuation) at the end of ``heading``'s region.
|
|
1595
|
+
|
|
1596
|
+
After the region's last entry when it has one, which needs no blank reasoning: the line
|
|
1597
|
+
that followed it — the block's trailing blank, or the next heading — still follows the
|
|
1598
|
+
line now appended. An **empty** surviving region is `place`'s empty-block case (RK108):
|
|
1599
|
+
the entry lands after the heading's own prose, with the blanks a first line needs on
|
|
1600
|
+
either side, so the introduction stays above the backlog and nothing is glued to a heading.
|
|
1601
|
+
"""
|
|
1602
|
+
region = [
|
|
1603
|
+
entry
|
|
1604
|
+
for entry in document.entries
|
|
1605
|
+
if heading.lineno < entry.lineno <= document.subtree_end(heading)
|
|
1606
|
+
]
|
|
1607
|
+
lines = document.lines
|
|
1608
|
+
if region:
|
|
1609
|
+
index, payload = region[-1].stop, [raw, *carrying]
|
|
1610
|
+
else:
|
|
1611
|
+
index = _after_preamble(document, heading)
|
|
1612
|
+
before: list[str] = []
|
|
1613
|
+
if index < len(lines) and blank(lines[index]):
|
|
1614
|
+
index += 1
|
|
1615
|
+
else:
|
|
1616
|
+
before = [""]
|
|
1617
|
+
after = [] if index >= len(lines) or blank(lines[index]) else [""]
|
|
1618
|
+
payload = [*before, raw, *carrying, *after]
|
|
1619
|
+
result = document
|
|
1620
|
+
for offset, line in enumerate(payload):
|
|
1621
|
+
result = result.insert_line(index + offset, line)
|
|
1622
|
+
return result
|