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/deferring.py
ADDED
|
@@ -0,0 +1,708 @@
|
|
|
1
|
+
"""The two doors the store needs, one of them the way back (RK91).
|
|
2
|
+
|
|
3
|
+
RK96 built the state and stopped there: a fifth marker in a fifth governed file, read by
|
|
4
|
+
the parser and the gate, and nothing that could put a line in it. So a pause was still
|
|
5
|
+
spelled as a retirement, which is terminal by construction โ the resolver reads a retired
|
|
6
|
+
dep as never (RK28), and a re-add cannot reclaim the id, because retired-never-reused is
|
|
7
|
+
enforced (RK4). Recording "not now" that way destroys exactly what makes it not-now: the
|
|
8
|
+
id every dependent names, the `ยงid` rationale, and the thread `origin` and `deps` key on.
|
|
9
|
+
|
|
10
|
+
:func:`defer` is the transaction `ship` and `retire` are, with two differences that are the
|
|
11
|
+
whole point:
|
|
12
|
+
|
|
13
|
+
* **The section is carried, not deleted.** A departure removes the design because a shipped
|
|
14
|
+
line has none left to state; a pause keeps it, and the gate already knows to leave a
|
|
15
|
+
section the store points at alone rather than reporting it as an orphan.
|
|
16
|
+
* **The destination is revivable.** :func:`resume` is the return direction the ledger's
|
|
17
|
+
doors lack, and it is the same all-or-nothing shape read backwards. That is not a reused
|
|
18
|
+
id: a deferred id was never retired, so the same work coming back under its own number is
|
|
19
|
+
the pause working, not the non-goal being crossed.
|
|
20
|
+
|
|
21
|
+
Two things this deliberately does not preserve, both because the file *is* the state (RK96):
|
|
22
|
+
|
|
23
|
+
* **The open marker.** The store holds โธ and nothing else, so ๐ and โณ are indistinguishable
|
|
24
|
+
the moment a line lands there. `resume --marker` is where the author says which it was โ
|
|
25
|
+
the default is the project's first, exactly as `add`'s is, and a marker invented from the
|
|
26
|
+
word "resume" would be this tool holding an opinion about someone else's maturity.
|
|
27
|
+
* **The indent.** A nested line said which roadmap line it belonged under (RK49), and that
|
|
28
|
+
line is not in the store โ the same reason `ship` files its entry at column zero.
|
|
29
|
+
|
|
30
|
+
The reason is a **derived prefix on the `why`**, which is `retire`'s shape one door over: the
|
|
31
|
+
author's sentence is never rewritten (L4), it is wrapped, and :func:`resume` unwraps exactly
|
|
32
|
+
what this module wrote. The prefix ends at the first ``): ``, so a reason that spells that
|
|
33
|
+
sequence is refused rather than stored โ a pause the return trip cannot undo is a pause that
|
|
34
|
+
silently became a rewrite of the design sentence.
|
|
35
|
+
"""
|
|
36
|
+
|
|
37
|
+
from __future__ import annotations
|
|
38
|
+
|
|
39
|
+
from collections.abc import Sequence
|
|
40
|
+
from dataclasses import dataclass, replace
|
|
41
|
+
from pathlib import Path
|
|
42
|
+
|
|
43
|
+
from roadkeep import claiming, queueing
|
|
44
|
+
from roadkeep.authoring import Insertion, place, remove_entry
|
|
45
|
+
from roadkeep.backlog import Backlog, NotOpen, Whereabouts
|
|
46
|
+
from roadkeep.config import DESIGN_ROLES, Config
|
|
47
|
+
from roadkeep.kernel.document import Document, Entry, save_all
|
|
48
|
+
from roadkeep.markers import refresh
|
|
49
|
+
from roadkeep.provenance import invocation
|
|
50
|
+
from roadkeep.kernel.schema import PAUSED_CLOSE, PAUSED_OPEN, Task, authored_why, pause_reason
|
|
51
|
+
from roadkeep.sections import declaring
|
|
52
|
+
|
|
53
|
+
__all__ = [
|
|
54
|
+
"Carried",
|
|
55
|
+
"NoStore",
|
|
56
|
+
"NotSetAside",
|
|
57
|
+
"Pause",
|
|
58
|
+
"Resumption",
|
|
59
|
+
"SetAside",
|
|
60
|
+
"UnrecoverableReason",
|
|
61
|
+
"defer",
|
|
62
|
+
"resume",
|
|
63
|
+
]
|
|
64
|
+
|
|
65
|
+
#: What the derived prefix opens and closes. One spelling, and since RK1115 it lives in the
|
|
66
|
+
#: kernel: this module composes it, and the rule that measures a `why` has to know what part
|
|
67
|
+
#: of one it wrote โ two spellings of that would be a limit disagreeing with the door about
|
|
68
|
+
#: which characters an author is charged for.
|
|
69
|
+
_OPEN = PAUSED_OPEN
|
|
70
|
+
_CLOSE = PAUSED_CLOSE
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
class NoStore(ValueError):
|
|
74
|
+
"""A pause with nowhere to go: this project declares no deferred file (RK96).
|
|
75
|
+
|
|
76
|
+
Refused and not scaffolded on the way past. A governed file is a path in
|
|
77
|
+
`roadkeep.toml` (L6) and `init` is what writes one โ a store a `defer` invented at the
|
|
78
|
+
moment it needed one would be a format decided by a verb, which is the thing Block A
|
|
79
|
+
exists to prevent.
|
|
80
|
+
"""
|
|
81
|
+
|
|
82
|
+
def __init__(self, task_id: str) -> None:
|
|
83
|
+
self.task_id = task_id
|
|
84
|
+
super().__init__(
|
|
85
|
+
f"{task_id} cannot be set aside: no deferred store is declared โ add "
|
|
86
|
+
f'`deferred = "<path>"` under [files] and create the file with its block '
|
|
87
|
+
f"headings, or retire the line if the pause is really an abandonment"
|
|
88
|
+
)
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
class NoPlacement(ValueError):
|
|
92
|
+
"""`--marker` on a resume that places no line (RK1083).
|
|
93
|
+
|
|
94
|
+
The reconciling path removes the store's stale copy and leaves the roadmap alone, so the
|
|
95
|
+
open marker a returned line would come back at has nothing to be about. Refused rather
|
|
96
|
+
than ignored, which is `NoCompletion`'s and `NoSpan`'s rule: a flag accepted where it
|
|
97
|
+
can take no effect is a flag the caller believes took one.
|
|
98
|
+
|
|
99
|
+
The remedy is the ordinary one โ `status <id> <marker>` writes the marker of a line that
|
|
100
|
+
is already there โ and it is named, because a refusal that only says no costs the reader
|
|
101
|
+
the turn this one saves.
|
|
102
|
+
"""
|
|
103
|
+
|
|
104
|
+
def __init__(self, task_id: str, where: str, lineno: int) -> None:
|
|
105
|
+
self.task_id = task_id
|
|
106
|
+
super().__init__(
|
|
107
|
+
f"--marker names the marker a returned line comes back at, and this call places "
|
|
108
|
+
f"none: {task_id} is already open at {where}:{lineno} and only the store's copy "
|
|
109
|
+
f"is removed โ `{invocation()} status {task_id} <marker>` writes the marker of a "
|
|
110
|
+
f"line that is already there"
|
|
111
|
+
)
|
|
112
|
+
|
|
113
|
+
|
|
114
|
+
class SetAside(ValueError):
|
|
115
|
+
"""The store already holds this id, so there is no line here to pause."""
|
|
116
|
+
|
|
117
|
+
def __init__(self, task_id: str, where: str, lineno: int) -> None:
|
|
118
|
+
self.task_id = task_id
|
|
119
|
+
self.lineno = lineno
|
|
120
|
+
super().__init__(
|
|
121
|
+
f"{task_id} is already set aside in {where}:{lineno}: a second line would be "
|
|
122
|
+
f"two answers to when this work comes back, and nothing says which is right"
|
|
123
|
+
)
|
|
124
|
+
|
|
125
|
+
|
|
126
|
+
class NotSetAside(KeyError):
|
|
127
|
+
"""`resume` against an id the store does not hold.
|
|
128
|
+
|
|
129
|
+
Names where it *is*, because "not in the store" is the same sentence for a task that is
|
|
130
|
+
open, one that shipped and one that never existed โ and only the last is a typo.
|
|
131
|
+
"""
|
|
132
|
+
|
|
133
|
+
def __init__(self, task_id: str, where: str, *, elsewhere: str = "") -> None:
|
|
134
|
+
self.task_id = task_id
|
|
135
|
+
found = f" ({elsewhere})" if elsewhere else ""
|
|
136
|
+
super().__init__(
|
|
137
|
+
f"{task_id} is not in {where}{found}: resume returns a line the store holds, "
|
|
138
|
+
f"and a task that never paused has nothing to come back from"
|
|
139
|
+
)
|
|
140
|
+
|
|
141
|
+
|
|
142
|
+
class UnrecoverableReason(ValueError):
|
|
143
|
+
"""A reason spelling the sequence that ends the derived prefix.
|
|
144
|
+
|
|
145
|
+
Refused at input rather than stored, because the damage is invisible until the return
|
|
146
|
+
trip: the unwrap stops at the first ``): ``, so the author's own sentence would come
|
|
147
|
+
back with the tail of the reason glued to its front, and `lint` cannot see a `why` that
|
|
148
|
+
is merely wrong.
|
|
149
|
+
"""
|
|
150
|
+
|
|
151
|
+
def __init__(self, reason: str) -> None:
|
|
152
|
+
super().__init__(
|
|
153
|
+
f"the reason may not contain {_CLOSE!r}: it is what closes the derived prefix, "
|
|
154
|
+
f"and resume would restore a sentence the pause rewrote โ {reason!r}"
|
|
155
|
+
)
|
|
156
|
+
|
|
157
|
+
|
|
158
|
+
@dataclass(frozen=True, slots=True)
|
|
159
|
+
class Carried:
|
|
160
|
+
"""The design a pause kept, and the file that actually declares it (RK229).
|
|
161
|
+
|
|
162
|
+
RK196 taught `ship` to resolve an anchor across the declared prose roles and to report
|
|
163
|
+
the file it wrote; this is the same sentence one verb over, and the reason it is a type
|
|
164
|
+
rather than a string is that the anchor alone is what let the CLI supply the rest โ a
|
|
165
|
+
project declaring `strategy` was told its design was kept in an `improvements` file it
|
|
166
|
+
does not have, and the KeyError that named it arrived *after* both writes.
|
|
167
|
+
|
|
168
|
+
`role` is None where no declared prose file holds the anchor, or where two do, and
|
|
169
|
+
`absence` is the sentence saying which โ never resolved by picking, for the reason a ship
|
|
170
|
+
does not pick either: which of two a line meant is `ref.ambiguous`, and a pointer
|
|
171
|
+
resolving to nothing is a `lint` finding this door has no business answering.
|
|
172
|
+
"""
|
|
173
|
+
|
|
174
|
+
#: As the line spells it, `ยง` included โ the pointer, not the id it usually equals.
|
|
175
|
+
anchor: str
|
|
176
|
+
#: The prose role holding it, where exactly one does. `Config.path` takes it from here.
|
|
177
|
+
role: str | None = None
|
|
178
|
+
#: Why no role answered, ready to print. Empty exactly when `role` is not None.
|
|
179
|
+
absence: str = ""
|
|
180
|
+
|
|
181
|
+
def line(self, config: Config) -> str:
|
|
182
|
+
"""The one line saying where a paused design stayed (RK229).
|
|
183
|
+
|
|
184
|
+
`kept in <file>` only where a file holds it. An absence spells itself instead of being
|
|
185
|
+
dressed as a location: "kept in IMPROVEMENTS.md" about a section that is not there
|
|
186
|
+
sends a reader to look, and the pause is right either way.
|
|
187
|
+
|
|
188
|
+
On the record since RK1170, where `_defer` was composing it: which file this resolved
|
|
189
|
+
to is what this type exists to carry, and a phrasing about it belongs with it.
|
|
190
|
+
"""
|
|
191
|
+
if self.role is None:
|
|
192
|
+
return f"{self.anchor} โ {self.absence}"
|
|
193
|
+
return f"{self.anchor} kept in {config.relative(config.path(self.role))}"
|
|
194
|
+
|
|
195
|
+
|
|
196
|
+
@dataclass(frozen=True, slots=True)
|
|
197
|
+
class Pause:
|
|
198
|
+
"""Every edit setting one line aside makes, as data, before it is written."""
|
|
199
|
+
|
|
200
|
+
task_id: str
|
|
201
|
+
#: The line as the store now holds it: โธ, and every other slot kept.
|
|
202
|
+
store: Insertion
|
|
203
|
+
#: The roadmap without it, with every annotation re-derived (RK8).
|
|
204
|
+
roadmap: Document
|
|
205
|
+
removed_from: int
|
|
206
|
+
refreshed: tuple[str, ...] = ()
|
|
207
|
+
marker: str = ""
|
|
208
|
+
#: The priority entry this pause took out (RK327), or `None` where the queue never
|
|
209
|
+
#: named it. Taken and not kept, because a paused line is one `pick` can never offer;
|
|
210
|
+
#: put back by the author at the `resume`, which is where the order is known again.
|
|
211
|
+
dequeued: str | None = None
|
|
212
|
+
#: The section this did **not** delete, named โ silence about a carried design reads
|
|
213
|
+
#: exactly like the deletion a departure makes. Resolved here and not by the caller
|
|
214
|
+
#: (RK229): the role is a fact about the files this transaction read.
|
|
215
|
+
carried: Carried | None = None
|
|
216
|
+
#: Open lines that still name this id. Reported and not refused: waiting on paused work
|
|
217
|
+
#: is a legitimate state, and it is what `deps` and RK92 are for.
|
|
218
|
+
dependents: tuple[str, ...] = ()
|
|
219
|
+
|
|
220
|
+
#: The checkout, so a claim on the paused line can be dropped (RK156). Every other door
|
|
221
|
+
#: releases one by moving the marker; this one takes the line out of the file the marker
|
|
222
|
+
#: is read in, which no later read can tell from a claim still held.
|
|
223
|
+
root: Path | None = None
|
|
224
|
+
#: Whether this call **reconciled** a contradiction rather than returning a line (RK1081):
|
|
225
|
+
#: the roadmap already carried the id, so the store entry was the stale half and only it
|
|
226
|
+
#: was removed. Reported rather than inferred โ the caller printing "returned to Block A"
|
|
227
|
+
#: over a line that never moved would be describing a write nobody made.
|
|
228
|
+
reconciled: bool = False
|
|
229
|
+
|
|
230
|
+
def save(self) -> tuple[Path, ...]:
|
|
231
|
+
"""Write both files, and answer every path that took (RK1130).
|
|
232
|
+
|
|
233
|
+
The store first, for the reason the ledger goes first in a departure (RK118): the
|
|
234
|
+
arrival is written before the removal, so a crash between them leaves the line in
|
|
235
|
+
both files โ visible, and a `resume` away โ rather than in neither.
|
|
236
|
+
"""
|
|
237
|
+
wrote = save_all(self.store.document, self.roadmap)
|
|
238
|
+
if self.root is not None:
|
|
239
|
+
# Last, and never a condition of the write: the worker who set this aside is not
|
|
240
|
+
# holding it, and a claim left behind would greet the `resume` (RK156). The same
|
|
241
|
+
# rule every marker write obeys (RK158), the marker here being โธ.
|
|
242
|
+
claiming.follow(self.root, self.task_id, self.marker, self.roadmap.entries)
|
|
243
|
+
return wrote
|
|
244
|
+
|
|
245
|
+
@property
|
|
246
|
+
def block(self) -> str:
|
|
247
|
+
return self.store.entry.task.block
|
|
248
|
+
|
|
249
|
+
def event(self, config: Config) -> dict[str, object]:
|
|
250
|
+
"""What this pause did to the block it left (RK38), off the roadmap it wrote."""
|
|
251
|
+
from roadkeep.rendering import _event # noqa: PLC0415 - RK260
|
|
252
|
+
|
|
253
|
+
return _event(self.task_id, self.block, self.roadmap, config)
|
|
254
|
+
|
|
255
|
+
def stated(self, config: Config, wrote: Sequence[Path]) -> str:
|
|
256
|
+
"""Where the line went, and what the pause kept (RK229, RK327).
|
|
257
|
+
|
|
258
|
+
Beside :meth:`payload` since RK1170. `wrote` is a parameter and not a field, because
|
|
259
|
+
:meth:`save` is the caller's step: a record that named paths before they were written
|
|
260
|
+
would be answering about a write that may not have happened.
|
|
261
|
+
"""
|
|
262
|
+
from roadkeep.rendering import ( # noqa: PLC0415 - RK260
|
|
263
|
+
_dequeued_rows,
|
|
264
|
+
_event_rows,
|
|
265
|
+
_staging_rows,
|
|
266
|
+
)
|
|
267
|
+
|
|
268
|
+
roadmap = config.relative(config.path("roadmap"))
|
|
269
|
+
store = config.relative(config.path("deferred"))
|
|
270
|
+
rows = [
|
|
271
|
+
f"{self.task_id} {self.marker} {store}:{self.store.lineno} under Block {self.block}",
|
|
272
|
+
f" removed {roadmap}:{self.removed_from}",
|
|
273
|
+
]
|
|
274
|
+
if self.carried is not None:
|
|
275
|
+
# Named, because every other door that moves a line deletes this section: silence
|
|
276
|
+
# about a design that was kept reads exactly like the deletion (RK6). The *file* is
|
|
277
|
+
# the pause's answer and never this line's (RK229) โ composing it here from the
|
|
278
|
+
# improvements default is what named a path a strategy-only project does not declare.
|
|
279
|
+
rows.append(f" carried {self.carried.line(config)}")
|
|
280
|
+
if self.dependents:
|
|
281
|
+
rows.append(f" still {', '.join(self.dependents)} name {self.task_id}")
|
|
282
|
+
if self.refreshed:
|
|
283
|
+
rows.append(f" derived {', '.join(self.refreshed)} (dep annotations re-derived)")
|
|
284
|
+
rows += _dequeued_rows(self.dequeued)
|
|
285
|
+
rows += _staging_rows(config.relative(one) for one in wrote)
|
|
286
|
+
rows += _event_rows(self.event(config), " ")
|
|
287
|
+
return "\n".join(rows)
|
|
288
|
+
|
|
289
|
+
def payload(self, config: Config, wrote: Sequence[Path]) -> dict[str, object]:
|
|
290
|
+
"""The same answer as data, with the design this did not delete (RK229)."""
|
|
291
|
+
from roadkeep.rendering import ( # noqa: PLC0415 - RK260
|
|
292
|
+
_carried_json,
|
|
293
|
+
_wrote_json,
|
|
294
|
+
)
|
|
295
|
+
|
|
296
|
+
return {
|
|
297
|
+
"id": self.task_id,
|
|
298
|
+
"marker": self.marker,
|
|
299
|
+
"deferred": {
|
|
300
|
+
"file": config.relative(config.path("deferred")),
|
|
301
|
+
"line": self.store.lineno,
|
|
302
|
+
"rendered": self.store.rendered,
|
|
303
|
+
},
|
|
304
|
+
"roadmap": {
|
|
305
|
+
"file": config.relative(config.path("roadmap")),
|
|
306
|
+
"removed": self.removed_from,
|
|
307
|
+
},
|
|
308
|
+
"carried": _carried_json(config, self.carried),
|
|
309
|
+
"dequeued": self.dequeued,
|
|
310
|
+
"dependents": list(self.dependents),
|
|
311
|
+
"refreshed": list(self.refreshed),
|
|
312
|
+
**_wrote_json(config, wrote),
|
|
313
|
+
"event": self.event(config),
|
|
314
|
+
}
|
|
315
|
+
|
|
316
|
+
|
|
317
|
+
@dataclass(frozen=True, slots=True)
|
|
318
|
+
class Resumption:
|
|
319
|
+
"""The same transaction read backwards: the line returns, the store lets it go."""
|
|
320
|
+
|
|
321
|
+
task_id: str
|
|
322
|
+
#: The roadmap as this write leaves it. A **document** and not an `Insertion` since
|
|
323
|
+
#: RK1086: that type is a line and the file that now holds it, which is right for the
|
|
324
|
+
#: act this verb was built for and wrong for the one RK1081 added. A reconciling call
|
|
325
|
+
#: places nothing, so it had to point the field at the entry it left alone โ and the
|
|
326
|
+
#: third act, where the *ledger* is what already states the outcome, has no entry
|
|
327
|
+
#: anywhere to point at. `Insertion(entry=None)` parses and the printer reads
|
|
328
|
+
#: `.entry.task.block` two lines later, which is how RK1084 found this rather than
|
|
329
|
+
#: shipping a verb.
|
|
330
|
+
roadmap: Document
|
|
331
|
+
#: The line this call put back, or `None` where it placed none. The two are different
|
|
332
|
+
#: answers and the shape now says which: a caller printing "returned to Block A" over a
|
|
333
|
+
#: line that never moved is describing a write nobody made (RK1083).
|
|
334
|
+
placed: Entry | None
|
|
335
|
+
store: Document
|
|
336
|
+
removed_from: int
|
|
337
|
+
refreshed: tuple[str, ...] = ()
|
|
338
|
+
marker: str = ""
|
|
339
|
+
#: The reason the pause recorded, removed from the `why` and reported once โ the last
|
|
340
|
+
#: place it is visible, because the line that comes back is a design and not a history.
|
|
341
|
+
was: str | None = None
|
|
342
|
+
#: The checkout, so the claim can follow the marker this returns the line at (RK158): a
|
|
343
|
+
#: `resume --marker ๐ ` is an assertion that somebody is on it, like every other ๐ write.
|
|
344
|
+
#: What it did is not a field here โ the command prints the marker, which is the fact, and
|
|
345
|
+
#: a second copy of it would be a second thing to keep true.
|
|
346
|
+
root: Path | None = None
|
|
347
|
+
#: Whether this call **reconciled** a contradiction rather than returning a line (RK1081):
|
|
348
|
+
#: the roadmap already carried the id, so the store entry was the stale half and only it
|
|
349
|
+
#: was removed. Reported rather than inferred โ the caller printing "returned to Block A"
|
|
350
|
+
#: over a line that never moved would be describing a write nobody made.
|
|
351
|
+
reconciled: bool = False
|
|
352
|
+
|
|
353
|
+
def save(self) -> tuple[Path, ...]:
|
|
354
|
+
# The same rule read backwards: the roadmap is the arrival now, so it goes first
|
|
355
|
+
# and the store's removal second (RK118). A line in both files is a state a reader
|
|
356
|
+
# can see and a second `resume` can finish; a line in neither is one nobody can.
|
|
357
|
+
wrote = save_all(self.roadmap, self.store)
|
|
358
|
+
if self.root is not None:
|
|
359
|
+
claiming.follow(
|
|
360
|
+
self.root, self.task_id, self.marker, self.roadmap.entries
|
|
361
|
+
)
|
|
362
|
+
return wrote
|
|
363
|
+
|
|
364
|
+
def standing(self, config: Config) -> Entry | None:
|
|
365
|
+
"""The line this call placed, or the one already there on a reconciling call (RK1086).
|
|
366
|
+
|
|
367
|
+
Asked rather than faked: the shape says a reconciliation places nothing, so the entry
|
|
368
|
+
being described has to be looked up where it already was.
|
|
369
|
+
"""
|
|
370
|
+
return self.placed or config.document("roadmap").by_id().get(self.task_id)
|
|
371
|
+
|
|
372
|
+
def event(self, config: Config) -> dict[str, object]:
|
|
373
|
+
"""What this return did to the block it landed in (RK38), off the roadmap it wrote."""
|
|
374
|
+
from roadkeep.rendering import _event # noqa: PLC0415 - RK260
|
|
375
|
+
|
|
376
|
+
standing = self.standing(config)
|
|
377
|
+
block = standing.task.block if standing else ""
|
|
378
|
+
return _event(self.task_id, block, self.roadmap, config)
|
|
379
|
+
|
|
380
|
+
def requeue(self, config: Config) -> str | None:
|
|
381
|
+
"""The `priority add` a resumed line may want, where this project has a queue (RK327).
|
|
382
|
+
|
|
383
|
+
Offered and never done. `defer` took the entry out because a paused line is one `pick`
|
|
384
|
+
can never offer; what it could not keep is **where in the order it sat**, the store
|
|
385
|
+
holding a line and not a rank โ so a resume that re-queued would be choosing a position
|
|
386
|
+
nobody stated. Silent where no heading declares a section, which is most projects: a
|
|
387
|
+
follow-up naming a list that does not exist is a command that cannot run.
|
|
388
|
+
|
|
389
|
+
On the record since RK1170, with both registers that print it: this is the half of the
|
|
390
|
+
pause the verb does not undo, which makes it part of what the transaction answers.
|
|
391
|
+
"""
|
|
392
|
+
try:
|
|
393
|
+
queue = queueing.declared(config)
|
|
394
|
+
except (KeyError, OSError): # a roadmap this command already reported on
|
|
395
|
+
return None
|
|
396
|
+
if queue.declared_in != "roadmap" or self.task_id in queue.tokens:
|
|
397
|
+
return None
|
|
398
|
+
return (
|
|
399
|
+
f"`{invocation()} priority add {self.task_id}` if it goes back in the order โ the "
|
|
400
|
+
f"pause took it out, and where it sat is not something the store kept"
|
|
401
|
+
)
|
|
402
|
+
|
|
403
|
+
def stated(self, config: Config, wrote: Sequence[Path]) -> str:
|
|
404
|
+
"""Which of the two acts this was, and what came back with the line (RK1083).
|
|
405
|
+
|
|
406
|
+
Beside :meth:`payload` since RK1170. `ship` answers the same shape the same way โ `RK1
|
|
407
|
+
closed` against `RK1 โ` โ because a caller holding an id should not have to know which
|
|
408
|
+
of two states the files are in, and the *output* is where they find out.
|
|
409
|
+
"""
|
|
410
|
+
from roadkeep.rendering import ( # noqa: PLC0415 - RK260
|
|
411
|
+
_event_rows,
|
|
412
|
+
_staging_rows,
|
|
413
|
+
)
|
|
414
|
+
|
|
415
|
+
roadmap = config.relative(config.path("roadmap"))
|
|
416
|
+
store = config.relative(config.path("deferred"))
|
|
417
|
+
standing = self.standing(config)
|
|
418
|
+
if self.reconciled:
|
|
419
|
+
rows = [
|
|
420
|
+
f"{self.task_id} reconciled {store}:{self.removed_from} removed, "
|
|
421
|
+
f"already {self.marker} in {roadmap}:{standing.lineno}",
|
|
422
|
+
" roadmap untouched: the open line is what the files should say",
|
|
423
|
+
]
|
|
424
|
+
else:
|
|
425
|
+
block = standing.task.block if standing else ""
|
|
426
|
+
rows = [
|
|
427
|
+
f"{self.task_id} {self.marker} {roadmap}:{self.placed.lineno} "
|
|
428
|
+
f"under Block {block}",
|
|
429
|
+
f" removed {store}:{self.removed_from}",
|
|
430
|
+
]
|
|
431
|
+
if self.was is not None:
|
|
432
|
+
# The last time the reason is visible: what comes back is a design, and the pause
|
|
433
|
+
# it went through is history the commit states rather than the line.
|
|
434
|
+
rows.append(f" was set aside: {self.was}")
|
|
435
|
+
if self.refreshed:
|
|
436
|
+
rows.append(f" derived {', '.join(self.refreshed)} (dep annotations re-derived)")
|
|
437
|
+
follow = self.requeue(config)
|
|
438
|
+
if follow is not None:
|
|
439
|
+
rows.append(f" requeue {follow}")
|
|
440
|
+
rows += _staging_rows(config.relative(one) for one in wrote)
|
|
441
|
+
rows += _event_rows(self.event(config), " ")
|
|
442
|
+
return "\n".join(rows)
|
|
443
|
+
|
|
444
|
+
def payload(self, config: Config, wrote: Sequence[Path]) -> dict[str, object]:
|
|
445
|
+
"""The same answer as data, saying which of the two acts it was (RK1083)."""
|
|
446
|
+
from roadkeep.rendering import _wrote_json # noqa: PLC0415 - RK260
|
|
447
|
+
|
|
448
|
+
return {
|
|
449
|
+
"id": self.task_id,
|
|
450
|
+
"marker": self.marker,
|
|
451
|
+
# Null on a reconciling call, which places no line โ a `line` there would be an
|
|
452
|
+
# address for a write nobody made (RK1086).
|
|
453
|
+
"roadmap": None
|
|
454
|
+
if self.placed is None
|
|
455
|
+
else {
|
|
456
|
+
"file": config.relative(config.path("roadmap")),
|
|
457
|
+
"line": self.placed.lineno,
|
|
458
|
+
"rendered": self.placed.raw,
|
|
459
|
+
},
|
|
460
|
+
"deferred": {
|
|
461
|
+
"file": config.relative(config.path("deferred")),
|
|
462
|
+
"removed": self.removed_from,
|
|
463
|
+
},
|
|
464
|
+
"was": self.was,
|
|
465
|
+
# Which of the two acts this was (RK1083): a reconciliation removes the store's
|
|
466
|
+
# stale copy and places nothing, so `roadmap.line` is where the line already was
|
|
467
|
+
# rather than where one landed.
|
|
468
|
+
"reconciled": self.reconciled,
|
|
469
|
+
"refreshed": list(self.refreshed),
|
|
470
|
+
# The half of the pause this does not undo (RK327): the entry the pause removed is
|
|
471
|
+
# the author's to put back, because where in the order it belonged is not a fact
|
|
472
|
+
# the store kept.
|
|
473
|
+
"requeue": self.requeue(config),
|
|
474
|
+
**_wrote_json(config, wrote),
|
|
475
|
+
"event": self.event(config),
|
|
476
|
+
}
|
|
477
|
+
|
|
478
|
+
|
|
479
|
+
def defer(config: Config, task_id: str, *, reason: str) -> Pause:
|
|
480
|
+
"""Move one open line to the store. Validates both edits before writing either.
|
|
481
|
+
|
|
482
|
+
Refused when the id is already terminal: an entry in the ledger says the work shipped or
|
|
483
|
+
was abandoned, and pausing it afterwards would make two files disagree about a decision
|
|
484
|
+
that is already recorded. That check is the ledger's own, so it holds whether the entry
|
|
485
|
+
is a โ
or a ๐.
|
|
486
|
+
"""
|
|
487
|
+
if not config.has("deferred"):
|
|
488
|
+
raise NoStore(task_id)
|
|
489
|
+
if _CLOSE in reason:
|
|
490
|
+
raise UnrecoverableReason(reason)
|
|
491
|
+
|
|
492
|
+
backlog = Backlog.load(config)
|
|
493
|
+
roadmap = backlog.roadmap
|
|
494
|
+
entry = roadmap.by_id().get(task_id)
|
|
495
|
+
if entry is None:
|
|
496
|
+
raise NotOpen(
|
|
497
|
+
task_id,
|
|
498
|
+
config.relative(config.path("roadmap")),
|
|
499
|
+
Whereabouts.of(config, task_id),
|
|
500
|
+
)
|
|
501
|
+
_refuse_recorded(config, task_id)
|
|
502
|
+
store = config.document("deferred")
|
|
503
|
+
held = store.by_id().get(task_id)
|
|
504
|
+
if held is not None:
|
|
505
|
+
raise SetAside(task_id, config.relative(config.path("deferred")), held.lineno)
|
|
506
|
+
|
|
507
|
+
marker = config.schema.deferred_marker
|
|
508
|
+
insertion = place(
|
|
509
|
+
store,
|
|
510
|
+
_as_paused(entry.task, marker, reason),
|
|
511
|
+
role="deferred",
|
|
512
|
+
config=config,
|
|
513
|
+
)
|
|
514
|
+
remaining = remove_entry(roadmap, entry)
|
|
515
|
+
# And the queue entry, in the same rewrite (RK327). Worth naming apart from the two
|
|
516
|
+
# terminal doors: the line is still work, so an entry naming it reads as live โ and yet
|
|
517
|
+
# `pick` can never offer a line the store holds, so the tier could only fire on nothing.
|
|
518
|
+
remaining, dequeued = queueing.without(remaining, config, task_id)
|
|
519
|
+
# Derived against the state this write *creates* โ the line is out of the roadmap โ for
|
|
520
|
+
# the same reason a departure does it (RK8): an annotation left un-derived by one door
|
|
521
|
+
# is one nothing else revisits.
|
|
522
|
+
# Both halves of the new state, not just the roadmap: the dependents' annotations are
|
|
523
|
+
# derived from where this id now *is* (RK92), and a refresh reading the store from disk
|
|
524
|
+
# would annotate against a file this transaction has not written yet.
|
|
525
|
+
derived = refresh(replace(backlog, roadmap=remaining, store=insertion.document))
|
|
526
|
+
return Pause(
|
|
527
|
+
task_id=task_id,
|
|
528
|
+
store=insertion,
|
|
529
|
+
roadmap=derived.document,
|
|
530
|
+
removed_from=entry.lineno,
|
|
531
|
+
refreshed=derived.changed,
|
|
532
|
+
marker=marker,
|
|
533
|
+
dequeued=dequeued,
|
|
534
|
+
carried=_carried(config, entry.task.ref),
|
|
535
|
+
dependents=tuple(
|
|
536
|
+
e.task.id for e in derived.document.entries if task_id in e.task.dep_ids
|
|
537
|
+
),
|
|
538
|
+
root=config.root,
|
|
539
|
+
)
|
|
540
|
+
|
|
541
|
+
|
|
542
|
+
def resume(config: Config, task_id: str, *, marker: str | None = None) -> Resumption:
|
|
543
|
+
"""Return one line from the store to its block. The same transaction, backwards.
|
|
544
|
+
|
|
545
|
+
`marker` is the open one the line comes back with, and it defaults to the project's
|
|
546
|
+
first exactly as `add`'s does: the store holds โธ and nothing else (RK96), so which open
|
|
547
|
+
marker the pause set aside is not a fact any file still has, and inventing one would be
|
|
548
|
+
this tool stating a maturity it cannot read.
|
|
549
|
+
"""
|
|
550
|
+
if not config.has("deferred"):
|
|
551
|
+
raise NoStore(task_id)
|
|
552
|
+
|
|
553
|
+
where = config.relative(config.path("deferred"))
|
|
554
|
+
store = config.document("deferred")
|
|
555
|
+
held = store.by_id().get(task_id)
|
|
556
|
+
if held is None:
|
|
557
|
+
raise NotSetAside(task_id, where, elsewhere=Whereabouts.of(config, task_id).sentence)
|
|
558
|
+
_refuse_recorded(config, task_id)
|
|
559
|
+
|
|
560
|
+
backlog = Backlog.load(config)
|
|
561
|
+
open_line = backlog.roadmap.by_id().get(task_id)
|
|
562
|
+
if open_line is not None:
|
|
563
|
+
if marker is not None:
|
|
564
|
+
raise NoPlacement(
|
|
565
|
+
task_id, config.relative(config.path("roadmap")), open_line.lineno
|
|
566
|
+
)
|
|
567
|
+
# The roadmap already says what a resume would write, so the store entry is the
|
|
568
|
+
# stale half and this call removes it (RK1081). The mirror of RK1075 one file over:
|
|
569
|
+
# two governed files disagreeing about one id, resolved towards the one that
|
|
570
|
+
# already states the outcome โ here the open line, there the ledger entry.
|
|
571
|
+
#
|
|
572
|
+
# Refusing was the earlier answer and it left the state with no verb at all: `defer`
|
|
573
|
+
# refuses because the store holds it, `ship` and `retire` *succeed* and leave the id
|
|
574
|
+
# recorded and still paused, and the gate said nothing. What a second line would be
|
|
575
|
+
# โ two answers to when the work comes back โ is what this prevents rather than
|
|
576
|
+
# what it creates, because no line is placed.
|
|
577
|
+
remaining = remove_entry(store, held)
|
|
578
|
+
derived = refresh(replace(backlog, store=remaining))
|
|
579
|
+
return Resumption(
|
|
580
|
+
task_id=task_id,
|
|
581
|
+
roadmap=derived.document,
|
|
582
|
+
placed=None,
|
|
583
|
+
store=remaining,
|
|
584
|
+
removed_from=held.lineno,
|
|
585
|
+
refreshed=tuple(name for name in derived.changed if name != task_id),
|
|
586
|
+
# The line's own, because no marker was chosen here: what this call did is
|
|
587
|
+
# remove a copy, and reporting a marker it did not write would be the
|
|
588
|
+
# placement the sentence above refuses to claim.
|
|
589
|
+
marker=open_line.task.status,
|
|
590
|
+
reconciled=True,
|
|
591
|
+
)
|
|
592
|
+
|
|
593
|
+
status = marker or config.schema.markers[0]
|
|
594
|
+
insertion = place(
|
|
595
|
+
backlog.roadmap,
|
|
596
|
+
_as_open(held.task, status),
|
|
597
|
+
role="roadmap",
|
|
598
|
+
config=config,
|
|
599
|
+
)
|
|
600
|
+
remaining = remove_entry(store, held)
|
|
601
|
+
# The store this write leaves behind, for `defer`'s reason read backwards: a dependent
|
|
602
|
+
# still annotated โธ after the pause ended is the stale cache RK8 exists to prevent.
|
|
603
|
+
derived = refresh(replace(backlog, roadmap=insertion.document, store=remaining))
|
|
604
|
+
returned = next(e for e in derived.document.entries if e.task.id == task_id)
|
|
605
|
+
return Resumption(
|
|
606
|
+
task_id=task_id,
|
|
607
|
+
roadmap=derived.document,
|
|
608
|
+
placed=returned,
|
|
609
|
+
store=remaining,
|
|
610
|
+
removed_from=held.lineno,
|
|
611
|
+
refreshed=tuple(name for name in derived.changed if name != task_id),
|
|
612
|
+
marker=status,
|
|
613
|
+
was=_reason(held.task.why),
|
|
614
|
+
root=config.root,
|
|
615
|
+
)
|
|
616
|
+
|
|
617
|
+
|
|
618
|
+
def _carried(config: Config, ref: str | None) -> Carried | None:
|
|
619
|
+
"""Where the design this pause kept actually is (RK229).
|
|
620
|
+
|
|
621
|
+
Answered on the way past rather than reported as an anchor for the CLI to place, because
|
|
622
|
+
the line naming a file is the one line in the answer whose job is to say where a reader
|
|
623
|
+
goes looking โ and RK96's whole argument for keeping the section is that they can.
|
|
624
|
+
|
|
625
|
+
Every outcome is a sentence and none is a refusal: nothing is being deleted here, so a
|
|
626
|
+
pointer that resolves to nothing or to two files is a pause that worked and a `lint`
|
|
627
|
+
finding the author already owes. Saying so beats a path composed out of the default.
|
|
628
|
+
"""
|
|
629
|
+
if ref is None:
|
|
630
|
+
return None
|
|
631
|
+
anchor = f"ยง{ref}"
|
|
632
|
+
roles = declaring(config, ref)
|
|
633
|
+
if len(roles) == 1:
|
|
634
|
+
return Carried(anchor=anchor, role=roles[0])
|
|
635
|
+
if roles:
|
|
636
|
+
both = " and ".join(config.relative(config.path(role)) for role in roles)
|
|
637
|
+
return Carried(
|
|
638
|
+
anchor=anchor,
|
|
639
|
+
absence=f"declared by {both}, so the pointer names neither",
|
|
640
|
+
)
|
|
641
|
+
# The design's two, not every prose role (RK1361): this pointer is a *task line's*, so a
|
|
642
|
+
# decisions file the project happens to declare is not somewhere its section could be โ
|
|
643
|
+
# naming it would report an absence closed by a `declare` that changes nothing here.
|
|
644
|
+
declared = tuple(role for role in DESIGN_ROLES if config.has(role))
|
|
645
|
+
if not declared:
|
|
646
|
+
return Carried(
|
|
647
|
+
anchor=anchor,
|
|
648
|
+
absence=f"this project declares no {' or '.join(DESIGN_ROLES)} file",
|
|
649
|
+
)
|
|
650
|
+
named = " or ".join(config.relative(config.path(role)) for role in declared)
|
|
651
|
+
return Carried(anchor=anchor, absence=f"not in {named}, so nothing was carried")
|
|
652
|
+
|
|
653
|
+
|
|
654
|
+
def _as_paused(task: Task, marker: str, reason: str) -> Task:
|
|
655
|
+
"""The same task as the store states it: โธ, the reason wrapped around the design."""
|
|
656
|
+
return replace(
|
|
657
|
+
task,
|
|
658
|
+
status=marker,
|
|
659
|
+
why=f"{_OPEN}{reason}{_CLOSE}{task.why}",
|
|
660
|
+
# At column zero, for `ship`'s reason (RK49): the indent named a roadmap line this
|
|
661
|
+
# one was nested under, and that line is not in the store.
|
|
662
|
+
indent="",
|
|
663
|
+
)
|
|
664
|
+
|
|
665
|
+
|
|
666
|
+
def _as_open(task: Task, marker: str) -> Task:
|
|
667
|
+
"""The same task as the roadmap states it again, with this module's prefix removed."""
|
|
668
|
+
return replace(task, status=marker, why=_unwrapped(task.why))
|
|
669
|
+
|
|
670
|
+
|
|
671
|
+
#: The reason a pause recorded, and the author's sentence without it. Both moved to the kernel
|
|
672
|
+
#: by RK1115, where the rule that measures a paused `why` reads them too โ named here because
|
|
673
|
+
#: this module is where the wrapping is composed, and a reader of `defer` looks for them here.
|
|
674
|
+
_reason = pause_reason
|
|
675
|
+
_unwrapped = authored_why
|
|
676
|
+
|
|
677
|
+
|
|
678
|
+
def _refuse_recorded(config: Config, task_id: str) -> None:
|
|
679
|
+
"""A pause is between open and terminal, so an id the ledger holds has neither door.
|
|
680
|
+
|
|
681
|
+
**Except the one pair this tool writes on purpose** (RK1215). `ship --part` records a
|
|
682
|
+
qualified half and leaves the line open at โณ, and this asked only *does the ledger hold
|
|
683
|
+
the id* โ so a line whose remainder waits on a decision, which is the case the store
|
|
684
|
+
exists for, was refused with :class:`~roadkeep.shipping.AlreadyRecorded`: the ledger's own
|
|
685
|
+
sentence, about a second entry neither of these two verbs would write.
|
|
686
|
+
|
|
687
|
+
:attr:`~roadkeep.kernel.schema.Task.in_halves` and never a second test of the qualifier,
|
|
688
|
+
which is the field :func:`~roadkeep.authoring._refuse_sibling_status` and
|
|
689
|
+
:func:`~roadkeep.linting._carried` already read for this pair โ so the door, the gate and
|
|
690
|
+
the pause cannot disagree about a state one of them creates (RK1080, RK1114).
|
|
691
|
+
"""
|
|
692
|
+
if not config.has("changelog") or not config.path("changelog").is_file():
|
|
693
|
+
return
|
|
694
|
+
recorded = config.document("changelog").by_id().get(task_id)
|
|
695
|
+
if recorded is None or recorded.task.in_halves:
|
|
696
|
+
return
|
|
697
|
+
# Imported here rather than at module scope: the two write paths are peers, and this is
|
|
698
|
+
# the one fact one of them owns about the other โ the ledger's refusal, in its words.
|
|
699
|
+
from roadkeep.shipping import AlreadyRecorded
|
|
700
|
+
|
|
701
|
+
raise AlreadyRecorded(
|
|
702
|
+
task_id,
|
|
703
|
+
config.relative(config.path("changelog")),
|
|
704
|
+
recorded.lineno,
|
|
705
|
+
recorded.task.status,
|
|
706
|
+
)
|
|
707
|
+
|
|
708
|
+
|