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,566 @@
|
|
|
1
|
+
"""The verbs whose subject is one line of the roadmap (RK494).
|
|
2
|
+
|
|
3
|
+
`add`, `status`, `amend`, `restate`, `renumber` and `next-id`, plus the two doors that are
|
|
4
|
+
not terminal — `defer` parks a line in the store with its id, its deps and its section, and
|
|
5
|
+
`resume` is the return direction the ledger has none of.
|
|
6
|
+
|
|
7
|
+
Each is a thin call into :mod:`roadkeep.authoring`, :mod:`roadkeep.renumbering` or
|
|
8
|
+
:mod:`roadkeep.deferring`. What lives here is the argument reading, the refusal and the
|
|
9
|
+
answer — never a rule, which would then be enforced on one surface and not on the other.
|
|
10
|
+
|
|
11
|
+
**And no longer the answer either** (RK1170): every write renders both registers off its own
|
|
12
|
+
record, so each door is the call, the save and a choice of reading. `next-id` renders three, the
|
|
13
|
+
id being stdout a shell captures and the promise a sentence that must not reach it.
|
|
14
|
+
"""
|
|
15
|
+
|
|
16
|
+
from __future__ import annotations
|
|
17
|
+
|
|
18
|
+
import argparse
|
|
19
|
+
import json
|
|
20
|
+
import sys
|
|
21
|
+
|
|
22
|
+
from roadkeep.authoring import add, amend, restate, set_status
|
|
23
|
+
from roadkeep.capturing import stamp
|
|
24
|
+
from roadkeep.config import Config
|
|
25
|
+
from roadkeep.deferring import defer, resume
|
|
26
|
+
from roadkeep.ids import derivation
|
|
27
|
+
from roadkeep.renumbering import renumber
|
|
28
|
+
from roadkeep.verbs.reading import _body_reader, _one_body, _piped
|
|
29
|
+
from roadkeep.serving import Prose
|
|
30
|
+
from roadkeep.verbs.declaring import (
|
|
31
|
+
_BODY_FILE,
|
|
32
|
+
_JSON_HELP,
|
|
33
|
+
_PIPE,
|
|
34
|
+
_marker_flag,
|
|
35
|
+
_reason_flag,
|
|
36
|
+
withheld,
|
|
37
|
+
)
|
|
38
|
+
from roadkeep.verbs.refusing import EXIT_OK, EXIT_USAGE, REFUSALS, _refused
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
def _next_id(config: Config, args: argparse.Namespace) -> int:
|
|
43
|
+
try:
|
|
44
|
+
derived = derivation(config, args.family)
|
|
45
|
+
except ValueError as error:
|
|
46
|
+
return _refused(error)
|
|
47
|
+
family = args.family or config.schema.prefix
|
|
48
|
+
# Three streams and not two (RK1170): the id is stdout because this command exists to be
|
|
49
|
+
# captured in a shell, and the promise is stderr because a second line in that capture is
|
|
50
|
+
# a broken id — so the branch is which reading, never whether to add a sentence.
|
|
51
|
+
if args.json:
|
|
52
|
+
print(json.dumps(derived.payload(config, family), indent=2))
|
|
53
|
+
return EXIT_OK
|
|
54
|
+
print(derived.stated())
|
|
55
|
+
for note in derived.notice():
|
|
56
|
+
print(note, file=sys.stderr)
|
|
57
|
+
return EXIT_OK
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
def _add(config: Config, args: argparse.Namespace) -> int:
|
|
61
|
+
# The pipe clash is `dispatch`'s, asked over what this verb's parser declares (RK1176) —
|
|
62
|
+
# this had the only copy of it, which is how `ship` sent two arguments to one stream with
|
|
63
|
+
# the refusal sitting one module away. What is left here is the other question: a body given
|
|
64
|
+
# twice, as a string and as a path, which no declaration can answer.
|
|
65
|
+
clash = _one_body("--section-body", args.section_body, args.section_body_file)
|
|
66
|
+
if clash is not None:
|
|
67
|
+
print(f"roadkeep: {clash}", file=sys.stderr)
|
|
68
|
+
return EXIT_USAGE
|
|
69
|
+
try:
|
|
70
|
+
# The reader is handed over unread (RK381), so the paragraph is fetched below every
|
|
71
|
+
# refusal the *line* raises — an id already spent, a `why` three words over, a block
|
|
72
|
+
# nothing declares — and a pipe does not rewind. Inside the try for the reason
|
|
73
|
+
# `section add` reads there: prose that is not UTF-8 raises UnicodeDecodeError, which
|
|
74
|
+
# is a ValueError, and is refused with the code every other bad input gets. Gated on
|
|
75
|
+
# the title, because an `add` with no rationale must never block on a pipe.
|
|
76
|
+
section = None
|
|
77
|
+
if args.section is not None:
|
|
78
|
+
section = (
|
|
79
|
+
args.section,
|
|
80
|
+
_body_reader(args.section_body, args.section_body_file),
|
|
81
|
+
)
|
|
82
|
+
insertion = add(
|
|
83
|
+
config,
|
|
84
|
+
block=args.block,
|
|
85
|
+
symptom=args.symptom,
|
|
86
|
+
why=_piped(args.why),
|
|
87
|
+
status=args.status,
|
|
88
|
+
deps=args.deps,
|
|
89
|
+
requires=args.requires,
|
|
90
|
+
ref=args.ref,
|
|
91
|
+
task_id=args.task_id,
|
|
92
|
+
family=args.family,
|
|
93
|
+
section=section,
|
|
94
|
+
)
|
|
95
|
+
except REFUSALS as error:
|
|
96
|
+
return _refused(error) # a SchemaError arrives here as the ValueError it is
|
|
97
|
+
|
|
98
|
+
# After the line is placed and the files are saved, and never a condition of either
|
|
99
|
+
# (RK1141): the capture is evidence in an ignored directory, so a stamp that cannot be
|
|
100
|
+
# written costs the link and not the task — `claiming.follow`'s rule for the same reason.
|
|
101
|
+
# The third copy of the argument RK1396 was about, resolved the same way: this one is the
|
|
102
|
+
# path the *capture offer* printed, so a project-relative address read from the process's
|
|
103
|
+
# directory left the line filed and the row it was meant to clear still open — the one
|
|
104
|
+
# failure this stamp is not allowed to have, being the half that costs nothing to get right.
|
|
105
|
+
stamped = (
|
|
106
|
+
stamp(config.locate(args.capture), insertion.entry.task.id) if args.capture else False
|
|
107
|
+
)
|
|
108
|
+
if args.json:
|
|
109
|
+
print(json.dumps(insertion.addition(config, args.capture, stamped), indent=2))
|
|
110
|
+
else:
|
|
111
|
+
print(insertion.added(config, args.capture, stamped))
|
|
112
|
+
return EXIT_OK
|
|
113
|
+
|
|
114
|
+
|
|
115
|
+
def _status(config: Config, args: argparse.Namespace) -> int:
|
|
116
|
+
"""Write one task's marker, and say what that did to the claim on its line (RK7, RK158).
|
|
117
|
+
|
|
118
|
+
Both registers come off the record (RK1170), the no-op reading included: a marker that did
|
|
119
|
+
not move still followed its claim, so the branch belongs with the answer and not in a door.
|
|
120
|
+
"""
|
|
121
|
+
try:
|
|
122
|
+
change = set_status(config, args.id, args.marker)
|
|
123
|
+
except REFUSALS as error:
|
|
124
|
+
return _refused(error)
|
|
125
|
+
|
|
126
|
+
if args.json:
|
|
127
|
+
print(json.dumps(change.payload(config), indent=2))
|
|
128
|
+
else:
|
|
129
|
+
print(change.stated(config))
|
|
130
|
+
return EXIT_OK
|
|
131
|
+
|
|
132
|
+
|
|
133
|
+
def _amend(config: Config, args: argparse.Namespace) -> int:
|
|
134
|
+
"""Correct one open line's why, deps or pointer, keeping its symptom and its id (RK65).
|
|
135
|
+
|
|
136
|
+
Both registers come off the record (RK1170), exactly as `restate`'s do: this door chooses
|
|
137
|
+
which reading to print and composes neither.
|
|
138
|
+
"""
|
|
139
|
+
# `--requires` counts (RK1311). The flag is in the parser, documented in the help two lines
|
|
140
|
+
# above this message, and works — and the guard that decides whether anything was asked for
|
|
141
|
+
# did not know it. So the only way to attach a requirement to a line that already exists
|
|
142
|
+
# was to pass a field that is not changing: measured in pportal over five lines, where one
|
|
143
|
+
# of them meant re-sending a `why` that then failed the line limit, because the annotation
|
|
144
|
+
# had made the line longer. Two round trips for a field the verb has.
|
|
145
|
+
if args.why is None and args.deps is None and args.ref is None and not args.requires:
|
|
146
|
+
# Named only where the project declares a vocabulary (L6): a flag offered here and
|
|
147
|
+
# refused by `requires.unknown` one call later is the detour RK16 keeps out of a
|
|
148
|
+
# remedy, and a project that declared none has no requirement to attach.
|
|
149
|
+
fields = "--why, --dep or --ref"
|
|
150
|
+
if config.schema.requirements:
|
|
151
|
+
fields = "--why, --dep, --requires or --ref"
|
|
152
|
+
print(f"roadkeep: nothing to amend: pass {fields}", file=sys.stderr)
|
|
153
|
+
return EXIT_USAGE
|
|
154
|
+
try:
|
|
155
|
+
amended = amend(
|
|
156
|
+
config,
|
|
157
|
+
args.id,
|
|
158
|
+
why=_piped(args.why),
|
|
159
|
+
deps=args.deps,
|
|
160
|
+
requires=args.requires,
|
|
161
|
+
ref=args.ref,
|
|
162
|
+
lines=args.lines,
|
|
163
|
+
)
|
|
164
|
+
except REFUSALS as error:
|
|
165
|
+
return _refused(error)
|
|
166
|
+
|
|
167
|
+
if args.json:
|
|
168
|
+
print(json.dumps(amended.payload(config), indent=2))
|
|
169
|
+
else:
|
|
170
|
+
print(amended.stated(config))
|
|
171
|
+
return EXIT_OK
|
|
172
|
+
|
|
173
|
+
|
|
174
|
+
def _restate(config: Config, args: argparse.Namespace) -> int:
|
|
175
|
+
"""Correct one open line's symptom, keeping its id, its deps and its section (RK178).
|
|
176
|
+
|
|
177
|
+
Both registers come off the record (RK1170): a write verb's answer is what the transaction
|
|
178
|
+
produced, and this door only chooses which reading to print.
|
|
179
|
+
"""
|
|
180
|
+
try:
|
|
181
|
+
restated = restate(
|
|
182
|
+
config, args.id, args.symptom, lines=args.lines, typo=args.typo
|
|
183
|
+
)
|
|
184
|
+
except REFUSALS as error:
|
|
185
|
+
return _refused(error)
|
|
186
|
+
|
|
187
|
+
if args.json:
|
|
188
|
+
print(json.dumps(restated.payload(config), indent=2))
|
|
189
|
+
else:
|
|
190
|
+
print(restated.stated(config))
|
|
191
|
+
return EXIT_OK
|
|
192
|
+
|
|
193
|
+
|
|
194
|
+
def _renumber(config: Config, args: argparse.Namespace) -> int:
|
|
195
|
+
"""Move one line to a free id, with its section, its subsections and its claim (RK74).
|
|
196
|
+
|
|
197
|
+
Both registers come off the record (RK1170); `wrote` is passed because saving is this
|
|
198
|
+
door's step, so the paths are a fact about the call and not about the transaction.
|
|
199
|
+
"""
|
|
200
|
+
try:
|
|
201
|
+
moved = renumber(config, args.id, args.to)
|
|
202
|
+
wrote = moved.save()
|
|
203
|
+
except REFUSALS as error:
|
|
204
|
+
return _refused(error)
|
|
205
|
+
|
|
206
|
+
if args.json:
|
|
207
|
+
print(json.dumps(moved.payload(config, wrote), indent=2))
|
|
208
|
+
else:
|
|
209
|
+
print(moved.stated(config, wrote))
|
|
210
|
+
return EXIT_OK
|
|
211
|
+
|
|
212
|
+
|
|
213
|
+
def _defer(config: Config, args: argparse.Namespace) -> int:
|
|
214
|
+
"""Set one open line aside in the store, keeping its design where it is (RK229, RK327).
|
|
215
|
+
|
|
216
|
+
Both registers come off the record (RK1170); `wrote` is passed because saving is this
|
|
217
|
+
door's step, so the paths are a fact about the call and not about the transaction.
|
|
218
|
+
"""
|
|
219
|
+
try:
|
|
220
|
+
pause = defer(config, args.id, reason=_piped(args.reason))
|
|
221
|
+
wrote = pause.save()
|
|
222
|
+
except REFUSALS as error:
|
|
223
|
+
return _refused(error)
|
|
224
|
+
|
|
225
|
+
if args.json:
|
|
226
|
+
print(json.dumps(pause.payload(config, wrote), indent=2))
|
|
227
|
+
else:
|
|
228
|
+
print(pause.stated(config, wrote))
|
|
229
|
+
return EXIT_OK
|
|
230
|
+
|
|
231
|
+
|
|
232
|
+
def _resume(config: Config, args: argparse.Namespace) -> int:
|
|
233
|
+
try:
|
|
234
|
+
resumption = resume(config, args.id, marker=args.marker)
|
|
235
|
+
wrote = resumption.save()
|
|
236
|
+
except REFUSALS as error:
|
|
237
|
+
return _refused(error)
|
|
238
|
+
|
|
239
|
+
if args.json:
|
|
240
|
+
print(json.dumps(resumption.payload(config, wrote), indent=2))
|
|
241
|
+
else:
|
|
242
|
+
print(resumption.stated(config, wrote))
|
|
243
|
+
return EXIT_OK
|
|
244
|
+
|
|
245
|
+
|
|
246
|
+
def declare_lines(subcommands: argparse._SubParsersAction) -> None:
|
|
247
|
+
"""This module's verbs, declared where their handlers are (RK1171).
|
|
248
|
+
|
|
249
|
+
`build_parser` called forty-nine blocks like these in a row; what it calls now is an index
|
|
250
|
+
over the modules that own them. The move is what RK1169 and RK1170 bought: the flags a verb
|
|
251
|
+
declares, the reasons it withholds and the record it answers with are one file's, so a
|
|
252
|
+
change to any of them is one file's too.
|
|
253
|
+
|
|
254
|
+
The order inside is `build_parser`'s own, which is where these blocks sat.
|
|
255
|
+
"""
|
|
256
|
+
next_id_parser = subcommands.add_parser(
|
|
257
|
+
"next-id",
|
|
258
|
+
help="the next unused task id, one past the highest anywhere",
|
|
259
|
+
description=(
|
|
260
|
+
"Print the next id. Never the first unused number: a retired id is never "
|
|
261
|
+
"reused, so filling its hole would make two tasks share it in the history."
|
|
262
|
+
),
|
|
263
|
+
)
|
|
264
|
+
next_id_parser.add_argument(
|
|
265
|
+
"--prefix",
|
|
266
|
+
dest="family",
|
|
267
|
+
help=(
|
|
268
|
+
"count in this track (default: the first declared) — two tracks sharing a "
|
|
269
|
+
"counter are two tracks that renumber each other"
|
|
270
|
+
),
|
|
271
|
+
)
|
|
272
|
+
next_id_parser.add_argument(
|
|
273
|
+
"--json",
|
|
274
|
+
action="store_true",
|
|
275
|
+
help="include where the highest id was found, so the answer can be audited",
|
|
276
|
+
)
|
|
277
|
+
# `reads_only` is what keeps a command out of the write lock (RK117), declared here
|
|
278
|
+
# beside `tolerates_config_error` because both are claims about the command rather than
|
|
279
|
+
# about its arguments. Absent means locked, so a new command is serialised until someone
|
|
280
|
+
# says it only reads — and `next-id` only reads: the race is not in the scan, it is in
|
|
281
|
+
# the span between this answer and the `add` that spends it.
|
|
282
|
+
next_id_parser.set_defaults(handler=_next_id, reads_only=True)
|
|
283
|
+
|
|
284
|
+
add_parser = subcommands.add_parser(
|
|
285
|
+
"add",
|
|
286
|
+
help="insert a task line under its block, refusing the fields at input",
|
|
287
|
+
description=(
|
|
288
|
+
"Compose, validate and insert one task line. Nothing is written unless "
|
|
289
|
+
"every field passes: a limit reported after the prose exists is a limit "
|
|
290
|
+
"discovered too late to save the tokens it was meant to save. With "
|
|
291
|
+
"--section the rationale the line points at is written in the same "
|
|
292
|
+
"transaction; without it, the follow-up the pointer needs is named."
|
|
293
|
+
),
|
|
294
|
+
)
|
|
295
|
+
add_parser.add_argument("--block", required=True, help="the block label, e.g. B")
|
|
296
|
+
add_parser.add_argument(
|
|
297
|
+
"--symptom", required=True, help="what does not work — a phrase, never a fix"
|
|
298
|
+
)
|
|
299
|
+
add_parser.add_argument(
|
|
300
|
+
"--why", required=True, help="one sentence, ending in a stop" + _PIPE
|
|
301
|
+
)
|
|
302
|
+
add_parser.add_argument(
|
|
303
|
+
"--dep",
|
|
304
|
+
action="append",
|
|
305
|
+
default=[],
|
|
306
|
+
dest="deps",
|
|
307
|
+
metavar="DEP",
|
|
308
|
+
help="a dep, repeatable: an id, 'Block X', a range, or work outside the backlog",
|
|
309
|
+
)
|
|
310
|
+
add_parser.add_argument(
|
|
311
|
+
"--requires",
|
|
312
|
+
action="append",
|
|
313
|
+
default=[],
|
|
314
|
+
dest="requires",
|
|
315
|
+
metavar="REQUIREMENT",
|
|
316
|
+
help=(
|
|
317
|
+
"what must be present to finish this, repeatable and declared in "
|
|
318
|
+
"`[requirements]`: not a dep — `pick` offers it only to a caller that has one"
|
|
319
|
+
),
|
|
320
|
+
)
|
|
321
|
+
_marker_flag(
|
|
322
|
+
add_parser,
|
|
323
|
+
"the status marker (default: the first marker roadkeep.toml declares)",
|
|
324
|
+
)
|
|
325
|
+
add_parser.add_argument(
|
|
326
|
+
"--id",
|
|
327
|
+
dest="task_id",
|
|
328
|
+
help="the id (default: derived, one past the highest anywhere)",
|
|
329
|
+
)
|
|
330
|
+
add_parser.add_argument(
|
|
331
|
+
"--prefix",
|
|
332
|
+
dest="family",
|
|
333
|
+
help=(
|
|
334
|
+
"which track the derived id counts in (default: the first declared); only "
|
|
335
|
+
"a backlog that numbers by track has a second one to name"
|
|
336
|
+
),
|
|
337
|
+
)
|
|
338
|
+
add_parser.add_argument(
|
|
339
|
+
"--ref",
|
|
340
|
+
help=(
|
|
341
|
+
"the rationale anchor, for ref_scheme = 'outline' only; otherwise derived — "
|
|
342
|
+
"<prefix>:<x.y> for a prose file [refs] gives a namespace"
|
|
343
|
+
),
|
|
344
|
+
)
|
|
345
|
+
add_parser.add_argument(
|
|
346
|
+
"--section",
|
|
347
|
+
metavar="TITLE",
|
|
348
|
+
help=(
|
|
349
|
+
"write the rationale under this heading, in the same transaction: the "
|
|
350
|
+
"pointer every line carries resolves to nothing until a section exists"
|
|
351
|
+
),
|
|
352
|
+
)
|
|
353
|
+
add_parser.add_argument(
|
|
354
|
+
"--section-body",
|
|
355
|
+
dest="section_body",
|
|
356
|
+
help="the rationale prose; omitted or '-' reads stdin. Read only with --section",
|
|
357
|
+
)
|
|
358
|
+
add_parser.add_argument(
|
|
359
|
+
"--section-body-file",
|
|
360
|
+
dest="section_body_file",
|
|
361
|
+
metavar="PATH",
|
|
362
|
+
help=_BODY_FILE.format(what="rationale"),
|
|
363
|
+
)
|
|
364
|
+
add_parser.add_argument(
|
|
365
|
+
"--capture",
|
|
366
|
+
metavar="PATH",
|
|
367
|
+
help=(
|
|
368
|
+
"the kept capture this line files, stamped with the id this call mints (RK1141) "
|
|
369
|
+
"— `report` prints this flag already filled in, so the row `stats` counts is "
|
|
370
|
+
"cleared by the act that closes it and never by a second step somebody remembers"
|
|
371
|
+
),
|
|
372
|
+
)
|
|
373
|
+
add_parser.add_argument(
|
|
374
|
+
"--json", action="store_true", help="the line, with the file and line it landed on"
|
|
375
|
+
)
|
|
376
|
+
# `reads_stdin` is declared here for the reason `reads_only` is (RK171): it is a claim about
|
|
377
|
+
# this command that a surface serving it has to know, and the only statement of it used to be
|
|
378
|
+
# the comment two lines above the read. Gated, because an `add` naming no section must never
|
|
379
|
+
# block on a pipe — which is what that comment said and nothing enforced.
|
|
380
|
+
withheld(
|
|
381
|
+
add_parser,
|
|
382
|
+
family="the id's prefix is `[ids]`' and `next-id` derives it; a caller choosing one is a caller numbering into another project's range",
|
|
383
|
+
capture='a path to a local artefact this transport does not share, and the verb that writes one is not a tool here',
|
|
384
|
+
)
|
|
385
|
+
add_parser.set_defaults(
|
|
386
|
+
handler=_add,
|
|
387
|
+
# Two, and this is the command that has two (RK329): the body was the obvious
|
|
388
|
+
# affordance because it is long, and the `why` is the one that actually needed it
|
|
389
|
+
# because it is the field that reliably carries what a shell reads first. Ungated,
|
|
390
|
+
# unlike the body: a `--why -` is the caller asking for the pipe outright.
|
|
391
|
+
reads_stdin=(
|
|
392
|
+
Prose(dest="section_body", gated_by="section", unless="section_body_file"),
|
|
393
|
+
Prose(dest="why", omitted=False),
|
|
394
|
+
),
|
|
395
|
+
)
|
|
396
|
+
|
|
397
|
+
status_parser = subcommands.add_parser(
|
|
398
|
+
"status",
|
|
399
|
+
help="set a task's marker in the roadmap, and nowhere else",
|
|
400
|
+
description=(
|
|
401
|
+
"Write one task's status marker. Refused if a sibling file already carries "
|
|
402
|
+
"one for that id: two files that both express status will eventually "
|
|
403
|
+
"express different status, and nothing says which is right."
|
|
404
|
+
),
|
|
405
|
+
)
|
|
406
|
+
status_parser.add_argument("id", help="the task, e.g. RK7")
|
|
407
|
+
status_parser.add_argument(
|
|
408
|
+
"marker", help="the new marker, from the open set this project declares"
|
|
409
|
+
)
|
|
410
|
+
status_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
|
|
411
|
+
status_parser.set_defaults(
|
|
412
|
+
handler=_status,
|
|
413
|
+
twin=(
|
|
414
|
+
"status writes a marker onto one line and needs both: `status <id> <marker>`."
|
|
415
|
+
" The backlog's numbers are `stats`, which needs neither — one character "
|
|
416
|
+
"apart, and this is the one that writes"
|
|
417
|
+
),
|
|
418
|
+
)
|
|
419
|
+
|
|
420
|
+
amend_parser = subcommands.add_parser(
|
|
421
|
+
"amend",
|
|
422
|
+
help="correct one open line's why, deps or pointer",
|
|
423
|
+
description=(
|
|
424
|
+
"Correct the three fields a project that adopted the tool has to be able to fix: "
|
|
425
|
+
"a pointer it never had, a dep naming an id in neither file, and the compression "
|
|
426
|
+
"of a `why` that was a paragraph before the limit existed. Validated at input "
|
|
427
|
+
"exactly as `add` validates it, or nothing is written. The `symptom` is not "
|
|
428
|
+
"amendable — it is the claim the line is, so a different one is a different task."
|
|
429
|
+
),
|
|
430
|
+
)
|
|
431
|
+
amend_parser.add_argument("id", help="the task, e.g. RK7")
|
|
432
|
+
amend_parser.add_argument(
|
|
433
|
+
"--why", help="the sentence, re-validated against the limit" + _PIPE
|
|
434
|
+
)
|
|
435
|
+
amend_parser.add_argument(
|
|
436
|
+
"--dep",
|
|
437
|
+
action="append",
|
|
438
|
+
dest="deps",
|
|
439
|
+
metavar="DEP",
|
|
440
|
+
help="a dep, repeatable: given at all, it replaces the whole group",
|
|
441
|
+
)
|
|
442
|
+
amend_parser.add_argument(
|
|
443
|
+
"--requires",
|
|
444
|
+
action="append",
|
|
445
|
+
dest="requires",
|
|
446
|
+
metavar="REQUIREMENT",
|
|
447
|
+
help="a requirement, repeatable: given at all, it replaces the whole group",
|
|
448
|
+
)
|
|
449
|
+
amend_parser.add_argument(
|
|
450
|
+
"--ref", help="the rationale anchor, for ref_scheme = 'outline'"
|
|
451
|
+
)
|
|
452
|
+
amend_parser.add_argument(
|
|
453
|
+
"--lines",
|
|
454
|
+
type=int,
|
|
455
|
+
help=(
|
|
456
|
+
"how many lines this correction replaces; required where the line wraps, which "
|
|
457
|
+
"on a roadmap only an adopted backlog can be"
|
|
458
|
+
),
|
|
459
|
+
)
|
|
460
|
+
amend_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
|
|
461
|
+
amend_parser.set_defaults(
|
|
462
|
+
handler=_amend, reads_stdin=(Prose(dest="why", omitted=False),)
|
|
463
|
+
)
|
|
464
|
+
|
|
465
|
+
restate_parser = subcommands.add_parser(
|
|
466
|
+
"restate",
|
|
467
|
+
help="correct one open line's symptom, keeping its id",
|
|
468
|
+
description=(
|
|
469
|
+
"The one field `amend` does not reach, at a door of its own. A different symptom "
|
|
470
|
+
"is normally a different task, which is why that verb excludes it — and a premise "
|
|
471
|
+
"that turns out false is not a different task, it is this file asserting "
|
|
472
|
+
"something untrue in the field a reader sees first. `retire` plus `add` is the "
|
|
473
|
+
"exit that was designed for it, and it spends an id, deletes a section that was "
|
|
474
|
+
"already right and records a departure that never happened. This keeps all three. "
|
|
475
|
+
"A verb rather than a flag, so the act has a name a reviewer can see."
|
|
476
|
+
),
|
|
477
|
+
)
|
|
478
|
+
restate_parser.add_argument("id", help="the task, e.g. RK7")
|
|
479
|
+
restate_parser.add_argument(
|
|
480
|
+
"--symptom",
|
|
481
|
+
required=True,
|
|
482
|
+
help="what does not work — re-validated against the limit, exactly as `add` does"
|
|
483
|
+
+ _PIPE,
|
|
484
|
+
)
|
|
485
|
+
restate_parser.add_argument(
|
|
486
|
+
"--lines",
|
|
487
|
+
type=int,
|
|
488
|
+
help="how many lines this restatement replaces; required where the line wraps",
|
|
489
|
+
)
|
|
490
|
+
restate_parser.add_argument(
|
|
491
|
+
"--typo",
|
|
492
|
+
action="store_true",
|
|
493
|
+
help=(
|
|
494
|
+
"a slip of the pen rather than a false premise: the claim is the one intended "
|
|
495
|
+
"and a word in it was wrong, so the answer and the payload say so"
|
|
496
|
+
),
|
|
497
|
+
)
|
|
498
|
+
restate_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
|
|
499
|
+
restate_parser.set_defaults(
|
|
500
|
+
handler=_restate,
|
|
501
|
+
# The field the pipe convention skipped, and the verb whose only prose argument it is
|
|
502
|
+
# (RK1187). A symptom carries the backtick and the apostrophe exactly as a `why` does,
|
|
503
|
+
# and is the one a shell corrupts most quietly — a symptom that lost an apostrophe
|
|
504
|
+
# still reads like prose somebody wrote, so nothing downstream calls it wrong. Ungated
|
|
505
|
+
# and sentinel-only, like `amend --why`: `--symptom` is required, so the omitted read
|
|
506
|
+
# is a shape argparse already refuses.
|
|
507
|
+
reads_stdin=(Prose(dest="symptom", omitted=False),),
|
|
508
|
+
)
|
|
509
|
+
|
|
510
|
+
renumber_parser = subcommands.add_parser(
|
|
511
|
+
"renumber",
|
|
512
|
+
help="move one open line to a free id, with its section and its dependents",
|
|
513
|
+
description=(
|
|
514
|
+
"Change one line's address, without a departure. The line, the section its "
|
|
515
|
+
"pointer resolves to and every dep naming it move in one transaction; the "
|
|
516
|
+
"ledger is never opened, because an id it records is a decision and not an "
|
|
517
|
+
"address. This is the repair a merge that allocated one id twice needs, and "
|
|
518
|
+
"the door `ship`, `retire` and `amend` all deliberately refuse to be."
|
|
519
|
+
),
|
|
520
|
+
)
|
|
521
|
+
renumber_parser.add_argument("id", help="the line to move, e.g. RK90")
|
|
522
|
+
renumber_parser.add_argument(
|
|
523
|
+
"--to",
|
|
524
|
+
help="the new id (default: derived, one past the highest in the line's family)",
|
|
525
|
+
)
|
|
526
|
+
renumber_parser.add_argument("--json", action="store_true", help="every edit, as data")
|
|
527
|
+
renumber_parser.set_defaults(handler=_renumber)
|
|
528
|
+
|
|
529
|
+
defer_parser = subcommands.add_parser(
|
|
530
|
+
"defer",
|
|
531
|
+
help="set a line aside without retiring it: the store, not the ledger",
|
|
532
|
+
description=(
|
|
533
|
+
"A pause spelled as a retirement is terminal — the id cannot come back, the "
|
|
534
|
+
"resolver reads the dep as never, and the rationale is deleted. This moves the "
|
|
535
|
+
"line to the deferred store instead, keeping every slot and the section."
|
|
536
|
+
),
|
|
537
|
+
)
|
|
538
|
+
defer_parser.add_argument("id", help="the task being set aside, e.g. RK33")
|
|
539
|
+
_reason_flag(
|
|
540
|
+
defer_parser,
|
|
541
|
+
"one sentence, the author's own: it wraps the why and a resume unwraps it" + _PIPE,
|
|
542
|
+
)
|
|
543
|
+
defer_parser.add_argument("--json", action="store_true", help="every edit, as data")
|
|
544
|
+
defer_parser.set_defaults(
|
|
545
|
+
handler=_defer, reads_stdin=(Prose(dest="reason", omitted=False),)
|
|
546
|
+
)
|
|
547
|
+
|
|
548
|
+
resume_parser = subcommands.add_parser(
|
|
549
|
+
"resume",
|
|
550
|
+
help="return a set-aside line to its block — the direction the ledger has none of",
|
|
551
|
+
description=(
|
|
552
|
+
"The store is revivable, which is what separates it from the two terminal "
|
|
553
|
+
"doors: the same id, the same deps, the same section, back under the block "
|
|
554
|
+
"the line left. The open marker is the one thing the store could not keep."
|
|
555
|
+
),
|
|
556
|
+
)
|
|
557
|
+
resume_parser.add_argument("id", help="the task coming back, e.g. RK33")
|
|
558
|
+
_marker_flag(
|
|
559
|
+
resume_parser,
|
|
560
|
+
"the open marker it returns with; omitted, the first this project declares — "
|
|
561
|
+
"the store holds one marker, so which one it was is not a fact any file kept",
|
|
562
|
+
dest="marker",
|
|
563
|
+
)
|
|
564
|
+
resume_parser.add_argument("--json", action="store_true", help="every edit, as data")
|
|
565
|
+
resume_parser.set_defaults(handler=_resume)
|
|
566
|
+
|