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
|
@@ -0,0 +1,819 @@
|
|
|
1
|
+
"""The verbs a task leaves by, and the two reads only the ledger can answer (RK494).
|
|
2
|
+
|
|
3
|
+
`ship`, `retire` and the `record` family write the terminal entry; `delivered` and
|
|
4
|
+
`reversals` read it back — what a block already shipped, and which of those deliveries was
|
|
5
|
+
later undone. Filed by their subject, an entry in the ledger, and not by whether they write
|
|
6
|
+
one: a proposal is checked against both, and the two reads come before it, not after.
|
|
7
|
+
|
|
8
|
+
**Every write here renders both registers off its own record** (RK1170), so each door is the
|
|
9
|
+
call, the save and a choice of reading — and this module no longer imports `rendering` at all.
|
|
10
|
+
The two reads still compose their answers here, which is the rest of that task.
|
|
11
|
+
"""
|
|
12
|
+
|
|
13
|
+
from __future__ import annotations
|
|
14
|
+
|
|
15
|
+
import argparse
|
|
16
|
+
import json
|
|
17
|
+
import sys
|
|
18
|
+
from collections.abc import Sequence
|
|
19
|
+
|
|
20
|
+
from roadkeep.backlog import Backlog, Stage
|
|
21
|
+
from roadkeep.config import Config
|
|
22
|
+
from roadkeep.kernel.document import declares, shading
|
|
23
|
+
from roadkeep.ranking import NEAREST, nearest
|
|
24
|
+
from roadkeep.reverting import Reversed, reversals
|
|
25
|
+
from roadkeep.shipping import (
|
|
26
|
+
Delivered,
|
|
27
|
+
Closure,
|
|
28
|
+
Partial,
|
|
29
|
+
amend as amend_record,
|
|
30
|
+
drop as drop_record,
|
|
31
|
+
move as move_record,
|
|
32
|
+
readdress as readdress_record,
|
|
33
|
+
record,
|
|
34
|
+
retire,
|
|
35
|
+
ship,
|
|
36
|
+
)
|
|
37
|
+
from roadkeep.serving import Prose
|
|
38
|
+
from roadkeep.verbs.declaring import (
|
|
39
|
+
_JSON_HELP,
|
|
40
|
+
_PIPE,
|
|
41
|
+
_reason_flag,
|
|
42
|
+
withheld,
|
|
43
|
+
)
|
|
44
|
+
from roadkeep.verbs.reading import _piped
|
|
45
|
+
from roadkeep.verbs.refusing import EXIT_GATE, EXIT_OK, EXIT_USAGE, REFUSALS, _refused
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
def _ship(config: Config, args: argparse.Namespace) -> int:
|
|
50
|
+
if args.remainder is not None and args.part is None:
|
|
51
|
+
# Refused rather than ignored (RK465, RK1233): a remainder on a whole shipment is a
|
|
52
|
+
# sentence about a line that is being removed, and honouring it silently would write
|
|
53
|
+
# the caller's words into a `why` the same transaction then deletes.
|
|
54
|
+
print(
|
|
55
|
+
"roadkeep: --remainder is what is left after --part, and this ship removes the "
|
|
56
|
+
"line: pass --part <what landed> too, or leave it off",
|
|
57
|
+
file=sys.stderr,
|
|
58
|
+
)
|
|
59
|
+
return EXIT_USAGE
|
|
60
|
+
try:
|
|
61
|
+
shipment = ship(
|
|
62
|
+
config,
|
|
63
|
+
args.id,
|
|
64
|
+
# Resolved by `dispatch` from what this verb's parser declares (RK1176), and no
|
|
65
|
+
# longer here: a call site that reads the pipe for one argument is a call site that
|
|
66
|
+
# can be written without it, which is how `--superseded-design` published a dash.
|
|
67
|
+
why=args.why,
|
|
68
|
+
part=args.part,
|
|
69
|
+
remainder=args.remainder,
|
|
70
|
+
lines=args.lines,
|
|
71
|
+
superseded=args.superseded_design,
|
|
72
|
+
recorded_in=args.recorded_in,
|
|
73
|
+
decides=args.decides,
|
|
74
|
+
decides_ref=args.decides_ref,
|
|
75
|
+
)
|
|
76
|
+
# The files this transaction wrote, answered by the write itself (RK309) — the half
|
|
77
|
+
# of the commit's contents no author declares, and never a second list rebuilt here.
|
|
78
|
+
wrote = shipment.save()
|
|
79
|
+
except REFUSALS as error:
|
|
80
|
+
return _refused(error)
|
|
81
|
+
|
|
82
|
+
if isinstance(shipment, Partial):
|
|
83
|
+
# Nothing was removed and nothing was dropped, so the departure's report would be
|
|
84
|
+
# three lines of None (RK121): what happened is an entry and a marker.
|
|
85
|
+
return _partly(config, shipment, args)
|
|
86
|
+
if isinstance(shipment, Closure):
|
|
87
|
+
# The ledger already holds the entry, so there is none to report (RK62): what this
|
|
88
|
+
# call did is remove the line that was left behind, and the evidence is where the
|
|
89
|
+
# entry already was.
|
|
90
|
+
return _closed(config, shipment, args, wrote)
|
|
91
|
+
|
|
92
|
+
if args.json:
|
|
93
|
+
print(json.dumps(shipment.payload(config, wrote), indent=2))
|
|
94
|
+
else:
|
|
95
|
+
print(shipment.stated(config, wrote))
|
|
96
|
+
return EXIT_OK
|
|
97
|
+
|
|
98
|
+
|
|
99
|
+
def _partly(config: Config, partial: Partial, args: argparse.Namespace) -> int:
|
|
100
|
+
"""Half of a task recorded, with its roadmap line still open (RK121)."""
|
|
101
|
+
if args.json:
|
|
102
|
+
print(json.dumps(partial.payload(config), indent=2))
|
|
103
|
+
else:
|
|
104
|
+
print(partial.stated(config))
|
|
105
|
+
return EXIT_OK
|
|
106
|
+
|
|
107
|
+
|
|
108
|
+
def _closed(
|
|
109
|
+
config: Config, closure: Closure, args: argparse.Namespace, wrote: Sequence[str] = ()
|
|
110
|
+
) -> int:
|
|
111
|
+
"""A roadmap line closed against an entry the ledger already had (RK62)."""
|
|
112
|
+
if args.json:
|
|
113
|
+
print(json.dumps(closure.payload(config, wrote), indent=2))
|
|
114
|
+
else:
|
|
115
|
+
print(closure.stated(config, wrote))
|
|
116
|
+
return EXIT_OK
|
|
117
|
+
|
|
118
|
+
|
|
119
|
+
def _record(config: Config, args: argparse.Namespace) -> int:
|
|
120
|
+
try:
|
|
121
|
+
entry = record(
|
|
122
|
+
config,
|
|
123
|
+
block=args.block,
|
|
124
|
+
symptom=args.symptom,
|
|
125
|
+
why=_piped(args.why),
|
|
126
|
+
task_id=args.task_id,
|
|
127
|
+
supersedes=args.supersedes,
|
|
128
|
+
lines=args.lines,
|
|
129
|
+
)
|
|
130
|
+
wrote = entry.save()
|
|
131
|
+
except REFUSALS as error:
|
|
132
|
+
return _refused(error)
|
|
133
|
+
|
|
134
|
+
if args.json:
|
|
135
|
+
print(json.dumps(entry.payload(config, wrote), indent=2))
|
|
136
|
+
else:
|
|
137
|
+
print(entry.stated(config, wrote))
|
|
138
|
+
return EXIT_OK
|
|
139
|
+
|
|
140
|
+
|
|
141
|
+
def _record_amend(config: Config, args: argparse.Namespace) -> int:
|
|
142
|
+
if args.why is None and args.part is None:
|
|
143
|
+
print("roadkeep: nothing to amend: pass --why or --part", file=sys.stderr)
|
|
144
|
+
return EXIT_USAGE
|
|
145
|
+
try:
|
|
146
|
+
# One read joined to the listing, not a second parse: `reversals` walks the same
|
|
147
|
+
# entries for the same clause, so asking it here is what keeps the two answers one
|
|
148
|
+
# fact (RK1042). Asked **before** the write and not after (RK1052): the mark lives
|
|
149
|
+
# inside the `why` this command is about to replace, so the post-write state cannot
|
|
150
|
+
# answer whether the entry being corrected had been undone. The parse is the one
|
|
151
|
+
# `amend` is about to make of the same bytes, so this costs a cache hit.
|
|
152
|
+
undone_by = {one.undone: one.by for one in reversals(config)}.get(args.id)
|
|
153
|
+
corrected = amend_record(
|
|
154
|
+
config, args.id, why=_piped(args.why), part=args.part, lines=args.lines
|
|
155
|
+
)
|
|
156
|
+
wrote = corrected.save()
|
|
157
|
+
except REFUSALS as error:
|
|
158
|
+
return _refused(error)
|
|
159
|
+
|
|
160
|
+
if args.json:
|
|
161
|
+
print(json.dumps(corrected.payload(config, wrote, undone_by), indent=2))
|
|
162
|
+
else:
|
|
163
|
+
print(corrected.stated(config, wrote, undone_by))
|
|
164
|
+
return EXIT_OK
|
|
165
|
+
|
|
166
|
+
|
|
167
|
+
def _record_move(config: Config, args: argparse.Namespace) -> int:
|
|
168
|
+
try:
|
|
169
|
+
refiled = move_record(config, args.id, to_block=args.to_block)
|
|
170
|
+
# Nothing is written where the entry already sits under that heading, so nothing is
|
|
171
|
+
# staged either: an empty list is the honest answer and `_print_staging` says nothing.
|
|
172
|
+
wrote = refiled.save() if refiled.moved else ()
|
|
173
|
+
except REFUSALS as error:
|
|
174
|
+
return _refused(error)
|
|
175
|
+
|
|
176
|
+
if args.json:
|
|
177
|
+
print(json.dumps(refiled.payload(config, wrote), indent=2))
|
|
178
|
+
else:
|
|
179
|
+
print(refiled.stated(config, wrote))
|
|
180
|
+
return EXIT_OK
|
|
181
|
+
|
|
182
|
+
|
|
183
|
+
def _record_renumber(config: Config, args: argparse.Namespace) -> int:
|
|
184
|
+
try:
|
|
185
|
+
moved = readdress_record(config, args.id, lineno=args.line, to=args.to)
|
|
186
|
+
wrote = moved.save()
|
|
187
|
+
except REFUSALS as error:
|
|
188
|
+
return _refused(error)
|
|
189
|
+
|
|
190
|
+
if args.json:
|
|
191
|
+
print(json.dumps(moved.payload(config, wrote), indent=2))
|
|
192
|
+
else:
|
|
193
|
+
print(moved.stated(config, wrote))
|
|
194
|
+
return EXIT_OK
|
|
195
|
+
|
|
196
|
+
|
|
197
|
+
def _record_drop(config: Config, args: argparse.Namespace) -> int:
|
|
198
|
+
try:
|
|
199
|
+
dropped = drop_record(config, args.id, lineno=args.line)
|
|
200
|
+
wrote = dropped.save()
|
|
201
|
+
except REFUSALS as error:
|
|
202
|
+
return _refused(error)
|
|
203
|
+
|
|
204
|
+
if args.json:
|
|
205
|
+
print(json.dumps(dropped.payload(config, wrote), indent=2))
|
|
206
|
+
else:
|
|
207
|
+
print(dropped.stated(config, wrote))
|
|
208
|
+
return EXIT_OK
|
|
209
|
+
|
|
210
|
+
|
|
211
|
+
def _delivered(config: Config, args: argparse.Namespace) -> int:
|
|
212
|
+
"""Every claim this block has already made good on (RK385).
|
|
213
|
+
|
|
214
|
+
**Symptoms and not entries.** A shipped line states two things — the problem it claimed
|
|
215
|
+
and the outcome it delivered — and a duplicate collides with the first. Printing both
|
|
216
|
+
doubles a read the author makes before every proposal, and the second half is the one
|
|
217
|
+
that never matches: an outcome is written in the vocabulary of the fix.
|
|
218
|
+
|
|
219
|
+
Unbounded, unlike `brief`'s carry of the non-goals (RK68). The bound there is what keeps
|
|
220
|
+
a *brief* an answer rather than the file; here the list **is** the answer, and a
|
|
221
|
+
truncated one is the failure mode this exists for — the entry that got elided is exactly
|
|
222
|
+
the one nobody read.
|
|
223
|
+
|
|
224
|
+
`--near` is the one bound, and it is not a truncation of this listing (RK442): it is the
|
|
225
|
+
same read asked a **narrower question**, so what bounds it is the sentence the caller
|
|
226
|
+
passed rather than a number this verb chose. That is the whole difference — an elision
|
|
227
|
+
picks entries to drop and this picks the entries that answer — and it is why the header
|
|
228
|
+
says how many of how many, why the plain listing is named beside it, and why the order
|
|
229
|
+
is published with no score under it (RK441).
|
|
230
|
+
|
|
231
|
+
Retired lines are in it. A claim that was abandoned is still a claim somebody made and
|
|
232
|
+
argued about, and a proposal restating one wants the argument more than the outcome —
|
|
233
|
+
the marker says which, so nothing is hidden and nothing is conflated.
|
|
234
|
+
|
|
235
|
+
**The label is resolved before the ledger is filtered (RK433).** This answer is consumed
|
|
236
|
+
as *evidence* — it is the read that decides whether an `add` is a duplicate — so the one
|
|
237
|
+
thing it may not do is come back empty for a question it never asked. Filtering the
|
|
238
|
+
entries by a literal made `Block Z has delivered nothing yet` the answer to four
|
|
239
|
+
different states: a block still being worked, whose lines are open and none of them
|
|
240
|
+
shipped; one whose work is all set aside; a heading opened before its lines; and a letter
|
|
241
|
+
the project has never used. Only the fourth is a mistake, and it is the one that files
|
|
242
|
+
the duplicate this verb exists to prevent. So :meth:`~roadkeep.backlog.Backlog.standing`
|
|
243
|
+
runs first and its sentence rides with every answer, empty or not: the count is a fact
|
|
244
|
+
about the ledger, the state is the fact about the label, and they say the same thing in
|
|
245
|
+
one of the four states only.
|
|
246
|
+
|
|
247
|
+
That sentence goes to **stdout** and on every state, which is where this parts company
|
|
248
|
+
with `_print_standing` (RK429) and for two reasons that are this verb's own. Stdout,
|
|
249
|
+
because there is no raw-file pipe to keep clean here — the header and the rows are
|
|
250
|
+
already derived, reformatted text rather than the file's own lines. Unconditionally,
|
|
251
|
+
because `Standing.settled` answers *which states an empty answer needs explaining by*,
|
|
252
|
+
and nothing filtered this one: the state of the label is the whole reason the count is
|
|
253
|
+
what it is, and three entries under a finished block is a different read from three under
|
|
254
|
+
a live one. `standing.recorded` and the length of the listing are the same number by
|
|
255
|
+
construction — both are `Document.block(label)` — so the figure printed twice is one
|
|
256
|
+
fact stated twice on purpose.
|
|
257
|
+
|
|
258
|
+
`unknown` exits **2**, never 0 or 1. Two, because `pick --block <x>`, `brief --block <x>`
|
|
259
|
+
and `list --block <x>` already answer a label nothing declares that way, and one meaning
|
|
260
|
+
per code is what a loop can branch on. Not one: in this tool 1 is a verdict about the
|
|
261
|
+
repository's own contents, and `_may_offer` reads a read-only 1 as exactly that (RK86) —
|
|
262
|
+
it would drop the capture offer a mistyped argv should keep. `--json` gets the refusal
|
|
263
|
+
and no payload, which is the line RK409 drew: a finished block is an answer and deserves
|
|
264
|
+
a shape, a name nothing declares is a refusal on every surface.
|
|
265
|
+
|
|
266
|
+
The header and the state row take `Standing.named` rather than an f-string (RK75):
|
|
267
|
+
`heading_word` is per project, and a report saying `Block G` to a project whose headings
|
|
268
|
+
all say `Track` names nothing its author wrote. That is fixed for this verb and not for
|
|
269
|
+
the file — the other reports here still spell it from a literal.
|
|
270
|
+
"""
|
|
271
|
+
try:
|
|
272
|
+
backlog = Backlog.load(config)
|
|
273
|
+
except (KeyError, OSError) as error:
|
|
274
|
+
return _refused(error)
|
|
275
|
+
|
|
276
|
+
ledger = backlog.ledger
|
|
277
|
+
if ledger is None:
|
|
278
|
+
print(
|
|
279
|
+
"roadkeep: this project declares no changelog, so nothing records what was "
|
|
280
|
+
"delivered — `non-goal list` is the other read before an `add`",
|
|
281
|
+
file=sys.stderr,
|
|
282
|
+
)
|
|
283
|
+
return EXIT_USAGE
|
|
284
|
+
label = args.block.strip()
|
|
285
|
+
standing = backlog.standing(label)
|
|
286
|
+
if standing.stage is Stage.UNKNOWN:
|
|
287
|
+
declared = sorted(backlog.declared_blocks())
|
|
288
|
+
# Printed here rather than raised through `_refused`: this refusal is composed and
|
|
289
|
+
# never raised, and `provenance.witness` on an exception carrying no traceback
|
|
290
|
+
# records `()` — which is not `None`, so `_answered` would take it as evidence and
|
|
291
|
+
# suppress the inventory RK267 reserves for exactly this case. The sibling refusal
|
|
292
|
+
# above, for a project that declares no changelog, already exits this way.
|
|
293
|
+
print(
|
|
294
|
+
f"roadkeep: {standing.sentence}{declares(declared)}: the ledger was not read, "
|
|
295
|
+
f"so this is not a block that delivered nothing{shading(label, declared)}",
|
|
296
|
+
file=sys.stderr,
|
|
297
|
+
)
|
|
298
|
+
return EXIT_USAGE
|
|
299
|
+
# `Document.block` and not a filter written here: it is the same call `Standing.of`
|
|
300
|
+
# makes, which is what makes this count and `standing.recorded` one number rather than
|
|
301
|
+
# two that agree.
|
|
302
|
+
entries = ledger.block(label)
|
|
303
|
+
# RK442: the whole block is what this verb answered with, and the question is whether one
|
|
304
|
+
# sentence collides with it. Ranked here rather than inside the reader, because the
|
|
305
|
+
# ordering is a property of the *query* and the block is the fact — and the unranked
|
|
306
|
+
# tuple stays exactly what it was, so `--near` narrows one answer and does not make a
|
|
307
|
+
# second one. `recorded` below is still the block's count, never the shown count.
|
|
308
|
+
recorded = len(entries)
|
|
309
|
+
if args.near is not None and not args.near.strip():
|
|
310
|
+
# An empty `--near` used to fall through to the unbounded listing, which answers a
|
|
311
|
+
# *different question* than the one asked and looks like the narrow answer until the
|
|
312
|
+
# caller counts the rows: 103 lines where five were asked for. Every prose argument
|
|
313
|
+
# in this tool refuses the empty slot, and a read is where it costs the most —
|
|
314
|
+
# nothing exits non-zero, so a wrong answer is the only signal there is.
|
|
315
|
+
print(
|
|
316
|
+
"roadkeep: --near is the symptom you are about to propose, and it arrived "
|
|
317
|
+
"empty: pass the sentence, or drop the flag for the whole block",
|
|
318
|
+
file=sys.stderr,
|
|
319
|
+
)
|
|
320
|
+
return EXIT_USAGE
|
|
321
|
+
if args.near:
|
|
322
|
+
entries = tuple(
|
|
323
|
+
entries[index]
|
|
324
|
+
for index in nearest(args.near, [e.task.symptom for e in entries], NEAREST)
|
|
325
|
+
)
|
|
326
|
+
where = config.relative(config.path("changelog"))
|
|
327
|
+
# One read joined to the listing, not a second parse: `reversals` walks the same entries
|
|
328
|
+
# for the same clause, so asking it here is what keeps the two answers one fact (RK1042).
|
|
329
|
+
answer = Delivered(
|
|
330
|
+
where=where,
|
|
331
|
+
standing=standing,
|
|
332
|
+
entries=entries,
|
|
333
|
+
recorded=recorded,
|
|
334
|
+
near=args.near or "",
|
|
335
|
+
reversed_by={one.undone: one.by for one in reversals(config)},
|
|
336
|
+
)
|
|
337
|
+
# Both registers off one result (RK1170). This is the read that decides whether an `add` is
|
|
338
|
+
# a duplicate, so the two had better say the same thing — and they were a printer and a
|
|
339
|
+
# payload builder in this handler, agreeing by hand over a header, a bound and a per-entry
|
|
340
|
+
# mark. The payload now carries what the listing shows by construction.
|
|
341
|
+
print(json.dumps(answer.payload(), indent=2) if args.json else answer)
|
|
342
|
+
return EXIT_OK
|
|
343
|
+
|
|
344
|
+
|
|
345
|
+
def _reversals(config: Config, args: argparse.Namespace) -> int:
|
|
346
|
+
"""What the ledger already undid (RK416), and with `--id` whether one thing is among it.
|
|
347
|
+
|
|
348
|
+
`--id` exits 1 rather than 0 for a reason the plain listing does not need: the caller is
|
|
349
|
+
a script or an agent about to spend an id, and an exit code is what it can branch on
|
|
350
|
+
without reading either stream. Exit 1 is "this was tried and undone" and never "you may
|
|
351
|
+
not" — the read states a fact, and whether the revert was about a broken implementation
|
|
352
|
+
or a wrong idea is the one thing nobody here can tell.
|
|
353
|
+
"""
|
|
354
|
+
try:
|
|
355
|
+
found = reversals(config)
|
|
356
|
+
except (KeyError, OSError) as error:
|
|
357
|
+
return _refused(error)
|
|
358
|
+
|
|
359
|
+
if args.task_id:
|
|
360
|
+
found = tuple(one for one in found if one.undone == args.task_id)
|
|
361
|
+
answer = Reversed(
|
|
362
|
+
found=found,
|
|
363
|
+
where=config.relative(config.path("changelog")),
|
|
364
|
+
root=config.root.as_posix(),
|
|
365
|
+
asked=args.task_id or "",
|
|
366
|
+
)
|
|
367
|
+
|
|
368
|
+
if args.json:
|
|
369
|
+
print(json.dumps(answer.payload(), indent=2))
|
|
370
|
+
else:
|
|
371
|
+
print(answer.stated())
|
|
372
|
+
return EXIT_GATE if answer.gated else EXIT_OK
|
|
373
|
+
|
|
374
|
+
|
|
375
|
+
def _supersede(config: Config, args: argparse.Namespace) -> int:
|
|
376
|
+
"""The one door a decision leaves by (RK1274), which is not a departure from a backlog.
|
|
377
|
+
|
|
378
|
+
Nothing is deleted and nothing is composed: both entries stay, the marker says which is
|
|
379
|
+
live, and the clause naming the replacement is derived — so this handler passes two ids
|
|
380
|
+
and reads the answer off the record like every other write here.
|
|
381
|
+
"""
|
|
382
|
+
from roadkeep.shipping import supersede # noqa: PLC0415 - RK260
|
|
383
|
+
|
|
384
|
+
try:
|
|
385
|
+
found = supersede(config, args.id, by=args.by)
|
|
386
|
+
wrote = found.save()
|
|
387
|
+
except REFUSALS as error:
|
|
388
|
+
return _refused(error)
|
|
389
|
+
|
|
390
|
+
if args.json:
|
|
391
|
+
print(json.dumps(found.payload(config, wrote), indent=2))
|
|
392
|
+
else:
|
|
393
|
+
print(found.stated(config, wrote))
|
|
394
|
+
return EXIT_OK
|
|
395
|
+
|
|
396
|
+
|
|
397
|
+
def _retire(config: Config, args: argparse.Namespace) -> int:
|
|
398
|
+
"""Record a line leaving without shipping, and say where its replacement is (RK32, RK244).
|
|
399
|
+
|
|
400
|
+
Both registers come off the record (RK1170) — the *retirement* pair, one shape carrying two
|
|
401
|
+
doors' answers. The replacement's id moved onto it with them: reading it back off argv was
|
|
402
|
+
the verb answering about the call it received rather than the transaction it made.
|
|
403
|
+
"""
|
|
404
|
+
try:
|
|
405
|
+
departure = retire(
|
|
406
|
+
config,
|
|
407
|
+
args.id,
|
|
408
|
+
reason=_piped(args.reason),
|
|
409
|
+
superseded_by=args.superseded_by,
|
|
410
|
+
)
|
|
411
|
+
wrote = departure.save()
|
|
412
|
+
except REFUSALS as error:
|
|
413
|
+
return _refused(error)
|
|
414
|
+
|
|
415
|
+
if args.json:
|
|
416
|
+
print(json.dumps(departure.retirement(config, wrote), indent=2))
|
|
417
|
+
else:
|
|
418
|
+
print(departure.retired(config, wrote))
|
|
419
|
+
return EXIT_OK
|
|
420
|
+
|
|
421
|
+
|
|
422
|
+
def declare_departures(subcommands: argparse._SubParsersAction) -> None:
|
|
423
|
+
"""This module's verbs, declared where their handlers are (RK1171).
|
|
424
|
+
|
|
425
|
+
`build_parser` called forty-nine blocks like these in a row; what it calls now is an index
|
|
426
|
+
over the modules that own them. The move is what RK1169 and RK1170 bought: the flags a verb
|
|
427
|
+
declares, the reasons it withholds and the record it answers with are one file's, so a
|
|
428
|
+
change to any of them is one file's too.
|
|
429
|
+
|
|
430
|
+
The order inside is `build_parser`'s own, which is where these blocks sat.
|
|
431
|
+
"""
|
|
432
|
+
ship_parser = subcommands.add_parser(
|
|
433
|
+
"ship",
|
|
434
|
+
help="move a task to the ledger, drop its rationale, clear the roadmap line",
|
|
435
|
+
description=(
|
|
436
|
+
"Ship one task in three edits across three files. Everything is validated "
|
|
437
|
+
"before anything is written, because whichever of the three is done by hand "
|
|
438
|
+
"last is the one that gets forgotten. `--why` is the outcome and is required: "
|
|
439
|
+
"the roadmap's sentence states the problem, and inheriting it files a defect "
|
|
440
|
+
"report under a heading that means done."
|
|
441
|
+
),
|
|
442
|
+
)
|
|
443
|
+
ship_parser.add_argument("id", help="the task to ship, e.g. RK5")
|
|
444
|
+
ship_parser.add_argument(
|
|
445
|
+
"--why",
|
|
446
|
+
help=(
|
|
447
|
+
"the outcome this shipped — required where an entry is written, because the "
|
|
448
|
+
"roadmap's sentence states a problem and is not inherited; refused where the "
|
|
449
|
+
"ledger already holds the id and this call only closes the line. Completing a "
|
|
450
|
+
"wrapped partial with --lines above one, it is the whole span: the first line "
|
|
451
|
+
"is the outcome and the rest is written back as the tail" + _PIPE
|
|
452
|
+
),
|
|
453
|
+
)
|
|
454
|
+
ship_parser.add_argument(
|
|
455
|
+
"--part",
|
|
456
|
+
help=(
|
|
457
|
+
"record only the half that landed and leave the line open, e.g. 'local "
|
|
458
|
+
"half'; a later ship with no --part completes it"
|
|
459
|
+
),
|
|
460
|
+
)
|
|
461
|
+
# The open half, as data (RK1233). Beside `--part` and narrowed to it, because a
|
|
462
|
+
# remainder on a whole shipment is a sentence about a line that is being removed.
|
|
463
|
+
ship_parser.add_argument(
|
|
464
|
+
"--remainder",
|
|
465
|
+
help="what is still left, with --part: it becomes the open line's why",
|
|
466
|
+
)
|
|
467
|
+
ship_parser.add_argument(
|
|
468
|
+
"--lines",
|
|
469
|
+
type=int,
|
|
470
|
+
help=(
|
|
471
|
+
"how many lines the completion replaces; required where the partial entry it "
|
|
472
|
+
"completes wraps, and refused where this call replaces no entry — above one it "
|
|
473
|
+
"is also what lets --why carry that span back instead of collapsing it"
|
|
474
|
+
),
|
|
475
|
+
)
|
|
476
|
+
ship_parser.add_argument(
|
|
477
|
+
"--superseded-design",
|
|
478
|
+
help=(
|
|
479
|
+
"what the design this deletes turned out to be wrong about, e.g. 'the resize "
|
|
480
|
+
"endpoint it called a new subsystem had shipped two blocks earlier'; appended "
|
|
481
|
+
"to the ledger's sentence with the section's address, since the entry is the "
|
|
482
|
+
"one place both survive the deletion" + _PIPE
|
|
483
|
+
),
|
|
484
|
+
)
|
|
485
|
+
# RK1267. No pipe: a path carries nothing a shell reads first, and the clause around it
|
|
486
|
+
# is derived, so there is no prose here for stdin to be the door to.
|
|
487
|
+
ship_parser.add_argument(
|
|
488
|
+
"--recorded-in",
|
|
489
|
+
dest="recorded_in",
|
|
490
|
+
help="the file the deleted design's durable half moved to; must resolve",
|
|
491
|
+
)
|
|
492
|
+
# RK1269. It reads the pipe for `--why`'s reason: a constraint names types, files and
|
|
493
|
+
# prior ids, so it carries the backtick and the apostrophe a shell reads first.
|
|
494
|
+
ship_parser.add_argument(
|
|
495
|
+
"--decides",
|
|
496
|
+
help=(
|
|
497
|
+
"the constraint the deleted design leaves behind, filed as one line in the "
|
|
498
|
+
"decisions role" + _PIPE
|
|
499
|
+
),
|
|
500
|
+
)
|
|
501
|
+
# RK1363. The address of the body that record keeps, on a project whose anchors are its
|
|
502
|
+
# own numbering. No pipe: it is an address and not prose, so nothing a shell eats is in it.
|
|
503
|
+
ship_parser.add_argument(
|
|
504
|
+
"--decides-ref",
|
|
505
|
+
dest="decides_ref",
|
|
506
|
+
metavar="ANCHOR",
|
|
507
|
+
help=(
|
|
508
|
+
"where the decision's body goes, as an outline anchor — required beside "
|
|
509
|
+
"--decides where `ref_scheme = \"outline\"` and refused where the anchor is the "
|
|
510
|
+
"id; `anchors --role decisions --next` names a free one"
|
|
511
|
+
),
|
|
512
|
+
)
|
|
513
|
+
ship_parser.add_argument("--json", action="store_true", help="every edit, as data")
|
|
514
|
+
ship_parser.set_defaults(
|
|
515
|
+
handler=_ship,
|
|
516
|
+
reads_stdin=(
|
|
517
|
+
Prose(dest="why", omitted=False),
|
|
518
|
+
# The argument RK1176 was filed about: the pipe is documented on every prose
|
|
519
|
+
# argument, and this one reached the ledger as a literal `-` because the handler
|
|
520
|
+
# resolved `--why` by hand and this was added after that line was written.
|
|
521
|
+
Prose(dest="superseded_design", omitted=False),
|
|
522
|
+
# RK1269, and declared here rather than remembered: a prose argument that is not
|
|
523
|
+
# on this tuple is one the pipe silently does not reach.
|
|
524
|
+
Prose(dest="decides", omitted=False),
|
|
525
|
+
),
|
|
526
|
+
)
|
|
527
|
+
|
|
528
|
+
record_parser = subcommands.add_parser(
|
|
529
|
+
"record",
|
|
530
|
+
help="write, correct, re-file, renumber or drop a ledger entry directly",
|
|
531
|
+
description=(
|
|
532
|
+
"The ledger's own doors, the ones the roadmap's are not: every other command "
|
|
533
|
+
"starts from a task line, and these start from the entry."
|
|
534
|
+
),
|
|
535
|
+
)
|
|
536
|
+
entries = record_parser.add_subparsers(dest="action", required=True)
|
|
537
|
+
|
|
538
|
+
record_add = entries.add_parser(
|
|
539
|
+
"add",
|
|
540
|
+
help="write a ledger entry directly, for shipped work no open line can carry",
|
|
541
|
+
description=(
|
|
542
|
+
"The fourth door, and the only one that starts nowhere: `ship` and both "
|
|
543
|
+
"retirements begin from an open roadmap line, so this is how the ledger records "
|
|
544
|
+
"work that has none. Never planned is one case and not the definition — a task "
|
|
545
|
+
"that was planned and shipped inside another's sentence needs its own entry too, "
|
|
546
|
+
"and so does a revert (--supersedes). What it does is write the entry and touch "
|
|
547
|
+
"nothing else; without it the only route in was a fictitious line shipped in the "
|
|
548
|
+
"same breath, which teaches that the format can be gamed."
|
|
549
|
+
),
|
|
550
|
+
)
|
|
551
|
+
record_add.add_argument("--block", required=True, help="the block label, e.g. B")
|
|
552
|
+
record_add.add_argument(
|
|
553
|
+
"--symptom",
|
|
554
|
+
required=True,
|
|
555
|
+
help="what did not work — a phrase, never the name of the patch that closed it",
|
|
556
|
+
)
|
|
557
|
+
record_add.add_argument(
|
|
558
|
+
"--why",
|
|
559
|
+
required=True,
|
|
560
|
+
help="one sentence, ending in a stop: the outcome" + _PIPE,
|
|
561
|
+
)
|
|
562
|
+
record_add.add_argument(
|
|
563
|
+
"--id",
|
|
564
|
+
dest="task_id",
|
|
565
|
+
help=(
|
|
566
|
+
"the id (default: derived, one past the highest anywhere); refused where a "
|
|
567
|
+
"line already holds it, allowed where only a sentence names it — which is how "
|
|
568
|
+
"an id cited but never recorded gets the entry it is missing"
|
|
569
|
+
),
|
|
570
|
+
)
|
|
571
|
+
record_add.add_argument(
|
|
572
|
+
"--supersedes",
|
|
573
|
+
metavar="ID",
|
|
574
|
+
help=(
|
|
575
|
+
"the entry this one reverts: its sentence gains `(superseded by <id>)` in the "
|
|
576
|
+
"same write, so the ledger's two records of one decision know about each other"
|
|
577
|
+
),
|
|
578
|
+
)
|
|
579
|
+
record_add.add_argument(
|
|
580
|
+
"--lines",
|
|
581
|
+
type=int,
|
|
582
|
+
# Declared only so a script that spells it gets `NoSpan` rather than argparse's
|
|
583
|
+
# `declares no --lines` (RK1056): the count authorised a span rewrite the pointer
|
|
584
|
+
# stopped making, and the refusal is the one answer that says which of the two
|
|
585
|
+
# changed. Withdrawn from the served tool, which has no script to keep working.
|
|
586
|
+
help=(
|
|
587
|
+
"refused, and kept only to say so: the --supersedes pointer is appended to the "
|
|
588
|
+
"sentence on the entry's first line and replaces no span, so a wrapped bullet "
|
|
589
|
+
"needs no count and keeps the lines under it"
|
|
590
|
+
),
|
|
591
|
+
)
|
|
592
|
+
record_add.add_argument(
|
|
593
|
+
"--json", action="store_true", help="the entry, with the file and line it landed on"
|
|
594
|
+
)
|
|
595
|
+
withheld(
|
|
596
|
+
record_add,
|
|
597
|
+
task_id="the ledger's id is the roadmap line's, and `ship` is what carries it across; typing one here is inventing an id the backlog never issued",
|
|
598
|
+
lines="the entry's shape is derived from what it records, and a count set by hand is the arrangement the schema replaced",
|
|
599
|
+
)
|
|
600
|
+
record_add.set_defaults(
|
|
601
|
+
handler=_record, reads_stdin=(Prose(dest="why", omitted=False),)
|
|
602
|
+
)
|
|
603
|
+
|
|
604
|
+
record_amend = entries.add_parser(
|
|
605
|
+
"amend",
|
|
606
|
+
help="correct a ledger entry's sentence where it stands",
|
|
607
|
+
description=(
|
|
608
|
+
"Rewrite one entry's `why`, or a partial's qualifier, without moving the line. "
|
|
609
|
+
"`drop` and `add` are not equivalent to this: they would remove the entry and "
|
|
610
|
+
"append a new one under its block, so a ledger read in the order work landed "
|
|
611
|
+
"stops being one and a reviewer sees a deletion where a word changed. The "
|
|
612
|
+
"`symptom` is the claim and is not a field, the id is `renumber`'s, and the "
|
|
613
|
+
"block is not offered because filing an entry elsewhere is a move."
|
|
614
|
+
),
|
|
615
|
+
)
|
|
616
|
+
record_amend.add_argument("id", help="the recorded id, e.g. RK41")
|
|
617
|
+
record_amend.add_argument(
|
|
618
|
+
"--why",
|
|
619
|
+
help=(
|
|
620
|
+
"the corrected sentence, one stop — or, with --lines above one, the whole span: "
|
|
621
|
+
"the first line is the sentence and the rest is written back as the tail" + _PIPE
|
|
622
|
+
),
|
|
623
|
+
)
|
|
624
|
+
record_amend.add_argument(
|
|
625
|
+
"--part",
|
|
626
|
+
help="correct a partial's qualifier; refused where the entry carries none",
|
|
627
|
+
)
|
|
628
|
+
record_amend.add_argument(
|
|
629
|
+
"--lines",
|
|
630
|
+
type=int,
|
|
631
|
+
help=(
|
|
632
|
+
"how many lines this correction replaces; required where the entry wraps, "
|
|
633
|
+
"because there the sentence runs past the line the parse holds — and above "
|
|
634
|
+
"one it is also what lets --why carry that span back"
|
|
635
|
+
),
|
|
636
|
+
)
|
|
637
|
+
record_amend.add_argument("--json", action="store_true", help=_JSON_HELP)
|
|
638
|
+
record_amend.set_defaults(
|
|
639
|
+
handler=_record_amend, reads_stdin=(Prose(dest="why", omitted=False),)
|
|
640
|
+
)
|
|
641
|
+
|
|
642
|
+
record_move = entries.add_parser(
|
|
643
|
+
"move",
|
|
644
|
+
help="re-file a ledger entry under another block heading",
|
|
645
|
+
description=(
|
|
646
|
+
"The move `amend` deliberately does not pretend is a correction. `ship` files an "
|
|
647
|
+
"entry under the block its roadmap line sat in, so a line filed under the wrong "
|
|
648
|
+
"one ships to the wrong one — and no other verb reaches it: `record add` refuses "
|
|
649
|
+
"an id that exists, `drop` wants the id stated twice, `renumber` changes the "
|
|
650
|
+
"address and not the heading. This removes the line and re-places it under the "
|
|
651
|
+
"named heading, reporting both positions, and refuses a heading the ledger does "
|
|
652
|
+
"not declare — `block add` is what writes one."
|
|
653
|
+
),
|
|
654
|
+
)
|
|
655
|
+
record_move.add_argument("id", help="the recorded id, e.g. RK41")
|
|
656
|
+
record_move.add_argument(
|
|
657
|
+
"--to-block",
|
|
658
|
+
required=True,
|
|
659
|
+
dest="to_block",
|
|
660
|
+
help="the block label to file it under, e.g. B; refused unless a heading declares it",
|
|
661
|
+
)
|
|
662
|
+
record_move.add_argument(
|
|
663
|
+
"--json", action="store_true", help="both positions, and the blocks they are under"
|
|
664
|
+
)
|
|
665
|
+
record_move.set_defaults(handler=_record_move)
|
|
666
|
+
|
|
667
|
+
record_drop = entries.add_parser(
|
|
668
|
+
"drop",
|
|
669
|
+
help="remove the later of two ledger entries for one id",
|
|
670
|
+
description=(
|
|
671
|
+
"Delete a duplicate entry, and only a duplicate: refused unless the ledger states "
|
|
672
|
+
"the id twice, because removing the only record of a decision is deleting history "
|
|
673
|
+
"rather than de-duplicating it. The first entry stays, since that is where a "
|
|
674
|
+
"reader already found the decision, and no other file is opened."
|
|
675
|
+
),
|
|
676
|
+
)
|
|
677
|
+
record_drop.add_argument("id", help="the id the ledger carries twice, e.g. RK41")
|
|
678
|
+
record_drop.add_argument(
|
|
679
|
+
"--line",
|
|
680
|
+
type=int,
|
|
681
|
+
help=(
|
|
682
|
+
"which of the two entries goes; required when they do not say the same thing, "
|
|
683
|
+
"because then they are two deliveries and not one recorded twice"
|
|
684
|
+
),
|
|
685
|
+
)
|
|
686
|
+
record_drop.add_argument(
|
|
687
|
+
"--json", action="store_true", help="which line went, and which one answers now"
|
|
688
|
+
)
|
|
689
|
+
record_drop.set_defaults(handler=_record_drop)
|
|
690
|
+
|
|
691
|
+
record_renumber = entries.add_parser(
|
|
692
|
+
"renumber",
|
|
693
|
+
help="give one of two entries for an id an address of its own",
|
|
694
|
+
description=(
|
|
695
|
+
"The counterpart of `renumber` for the file that verb never opens. Renumbering "
|
|
696
|
+
"a record is normally how a `git log -S` starts returning two unrelated "
|
|
697
|
+
"designs — and that argument inverts on a collision, where the shared id is "
|
|
698
|
+
"already what makes the history unreadable. Refused on anything but an id the "
|
|
699
|
+
"ledger states twice, and which of the entries moves is yours to name: the one "
|
|
700
|
+
"that earned the id from a roadmap line is the one to leave alone."
|
|
701
|
+
),
|
|
702
|
+
)
|
|
703
|
+
record_renumber.add_argument("id", help="the id the ledger carries twice, e.g. RK41")
|
|
704
|
+
record_renumber.add_argument(
|
|
705
|
+
"--line", type=int, help="the entry that moves; named, never defaulted"
|
|
706
|
+
)
|
|
707
|
+
record_renumber.add_argument(
|
|
708
|
+
"--to", help="the new id (default: derived, one past the highest in its family)"
|
|
709
|
+
)
|
|
710
|
+
record_renumber.add_argument("--json", action="store_true", help=_JSON_HELP)
|
|
711
|
+
record_renumber.set_defaults(handler=_record_renumber)
|
|
712
|
+
|
|
713
|
+
delivered_parser = subcommands.add_parser(
|
|
714
|
+
"delivered",
|
|
715
|
+
help="what a block has already shipped, as claims — the read before an `add`",
|
|
716
|
+
description=(
|
|
717
|
+
"The other list to consult before proposing work, beside `non-goal list` "
|
|
718
|
+
"(RK69). A duplicate is not refused and could not be: RK378 restated RK340 the "
|
|
719
|
+
"day after it shipped and RK382 restated RK178 a day later, and a lexical match "
|
|
720
|
+
"cannot be gated: measured over this ledger it ranks the true pair in the top "
|
|
721
|
+
"three and still scores below what an entry with no duplicate scores against "
|
|
722
|
+
"its own nearest neighbour, so no threshold separates them. Two people "
|
|
723
|
+
"describing one problem use disjoint words, and recognising that takes meaning "
|
|
724
|
+
"this tool has none of (L4). So it states what "
|
|
725
|
+
"the block delivered and you read it. Symptoms alone: the claim is what a "
|
|
726
|
+
"duplicate collides with, and the outcome sentence doubles the length. A letter "
|
|
727
|
+
"no heading declares is refused rather than answered as empty — that answer is "
|
|
728
|
+
"read as evidence — and where the label is declared the reply says which of "
|
|
729
|
+
"live, paused, finished or empty the block is. `--near` is the same read "
|
|
730
|
+
f"bounded by the question (RK442): the {NEAREST} entries nearest the sentence "
|
|
731
|
+
"you are about to propose, in order, instead of the whole block. The order is "
|
|
732
|
+
"the answer and there is no score — RK441 measured that the absolute one "
|
|
733
|
+
"separates nothing, so publishing it would invite a threshold that cannot exist."
|
|
734
|
+
),
|
|
735
|
+
)
|
|
736
|
+
delivered_parser.add_argument("block", help="the block label, e.g. B")
|
|
737
|
+
delivered_parser.add_argument(
|
|
738
|
+
"--near",
|
|
739
|
+
metavar="SYMPTOM",
|
|
740
|
+
help=(
|
|
741
|
+
f"the symptom about to be proposed: print the {NEAREST} entries nearest it "
|
|
742
|
+
"rather than the block, ranked by word overlap and never refused or warned about"
|
|
743
|
+
),
|
|
744
|
+
)
|
|
745
|
+
delivered_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
|
|
746
|
+
delivered_parser.set_defaults(handler=_delivered, reads_only=True)
|
|
747
|
+
|
|
748
|
+
reversals_parser = subcommands.add_parser(
|
|
749
|
+
"reversals",
|
|
750
|
+
help="the decisions this ledger already made and undid, with the argument",
|
|
751
|
+
description=(
|
|
752
|
+
"A revert is filed as a delivery, so a duplicate check answers `yes, shipped` "
|
|
753
|
+
"about the entry that says the work did not hold. This reads the forward "
|
|
754
|
+
"pointer back: every id the ledger marks superseded, the entry that superseded "
|
|
755
|
+
"it, and that entry's sentence — which is the argument a fresh proposal is "
|
|
756
|
+
"against. Read it before an `add`, not after. It refuses nothing: re-proposing "
|
|
757
|
+
"reverted work is sometimes right, and which is a judgement the tool never makes."
|
|
758
|
+
),
|
|
759
|
+
)
|
|
760
|
+
reversals_parser.add_argument(
|
|
761
|
+
"--id",
|
|
762
|
+
dest="task_id",
|
|
763
|
+
help="ask about one id: exits 1 where that id's decision was reversed",
|
|
764
|
+
)
|
|
765
|
+
reversals_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
|
|
766
|
+
reversals_parser.set_defaults(handler=_reversals, reads_only=True)
|
|
767
|
+
|
|
768
|
+
|
|
769
|
+
supersede_parser = subcommands.add_parser(
|
|
770
|
+
"supersede",
|
|
771
|
+
help="mark one decision replaced by another, in the file that holds both",
|
|
772
|
+
description=(
|
|
773
|
+
"The decisions role's one departure. A roadmap line leaves by three doors and a "
|
|
774
|
+
"decision leaves by being replaced, so nothing in that file is ever deleted: this "
|
|
775
|
+
"appends the forward pointer to the entry that is now stale and moves its marker, "
|
|
776
|
+
"in one write. Both ids have to be decisions this file already records — the "
|
|
777
|
+
"replacement is written by `ship --decides` before it can replace anything — and "
|
|
778
|
+
"there is no reason field, because why one decision replaced another is the "
|
|
779
|
+
"argument in the entry that replaced it, one line away."
|
|
780
|
+
),
|
|
781
|
+
)
|
|
782
|
+
supersede_parser.add_argument("id", help="the decision being replaced, e.g. RK5")
|
|
783
|
+
supersede_parser.add_argument(
|
|
784
|
+
"--by",
|
|
785
|
+
required=True,
|
|
786
|
+
metavar="ID",
|
|
787
|
+
help="the decision that replaces it, already filed in the same file",
|
|
788
|
+
)
|
|
789
|
+
supersede_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
|
|
790
|
+
supersede_parser.set_defaults(handler=_supersede)
|
|
791
|
+
|
|
792
|
+
retire_parser = subcommands.add_parser(
|
|
793
|
+
"retire",
|
|
794
|
+
help="record a line leaving without shipping: replaced by another, or abandoned",
|
|
795
|
+
description=(
|
|
796
|
+
"The two departures that are not a ship: the work moved to another id "
|
|
797
|
+
"(--superseded-by), or it is not being done. Both write one ledger line under "
|
|
798
|
+
"the block it belonged to, with the forward pointer where there is one, and no "
|
|
799
|
+
"design — which is what a gap here otherwise reads as, a botched hand-edit."
|
|
800
|
+
),
|
|
801
|
+
)
|
|
802
|
+
retire_parser.add_argument("id", help="the task leaving, e.g. RK33")
|
|
803
|
+
retire_parser.add_argument(
|
|
804
|
+
"--superseded-by",
|
|
805
|
+
dest="superseded_by",
|
|
806
|
+
metavar="ID",
|
|
807
|
+
help=(
|
|
808
|
+
"the id that takes the work over, which is a replacement and not an "
|
|
809
|
+
"abandonment; omitted, the line is recorded as abandoned"
|
|
810
|
+
),
|
|
811
|
+
)
|
|
812
|
+
_reason_flag(
|
|
813
|
+
retire_parser, "one sentence, the author's own: the tool never writes it" + _PIPE
|
|
814
|
+
)
|
|
815
|
+
retire_parser.add_argument("--json", action="store_true", help="every edit, as data")
|
|
816
|
+
retire_parser.set_defaults(
|
|
817
|
+
handler=_retire, reads_stdin=(Prose(dest="reason", omitted=False),)
|
|
818
|
+
)
|
|
819
|
+
|