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,2138 @@
|
|
|
1
|
+
"""Every verb that answers a question, which is why it is the largest of them (RK494).
|
|
2
|
+
|
|
3
|
+
`list`, `stats`, `audit`, `show`, `brief`, `pick`, `budget`, `deps`, `anchors`, `gaps`,
|
|
4
|
+
`origin`, `weight`, `remaining`, `claims`, `claim`, `writes` and `export` — L5's whole
|
|
5
|
+
surface, where a question costs a command instead of a file in the context.
|
|
6
|
+
|
|
7
|
+
The three that can write are here anyway and say so: `brief --claim`, `pick --claim` and
|
|
8
|
+
`claims --prune` move a marker or a registry, which is what :func:`roadkeep.cli.dispatch`
|
|
9
|
+
reads to take the lock (RK167). Their subject is still the question, and filing a verb by
|
|
10
|
+
what one flag makes it would put one verb in two places.
|
|
11
|
+
"""
|
|
12
|
+
|
|
13
|
+
from __future__ import annotations
|
|
14
|
+
|
|
15
|
+
import argparse
|
|
16
|
+
import json
|
|
17
|
+
import sys
|
|
18
|
+
|
|
19
|
+
from roadkeep import attesting, claiming
|
|
20
|
+
|
|
21
|
+
from roadkeep.backlog import Backlog, NotOpen, Stage, Standing, Whereabouts
|
|
22
|
+
from roadkeep.capturing import debt
|
|
23
|
+
from roadkeep.briefing import NothingToBrief, brief
|
|
24
|
+
from roadkeep.budgeting import (
|
|
25
|
+
Load,
|
|
26
|
+
Session,
|
|
27
|
+
body_budget,
|
|
28
|
+
budget,
|
|
29
|
+
file_budget,
|
|
30
|
+
notice_budget,
|
|
31
|
+
non_goal_budget,
|
|
32
|
+
)
|
|
33
|
+
from roadkeep.config import Config, PROSE_ROLES
|
|
34
|
+
from roadkeep.counting import Census
|
|
35
|
+
from roadkeep.kernel.document import StaleFile, write_all
|
|
36
|
+
from roadkeep.exporting import DEFAULTS, project, spec, splice_into
|
|
37
|
+
from roadkeep.graph import Dependencies
|
|
38
|
+
from roadkeep.history import (
|
|
39
|
+
Unclosed,
|
|
40
|
+
pending,
|
|
41
|
+
Addresses,
|
|
42
|
+
HistoryUnavailable,
|
|
43
|
+
cited_origin,
|
|
44
|
+
families_of_block,
|
|
45
|
+
Gapped,
|
|
46
|
+
gaps,
|
|
47
|
+
indexed,
|
|
48
|
+
origin_of,
|
|
49
|
+
status,
|
|
50
|
+
)
|
|
51
|
+
from roadkeep.picking import Claim, Picked, pick, take
|
|
52
|
+
from roadkeep.provenance import invocation
|
|
53
|
+
from roadkeep.remaining import EVIDENCE, QueryError, count, declared
|
|
54
|
+
from roadkeep.rendering import (
|
|
55
|
+
CHARACTER_UNIT,
|
|
56
|
+
_claim_event,
|
|
57
|
+
_commits_json,
|
|
58
|
+
_load_json,
|
|
59
|
+
_nothing_json,
|
|
60
|
+
)
|
|
61
|
+
from roadkeep.serving import Prose, Withheld, detail, surface
|
|
62
|
+
from roadkeep.showing import show
|
|
63
|
+
from roadkeep.verbs.declaring import (
|
|
64
|
+
_DESIGNED_HELP,
|
|
65
|
+
_HAVE_HELP,
|
|
66
|
+
_JSON_HELP,
|
|
67
|
+
_PIPE,
|
|
68
|
+
_counting_flags,
|
|
69
|
+
_marker_flag,
|
|
70
|
+
answers,
|
|
71
|
+
narrows,
|
|
72
|
+
withheld,
|
|
73
|
+
)
|
|
74
|
+
from roadkeep.verbs.reading import _body_reader, _one_body, _piped
|
|
75
|
+
from roadkeep.verbs.refusing import EXIT_GATE, EXIT_OK, EXIT_USAGE, REFUSALS, _refused
|
|
76
|
+
from roadkeep.weighing import Weighed, weigh
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
def _census(config: Config, args: argparse.Namespace) -> tuple[Census, Standing | None]:
|
|
80
|
+
"""The census a `--block` narrows, and what became of the label it named (RK429).
|
|
81
|
+
|
|
82
|
+
A count reads one file, and keeping it that way is why `stats` cannot go stale against
|
|
83
|
+
a changelog it never read. So the second file is opened only where a label was named,
|
|
84
|
+
and what it answers is never counted — only said, on stderr, beside a listing that is
|
|
85
|
+
still exactly what the file holds.
|
|
86
|
+
|
|
87
|
+
Exactly one state changes what this returns, and it is the narrow one: a label this
|
|
88
|
+
file declares no heading for **and** that has nothing left anywhere — the block whose
|
|
89
|
+
last line shipped and whose roadmap heading `block drop` then took. A **live** block
|
|
90
|
+
missing from the file being counted keeps its refusal, because there the file really
|
|
91
|
+
does not declare a label that work is filed under, and `unknown` keeps its own for the
|
|
92
|
+
reason it exists: it is the only one that is a typo.
|
|
93
|
+
"""
|
|
94
|
+
marker = getattr(args, "marker", None)
|
|
95
|
+
census = Census.read(config, args.role)
|
|
96
|
+
if args.block is None:
|
|
97
|
+
return census.select(marker=marker), None
|
|
98
|
+
if not config.has("roadmap") or not config.path("roadmap").is_file():
|
|
99
|
+
# Nothing to join against: the reader below needs the roadmap, and a project
|
|
100
|
+
# counting a ledger before `init` wrote one still gets the count it asked for.
|
|
101
|
+
return census.select(block=args.block, marker=marker), None
|
|
102
|
+
standing = Backlog.load(config).standing(args.block)
|
|
103
|
+
if standing.settled and args.block not in census.blocks:
|
|
104
|
+
# Narrowed by the marker first and *then* emptied, so an undeclared marker is
|
|
105
|
+
# refused here exactly as it is on every other path: a filter nobody validated is
|
|
106
|
+
# a filter that silently matches nothing, which is the answer a clean file gives.
|
|
107
|
+
return census.select(marker=marker).elsewhere(args.block), standing
|
|
108
|
+
if standing.stage is Stage.UNKNOWN and args.block in census.blocks:
|
|
109
|
+
# The file being counted declares a label the roadmap and the ledger do not — a
|
|
110
|
+
# deferred store is the one that can. Saying `unknown` beside the lines it just
|
|
111
|
+
# listed would be the payload contradicting the listing.
|
|
112
|
+
return census.select(block=args.block, marker=marker), None
|
|
113
|
+
return census.select(block=args.block, marker=marker), standing
|
|
114
|
+
|
|
115
|
+
|
|
116
|
+
def _list(config: Config, args: argparse.Namespace) -> int:
|
|
117
|
+
try:
|
|
118
|
+
census, standing = _census(config, args)
|
|
119
|
+
except (KeyError, OSError) as error:
|
|
120
|
+
return _refused(error)
|
|
121
|
+
|
|
122
|
+
if args.json:
|
|
123
|
+
print(json.dumps(census.listing(standing), indent=2))
|
|
124
|
+
else:
|
|
125
|
+
listed = census.listed(args.ids)
|
|
126
|
+
if listed:
|
|
127
|
+
print(listed)
|
|
128
|
+
for note in census.notes(standing):
|
|
129
|
+
print(note, file=sys.stderr)
|
|
130
|
+
return EXIT_OK
|
|
131
|
+
|
|
132
|
+
|
|
133
|
+
def _stats(config: Config, args: argparse.Namespace) -> int:
|
|
134
|
+
try:
|
|
135
|
+
census, standing = _census(config, args)
|
|
136
|
+
except (KeyError, OSError) as error:
|
|
137
|
+
return _refused(error)
|
|
138
|
+
# The capture debt is a second subject and joined here (RK1139): a capture is not a line
|
|
139
|
+
# of the file this counts, so reading one inside the census would make a count of the
|
|
140
|
+
# roadmap depend on a directory git ignores.
|
|
141
|
+
owed = debt(config)
|
|
142
|
+
if args.json:
|
|
143
|
+
print(json.dumps(census.counts(config, standing, owed), indent=2))
|
|
144
|
+
else:
|
|
145
|
+
print(census.counted_out(config, owed))
|
|
146
|
+
for note in census.silence(standing):
|
|
147
|
+
print(note, file=sys.stderr)
|
|
148
|
+
return EXIT_OK
|
|
149
|
+
|
|
150
|
+
|
|
151
|
+
def _audit(config: Config, args: argparse.Namespace) -> int:
|
|
152
|
+
try:
|
|
153
|
+
census, standing = _census(config, args)
|
|
154
|
+
except (KeyError, OSError) as error:
|
|
155
|
+
return _refused(error)
|
|
156
|
+
|
|
157
|
+
if args.json:
|
|
158
|
+
print(json.dumps(census.audit(standing), indent=2))
|
|
159
|
+
else:
|
|
160
|
+
print(census.audited())
|
|
161
|
+
for note in census.silence(standing):
|
|
162
|
+
print(note, file=sys.stderr)
|
|
163
|
+
return EXIT_OK
|
|
164
|
+
|
|
165
|
+
|
|
166
|
+
def _claims(config: Config, args: argparse.Namespace) -> int:
|
|
167
|
+
"""The registry read against the roadmap (RK161). Nothing here is a failure, so exit 0."""
|
|
168
|
+
try:
|
|
169
|
+
# The whole backlog and not the roadmap alone (RK164): three of the four ways an id can
|
|
170
|
+
# be absent from it are recorded in the other two files.
|
|
171
|
+
if args.prune:
|
|
172
|
+
pruning = claiming.prune(config)
|
|
173
|
+
rows, dropped = pruning.kept, pruning.dropped
|
|
174
|
+
else:
|
|
175
|
+
rows, dropped = claiming.survey(Backlog.load(config)), ()
|
|
176
|
+
except (KeyError, OSError) as error:
|
|
177
|
+
return _refused(error)
|
|
178
|
+
|
|
179
|
+
answer = claiming.Registry(
|
|
180
|
+
rows=tuple(rows),
|
|
181
|
+
dropped=tuple(dropped),
|
|
182
|
+
pruned=bool(args.prune),
|
|
183
|
+
registry=str(claiming.path(config.root)),
|
|
184
|
+
window=config.held,
|
|
185
|
+
)
|
|
186
|
+
|
|
187
|
+
if args.json:
|
|
188
|
+
print(json.dumps(answer.payload(), indent=2))
|
|
189
|
+
else:
|
|
190
|
+
print(answer.stated())
|
|
191
|
+
return EXIT_OK
|
|
192
|
+
|
|
193
|
+
|
|
194
|
+
def _claim(config: Config, args: argparse.Namespace) -> int:
|
|
195
|
+
"""One held line's scope: declared, or read back at the commit (RK280).
|
|
196
|
+
|
|
197
|
+
The read is the half that earns the command. `git status` shows a tree two sessions wrote
|
|
198
|
+
and says nothing about which half is whose, so the author committing was left an analysis
|
|
199
|
+
to make with no facts to make it from — and `agents.md` carried the answer as advice,
|
|
200
|
+
which RK1 says does not hold. Here the three lists are separate because the caller does
|
|
201
|
+
three different things with them: stage `mine`, leave `theirs`, and decide about `loose`.
|
|
202
|
+
|
|
203
|
+
`--add-path` is the same write from the other end (RK307), and passing both is refused
|
|
204
|
+
rather than merged: `--path` says *this is the scope* and `--add-path` says *and this
|
|
205
|
+
too*, so a call making both statements is one whose author has not decided which — and
|
|
206
|
+
reading it as either would be the tool picking.
|
|
207
|
+
"""
|
|
208
|
+
backlog = Backlog.load(config)
|
|
209
|
+
entries = backlog.roadmap.entries
|
|
210
|
+
if args.path and args.add_path:
|
|
211
|
+
return _refused(
|
|
212
|
+
ValueError(
|
|
213
|
+
"--path replaces the scope and --add-path keeps it, so a call passing both "
|
|
214
|
+
"says two things about one commit: name the whole scope with --path, or add "
|
|
215
|
+
"to what is already there with --add-path alone"
|
|
216
|
+
)
|
|
217
|
+
)
|
|
218
|
+
try:
|
|
219
|
+
if args.path or args.add_path:
|
|
220
|
+
mine = claiming.scope(
|
|
221
|
+
config,
|
|
222
|
+
args.id,
|
|
223
|
+
args.path or args.add_path,
|
|
224
|
+
extend=bool(args.add_path),
|
|
225
|
+
)
|
|
226
|
+
else:
|
|
227
|
+
held = next((one for one in claiming.live(config, entries) if one.id == args.id), None)
|
|
228
|
+
if held is None:
|
|
229
|
+
raise claiming.NotHeld(args.id)
|
|
230
|
+
mine = held.paths
|
|
231
|
+
except (claiming.NotHeld, KeyError, OSError) as error:
|
|
232
|
+
return _refused(error)
|
|
233
|
+
|
|
234
|
+
# What this task's own transactions already wrote (RK342), by the reading `ship` makes
|
|
235
|
+
# off its own `save` — which only exists inside a transaction, so here it is read off
|
|
236
|
+
# the files: a claim moved a marker onto this line and the projections were refreshed
|
|
237
|
+
# from it, and both diffs name the id. Without it the report called them `loose`, which
|
|
238
|
+
# reads as *somebody else touched this*, and the author declared them by hand to
|
|
239
|
+
# silence it — the scope then carrying paths that were never the work.
|
|
240
|
+
seen = status(config)
|
|
241
|
+
wrote = claiming.written(config, args.id, seen.changed)
|
|
242
|
+
# The subtraction is `claiming`'s (RK294), because `ship` asks for the same lists at the
|
|
243
|
+
# moment of committing and two compositions of one answer is how they come to disagree.
|
|
244
|
+
# Git is asked here and not there: this command was told to answer.
|
|
245
|
+
# `accounted=wrote` (RK1117): here the word means what it always meant on this path — the
|
|
246
|
+
# dirty governed files whose diff carries this id — and the subtraction it feeds is the
|
|
247
|
+
# same one a departure makes, now made in one place rather than by each printer.
|
|
248
|
+
#
|
|
249
|
+
# And `shared` with it (RK1122): this is the read a commit is composed from, so the ids
|
|
250
|
+
# inside a file it is about to stage are exactly what it exists to say. Asked here rather
|
|
251
|
+
# than deep in the split for the same reason git is — this command was told to answer.
|
|
252
|
+
answer = claiming.Claimed(
|
|
253
|
+
task_id=args.id,
|
|
254
|
+
scope=claiming.split(
|
|
255
|
+
config,
|
|
256
|
+
args.id,
|
|
257
|
+
entries,
|
|
258
|
+
seen.changed,
|
|
259
|
+
indexed(config),
|
|
260
|
+
accounted=wrote,
|
|
261
|
+
shared=claiming.sharing(config, args.id, wrote),
|
|
262
|
+
staged=seen.staged,
|
|
263
|
+
),
|
|
264
|
+
wrote=tuple(wrote),
|
|
265
|
+
)
|
|
266
|
+
|
|
267
|
+
# Three registers and not two (RK1170): `--porcelain` is a third reading of one result and
|
|
268
|
+
# not a narrowing of either — a shell consumes it, so it carries paths and nothing else.
|
|
269
|
+
if args.porcelain:
|
|
270
|
+
print(answer.porcelain())
|
|
271
|
+
elif args.json:
|
|
272
|
+
print(json.dumps(answer.payload(), indent=2))
|
|
273
|
+
else:
|
|
274
|
+
print(answer.stated())
|
|
275
|
+
return EXIT_OK
|
|
276
|
+
|
|
277
|
+
|
|
278
|
+
def _writes(config: Config, args: argparse.Namespace) -> int:
|
|
279
|
+
"""The write record read against the files (RK200). Nothing here is a failure, so exit 0."""
|
|
280
|
+
survey = attesting.Survey(
|
|
281
|
+
attesting.survey(config), str(attesting.record_path(config.root))
|
|
282
|
+
)
|
|
283
|
+
if args.json:
|
|
284
|
+
print(json.dumps(survey.payload(), indent=2))
|
|
285
|
+
else:
|
|
286
|
+
print(survey.stated())
|
|
287
|
+
return EXIT_OK
|
|
288
|
+
|
|
289
|
+
|
|
290
|
+
def _brief(config: Config, args: argparse.Namespace) -> int:
|
|
291
|
+
if args.id is not None and (args.block is not None or args.designed or args.have):
|
|
292
|
+
# Two answers to one question: the id names a task and the others name a search.
|
|
293
|
+
# `--have` joins them for the same reason and not a weaker one (RK1297): it narrows
|
|
294
|
+
# what may be *chosen*, and a caller that named the line has already chosen — the
|
|
295
|
+
# refusal it would otherwise want is `brief <id>`'s own, which this verb does not make.
|
|
296
|
+
narrowed = (
|
|
297
|
+
"--block"
|
|
298
|
+
if args.block is not None
|
|
299
|
+
else ("--designed" if args.designed else "--have")
|
|
300
|
+
)
|
|
301
|
+
print(
|
|
302
|
+
f"roadkeep: give an id or {narrowed}, not both: an id is already the answer "
|
|
303
|
+
f"{narrowed} would look for",
|
|
304
|
+
file=sys.stderr,
|
|
305
|
+
)
|
|
306
|
+
return EXIT_USAGE
|
|
307
|
+
try:
|
|
308
|
+
gathered = brief(
|
|
309
|
+
config, args.id, args.block, args.designed, args.claim, args.have
|
|
310
|
+
)
|
|
311
|
+
except NothingToBrief as nothing:
|
|
312
|
+
# The one branch a loop actually reads, and the one `--json` did not cover (RK409).
|
|
313
|
+
# `brief --block <x>` is how a worker asks what to do next, and "nothing is open in
|
|
314
|
+
# Block <x>" is the only answer that means the block is finished — so a loop driving
|
|
315
|
+
# one to completion polls exactly this, and asked for JSON got an empty stdout and
|
|
316
|
+
# the sentence on stderr, where a real failure also lands.
|
|
317
|
+
#
|
|
318
|
+
# Still **not** exit 0, and still not a fourth exit code. An empty answer is nothing
|
|
319
|
+
# to brief, so succeeding would make a typo'd block name look like a finished one;
|
|
320
|
+
# and what the caller could not do at exit 2 was tell those two apart, which the
|
|
321
|
+
# payload now answers directly — `standing.state` is the word, `empty` stays the
|
|
322
|
+
# boolean it always was, and the refusal for a name nothing declares never reaches
|
|
323
|
+
# here at all (RK429 made the sentence say which; this comment predates it).
|
|
324
|
+
if args.json:
|
|
325
|
+
print(json.dumps(_nothing_json(nothing, args), indent=2))
|
|
326
|
+
return EXIT_USAGE
|
|
327
|
+
return _refused(nothing)
|
|
328
|
+
except REFUSALS as error:
|
|
329
|
+
# The whole tuple, because `--claim` makes this a write (RK149): every refusal that
|
|
330
|
+
# guards a marker reaches here, plus the one this door has of its own — a named line
|
|
331
|
+
# somebody else is already holding.
|
|
332
|
+
return _refused(error)
|
|
333
|
+
|
|
334
|
+
# Both registers off the record (RK1170), and the last of the verbs that task measured:
|
|
335
|
+
# `Brief` is the answer, and its two readings were 20 prints here and a builder in
|
|
336
|
+
# `rendering.py` — one answer in two files, with neither of them where a brief is composed.
|
|
337
|
+
print(json.dumps(gathered.payload(config), indent=2) if args.json else gathered.stated(config))
|
|
338
|
+
return EXIT_OK
|
|
339
|
+
|
|
340
|
+
|
|
341
|
+
def _show(config: Config, args: argparse.Namespace) -> int:
|
|
342
|
+
"""One task, whole, from every file that holds a piece of it (RK9).
|
|
343
|
+
|
|
344
|
+
Both registers come off the record (RK1170): `View` is the answer, and its two readings were a
|
|
345
|
+
printer here and a builder in `rendering.py` — one verb spelled in two files, with neither
|
|
346
|
+
holding both. What is left here is the door.
|
|
347
|
+
"""
|
|
348
|
+
try:
|
|
349
|
+
view = show(config, args.id)
|
|
350
|
+
except (KeyError, OSError) as error:
|
|
351
|
+
return _refused(error)
|
|
352
|
+
|
|
353
|
+
if args.json:
|
|
354
|
+
print(json.dumps(view.payload(body=not args.no_body), indent=2))
|
|
355
|
+
else:
|
|
356
|
+
print(view.stated(config, body=not args.no_body))
|
|
357
|
+
return EXIT_OK
|
|
358
|
+
|
|
359
|
+
|
|
360
|
+
def _cost(config: Config, args: argparse.Namespace) -> int:
|
|
361
|
+
"""What this project's surface already spends (RK1321).
|
|
362
|
+
|
|
363
|
+
`_budget`'s dispatch for the other tense. The three subjects moved here whole — the same
|
|
364
|
+
readers, the same registers — because what split was the *verb* and not any answer: eight
|
|
365
|
+
subjects under one name made `budget` the largest served tool at 2,741, against a per-tool
|
|
366
|
+
ceiling calibrated on `ship` at 2,466, so whichever arrived last was refused by a limit
|
|
367
|
+
none of them was about.
|
|
368
|
+
|
|
369
|
+
Which subject was asked for, and that exactly one was, is `answers` at this verb's own
|
|
370
|
+
`add_parser` and `dispatch`'s to refuse (RK489) — so what is left here is the dispatch.
|
|
371
|
+
"""
|
|
372
|
+
# `is not None` and not truth (RK1236): bare `--tools` is the empty string, the flag
|
|
373
|
+
# taking a value, which is `--brief`'s reading one subject over.
|
|
374
|
+
if args.tools is not None:
|
|
375
|
+
return _tools_budget(config, args)
|
|
376
|
+
if args.brief is not None:
|
|
377
|
+
return _brief_budget(config, args)
|
|
378
|
+
if args.session:
|
|
379
|
+
return _session_budget(config, args)
|
|
380
|
+
# No subject is the default here, unlike `budget`, whose bare form is about the line `add`
|
|
381
|
+
# would write next. These three are three cadences — once at connect, once per turn, once
|
|
382
|
+
# per read — and privileging one would make the other two look like narrowings of it.
|
|
383
|
+
print(
|
|
384
|
+
"roadkeep: cost takes a subject: --tools for the served surface, --brief for what "
|
|
385
|
+
"that read costs a tool result, --session for both against their cadences",
|
|
386
|
+
file=sys.stderr,
|
|
387
|
+
)
|
|
388
|
+
return EXIT_USAGE
|
|
389
|
+
|
|
390
|
+
|
|
391
|
+
def _budget(config: Config, args: argparse.Namespace) -> int:
|
|
392
|
+
# Which of the three subjects was asked for, and whether `--role` or `--lead` came with
|
|
393
|
+
# the one it narrows, are `answers` and `narrows` at this verb's own `add_parser` and
|
|
394
|
+
# `dispatch`'s to refuse (RK489). What is left here is the dispatch itself.
|
|
395
|
+
if args.anchor:
|
|
396
|
+
return _body_budget(config, args)
|
|
397
|
+
if args.non_goal:
|
|
398
|
+
return _non_goal_budget(config, args)
|
|
399
|
+
if args.file is not None:
|
|
400
|
+
return _file_budget(config, args)
|
|
401
|
+
clash = _one_body("--body", args.body, args.body_file)
|
|
402
|
+
if clash is not None:
|
|
403
|
+
print(f"roadkeep: {clash}", file=sys.stderr)
|
|
404
|
+
return EXIT_USAGE
|
|
405
|
+
try:
|
|
406
|
+
answer = budget(
|
|
407
|
+
config,
|
|
408
|
+
args.id,
|
|
409
|
+
block=args.block,
|
|
410
|
+
deps=args.deps,
|
|
411
|
+
status=args.status,
|
|
412
|
+
symptom=args.symptom,
|
|
413
|
+
family=args.family,
|
|
414
|
+
ref=args.ref,
|
|
415
|
+
# Read here and not in `budgeting`, which touches no stream: the pipe is this
|
|
416
|
+
# surface's affordance and the module measures whatever it is handed (RK1190).
|
|
417
|
+
why=_piped(args.why),
|
|
418
|
+
# And the other half of the same transaction (RK1224): `add --section` writes a
|
|
419
|
+
# line and a body together, so pricing them in two calls made the retry for a
|
|
420
|
+
# three-character overflow carry the whole paragraph again.
|
|
421
|
+
body=(
|
|
422
|
+
None
|
|
423
|
+
if args.body is None and args.body_file is None
|
|
424
|
+
else _body_reader(args.body, args.body_file)()
|
|
425
|
+
),
|
|
426
|
+
# The third write off the same line (RK1305). `is not None` and not truth, which is
|
|
427
|
+
# `--tools`' reading: bare `--retire` is the empty string and means abandoned.
|
|
428
|
+
retire=args.retire,
|
|
429
|
+
)
|
|
430
|
+
except REFUSALS as error:
|
|
431
|
+
return _refused(error)
|
|
432
|
+
|
|
433
|
+
# Both registers off the record (RK1170): `Budget` already was the result this verb computed,
|
|
434
|
+
# and its two readings were a printer here and a builder in `rendering.py` — one answer in two
|
|
435
|
+
# files, with neither holding both.
|
|
436
|
+
print(json.dumps(answer.payload(), indent=2) if args.json else answer)
|
|
437
|
+
# Both halves of the transaction decide it (RK1224): a body three words over is a call the
|
|
438
|
+
# `add` refuses whole, so an exit that spoke only for the line would answer a question
|
|
439
|
+
# narrower than the one the caller asked.
|
|
440
|
+
return _verdict(
|
|
441
|
+
any(share.over for share in answer.shares if share.drafted)
|
|
442
|
+
or bool(answer.section is not None and answer.section.over)
|
|
443
|
+
)
|
|
444
|
+
|
|
445
|
+
|
|
446
|
+
def _verdict(over: bool) -> int:
|
|
447
|
+
"""Exit 1 where a draft this call was handed does not fit (RK1190).
|
|
448
|
+
|
|
449
|
+
`EXIT_GATE`, and it is that code's own meaning: the write this read stands in for would have
|
|
450
|
+
refused, and a caller asking *will this fit* should not have to parse prose for the one bit
|
|
451
|
+
it asked for. Over MCP the same code becomes `isError`, which is what makes the answer usable
|
|
452
|
+
by the agent this whole read exists for.
|
|
453
|
+
|
|
454
|
+
**Only about a draft**, which is the narrowing that keeps this a read. A line the roadmap
|
|
455
|
+
already holds over its allowance is a `lint` finding and the gate's business; reporting it
|
|
456
|
+
here as a failure would make `budget <id>` exit non-zero over a file it was only asked to
|
|
457
|
+
describe, and make one verb answer for two different questions with one code.
|
|
458
|
+
"""
|
|
459
|
+
return EXIT_GATE if over else EXIT_OK
|
|
460
|
+
|
|
461
|
+
|
|
462
|
+
def _body_budget(config: Config, args: argparse.Namespace) -> int:
|
|
463
|
+
"""What a section body may say, before it is written — and what a draft of it costs.
|
|
464
|
+
|
|
465
|
+
The draft is read the way every writing verb reads one (RK381, RK329): a literal, a path,
|
|
466
|
+
or the pipe that `-` names. Unlike those verbs it is **optional here**, so an omitted
|
|
467
|
+
`--body` reads nothing at all rather than blocking on a stream nobody opened — the whole
|
|
468
|
+
subject of this call is a limit, which is answerable with no prose in hand (RK1190).
|
|
469
|
+
"""
|
|
470
|
+
clash = _one_body("--body", args.body, args.body_file)
|
|
471
|
+
if clash is not None:
|
|
472
|
+
print(f"roadkeep: {clash}", file=sys.stderr)
|
|
473
|
+
return EXIT_USAGE
|
|
474
|
+
try:
|
|
475
|
+
# Inside the try for `section add`'s reason: prose that is not UTF-8 raises
|
|
476
|
+
# UnicodeDecodeError, which is a ValueError and is refused with the same code.
|
|
477
|
+
draft = (
|
|
478
|
+
None
|
|
479
|
+
if args.body is None and args.body_file is None
|
|
480
|
+
else _body_reader(args.body, args.body_file)()
|
|
481
|
+
)
|
|
482
|
+
answer = body_budget(config, args.anchor, args.role, draft)
|
|
483
|
+
except REFUSALS as error:
|
|
484
|
+
return _refused(error)
|
|
485
|
+
if args.json:
|
|
486
|
+
print(json.dumps({"subject": "section", **answer.payload()}, indent=2))
|
|
487
|
+
return _verdict(bool(answer.over))
|
|
488
|
+
state = "written" if answer.written else "the section add would write"
|
|
489
|
+
print(f"§{answer.anchor} {answer.role} ({state})")
|
|
490
|
+
print(f" body {answer.stated(named=False)}")
|
|
491
|
+
return _verdict(bool(answer.over))
|
|
492
|
+
|
|
493
|
+
|
|
494
|
+
def _file_budget(config: Config, args: argparse.Namespace) -> int:
|
|
495
|
+
"""What an always-loaded file has left, before the edit is composed (RK345)."""
|
|
496
|
+
try:
|
|
497
|
+
loads = file_budget(config, args.file or None)
|
|
498
|
+
except REFUSALS as error:
|
|
499
|
+
return _refused(error)
|
|
500
|
+
if args.json:
|
|
501
|
+
print(json.dumps({"subject": "file", "files": [_load_json(one) for one in loads]},
|
|
502
|
+
indent=2))
|
|
503
|
+
return EXIT_OK
|
|
504
|
+
for load in loads:
|
|
505
|
+
# The state `lint` calls `budget.absent`, said here too: a declared file that is not
|
|
506
|
+
# there has its whole budget free, which is the one reading that looks like room.
|
|
507
|
+
state = "on disk" if load.present else "not on disk — the entry holds nothing"
|
|
508
|
+
print(f"{load.path} budgeted ({state})")
|
|
509
|
+
for cost in load.costs:
|
|
510
|
+
# No aim and no second unit (RK258): `[budgets]` is declared in what the loader
|
|
511
|
+
# pays, so a word figure beside it would be a number this project never stated.
|
|
512
|
+
over = f", {cost.over} over" if cost.over else f", {cost.left} left"
|
|
513
|
+
print(f" {cost.unit:<11}{cost.taken} of {cost.limit}{over}")
|
|
514
|
+
if load.translated:
|
|
515
|
+
# The remainder the ceiling does not charge (RK1105). Printed under the units and
|
|
516
|
+
# not beside one, because it is a fact about the checkout and not about the budget:
|
|
517
|
+
# the number above decides, and this one is what a loader here actually reads.
|
|
518
|
+
print(
|
|
519
|
+
f" {'checkout':<11}{load.translated} more, this tree's lines ending CRLF — "
|
|
520
|
+
f"counted as the commit stores them"
|
|
521
|
+
)
|
|
522
|
+
_print_parts(load)
|
|
523
|
+
if load.characters is not None:
|
|
524
|
+
# The figure the author is actually deciding against (RK1250), on the read RK345
|
|
525
|
+
# built for the moment before an edit — `--session` has had it since RK1245 and
|
|
526
|
+
# this one, the more likely to be open, threw it away.
|
|
527
|
+
#
|
|
528
|
+
# A **row** and not a clause on a cost, which is RK258's line kept rather than
|
|
529
|
+
# crossed: that task refused a word figure *beside a declared unit*, because
|
|
530
|
+
# `[budgets]` is stated in what the loader pays and an aim next to it would be a
|
|
531
|
+
# number this project never wrote. This is not next to one and is not an aim — it
|
|
532
|
+
# is a reading, and its clause says outright that nothing limits it.
|
|
533
|
+
#
|
|
534
|
+
# **Last, and under the breakdown** (RK1252). Printed between the limits and the
|
|
535
|
+
# sections, it was the total a reader met immediately before a list ranked in
|
|
536
|
+
# another unit — so the adjacency said *this is what those are of*, which it is
|
|
537
|
+
# not. The breakdown belongs to the ceiling above it; this belongs to neither.
|
|
538
|
+
print(
|
|
539
|
+
f" {'reader':<11}{load.characters} utf-16-code-units, what a model is "
|
|
540
|
+
f"charged — a reading, and nothing here limits it"
|
|
541
|
+
)
|
|
542
|
+
return EXIT_OK
|
|
543
|
+
|
|
544
|
+
|
|
545
|
+
#: How many sections the terminal names, for `_LARGEST_TOOLS`' reason: the largest few are
|
|
546
|
+
#: where the size went, and a caller reading a report to decide what to cut wants those.
|
|
547
|
+
_LARGEST_PARTS = 4
|
|
548
|
+
|
|
549
|
+
|
|
550
|
+
def _print_parts(load: Load) -> None:
|
|
551
|
+
"""Where the size is, so the next compression is aimed (RK1092).
|
|
552
|
+
|
|
553
|
+
The read `cost --tools` makes about the served surface, one file over: a total says an
|
|
554
|
+
edit will be refused and says nothing about what to take out, and `agents.md` reaching
|
|
555
|
+
eight bytes of room turned *compress the prose* into a preference nothing had re-measured.
|
|
556
|
+
|
|
557
|
+
Only where the file is on disk and holds more than one section, because a single-section
|
|
558
|
+
file's breakdown is the total printed twice.
|
|
559
|
+
|
|
560
|
+
**Ranked by the limit about to refuse** (RK1252), which is :attr:`Load.ranked`'s decision
|
|
561
|
+
and not this renderer's: a file at 104 of 125 lines and 6906 of 8400 bytes is a line
|
|
562
|
+
problem, and a list ordered by bytes names a section that is not the one to cut. The
|
|
563
|
+
ranking unit leads the row, so the column a reader sorts on is the column they scan.
|
|
564
|
+
"""
|
|
565
|
+
if len(load.parts) < 2:
|
|
566
|
+
return
|
|
567
|
+
unit = "bytes" if load.tightest is None else load.tightest.unit
|
|
568
|
+
other = "bytes" if unit == "lines" else "lines"
|
|
569
|
+
ranked = load.ranked
|
|
570
|
+
# Three figures need a header, where two did not (RK1253): the leading column varies with
|
|
571
|
+
# the ceiling and the third is a reading rather than a limit, so a row of bare numbers no
|
|
572
|
+
# longer says which is which. Named in the order they are printed, ranking unit first.
|
|
573
|
+
reading = " reader" if ranked[0].characters is not None else ""
|
|
574
|
+
print(f" {unit:>6} {other:>6}{reading}")
|
|
575
|
+
for part in ranked[:_LARGEST_PARTS]:
|
|
576
|
+
first, second = (part.lines, part.bytes) if unit == "lines" else (part.bytes, part.lines)
|
|
577
|
+
# Both declared columns at one width, because which of them leads now varies: a `>3`
|
|
578
|
+
# sized for lines misaligns the byte figure it may now hold.
|
|
579
|
+
said = f" {first:>6} {second:>6}"
|
|
580
|
+
if part.characters is not None:
|
|
581
|
+
said += f" {part.characters:>6}"
|
|
582
|
+
print(f"{said} {part.heading or '(before the first ##)'}")
|
|
583
|
+
if len(ranked) > _LARGEST_PARTS:
|
|
584
|
+
print(f" … and {len(ranked) - _LARGEST_PARTS} more — `--json` lists every one")
|
|
585
|
+
|
|
586
|
+
|
|
587
|
+
def _non_goal_budget(config: Config, args: argparse.Namespace) -> int:
|
|
588
|
+
"""The two limits the roadmap's other bullet has (RK283)."""
|
|
589
|
+
try:
|
|
590
|
+
shares = non_goal_budget(config, args.lead)
|
|
591
|
+
except REFUSALS as error:
|
|
592
|
+
return _refused(error)
|
|
593
|
+
if args.json:
|
|
594
|
+
print(json.dumps({"subject": "non-goal", "lead": args.lead,
|
|
595
|
+
"fields": [one.payload() for one in shares]}, indent=2))
|
|
596
|
+
return EXIT_OK
|
|
597
|
+
where = config.relative(config.path("roadmap"))
|
|
598
|
+
state = f"the bullet leading {args.lead!r}" if args.lead else "the bullet add would write"
|
|
599
|
+
print(f"non-goals {where} ({state})")
|
|
600
|
+
# The line `Budget.__str__` prints for the same reason (RK1366): `non-goal amend --why`
|
|
601
|
+
# replaces that argument, so each remainder below is the whole limit and a reader given
|
|
602
|
+
# `37 written, 200 left` against 200 otherwise reads the two as adding up.
|
|
603
|
+
if any(share.replaced and share.taken for share in shares):
|
|
604
|
+
print(
|
|
605
|
+
" replacing what is written below, so each remainder is the whole limit and "
|
|
606
|
+
"not what is left beside it — an amend rewrites the field"
|
|
607
|
+
)
|
|
608
|
+
for share in shares:
|
|
609
|
+
# No `bound_by_line`: a non-goal is two fields on two lines and there is no third
|
|
610
|
+
# limit measured across them, which is the whole difference from a task line.
|
|
611
|
+
taken = f", {share.taken} written, {share.left} left" if share.taken else ""
|
|
612
|
+
print(f" {share.field:<11}{share.limit}{taken} {share.aimed}")
|
|
613
|
+
return EXIT_OK
|
|
614
|
+
|
|
615
|
+
|
|
616
|
+
#: How many tools the listing names before it stops naming them one by one. The largest few
|
|
617
|
+
#: are where the size went, and a caller reading a report to decide what to cut wants those;
|
|
618
|
+
#: the rest is the total, which is the number this read exists to state (RK464).
|
|
619
|
+
_LARGEST_TOOLS = 5
|
|
620
|
+
|
|
621
|
+
|
|
622
|
+
def _session_budget(config: Config, args: argparse.Namespace) -> int:
|
|
623
|
+
"""Both halves of what a session pays, against the cadence each is paid at (RK1095).
|
|
624
|
+
|
|
625
|
+
`--tools` totals the served schema and `--file` totals a resident file, and neither knew
|
|
626
|
+
the other existed — so an author deciding whether to cut a tool description or a
|
|
627
|
+
paragraph ran two commands and subtracted by hand. That is the arithmetic RK183 removed
|
|
628
|
+
from the line budget and RK345 from the file one, still standing one level above both.
|
|
629
|
+
|
|
630
|
+
**Two figures and never a sum.** The schema is sent once at the handshake and a resident
|
|
631
|
+
file is read on every turn, so adding them produces a number that is wrong for every
|
|
632
|
+
session whose turn count is not one — which is all of them. What is honest is naming each
|
|
633
|
+
against what it is paid for, and letting the reader multiply the half that repeats.
|
|
634
|
+
|
|
635
|
+
The skill is not here, deliberately (RK23): it is trigger-loaded, so it costs the turns
|
|
636
|
+
that write and nothing on the turns that do not, and pricing it as resident would be the
|
|
637
|
+
third figure this read exists to avoid inventing.
|
|
638
|
+
"""
|
|
639
|
+
# One measurement, two readers (RK1096) — the rule RK345 already states about the file
|
|
640
|
+
# half, applied to the surface: `--tools` ranks what this returns and `--session` totals
|
|
641
|
+
# it, so a change to what the handshake carries moves both or neither.
|
|
642
|
+
sent = surface(config)
|
|
643
|
+
resident, limit = notice_budget(config)
|
|
644
|
+
answer = Session(
|
|
645
|
+
once=sent.characters,
|
|
646
|
+
tools=len(sent.tools),
|
|
647
|
+
# The records themselves (RK1248): both readings of one file (RK1245) plus the room
|
|
648
|
+
# its own `[budgets]` line declares, all of which `Load` already holds.
|
|
649
|
+
resident=file_budget(config) if config.budgets else (),
|
|
650
|
+
# The third thing a session pays for (RK1243), and the one that had a ceiling nobody
|
|
651
|
+
# could ask about — measured off `announce`, so it is the line this project's sessions
|
|
652
|
+
# actually get rather than a second estimate of it.
|
|
653
|
+
# What the checkout contributes, named apart from what the surface does (RK1334): a
|
|
654
|
+
# session really is sent it, so it stays inside `once`, and no author can edit it, so
|
|
655
|
+
# the ceiling is not about it.
|
|
656
|
+
provenance=sent.provenance,
|
|
657
|
+
notice=resident,
|
|
658
|
+
notice_limit=limit,
|
|
659
|
+
# The ceiling `budget.session` refuses this total against, which is the single one
|
|
660
|
+
# there is (RK1333): read off the config here rather than recomputed, so the row and
|
|
661
|
+
# the gate cannot come apart the way the row and the notice's ceiling already had.
|
|
662
|
+
once_limit=config.tool_session,
|
|
663
|
+
)
|
|
664
|
+
|
|
665
|
+
if args.json:
|
|
666
|
+
print(json.dumps(answer.payload(CHARACTER_UNIT), indent=2))
|
|
667
|
+
else:
|
|
668
|
+
print(answer.stated(CHARACTER_UNIT))
|
|
669
|
+
return EXIT_OK
|
|
670
|
+
|
|
671
|
+
|
|
672
|
+
def _brief_budget(config: Config, args: argparse.Namespace) -> int:
|
|
673
|
+
"""What a brief costs a tool result, per open line or for the one named (RK1286).
|
|
674
|
+
|
|
675
|
+
The sixth subject, and the one about a **read** rather than about prose or a file. Every
|
|
676
|
+
resident file has a budget and the served surface has two, on RK30's argument that a limit
|
|
677
|
+
nobody counts is a limit that moves — and the read this project recommends over reading
|
|
678
|
+
the file had none, while growing four arithmetic rows in one session.
|
|
679
|
+
"""
|
|
680
|
+
from roadkeep.budgeting import brief_budget # noqa: PLC0415 - RK260
|
|
681
|
+
|
|
682
|
+
try:
|
|
683
|
+
found = brief_budget(config, args.brief or None)
|
|
684
|
+
except (KeyError, OSError) as error:
|
|
685
|
+
return _refused(error)
|
|
686
|
+
|
|
687
|
+
if args.json:
|
|
688
|
+
print(
|
|
689
|
+
json.dumps(
|
|
690
|
+
{
|
|
691
|
+
"unit": CHARACTER_UNIT,
|
|
692
|
+
"limit": found.limit,
|
|
693
|
+
"briefs": [
|
|
694
|
+
{"id": one.id, "characters": one.characters, "over": one.over(found.limit)}
|
|
695
|
+
for one in found.briefs
|
|
696
|
+
],
|
|
697
|
+
# What the ranking could not measure (RK1288), which is the fact the
|
|
698
|
+
# widest is wrong without: `[]` is an answer and never an absence.
|
|
699
|
+
"unpriced": [
|
|
700
|
+
{"id": one.id, "because": one.because} for one in found.unpriced
|
|
701
|
+
],
|
|
702
|
+
# Carried and never reconstructed (RK1289): priced, refused and not asked
|
|
703
|
+
# for are three numbers that add up to this one.
|
|
704
|
+
"elided": found.elided,
|
|
705
|
+
"open_lines": found.open_lines,
|
|
706
|
+
},
|
|
707
|
+
indent=2,
|
|
708
|
+
)
|
|
709
|
+
)
|
|
710
|
+
return EXIT_OK
|
|
711
|
+
# Both, because a ranking that is empty and a ranking whose every line refused are two
|
|
712
|
+
# answers (RK1288): the second has everything to report and nothing in the first column.
|
|
713
|
+
if not (found.briefs or found.unpriced):
|
|
714
|
+
print(
|
|
715
|
+
f"roadkeep: no open line to brief, so there is nothing to price — "
|
|
716
|
+
f"`{invocation()} list` says what the backlog holds"
|
|
717
|
+
)
|
|
718
|
+
return EXIT_OK
|
|
719
|
+
# The verdict says what it was taken over (RK1292). `0 over` beside a listing that names
|
|
720
|
+
# a line nobody could measure is a claim the ranking is not entitled to: the widest is
|
|
721
|
+
# the bound, and an unmeasured line is the shape most likely to be it. The gate has no
|
|
722
|
+
# such problem — there the absence is its own finding and the exit code is 1 either way —
|
|
723
|
+
# and here one string carried both the count and the confidence. Silent where nothing
|
|
724
|
+
# went unmeasured, which keeps the ordinary answer exactly as short as it was.
|
|
725
|
+
qualified = f", {len(found.unpriced)} unpriced" if found.unpriced else ""
|
|
726
|
+
ceiling = (
|
|
727
|
+
"no [reads] brief — this project declares no ceiling for the read that replaces "
|
|
728
|
+
"reading the file"
|
|
729
|
+
if found.limit is None
|
|
730
|
+
else f"{found.limit} allowed, {len(found.over)} over{qualified}"
|
|
731
|
+
)
|
|
732
|
+
rows = [f"{len(found.briefs)} brief(s), widest first, in {CHARACTER_UNIT}: {ceiling}"]
|
|
733
|
+
for one in found.briefs:
|
|
734
|
+
room = "" if found.limit is None else f" {found.limit - one.characters:+d}"
|
|
735
|
+
rows.append(f" {one.id:<10} {one.characters}{room}")
|
|
736
|
+
# Named under the ranking (RK1288): a line the read could not compose is the one most
|
|
737
|
+
# likely to have been the widest, so the top of the rest is not the answer while it is
|
|
738
|
+
# unaccounted for — and what refused it is the tool's own sentence, not one composed here.
|
|
739
|
+
rows += [f" {one.id:<10} unpriced — {one.because}" for one in found.unpriced]
|
|
740
|
+
print("\n".join(rows))
|
|
741
|
+
return EXIT_OK
|
|
742
|
+
|
|
743
|
+
|
|
744
|
+
def _tools_budget(config: Config, args: argparse.Namespace) -> int:
|
|
745
|
+
"""What this project's tool list costs a session, stated because nothing stated it (RK464).
|
|
746
|
+
|
|
747
|
+
RK30 put `[budgets]` on the files a session loads every turn, because resident prose has
|
|
748
|
+
no natural ceiling — the 186 KB `agents.md` in §0.1 is the measurement this project starts
|
|
749
|
+
from — and `lint` refuses one over. The schema this server publishes was counted nowhere:
|
|
750
|
+
measured on a three-file project, 51 tools and 52,892 characters, six times the budget the
|
|
751
|
+
resident file is held to, paid once per session that connects the server.
|
|
752
|
+
|
|
753
|
+
That is not a claim the list is too long. It is that the number was not stated, and RK30's
|
|
754
|
+
own argument is that a limit nobody counts is a limit that moves: every task adding a tool
|
|
755
|
+
or a sentence to a description spends this, and each spend looks free where it is written.
|
|
756
|
+
|
|
757
|
+
**And the ceiling §RK464 left open** (RK1059), once the number had been looked at: it is
|
|
758
|
+
per tool, declared as `[tools] characters`, and `lint` refuses one over. A total names
|
|
759
|
+
nothing — it fails on whichever tool is added last — where a per-tool figure is refused
|
|
760
|
+
by the tool whose description somebody just edited, which is the ranking this read
|
|
761
|
+
already prints. Reported here as the room a caller has before the gate says no, which is
|
|
762
|
+
the pairing RK345 makes everywhere else: a limit that reaches an author only as a refusal
|
|
763
|
+
is the verdict-after-the-prose this project exists to replace.
|
|
764
|
+
|
|
765
|
+
**Both halves of what a session is handed** (RK1062), because one of them was a place to
|
|
766
|
+
hide in. The handshake is the other message sent before the first call, and RK1060 moved
|
|
767
|
+
a paragraph from the tool list into it — a real saving, reported gross, by a read that
|
|
768
|
+
could not see where it went. An edit that saved nothing would have measured the same.
|
|
769
|
+
Not folded into the ranking: no per-tool ceiling is about it, so it is named under them.
|
|
770
|
+
|
|
771
|
+
Derived from :func:`~roadkeep.serving.descriptors`, so it is the payload a client is
|
|
772
|
+
actually sent rather than a second estimate of it: a description reworded in `cli.py`
|
|
773
|
+
moves this figure, which is the whole reason the number is worth reading.
|
|
774
|
+
"""
|
|
775
|
+
if args.tools:
|
|
776
|
+
# Named, so the question is which of *this* tool's fields spent the bytes (RK1236) —
|
|
777
|
+
# the one the ranking below cannot answer, and the one a caller has the moment `lint`
|
|
778
|
+
# names a tool that is over.
|
|
779
|
+
try:
|
|
780
|
+
one = detail(config, args.tools)
|
|
781
|
+
except Withheld as withheld:
|
|
782
|
+
# The one refusal here with a remedy (RK1360): the tool exists and this project is
|
|
783
|
+
# not sent it, so the answer is the `declare` that changes that and never the
|
|
784
|
+
# ranking, which is a list this verb is correctly absent from.
|
|
785
|
+
print(f"roadkeep: refused: {withheld}", file=sys.stderr)
|
|
786
|
+
return EXIT_USAGE
|
|
787
|
+
except KeyError:
|
|
788
|
+
print(
|
|
789
|
+
f"roadkeep: refused: {args.tools!r} is not a tool this project serves — "
|
|
790
|
+
f"`{invocation()} cost --tools` ranks every one, and `--json` lists them",
|
|
791
|
+
file=sys.stderr,
|
|
792
|
+
)
|
|
793
|
+
return EXIT_USAGE
|
|
794
|
+
if args.json:
|
|
795
|
+
print(json.dumps(one.payload(CHARACTER_UNIT, config.tool_characters), indent=2))
|
|
796
|
+
else:
|
|
797
|
+
print(one.stated(CHARACTER_UNIT, config.tool_characters))
|
|
798
|
+
return EXIT_OK
|
|
799
|
+
|
|
800
|
+
# The same measurement `--session` totals (RK1096), so the ranking and the total cannot
|
|
801
|
+
# come to disagree about what a client is sent.
|
|
802
|
+
sent = surface(config)
|
|
803
|
+
|
|
804
|
+
if args.json:
|
|
805
|
+
print(json.dumps(sent.payload(CHARACTER_UNIT, config.tool_characters, config.tool_session), indent=2))
|
|
806
|
+
else:
|
|
807
|
+
print(sent.stated(
|
|
808
|
+
CHARACTER_UNIT, config.tool_characters, _LARGEST_TOOLS, config.tool_session
|
|
809
|
+
))
|
|
810
|
+
return EXIT_OK
|
|
811
|
+
|
|
812
|
+
|
|
813
|
+
def _pick(config: Config, args: argparse.Namespace) -> int:
|
|
814
|
+
"""The next task this backlog offers, and why that one (RK11).
|
|
815
|
+
|
|
816
|
+
Both registers come off one record (RK1170): the choice, the claim and the event reached this
|
|
817
|
+
handler as three values and were rendered here and in `rendering.py`, so the verb's two
|
|
818
|
+
readings sat in two files and neither was where the choice is made.
|
|
819
|
+
"""
|
|
820
|
+
claim: Claim | None = None
|
|
821
|
+
try:
|
|
822
|
+
if args.claim:
|
|
823
|
+
claim = take(config, args.block, args.designed, available=args.have)
|
|
824
|
+
choice = claim.choice
|
|
825
|
+
else:
|
|
826
|
+
choice = pick(config, args.block, args.designed, available=args.have)
|
|
827
|
+
except REFUSALS as error:
|
|
828
|
+
# The whole tuple and not `(KeyError, OSError)`: with `--claim` this command writes a
|
|
829
|
+
# marker, so every refusal that guards a marker — a stale file, a sibling stating
|
|
830
|
+
# status — reaches here, and a traceback is what the caller would otherwise read.
|
|
831
|
+
return _refused(error)
|
|
832
|
+
|
|
833
|
+
answer = Picked(
|
|
834
|
+
config=config, choice=choice, claim=claim, event=_claim_event(claim, config)
|
|
835
|
+
)
|
|
836
|
+
print(json.dumps(answer.payload(), indent=2) if args.json else answer)
|
|
837
|
+
return EXIT_OK
|
|
838
|
+
|
|
839
|
+
|
|
840
|
+
def _export(config: Config, args: argparse.Namespace) -> int:
|
|
841
|
+
# One task as a document, which is a different subject and not a fourth destination
|
|
842
|
+
# (RK1362): the backlog projection answers about every line and this answers about one,
|
|
843
|
+
# so composing them would be two documents spliced into one file.
|
|
844
|
+
if args.spec is not None:
|
|
845
|
+
try:
|
|
846
|
+
print(spec(config, args.spec).markdown(), end="")
|
|
847
|
+
except (KeyError, ValueError) as error:
|
|
848
|
+
return _refused(error)
|
|
849
|
+
return EXIT_OK
|
|
850
|
+
# Both destinations in one run: a README and a page that restate the same backlog have
|
|
851
|
+
# to be refreshed by the same call, or the one nobody remembered is the stale one —
|
|
852
|
+
# which is the whole symptom RK39 names, and it named the site too.
|
|
853
|
+
chosen: list[tuple[str, str | None]] = [
|
|
854
|
+
(flag, name)
|
|
855
|
+
for flag, name in (("readme", args.readme), ("site", args.site))
|
|
856
|
+
if name is not None
|
|
857
|
+
]
|
|
858
|
+
if args.contents:
|
|
859
|
+
# No path of its own (RK1110): the target is the project's `[files]` rationale file, so
|
|
860
|
+
# a path here would be a second answer to a question the config already answers —
|
|
861
|
+
# `None` is what sends `splice_into` through the resolver the gate reads too.
|
|
862
|
+
chosen.append(("contents", None))
|
|
863
|
+
try:
|
|
864
|
+
projection = project(config)
|
|
865
|
+
if not chosen:
|
|
866
|
+
print(projection.json() if args.json else projection.markdown())
|
|
867
|
+
return EXIT_OK
|
|
868
|
+
planned = [splice_into(config, projection, flag, name) for flag, name in chosen]
|
|
869
|
+
# Both targets or neither (RK187, RK6): the splice is planned per file and the
|
|
870
|
+
# writes are made together, so a README refreshed beside a site refused is a state
|
|
871
|
+
# the command cannot leave — and the re-run it advises meets a whole tree.
|
|
872
|
+
write_all(*[write for write, _ in planned if write is not None])
|
|
873
|
+
except (KeyError, ValueError, OSError, StaleFile) as error:
|
|
874
|
+
return _refused(error)
|
|
875
|
+
|
|
876
|
+
for _, line in planned:
|
|
877
|
+
print(line)
|
|
878
|
+
return EXIT_OK
|
|
879
|
+
|
|
880
|
+
|
|
881
|
+
def _gaps(config: Config, args: argparse.Namespace) -> int:
|
|
882
|
+
"""Which ids below the highest no file carries, and what became of each (RK39, RK95).
|
|
883
|
+
|
|
884
|
+
Both registers come off one result (RK1170): `Gapped` renders them beside the reading that
|
|
885
|
+
found the gaps, so the collapsed rows the printed answer shows and the per-id list the payload
|
|
886
|
+
carries are two readings of one thing rather than two functions two files apart.
|
|
887
|
+
"""
|
|
888
|
+
answer = Gapped(gaps=gaps(config))
|
|
889
|
+
print(json.dumps(answer.payload(), indent=2) if args.json else answer)
|
|
890
|
+
return EXIT_OK
|
|
891
|
+
|
|
892
|
+
|
|
893
|
+
def _govern(config: Config, args: argparse.Namespace) -> int:
|
|
894
|
+
"""A governed number, read and then declared in the same call (RK1272).
|
|
895
|
+
|
|
896
|
+
The read alone where no value is passed, which is the half that already existed under four
|
|
897
|
+
other verbs and nowhere near the declaration. Writes and so is not `reads_only`.
|
|
898
|
+
"""
|
|
899
|
+
from roadkeep.governing import govern, reading # noqa: PLC0415 - RK260
|
|
900
|
+
|
|
901
|
+
try:
|
|
902
|
+
if args.at is None:
|
|
903
|
+
found = reading(config, args.key, file=args.file or "", role=args.role or "")
|
|
904
|
+
print(json.dumps(_reading_json(found), indent=2) if args.json else found.stated())
|
|
905
|
+
return EXIT_OK
|
|
906
|
+
written = govern(
|
|
907
|
+
config,
|
|
908
|
+
args.key,
|
|
909
|
+
args.at,
|
|
910
|
+
file=args.file or "",
|
|
911
|
+
role=args.role or "",
|
|
912
|
+
because=args.because or "",
|
|
913
|
+
instead=args.instead or "",
|
|
914
|
+
)
|
|
915
|
+
except REFUSALS as error:
|
|
916
|
+
return _refused(error)
|
|
917
|
+
|
|
918
|
+
if args.json:
|
|
919
|
+
print(json.dumps(written.payload(config), indent=2))
|
|
920
|
+
else:
|
|
921
|
+
print(written.stated(config))
|
|
922
|
+
return EXIT_OK
|
|
923
|
+
|
|
924
|
+
|
|
925
|
+
def _reading_json(found) -> dict:
|
|
926
|
+
"""The measurement alone, shaped as the write's own `reading` block is (RK1272)."""
|
|
927
|
+
return {
|
|
928
|
+
"address": found.address,
|
|
929
|
+
"unit": found.unit,
|
|
930
|
+
"sites": found.sites,
|
|
931
|
+
"worst": found.worst,
|
|
932
|
+
"where": found.where,
|
|
933
|
+
"declared": found.declared,
|
|
934
|
+
# Beside it in both registers (RK1343): a consumer reading `declared: null` cannot
|
|
935
|
+
# tell a key this build falls back on from one nothing holds, and the two are the
|
|
936
|
+
# difference between a lenient gate and no gate.
|
|
937
|
+
"default": found.default,
|
|
938
|
+
"unmeasured": found.unmeasured or None,
|
|
939
|
+
"because": list(found.because),
|
|
940
|
+
}
|
|
941
|
+
|
|
942
|
+
|
|
943
|
+
def _config_shape(config: Config, args: argparse.Namespace) -> int:
|
|
944
|
+
"""What `roadkeep.toml` may declare, and what this project did (RK1270).
|
|
945
|
+
|
|
946
|
+
Never refused over the project's *state* — a tree with no config at all is answered, that
|
|
947
|
+
being the caller who most needs the list — and refused over the **argument**, a table name
|
|
948
|
+
this build does not have being a typo rather than a table somebody has yet to declare.
|
|
949
|
+
"""
|
|
950
|
+
from roadkeep.describing import payload, shape, stated # noqa: PLC0415 - RK260
|
|
951
|
+
|
|
952
|
+
try:
|
|
953
|
+
# Straight through, and the default is `None` rather than `""` for exactly one
|
|
954
|
+
# reason: the top level's own name *is* the empty string, so a default of `""` would
|
|
955
|
+
# make `--table ""` unaskable — the one table a reader starts from.
|
|
956
|
+
found = shape(config, args.table)
|
|
957
|
+
except KeyError as error:
|
|
958
|
+
return _refused(error)
|
|
959
|
+
|
|
960
|
+
if args.json:
|
|
961
|
+
print(json.dumps(payload(found), indent=2))
|
|
962
|
+
else:
|
|
963
|
+
print(stated(found))
|
|
964
|
+
return EXIT_OK
|
|
965
|
+
|
|
966
|
+
|
|
967
|
+
def _commands(config: Config, args: argparse.Namespace) -> int:
|
|
968
|
+
"""What this build's command line takes, as data rather than as terminal text (RK1401).
|
|
969
|
+
|
|
970
|
+
`_config_shape`'s twin, and refused the same way: never over the project's *state* — a
|
|
971
|
+
tree with no config at all is answered, that being the reader deciding whether to adopt —
|
|
972
|
+
and refused over the **argument**, a verb this build does not have being a typo rather
|
|
973
|
+
than one somebody has yet to install.
|
|
974
|
+
"""
|
|
975
|
+
from roadkeep.commanding import commands, payload, stated # noqa: PLC0415 - RK260
|
|
976
|
+
|
|
977
|
+
try:
|
|
978
|
+
found = commands(config, args.command)
|
|
979
|
+
except KeyError as error:
|
|
980
|
+
return _refused(error)
|
|
981
|
+
|
|
982
|
+
if args.json:
|
|
983
|
+
print(json.dumps(payload(found), indent=2))
|
|
984
|
+
else:
|
|
985
|
+
print(stated(found))
|
|
986
|
+
return EXIT_OK
|
|
987
|
+
|
|
988
|
+
|
|
989
|
+
def _anchors(config: Config, args: argparse.Namespace) -> int:
|
|
990
|
+
"""Live and retired addresses across this project's prose (RK247, RK297).
|
|
991
|
+
|
|
992
|
+
Four readings off one record (RK1170) — the wide report and its payload, and the free
|
|
993
|
+
address alone in each register. What stays here is the three **argv** refusals: which
|
|
994
|
+
prose file, which of two narrowings, and a block whose lines point nowhere. Those are
|
|
995
|
+
about the call and not about the answer, which is why they never reached the record.
|
|
996
|
+
"""
|
|
997
|
+
# Every declared role unless one is named. `--role` narrows the *listing* and never the
|
|
998
|
+
# free address, which is computed per namespace (RK340, RK346): where no `[refs]` declares
|
|
999
|
+
# one, both files number into the same namespace and a `next` taken from one of them is
|
|
1000
|
+
# the answer this read exists to stop somebody acting on (RK297); where one is declared,
|
|
1001
|
+
# the row for that namespace is that file's own and the sibling's is not an answer about
|
|
1002
|
+
# it. Reading every role either way is what makes `doubled` visible before a pick (RK383).
|
|
1003
|
+
asked = [one for one in PROSE_ROLES if config.has(one)]
|
|
1004
|
+
role = args.role or ""
|
|
1005
|
+
if (role and not config.has(role)) or not asked:
|
|
1006
|
+
print(
|
|
1007
|
+
f"roadkeep: this project declares no {role or 'prose'} file "
|
|
1008
|
+
f"({', '.join(PROSE_ROLES)} is what an anchor lives in)",
|
|
1009
|
+
file=sys.stderr,
|
|
1010
|
+
)
|
|
1011
|
+
return EXIT_USAGE
|
|
1012
|
+
# The block a caller knows, resolved to the family they do not (RK312): under an outline
|
|
1013
|
+
# the prose file declares no block heading, so which numeral a block's designs sit under
|
|
1014
|
+
# is written nowhere and used to be globbed out of the pointers by hand.
|
|
1015
|
+
block = args.block or ""
|
|
1016
|
+
if block and args.family:
|
|
1017
|
+
print(
|
|
1018
|
+
"roadkeep: --block resolves to a family, so passing both asks two questions: "
|
|
1019
|
+
f"`{invocation()} anchors --block {block}` names the families, and "
|
|
1020
|
+
f"`{invocation()} anchors --family <one of them>` narrows to it",
|
|
1021
|
+
file=sys.stderr,
|
|
1022
|
+
)
|
|
1023
|
+
return EXIT_USAGE
|
|
1024
|
+
spans: tuple[str, ...] = ()
|
|
1025
|
+
if block:
|
|
1026
|
+
spans = families_of_block(config, block)
|
|
1027
|
+
if not spans:
|
|
1028
|
+
print(
|
|
1029
|
+
f"roadkeep: no open line in Block {block} carries a pointer, so nothing "
|
|
1030
|
+
f"says which family its prose lives under — `anchors` alone lists every "
|
|
1031
|
+
f"top-level, and its next free one is where a new block starts",
|
|
1032
|
+
file=sys.stderr,
|
|
1033
|
+
)
|
|
1034
|
+
return EXIT_USAGE
|
|
1035
|
+
if len(spans) == 1:
|
|
1036
|
+
args.family = spans[0]
|
|
1037
|
+
|
|
1038
|
+
found = Addresses.of(
|
|
1039
|
+
config, role, args.family or "", [role] if role else asked, block, spans
|
|
1040
|
+
)
|
|
1041
|
+
if args.only_next:
|
|
1042
|
+
if args.json:
|
|
1043
|
+
print(json.dumps(found.free_payload(), indent=2))
|
|
1044
|
+
return EXIT_OK
|
|
1045
|
+
out, notes = found.freely()
|
|
1046
|
+
if not out:
|
|
1047
|
+
# The one refusal the narrow read has of its own: an empty stdout here reads as a
|
|
1048
|
+
# command that failed quietly, and this form exists to be captured.
|
|
1049
|
+
#
|
|
1050
|
+
# **Both spellings, because the first address chooses the system** (RK1211). This
|
|
1051
|
+
# named `I.1` by hand, on the one file with no family to read a system off — which
|
|
1052
|
+
# is exactly why `next_family` answers None here at all. So one half of the command
|
|
1053
|
+
# declined to guess and the other half guessed, and following the guess made the
|
|
1054
|
+
# file this tool then cannot read: measured on a project holding `1` and `1.1`,
|
|
1055
|
+
# offered `I.1`, which took its top levels to `1` and `I` — two systems tying at 1,
|
|
1056
|
+
# RK1210's nondeterminism, entered through a message that never mentions it.
|
|
1057
|
+
#
|
|
1058
|
+
# Naming both is what shows the choice exists. Naming one keeps a decision that is
|
|
1059
|
+
# the author's (L4, L6): a project outlining `1`, `2`, `3` is as ordinary as one
|
|
1060
|
+
# outlining `I`, `II`, `III`, and every address after the first is spelled the way
|
|
1061
|
+
# the first one was.
|
|
1062
|
+
print(
|
|
1063
|
+
"roadkeep: no outline family exists yet, so none is spent — the first "
|
|
1064
|
+
"address decides the system every address after it is spelled in, and that "
|
|
1065
|
+
"is yours: `add --ref I.1` or `add --ref 1.1`, whichever this project "
|
|
1066
|
+
"numbers in",
|
|
1067
|
+
file=sys.stderr,
|
|
1068
|
+
)
|
|
1069
|
+
return EXIT_USAGE
|
|
1070
|
+
print(chr(10).join(out))
|
|
1071
|
+
for note in notes:
|
|
1072
|
+
print(note, file=sys.stderr)
|
|
1073
|
+
return EXIT_OK
|
|
1074
|
+
|
|
1075
|
+
if args.json:
|
|
1076
|
+
print(json.dumps(found.payload(config, args.claims), indent=2))
|
|
1077
|
+
else:
|
|
1078
|
+
print(found.stated(config, args.claims))
|
|
1079
|
+
return EXIT_OK
|
|
1080
|
+
|
|
1081
|
+
|
|
1082
|
+
def _deps(config: Config, args: argparse.Namespace) -> int:
|
|
1083
|
+
try:
|
|
1084
|
+
backlog = Backlog.load(config)
|
|
1085
|
+
except (KeyError, OSError) as error:
|
|
1086
|
+
return _refused(error) # a declared file that is not there yet: `init` (RK18)
|
|
1087
|
+
try:
|
|
1088
|
+
found = Dependencies.of(backlog, args.id)
|
|
1089
|
+
except KeyError:
|
|
1090
|
+
# The shared refusal and no longer a second spelling of it (RK1342). `NotOpen` says
|
|
1091
|
+
# of itself that *the sentence has one spelling for every caller that asks*, and
|
|
1092
|
+
# answers three ways — in the changelog, paused with the store's own sentence and the
|
|
1093
|
+
# `resume` that undoes it, or nothing carries the id. This site hand-rolled two of
|
|
1094
|
+
# them, so the pause RK1213 taught that class to name was the one case it could not:
|
|
1095
|
+
# a sentence with two writers agrees until one of them grows a case.
|
|
1096
|
+
return _refused(
|
|
1097
|
+
NotOpen(
|
|
1098
|
+
args.id,
|
|
1099
|
+
config.relative(config.path("roadmap")),
|
|
1100
|
+
Whereabouts.of(config, args.id),
|
|
1101
|
+
)
|
|
1102
|
+
)
|
|
1103
|
+
|
|
1104
|
+
if args.json:
|
|
1105
|
+
print(json.dumps(found.payload(), indent=2))
|
|
1106
|
+
else:
|
|
1107
|
+
print(found.stated())
|
|
1108
|
+
return EXIT_OK
|
|
1109
|
+
|
|
1110
|
+
|
|
1111
|
+
def _origin(config: Config, args: argparse.Namespace) -> int:
|
|
1112
|
+
if args.id.startswith("§"):
|
|
1113
|
+
return _cited(config, args)
|
|
1114
|
+
try:
|
|
1115
|
+
origin = origin_of(config, args.id)
|
|
1116
|
+
except HistoryUnavailable as error:
|
|
1117
|
+
print(f"roadkeep: no history to resolve against ({error})", file=sys.stderr)
|
|
1118
|
+
return EXIT_USAGE
|
|
1119
|
+
|
|
1120
|
+
if args.json:
|
|
1121
|
+
print(json.dumps({"id": origin.task_id, **_commits_json(origin)}, indent=2))
|
|
1122
|
+
return EXIT_OK
|
|
1123
|
+
|
|
1124
|
+
if origin.proposed_in is None and origin.shipped_in is None:
|
|
1125
|
+
print(f"{args.id}: nothing in history mentions it yet")
|
|
1126
|
+
return EXIT_OK
|
|
1127
|
+
for label, commit in (("proposed", origin.proposed_in), ("shipped", origin.shipped_in)):
|
|
1128
|
+
if commit is None:
|
|
1129
|
+
print(f" {label:<9} —")
|
|
1130
|
+
continue
|
|
1131
|
+
print(f" {label:<9} {commit.short} {commit.date[:10]} {commit.subject}")
|
|
1132
|
+
if args.why and origin.shipped_in is not None:
|
|
1133
|
+
print()
|
|
1134
|
+
print(origin.shipped_in.reasoning)
|
|
1135
|
+
return EXIT_OK
|
|
1136
|
+
|
|
1137
|
+
|
|
1138
|
+
def _cited(config: Config, args: argparse.Namespace) -> int:
|
|
1139
|
+
"""Where the design behind a dangling citation went (RK212).
|
|
1140
|
+
|
|
1141
|
+
`ship` names the sections left citing what it deleted (RK206), which serves the author
|
|
1142
|
+
at the moment of the write. This serves the reader who meets `§XVIII.12` a year later:
|
|
1143
|
+
the files hold no answer, because `as_ledger` keeps no pointer, so a citation of a
|
|
1144
|
+
shipped design and a typo read exactly alike.
|
|
1145
|
+
|
|
1146
|
+
A question and not a check, decided by counting: 37 such references across this
|
|
1147
|
+
repository, claude-tray, Shio and Turing, of which 36 are in outline projects whose
|
|
1148
|
+
anchor carries no id at all. A finding would fail four files whose prose is correct;
|
|
1149
|
+
28 notes in one Turing report would be output nobody reads. So it costs nothing until
|
|
1150
|
+
somebody meets the reference and asks (L5).
|
|
1151
|
+
"""
|
|
1152
|
+
anchor = args.id.lstrip("§")
|
|
1153
|
+
found = cited_origin(config, anchor)
|
|
1154
|
+
# Both registers off the record (RK1170), and the role spelled by this project (RK75): the
|
|
1155
|
+
# answer is `Cited`'s, and what the printed one needs beyond the fact is the file's name.
|
|
1156
|
+
where = config.relative(config.path(found.role)) if config.has(found.role) else found.role
|
|
1157
|
+
if args.json:
|
|
1158
|
+
print(json.dumps(found.payload(), indent=2))
|
|
1159
|
+
else:
|
|
1160
|
+
print(found.stated(where, why=args.why))
|
|
1161
|
+
return EXIT_OK
|
|
1162
|
+
|
|
1163
|
+
|
|
1164
|
+
def _weight(config: Config, args: argparse.Namespace) -> int:
|
|
1165
|
+
"""Print what comparable tasks cost (RK71). Numbers only — the judgement is the author's.
|
|
1166
|
+
|
|
1167
|
+
No advice line: what a spread means for the line being written is an editorial call, and
|
|
1168
|
+
a tool that phrased it would be writing the reasoning it exists not to write (L4).
|
|
1169
|
+
|
|
1170
|
+
Both registers come off one result (RK1170): this verb was the shape the task measured — the
|
|
1171
|
+
plain answer spelled here and its payload in `rendering.py`, one verb's two readings two files
|
|
1172
|
+
apart, with neither file holding both. `Weighed` is that result, beside the numbers it is
|
|
1173
|
+
derived from, and what is left here is the door: run it, and say which register was asked for.
|
|
1174
|
+
"""
|
|
1175
|
+
try:
|
|
1176
|
+
weights = weigh(config, args.block)
|
|
1177
|
+
except HistoryUnavailable as error:
|
|
1178
|
+
print(f"roadkeep: no history to weigh against ({error})", file=sys.stderr)
|
|
1179
|
+
return EXIT_USAGE
|
|
1180
|
+
except (KeyError, OSError) as error:
|
|
1181
|
+
return _refused(error)
|
|
1182
|
+
|
|
1183
|
+
answer = Weighed(
|
|
1184
|
+
where=config.relative(config.path("changelog")),
|
|
1185
|
+
weights=weights,
|
|
1186
|
+
records=args.records,
|
|
1187
|
+
)
|
|
1188
|
+
print(json.dumps(answer.payload(), indent=2) if args.json else answer)
|
|
1189
|
+
return EXIT_OK
|
|
1190
|
+
|
|
1191
|
+
|
|
1192
|
+
def _remaining(config: Config, args: argparse.Namespace) -> int:
|
|
1193
|
+
"""Run the query a task's own design declares, against this tree, now (RK492).
|
|
1194
|
+
|
|
1195
|
+
A read in the strict sense: nothing is written, nothing is cached, and the exit code says
|
|
1196
|
+
the call was answered rather than what the answer was. A migration with sites left is not
|
|
1197
|
+
a failing gate — `lint` is what refuses — and a `remaining` that exited 1 while work was
|
|
1198
|
+
outstanding would be a verb nobody could put in a loop.
|
|
1199
|
+
"""
|
|
1200
|
+
try:
|
|
1201
|
+
view = show(config, args.id)
|
|
1202
|
+
except (KeyError, OSError) as error:
|
|
1203
|
+
return _refused(error)
|
|
1204
|
+
if view.section is None:
|
|
1205
|
+
# The pointer's own failure, in the words `show` already composed for it: a task with
|
|
1206
|
+
# no design has no query, and which of the four absences it is matters to the repair.
|
|
1207
|
+
print(f"roadkeep: {args.id} has no section: {view.section_absence}", file=sys.stderr)
|
|
1208
|
+
return EXIT_USAGE
|
|
1209
|
+
try:
|
|
1210
|
+
clauses = declared(view.section.body)
|
|
1211
|
+
except QueryError as error:
|
|
1212
|
+
return _refused(error)
|
|
1213
|
+
if not clauses:
|
|
1214
|
+
# An answer and not a refusal: *this design declares no query* is a fact about the
|
|
1215
|
+
# task, and a read that refused it would be read as evidence the id was wrong. The
|
|
1216
|
+
# grammar is named, because the next thing a caller wants is to write one.
|
|
1217
|
+
if args.json:
|
|
1218
|
+
print(json.dumps({"id": args.id, "query": [], "total": None}, indent=2))
|
|
1219
|
+
else:
|
|
1220
|
+
print(
|
|
1221
|
+
f"{args.id} declares no query: a `roadkeep-remaining` fenced block in "
|
|
1222
|
+
f"§{view.entry.task.ref or args.id}, one `<pathspec> :: <regex>` per line"
|
|
1223
|
+
)
|
|
1224
|
+
return EXIT_OK
|
|
1225
|
+
found = count(config.root, args.id, clauses)
|
|
1226
|
+
print(json.dumps(found.payload(), indent=2) if args.json else str(found))
|
|
1227
|
+
return EXIT_OK
|
|
1228
|
+
|
|
1229
|
+
|
|
1230
|
+
|
|
1231
|
+
def _unclosed(config: Config, args: argparse.Namespace) -> int:
|
|
1232
|
+
"""Open lines the history already speaks for (RK1201). Nothing here fails, so exit 0.
|
|
1233
|
+
|
|
1234
|
+
Both registers come off one record (RK1170), and the exit code is not one of them: a
|
|
1235
|
+
commit naming an id is not evidence the work is done, so a non-zero here would fail every
|
|
1236
|
+
session that is mid-task — which is the shape a report must not take.
|
|
1237
|
+
"""
|
|
1238
|
+
try:
|
|
1239
|
+
answer = Unclosed(rows=pending(config))
|
|
1240
|
+
except (KeyError, OSError) as error:
|
|
1241
|
+
return _refused(error)
|
|
1242
|
+
|
|
1243
|
+
if args.json:
|
|
1244
|
+
print(json.dumps(answer.payload(), indent=2))
|
|
1245
|
+
else:
|
|
1246
|
+
print(answer.stated())
|
|
1247
|
+
return EXIT_OK
|
|
1248
|
+
|
|
1249
|
+
|
|
1250
|
+
|
|
1251
|
+
def _evidence(config: Config, args: argparse.Namespace) -> int:
|
|
1252
|
+
"""What a task's own design says would prove it done, counted now (RK1184).
|
|
1253
|
+
|
|
1254
|
+
`remaining` with the sign flipped, and the same read: sites that must **exist** rather
|
|
1255
|
+
than sites still there. Never a verdict — the pattern is the author's claim and the count
|
|
1256
|
+
is the answer, so `0` says the evidence is not there yet and whether that is the work
|
|
1257
|
+
being done is the caller's judgement (L4).
|
|
1258
|
+
|
|
1259
|
+
The exit code says the call was answered and never what the answer was, for `remaining`'s
|
|
1260
|
+
reason: a criterion unmet is work outstanding, which is not a failing gate.
|
|
1261
|
+
"""
|
|
1262
|
+
try:
|
|
1263
|
+
view = show(config, args.id)
|
|
1264
|
+
except (KeyError, OSError) as error:
|
|
1265
|
+
return _refused(error)
|
|
1266
|
+
if view.section is None:
|
|
1267
|
+
print(f"roadkeep: {args.id} has no section: {view.section_absence}", file=sys.stderr)
|
|
1268
|
+
return EXIT_USAGE
|
|
1269
|
+
try:
|
|
1270
|
+
clauses = declared(view.section.body, EVIDENCE)
|
|
1271
|
+
except QueryError as error:
|
|
1272
|
+
return _refused(error)
|
|
1273
|
+
if not clauses:
|
|
1274
|
+
# An answer and not a refusal, exactly as `remaining` reads an absent query: *this
|
|
1275
|
+
# design declares no criterion* is a fact about the task, and the grammar is named
|
|
1276
|
+
# because writing one is the next thing a caller wants.
|
|
1277
|
+
if args.json:
|
|
1278
|
+
print(json.dumps({"id": args.id, "kind": EVIDENCE, "query": [], "total": None}, indent=2))
|
|
1279
|
+
else:
|
|
1280
|
+
print(
|
|
1281
|
+
f"{args.id} declares no criterion: a `{EVIDENCE}` fenced block in "
|
|
1282
|
+
f"§{view.entry.task.ref or args.id}, one `<pathspec> :: <regex>` per line"
|
|
1283
|
+
)
|
|
1284
|
+
return EXIT_OK
|
|
1285
|
+
found = count(config.root, args.id, clauses, EVIDENCE)
|
|
1286
|
+
print(json.dumps(found.payload(), indent=2) if args.json else str(found))
|
|
1287
|
+
return EXIT_OK
|
|
1288
|
+
|
|
1289
|
+
|
|
1290
|
+
def declare_reads(subcommands: argparse._SubParsersAction) -> None:
|
|
1291
|
+
"""This module's verbs, declared where their handlers are (RK1171).
|
|
1292
|
+
|
|
1293
|
+
`build_parser` called forty-nine blocks like these in a row; what it calls now is an index
|
|
1294
|
+
over the modules that own them. The move is what RK1169 and RK1170 bought: the flags a verb
|
|
1295
|
+
declares, the reasons it withholds and the record it answers with are one file's, so a
|
|
1296
|
+
change to any of them is one file's too.
|
|
1297
|
+
|
|
1298
|
+
The order inside is `build_parser`'s own, which is where these blocks sat.
|
|
1299
|
+
"""
|
|
1300
|
+
list_parser = subcommands.add_parser(
|
|
1301
|
+
"list",
|
|
1302
|
+
help="the task lines, filtered, printed verbatim",
|
|
1303
|
+
description=(
|
|
1304
|
+
"Print the lines a filter selects, exactly as the file spells them. A "
|
|
1305
|
+
"marker-bearing line the grammar did not accept is reported on stderr with "
|
|
1306
|
+
"the count, so a filtered listing can never look complete when it is not."
|
|
1307
|
+
),
|
|
1308
|
+
)
|
|
1309
|
+
_counting_flags(list_parser)
|
|
1310
|
+
_marker_flag(list_parser, "only this status marker", dest="marker")
|
|
1311
|
+
list_parser.add_argument(
|
|
1312
|
+
"--ids", action="store_true", help="print ids alone, one per line"
|
|
1313
|
+
)
|
|
1314
|
+
withheld(
|
|
1315
|
+
list_parser,
|
|
1316
|
+
ids='how a terminal prints: the payload carries every id in `tasks`, so a caller over this transport already has what the flag composes',
|
|
1317
|
+
)
|
|
1318
|
+
list_parser.set_defaults(handler=_list, reads_only=True)
|
|
1319
|
+
# Two output *forms* of one read are two answers, exactly as `budget`'s subjects are
|
|
1320
|
+
# (RK465's rule, RK467's find): the payload came back whole with nothing said about the
|
|
1321
|
+
# flag that shaped nothing.
|
|
1322
|
+
answers(list_parser, ("ids", "the listing as bare ids"), ("json", "the payload"))
|
|
1323
|
+
|
|
1324
|
+
stats_parser = subcommands.add_parser(
|
|
1325
|
+
"stats",
|
|
1326
|
+
help="counts per block and per marker, with what was not counted",
|
|
1327
|
+
description=(
|
|
1328
|
+
"Count the file. Every count carries the number of marker-bearing lines it "
|
|
1329
|
+
"could *not* read, printed even when it is zero: a grep reports the "
|
|
1330
|
+
"remainder with no indication that anything is missing."
|
|
1331
|
+
),
|
|
1332
|
+
)
|
|
1333
|
+
_counting_flags(stats_parser)
|
|
1334
|
+
stats_parser.set_defaults(handler=_stats, reads_only=True)
|
|
1335
|
+
|
|
1336
|
+
audit_parser = subcommands.add_parser(
|
|
1337
|
+
"audit",
|
|
1338
|
+
help="every marker-bearing line the count did not count, and why",
|
|
1339
|
+
description=(
|
|
1340
|
+
"Print the misses. This is what makes a count trustable rather than an "
|
|
1341
|
+
"extra: exit stays 0, because reporting is not the gate (`lint`, RK14) — "
|
|
1342
|
+
"an audit that failed a build would be a gate nobody could adopt first."
|
|
1343
|
+
),
|
|
1344
|
+
)
|
|
1345
|
+
_counting_flags(audit_parser)
|
|
1346
|
+
audit_parser.set_defaults(handler=_audit, reads_only=True)
|
|
1347
|
+
|
|
1348
|
+
claims_parser = subcommands.add_parser(
|
|
1349
|
+
"claims",
|
|
1350
|
+
help="which lines a worker is holding, oldest first, and where that is recorded",
|
|
1351
|
+
description=(
|
|
1352
|
+
"List the claim registry against the roadmap: held, expired — stepped over, so "
|
|
1353
|
+
"the line is offered again — or stale, meaning the marker moved and nothing "
|
|
1354
|
+
"reads the entry. Ranks nothing and offers nothing: `pick` decides what to work "
|
|
1355
|
+
"on, and the release is a marker."
|
|
1356
|
+
),
|
|
1357
|
+
)
|
|
1358
|
+
claims_parser.add_argument(
|
|
1359
|
+
"--prune",
|
|
1360
|
+
action="store_true",
|
|
1361
|
+
help=(
|
|
1362
|
+
"drop the rows that are not claims and keep the ones that are, which is the "
|
|
1363
|
+
"reconciliation a marker write performs and the only other remedy is the file"
|
|
1364
|
+
),
|
|
1365
|
+
)
|
|
1366
|
+
claims_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
|
|
1367
|
+
# A read that can write, so it declares which flag makes it one (RK167): `dispatch` keeps
|
|
1368
|
+
# deciding the lock, and reading the registry never waits on one.
|
|
1369
|
+
withheld(
|
|
1370
|
+
claims_parser,
|
|
1371
|
+
prune='it writes the registry, exactly as `lint --fix` writes the files (RK16)',
|
|
1372
|
+
)
|
|
1373
|
+
claims_parser.set_defaults(handler=_claims, reads_only=True, writes_when="prune")
|
|
1374
|
+
|
|
1375
|
+
claim_parser = subcommands.add_parser(
|
|
1376
|
+
"claim",
|
|
1377
|
+
help="the paths one held line's commit owns, declared once and answered on demand",
|
|
1378
|
+
description=(
|
|
1379
|
+
"Say which paths this task will touch, and read them back at the moment of "
|
|
1380
|
+
"committing. Without --path it answers what was declared, plus what the tree "
|
|
1381
|
+
"holds that another live claim says is its own — the analysis `git add -A` "
|
|
1382
|
+
"cannot make. Declared verbatim: nothing here reads the disk or the task's "
|
|
1383
|
+
"prose to guess a path, and nothing here dates a claim."
|
|
1384
|
+
),
|
|
1385
|
+
)
|
|
1386
|
+
claim_parser.add_argument("id", help="the task id, which a live claim must already hold")
|
|
1387
|
+
claim_parser.add_argument(
|
|
1388
|
+
"--path",
|
|
1389
|
+
action="append",
|
|
1390
|
+
default=[],
|
|
1391
|
+
metavar="PATH",
|
|
1392
|
+
help=(
|
|
1393
|
+
"a path this task's commit owns, repeatable; replaces the whole scope, so a "
|
|
1394
|
+
"correction is one call and not a file to edit"
|
|
1395
|
+
),
|
|
1396
|
+
)
|
|
1397
|
+
claim_parser.add_argument(
|
|
1398
|
+
"--add-path",
|
|
1399
|
+
action="append",
|
|
1400
|
+
default=[],
|
|
1401
|
+
metavar="PATH",
|
|
1402
|
+
dest="add_path",
|
|
1403
|
+
help=(
|
|
1404
|
+
"a path this task's commit *also* owns, repeatable; keeps what was declared, so "
|
|
1405
|
+
"a file the work turned up is one argument and not the whole scope again"
|
|
1406
|
+
),
|
|
1407
|
+
)
|
|
1408
|
+
claim_parser.add_argument(
|
|
1409
|
+
"--porcelain",
|
|
1410
|
+
action="store_true",
|
|
1411
|
+
help="the paths alone, one per line — what a commit script feeds to `git add --`",
|
|
1412
|
+
)
|
|
1413
|
+
claim_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
|
|
1414
|
+
# A read that can write, declared the way `claims --prune` declares it (RK167) — and by
|
|
1415
|
+
# two arguments (RK307), because either of them is the write.
|
|
1416
|
+
withheld(
|
|
1417
|
+
claim_parser,
|
|
1418
|
+
porcelain='how a terminal prints, for a caller that is already reading JSON',
|
|
1419
|
+
)
|
|
1420
|
+
claim_parser.set_defaults(
|
|
1421
|
+
handler=_claim,
|
|
1422
|
+
reads_only=True,
|
|
1423
|
+
writes_when=("path", "add_path"),
|
|
1424
|
+
# The second pair, found by the read RK339 asked for: same one-edit distance, same
|
|
1425
|
+
# asymmetry, and the same verb typed wanting the listing.
|
|
1426
|
+
twin=(
|
|
1427
|
+
"claim reads one line's scope back and needs it: `claim <id>`, or "
|
|
1428
|
+
"`claim <id> --path …` to declare what this commit owns. The registry "
|
|
1429
|
+
"listing is `claims`, which needs no id"
|
|
1430
|
+
),
|
|
1431
|
+
)
|
|
1432
|
+
# The sixth pair, and the first one the *declaration* found rather than a sweep (RK489):
|
|
1433
|
+
# `--porcelain` returned before `--json` was read, so a caller asking for the payload got
|
|
1434
|
+
# the paths, byte for byte. RK467's sweep could never see it — it runs against a fixture
|
|
1435
|
+
# with no live claim, where every `claim` pair exits 2 for want of one — which is the
|
|
1436
|
+
# limit of finding a class by probing, one probe away from the class being declarable.
|
|
1437
|
+
answers(
|
|
1438
|
+
claim_parser,
|
|
1439
|
+
("porcelain", "the paths alone, for `git add --`"),
|
|
1440
|
+
("json", "the payload"),
|
|
1441
|
+
)
|
|
1442
|
+
|
|
1443
|
+
writes_parser = subcommands.add_parser(
|
|
1444
|
+
"writes",
|
|
1445
|
+
help="which governed files a verb wrote, which nothing did, and where that is recorded",
|
|
1446
|
+
description=(
|
|
1447
|
+
"Read the write record against the files: attested — the bytes a verb left — "
|
|
1448
|
+
"unattested, meaning something else produced them, or unrecorded, meaning no "
|
|
1449
|
+
"verb has run here yet. Moves no baseline, so asking twice answers twice; the "
|
|
1450
|
+
"`Stop` hook states it once and consumes it (RK175)."
|
|
1451
|
+
),
|
|
1452
|
+
)
|
|
1453
|
+
writes_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
|
|
1454
|
+
# Never a write, not even behind a flag: re-baselining is what the `Stop` block does, and a
|
|
1455
|
+
# query offering it would be the laundering `dispatch` refuses queries in the first place.
|
|
1456
|
+
writes_parser.set_defaults(handler=_writes, reads_only=True)
|
|
1457
|
+
|
|
1458
|
+
unclosed_parser = subcommands.add_parser(
|
|
1459
|
+
"unclosed",
|
|
1460
|
+
help="open lines whose work the history already names, and what closes each",
|
|
1461
|
+
description=(
|
|
1462
|
+
"Which open lines already have commits naming them, and no ledger entry. A "
|
|
1463
|
+
"session that shipped the code and forgot the line leaves a state `gaps` "
|
|
1464
|
+
"cannot see — that verb explains an id in neither file, and this one is in "
|
|
1465
|
+
"the roadmap — and `origin` answers one id at a time, so it is a confirmation "
|
|
1466
|
+
"and never a discovery. The commit that *filed* each id is dropped: `add` "
|
|
1467
|
+
"mints the id, so nothing could name one before the line existed. A report "
|
|
1468
|
+
"and never a gate: work under way is exactly this shape, and what a partial "
|
|
1469
|
+
"landing wants is `ship --part`."
|
|
1470
|
+
),
|
|
1471
|
+
)
|
|
1472
|
+
unclosed_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
|
|
1473
|
+
unclosed_parser.set_defaults(handler=_unclosed, reads_only=True)
|
|
1474
|
+
|
|
1475
|
+
brief_parser = subcommands.add_parser(
|
|
1476
|
+
"brief",
|
|
1477
|
+
help="everything it costs to start one task, in one call",
|
|
1478
|
+
description=(
|
|
1479
|
+
"Compose the line, its rationale, its resolved deps, the blocker chain, what "
|
|
1480
|
+
"shipping it unblocks and the non-goals that bind it. With no id, briefs "
|
|
1481
|
+
"whatever `pick` would choose, which makes the first call the only one."
|
|
1482
|
+
),
|
|
1483
|
+
)
|
|
1484
|
+
brief_parser.add_argument(
|
|
1485
|
+
"id", nargs="?", help="the task; omitted, `pick` chooses it"
|
|
1486
|
+
)
|
|
1487
|
+
brief_parser.add_argument(
|
|
1488
|
+
"--block", help="scope the pick to one block, e.g. C (only without an id)"
|
|
1489
|
+
)
|
|
1490
|
+
brief_parser.add_argument(
|
|
1491
|
+
"--designed",
|
|
1492
|
+
action="store_true",
|
|
1493
|
+
help=_DESIGNED_HELP,
|
|
1494
|
+
)
|
|
1495
|
+
brief_parser.add_argument(
|
|
1496
|
+
"--have",
|
|
1497
|
+
action="append",
|
|
1498
|
+
default=[],
|
|
1499
|
+
metavar="REQUIREMENT",
|
|
1500
|
+
help=_HAVE_HELP,
|
|
1501
|
+
)
|
|
1502
|
+
brief_parser.add_argument(
|
|
1503
|
+
"--claim",
|
|
1504
|
+
action="store_true",
|
|
1505
|
+
help=(
|
|
1506
|
+
"take the line as well as describing it: the marker moves to in-progress in the "
|
|
1507
|
+
"same transaction, and a named id another worker holds is refused"
|
|
1508
|
+
),
|
|
1509
|
+
)
|
|
1510
|
+
brief_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
|
|
1511
|
+
withheld(
|
|
1512
|
+
brief_parser,
|
|
1513
|
+
claim='it writes, and a read that writes is a read a caller stops making freely (L5) — so the writing door is a tool of its own with its own hint',
|
|
1514
|
+
)
|
|
1515
|
+
brief_parser.set_defaults(handler=_brief, reads_only=True, writes_when="claim")
|
|
1516
|
+
|
|
1517
|
+
budget_parser = subcommands.add_parser(
|
|
1518
|
+
"budget",
|
|
1519
|
+
help="how many characters a line has left for prose, before one is written",
|
|
1520
|
+
description=(
|
|
1521
|
+
"Report what a line leaves its prose fields, derived from the id, the marker, "
|
|
1522
|
+
"the deps and the pointer — all known before the first word. The drafts "
|
|
1523
|
+
"(--symptom, --why, --body) are measured, never composed, and exit 1 when "
|
|
1524
|
+
"over: the refusal, without the write."
|
|
1525
|
+
),
|
|
1526
|
+
)
|
|
1527
|
+
budget_parser.add_argument(
|
|
1528
|
+
"id",
|
|
1529
|
+
nargs="?",
|
|
1530
|
+
help="an existing line, e.g. RK12 — omitted, the line `add` would write next",
|
|
1531
|
+
)
|
|
1532
|
+
budget_parser.add_argument(
|
|
1533
|
+
"--block", default="", help="the block the line would be filed under, e.g. B"
|
|
1534
|
+
)
|
|
1535
|
+
budget_parser.add_argument(
|
|
1536
|
+
"--dep",
|
|
1537
|
+
action="append",
|
|
1538
|
+
default=[],
|
|
1539
|
+
dest="deps",
|
|
1540
|
+
metavar="DEP",
|
|
1541
|
+
help="a dep the line would carry, repeatable: the group is what moves the number",
|
|
1542
|
+
)
|
|
1543
|
+
_marker_flag(
|
|
1544
|
+
budget_parser, "the marker the line would carry (default: the first declared)"
|
|
1545
|
+
)
|
|
1546
|
+
budget_parser.add_argument(
|
|
1547
|
+
"--symptom",
|
|
1548
|
+
default="",
|
|
1549
|
+
help="the symptom, drafted or written: what it takes is what the why loses",
|
|
1550
|
+
)
|
|
1551
|
+
# The draft, at the door that already states the allowance (RK1190). Measured and never
|
|
1552
|
+
# composed: a `why` twice its limit is a number here and a refusal on `add`, and that
|
|
1553
|
+
# difference is the whole reason this argument exists rather than a `--dry-run`.
|
|
1554
|
+
budget_parser.add_argument(
|
|
1555
|
+
"--why",
|
|
1556
|
+
help=(
|
|
1557
|
+
"a draft of the why, measured against its allowance instead of refused by it"
|
|
1558
|
+
+ _PIPE
|
|
1559
|
+
),
|
|
1560
|
+
)
|
|
1561
|
+
budget_parser.add_argument(
|
|
1562
|
+
"--prefix",
|
|
1563
|
+
dest="family",
|
|
1564
|
+
help="count the derived id in this track (default: the first declared)",
|
|
1565
|
+
)
|
|
1566
|
+
budget_parser.add_argument(
|
|
1567
|
+
"--ref",
|
|
1568
|
+
help=(
|
|
1569
|
+
"the anchor the line would point at, for ref_scheme = 'outline' only: the "
|
|
1570
|
+
"pointer is structure, so unnamed the budget assumes the widest on file"
|
|
1571
|
+
),
|
|
1572
|
+
)
|
|
1573
|
+
# The other two prose limits, at the same door and never as a `--dry-run` (RK283): both
|
|
1574
|
+
# are facts about the file and the role, so both are answerable with no prose in hand.
|
|
1575
|
+
budget_parser.add_argument(
|
|
1576
|
+
"--anchor",
|
|
1577
|
+
metavar="ANCHOR",
|
|
1578
|
+
help="a section, e.g. RK12: what its body may say in words, and what it spends",
|
|
1579
|
+
)
|
|
1580
|
+
budget_parser.add_argument(
|
|
1581
|
+
"--role",
|
|
1582
|
+
choices=PROSE_ROLES,
|
|
1583
|
+
help="which prose file --anchor is priced against (default: the one holding it)",
|
|
1584
|
+
)
|
|
1585
|
+
# The section's own draft, beside the field's (RK1190). Two flags rather than one, for
|
|
1586
|
+
# `section add`'s reason (RK381): a body is the longest thing an author composes, and a
|
|
1587
|
+
# path is what a caller reaches for when the prose will not fit in a shell argument.
|
|
1588
|
+
budget_parser.add_argument(
|
|
1589
|
+
"--body",
|
|
1590
|
+
help="a draft body: what it costs the section this call is about" + _PIPE,
|
|
1591
|
+
)
|
|
1592
|
+
budget_parser.add_argument(
|
|
1593
|
+
"--body-file",
|
|
1594
|
+
dest="body_file",
|
|
1595
|
+
metavar="PATH",
|
|
1596
|
+
help="read the draft body from a file instead, with --anchor",
|
|
1597
|
+
)
|
|
1598
|
+
# The third write off the same line (RK1305), and the one this read did not answer for: a
|
|
1599
|
+
# retirement's reason shares the ledger's limit with a derived prefix, so the usable
|
|
1600
|
+
# maximum is neither the published one nor the one a ship is quoted. A value and not a
|
|
1601
|
+
# flag, for `--tools`' reason: bare is the abandonment and named is the supersession, which
|
|
1602
|
+
# spends more of the field before the author starts.
|
|
1603
|
+
budget_parser.add_argument(
|
|
1604
|
+
"--retire",
|
|
1605
|
+
nargs="?",
|
|
1606
|
+
const="",
|
|
1607
|
+
metavar="SUPERSEDED_BY",
|
|
1608
|
+
help=(
|
|
1609
|
+
"what a retirement's reason has — bare, abandoned; named, superseded by that "
|
|
1610
|
+
"id, which costs more of the field"
|
|
1611
|
+
),
|
|
1612
|
+
)
|
|
1613
|
+
budget_parser.add_argument(
|
|
1614
|
+
"--non-goal",
|
|
1615
|
+
dest="non_goal",
|
|
1616
|
+
action="store_true",
|
|
1617
|
+
help="the two limits `non-goal add` enforces, which are the list's own",
|
|
1618
|
+
)
|
|
1619
|
+
budget_parser.add_argument(
|
|
1620
|
+
"--lead",
|
|
1621
|
+
help="a non-goal that exists, with --non-goal: what its reason has left",
|
|
1622
|
+
)
|
|
1623
|
+
# The fourth subject, and the one limit this format holds that had no pre-write read
|
|
1624
|
+
# (RK345): every other budget is derived from a line, and this one from the file on disk.
|
|
1625
|
+
budget_parser.add_argument(
|
|
1626
|
+
"--file",
|
|
1627
|
+
nargs="?",
|
|
1628
|
+
const="",
|
|
1629
|
+
metavar="PATH",
|
|
1630
|
+
help=(
|
|
1631
|
+
"an every-turn file `[budgets]` declares, e.g. agents.md: what it costs and "
|
|
1632
|
+
"what is left — bare, every declared budget"
|
|
1633
|
+
),
|
|
1634
|
+
)
|
|
1635
|
+
budget_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
|
|
1636
|
+
withheld(
|
|
1637
|
+
budget_parser,
|
|
1638
|
+
family="`add`'s reason read back: the answer is about the id this project would issue next, and a prefix typed here asks about one it would not",
|
|
1639
|
+
body_file="this read exists because a refusal over the transport costs the whole payload again, and the three verbs that write a body now take a path (RK1260), which is refused for the corrected field alone — so the draft still worth pricing here is the one that arrived in the call",
|
|
1640
|
+
)
|
|
1641
|
+
# Declared although this verb writes nothing (RK1260). `reads_stdin` is not about the
|
|
1642
|
+
# write lock: it is what a surface with no pipe reads to refuse `-` by name instead of
|
|
1643
|
+
# measuring a one-character draft and answering about it. Two of the three drafts reach the
|
|
1644
|
+
# pipe — `--symptom` never did, though the description above claimed all three, which is
|
|
1645
|
+
# what the declaration makes checkable.
|
|
1646
|
+
budget_parser.set_defaults(
|
|
1647
|
+
handler=_budget,
|
|
1648
|
+
reads_only=True,
|
|
1649
|
+
reads_stdin=(
|
|
1650
|
+
Prose(dest="why", omitted=False),
|
|
1651
|
+
Prose(dest="body", omitted=False, unless="body_file"),
|
|
1652
|
+
),
|
|
1653
|
+
)
|
|
1654
|
+
# The subjects this verb keeps (RK283/RK345), declared rather than checked by hand (RK489).
|
|
1655
|
+
# Named rather than inferred from the positional: under the id scheme `RK12` is both a
|
|
1656
|
+
# line and an anchor, and a command that guessed which one was meant would be a budget
|
|
1657
|
+
# the caller has to check before trusting.
|
|
1658
|
+
answers(
|
|
1659
|
+
budget_parser,
|
|
1660
|
+
("anchor", "one section's prose"),
|
|
1661
|
+
("non_goal", "the roadmap's other bullet"),
|
|
1662
|
+
("file", "an every-turn file"),
|
|
1663
|
+
)
|
|
1664
|
+
|
|
1665
|
+
# The other half of what `budget` was (RK1321). Eight subjects under one name made it the
|
|
1666
|
+
# largest served tool — 2,741 against a per-tool ceiling calibrated on `ship` at 2,466 —
|
|
1667
|
+
# so whichever subject arrived last was refused by a limit none of them was about. The
|
|
1668
|
+
# seam is the tense: `budget` says what a write **may** spend before a word exists, and
|
|
1669
|
+
# this says what a surface **does** spend, already, every session.
|
|
1670
|
+
cost_parser = subcommands.add_parser(
|
|
1671
|
+
"cost",
|
|
1672
|
+
help="what this project's surface costs a session, and where",
|
|
1673
|
+
description=(
|
|
1674
|
+
"Report what a caller already pays: the tool list once at connect, the files "
|
|
1675
|
+
"loaded on every turn, and what the read that replaces opening a file costs a "
|
|
1676
|
+
"tool result. `budget` is the other tense — what a write may spend before a "
|
|
1677
|
+
"word of it exists. Reads; never writes."
|
|
1678
|
+
),
|
|
1679
|
+
)
|
|
1680
|
+
# A value and not a flag (RK1236): bare is the ranking over every tool, and named is the
|
|
1681
|
+
# ranking inside one — the question a caller has the moment the gate names a tool.
|
|
1682
|
+
cost_parser.add_argument(
|
|
1683
|
+
"--tools",
|
|
1684
|
+
nargs="?",
|
|
1685
|
+
const="",
|
|
1686
|
+
metavar="TOOL",
|
|
1687
|
+
help=(
|
|
1688
|
+
"what the tool list costs a session — bare, every tool ranked; named, e.g. "
|
|
1689
|
+
"ship, what each of that one's fields spent"
|
|
1690
|
+
),
|
|
1691
|
+
)
|
|
1692
|
+
cost_parser.add_argument(
|
|
1693
|
+
"--brief",
|
|
1694
|
+
nargs="?",
|
|
1695
|
+
const="",
|
|
1696
|
+
metavar="ID",
|
|
1697
|
+
help="what a brief costs a tool result — bare, every open line, widest first",
|
|
1698
|
+
)
|
|
1699
|
+
cost_parser.add_argument(
|
|
1700
|
+
"--session",
|
|
1701
|
+
action="store_true",
|
|
1702
|
+
help=(
|
|
1703
|
+
"what one session pays: the served schema once at connect and every "
|
|
1704
|
+
"`[budgets]` file each turn, against the cadence of each"
|
|
1705
|
+
),
|
|
1706
|
+
)
|
|
1707
|
+
cost_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
|
|
1708
|
+
cost_parser.set_defaults(handler=_cost, reads_only=True)
|
|
1709
|
+
answers(
|
|
1710
|
+
cost_parser,
|
|
1711
|
+
("tools", "what this tool surface costs a session"),
|
|
1712
|
+
("brief", "what the read that replaces the file costs a tool result"),
|
|
1713
|
+
("session", "both halves of what a session pays, against their cadences"),
|
|
1714
|
+
)
|
|
1715
|
+
narrows(budget_parser, "role", "anchor")
|
|
1716
|
+
# `--body` is **not** narrowed to `--anchor` (RK1224). It was, and that was the last thing
|
|
1717
|
+
# standing between this verb and one call for a whole `add --section`: the line subject
|
|
1718
|
+
# already reports the section its pointer names (RK301), so a draft body handed to it has
|
|
1719
|
+
# somewhere to be measured — and without that, the transaction `add` validates as one unit
|
|
1720
|
+
# took two reads to price. Measured filing one Shio task: four calls, three of them `why`
|
|
1721
|
+
# overflows of 176, 171 and 170 against 167, each throwing away the 250-word body that
|
|
1722
|
+
# travelled beside it. The field that failed was three characters too long and the payload
|
|
1723
|
+
# re-sent to fix it was two orders of magnitude larger.
|
|
1724
|
+
#
|
|
1725
|
+
# Still refused beside a subject with no section at all — `--file`, `--tools`, `--session`
|
|
1726
|
+
# — which is what `_one_answer` decides from `answers` above, and which is RK465's rule
|
|
1727
|
+
# kept where it applies: a draft measured against nothing is a number the caller misreads.
|
|
1728
|
+
narrows(budget_parser, "lead", "non_goal")
|
|
1729
|
+
|
|
1730
|
+
show_parser = subcommands.add_parser(
|
|
1731
|
+
"show",
|
|
1732
|
+
help="one task: its line, its rationale section and the paths it names",
|
|
1733
|
+
description=(
|
|
1734
|
+
"Join what a task is out of the files that hold a piece of it. Nothing is "
|
|
1735
|
+
"stored to make this possible: the section is found by the pointer, and a "
|
|
1736
|
+
"pointer that resolves to nothing is reported as the absence it is."
|
|
1737
|
+
),
|
|
1738
|
+
)
|
|
1739
|
+
show_parser.add_argument("id", help="the task, e.g. RK12")
|
|
1740
|
+
show_parser.add_argument(
|
|
1741
|
+
"--no-body",
|
|
1742
|
+
dest="no_body",
|
|
1743
|
+
action="store_true",
|
|
1744
|
+
help="omit the section's prose, keeping the line and where the prose is",
|
|
1745
|
+
)
|
|
1746
|
+
show_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
|
|
1747
|
+
show_parser.set_defaults(handler=_show, reads_only=True)
|
|
1748
|
+
|
|
1749
|
+
pick_parser = subcommands.add_parser(
|
|
1750
|
+
"pick",
|
|
1751
|
+
help="the next task to work on, and the reason it was chosen",
|
|
1752
|
+
description=(
|
|
1753
|
+
"Apply three tiers — work already in progress, the declared priority, then "
|
|
1754
|
+
"the lowest ready id — and print which one answered. A task blocked outside "
|
|
1755
|
+
"the backlog is never offered: shipping cannot unblock it."
|
|
1756
|
+
),
|
|
1757
|
+
)
|
|
1758
|
+
pick_parser.add_argument(
|
|
1759
|
+
"--block",
|
|
1760
|
+
help=(
|
|
1761
|
+
"scope every part of the answer to one block, so 'nothing to pick' is a "
|
|
1762
|
+
"statement about that block and not about a lower id somewhere else"
|
|
1763
|
+
),
|
|
1764
|
+
)
|
|
1765
|
+
pick_parser.add_argument(
|
|
1766
|
+
"--designed",
|
|
1767
|
+
action="store_true",
|
|
1768
|
+
help=_DESIGNED_HELP,
|
|
1769
|
+
)
|
|
1770
|
+
pick_parser.add_argument(
|
|
1771
|
+
"--have",
|
|
1772
|
+
action="append",
|
|
1773
|
+
default=[],
|
|
1774
|
+
metavar="REQUIREMENT",
|
|
1775
|
+
help=_HAVE_HELP,
|
|
1776
|
+
)
|
|
1777
|
+
pick_parser.add_argument(
|
|
1778
|
+
"--claim",
|
|
1779
|
+
action="store_true",
|
|
1780
|
+
help=(
|
|
1781
|
+
"take the line as well as read it: the marker moves to in-progress in the same "
|
|
1782
|
+
"transaction, so the next caller is answered with something else"
|
|
1783
|
+
),
|
|
1784
|
+
)
|
|
1785
|
+
pick_parser.add_argument(
|
|
1786
|
+
"--json", action="store_true", help="the pick, the tier and the counts"
|
|
1787
|
+
)
|
|
1788
|
+
# The query it is without `--claim`, and the write it is with one (RK167). `take` still
|
|
1789
|
+
# holds a lock of its own over the answer *and* the marker, that pair being what has to be
|
|
1790
|
+
# indivisible for every caller — re-entrant, so declaring it here costs nothing twice.
|
|
1791
|
+
withheld(
|
|
1792
|
+
pick_parser,
|
|
1793
|
+
claim="`brief`'s reason, and its answer too: the writing door is already served as the `claim` tool, so a second flag here would be a second spelling of it",
|
|
1794
|
+
)
|
|
1795
|
+
pick_parser.set_defaults(handler=_pick, reads_only=True, writes_when="claim")
|
|
1796
|
+
|
|
1797
|
+
export_parser = subcommands.add_parser(
|
|
1798
|
+
"export",
|
|
1799
|
+
help="project the backlog onto a README block, a page, or a JSON payload",
|
|
1800
|
+
description=(
|
|
1801
|
+
"Derive what another file would restate: counts per block and the next ready "
|
|
1802
|
+
"line. Idempotent and stamped with nothing, so a refresh with nothing to say "
|
|
1803
|
+
"makes no diff — and every character of content already passed `add`."
|
|
1804
|
+
),
|
|
1805
|
+
)
|
|
1806
|
+
export_parser.add_argument(
|
|
1807
|
+
"--readme",
|
|
1808
|
+
nargs="?",
|
|
1809
|
+
const=DEFAULTS["readme"].name,
|
|
1810
|
+
metavar="PATH",
|
|
1811
|
+
help=(
|
|
1812
|
+
f"write the block between the roadkeep markers in this file "
|
|
1813
|
+
f"(default {DEFAULTS['readme'].name})"
|
|
1814
|
+
),
|
|
1815
|
+
)
|
|
1816
|
+
export_parser.add_argument(
|
|
1817
|
+
"--site",
|
|
1818
|
+
nargs="?",
|
|
1819
|
+
const=DEFAULTS["site"].name,
|
|
1820
|
+
metavar="PATH",
|
|
1821
|
+
help=(
|
|
1822
|
+
f"the same projection as HTML, between the same two markers "
|
|
1823
|
+
f"(default {DEFAULTS['site'].name})"
|
|
1824
|
+
),
|
|
1825
|
+
)
|
|
1826
|
+
export_parser.add_argument(
|
|
1827
|
+
"--contents",
|
|
1828
|
+
action="store_true",
|
|
1829
|
+
help=(
|
|
1830
|
+
"refresh the table of contents inside this project's rationale file, between the "
|
|
1831
|
+
"same two markers: every row is a heading that file already carries, so a `ship` "
|
|
1832
|
+
"that drops a section leaves the list wrong until this runs. Takes no path — the "
|
|
1833
|
+
"target is `[files]`' own"
|
|
1834
|
+
),
|
|
1835
|
+
)
|
|
1836
|
+
export_parser.add_argument(
|
|
1837
|
+
"--spec",
|
|
1838
|
+
metavar="ID",
|
|
1839
|
+
help=(
|
|
1840
|
+
"one task as a document: its claim, what it depends on, what would finish it, "
|
|
1841
|
+
"the non-goals that bind it and its design section whole. `brief` is the same "
|
|
1842
|
+
"join bounded to a tool result; this one is bounded by a file, for a reviewer, "
|
|
1843
|
+
"a second agent or a CI job that cannot run the read"
|
|
1844
|
+
),
|
|
1845
|
+
)
|
|
1846
|
+
export_parser.add_argument(
|
|
1847
|
+
"--json", action="store_true", help="the payload a site build reads"
|
|
1848
|
+
)
|
|
1849
|
+
export_parser.set_defaults(handler=_export)
|
|
1850
|
+
# `--json` is a subject and a destination is a write, so asking for both asks two
|
|
1851
|
+
# questions (RK466). `--readme` and `--site` are not that shape — they are two
|
|
1852
|
+
# destinations of one projection and compose, which RK39 asked for, so they are one
|
|
1853
|
+
# group: the whole reason :class:`Answer` holds a group rather than a flag.
|
|
1854
|
+
answers(
|
|
1855
|
+
export_parser,
|
|
1856
|
+
("json", "the projection printed"),
|
|
1857
|
+
(("readme", "site"), "the projection written into a file"),
|
|
1858
|
+
# A third subject and not a third destination (RK1362): this one is about one task,
|
|
1859
|
+
# so it answers a different question rather than putting the same answer somewhere
|
|
1860
|
+
# else. `brief <id> --json` is the payload read; this verb's `--json` is the site
|
|
1861
|
+
# build's, and the two are about different documents.
|
|
1862
|
+
("spec", "one task as a document"),
|
|
1863
|
+
)
|
|
1864
|
+
|
|
1865
|
+
gaps_parser = subcommands.add_parser(
|
|
1866
|
+
"gaps",
|
|
1867
|
+
help="ids in neither file, resolved against the commit that removed them",
|
|
1868
|
+
description=(
|
|
1869
|
+
"Every id below the highest that no line carries. Each resolves to the commit "
|
|
1870
|
+
"whose message holds the decision, to 'never carried' when a complete history "
|
|
1871
|
+
"mentions it nowhere, or to 'unresolvable' when there is no history to search "
|
|
1872
|
+
"— three different answers from 'retired', none of them a weaker one."
|
|
1873
|
+
),
|
|
1874
|
+
)
|
|
1875
|
+
gaps_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
|
|
1876
|
+
gaps_parser.set_defaults(handler=_gaps, reads_only=True)
|
|
1877
|
+
|
|
1878
|
+
govern_parser = subcommands.add_parser(
|
|
1879
|
+
"govern",
|
|
1880
|
+
help="declare one number roadkeep.toml governs, against the reading that decides it",
|
|
1881
|
+
description=(
|
|
1882
|
+
"Take the reading and write the number in one call. `[limits]`, `[budgets]`, "
|
|
1883
|
+
"`[tools]` and `[claims]` hold the values that are a judgement about a figure, "
|
|
1884
|
+
"and each already had the read that decides it somewhere else. With no value it "
|
|
1885
|
+
"prints the reading alone. A limit this project already breaks is refused rather "
|
|
1886
|
+
"than written. Why this number and not the next is yours to write and this "
|
|
1887
|
+
"verb's to place: `--because` stacks your sentence above the key, and `--instead` "
|
|
1888
|
+
"replaces the argument standing there, for a reading that has moved."
|
|
1889
|
+
),
|
|
1890
|
+
)
|
|
1891
|
+
govern_parser.add_argument(
|
|
1892
|
+
"key",
|
|
1893
|
+
help="the address, as `config` prints one — e.g. limits.symptom, tools.session",
|
|
1894
|
+
)
|
|
1895
|
+
govern_parser.add_argument(
|
|
1896
|
+
"at",
|
|
1897
|
+
nargs="?",
|
|
1898
|
+
type=int,
|
|
1899
|
+
help="the number to declare; omitted, the reading is printed and nothing is written",
|
|
1900
|
+
)
|
|
1901
|
+
govern_parser.add_argument(
|
|
1902
|
+
"--role",
|
|
1903
|
+
help="which role's limits, for a `[limits.<role>]` table (default: the shared one)",
|
|
1904
|
+
)
|
|
1905
|
+
govern_parser.add_argument(
|
|
1906
|
+
"--file",
|
|
1907
|
+
help="which every-turn file, for a `[budgets]` entry — the path the config spells",
|
|
1908
|
+
)
|
|
1909
|
+
govern_parser.add_argument(
|
|
1910
|
+
"--because",
|
|
1911
|
+
default="",
|
|
1912
|
+
help="your argument for this number, wrapped into comments above the key",
|
|
1913
|
+
)
|
|
1914
|
+
govern_parser.add_argument(
|
|
1915
|
+
"--instead",
|
|
1916
|
+
default="",
|
|
1917
|
+
help=(
|
|
1918
|
+
"the same sentence, replacing the run above the key instead of stacking on it; "
|
|
1919
|
+
"the answer names every line it took out"
|
|
1920
|
+
),
|
|
1921
|
+
)
|
|
1922
|
+
govern_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
|
|
1923
|
+
govern_parser.set_defaults(handler=_govern)
|
|
1924
|
+
|
|
1925
|
+
config_parser = subcommands.add_parser(
|
|
1926
|
+
"config",
|
|
1927
|
+
help="what roadkeep.toml may declare: every table, key, type and default",
|
|
1928
|
+
description=(
|
|
1929
|
+
"Print the shape of this project's own configuration, answered by the package "
|
|
1930
|
+
"that refuses everything else (RK1270). One row per key — its table, its type, "
|
|
1931
|
+
"what this build uses when nobody declares it, and whether this project did — "
|
|
1932
|
+
"with the sentence the source already carries above each table. What is listed "
|
|
1933
|
+
"is what *this* copy accepts, which is how a key it predates is told from a typo, "
|
|
1934
|
+
"so the build that answered is named. Last, what this build *fixes* from its own "
|
|
1935
|
+
"corpus and no project declares, with the reading behind it. It reads and never "
|
|
1936
|
+
"writes."
|
|
1937
|
+
),
|
|
1938
|
+
)
|
|
1939
|
+
config_parser.add_argument(
|
|
1940
|
+
"--table",
|
|
1941
|
+
default=None,
|
|
1942
|
+
help=(
|
|
1943
|
+
"one table, spelled as the answer spells it — omitted, every one; the top level "
|
|
1944
|
+
"is the empty string, and a table declared per role or per path carries the "
|
|
1945
|
+
"placeholder, e.g. rules.<role>"
|
|
1946
|
+
),
|
|
1947
|
+
)
|
|
1948
|
+
config_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
|
|
1949
|
+
config_parser.set_defaults(handler=_config_shape, reads_only=True)
|
|
1950
|
+
|
|
1951
|
+
commands_parser = subcommands.add_parser(
|
|
1952
|
+
"commands",
|
|
1953
|
+
help="what may be typed: every verb, its arguments, defaults and served exposure",
|
|
1954
|
+
description=(
|
|
1955
|
+
"Print this build's own command surface as data (RK1401). One block per verb — "
|
|
1956
|
+
"whether it reads or writes, the flag that turns a read into a write, and one "
|
|
1957
|
+
"row per argument with its spellings, what it takes, its default and the "
|
|
1958
|
+
"sentence the parser already carries — plus which tool an agent is served it as, "
|
|
1959
|
+
"and which of its arguments that surface exposes on *this* project. `config` "
|
|
1960
|
+
"answers what roadkeep.toml may declare; this answers what may be typed. What is "
|
|
1961
|
+
"listed is what *this* copy takes, so the build that answered is named. It reads "
|
|
1962
|
+
"and never writes."
|
|
1963
|
+
),
|
|
1964
|
+
)
|
|
1965
|
+
commands_parser.add_argument(
|
|
1966
|
+
"--command",
|
|
1967
|
+
default=None,
|
|
1968
|
+
metavar="VERB",
|
|
1969
|
+
help=(
|
|
1970
|
+
"one verb, spelled as the answer spells it — omitted, every one; a nested one "
|
|
1971
|
+
"carries its path, e.g. 'section add'"
|
|
1972
|
+
),
|
|
1973
|
+
)
|
|
1974
|
+
commands_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
|
|
1975
|
+
commands_parser.set_defaults(handler=_commands, reads_only=True)
|
|
1976
|
+
|
|
1977
|
+
anchors_parser = subcommands.add_parser(
|
|
1978
|
+
"anchors",
|
|
1979
|
+
help="which outline addresses this project has ever declared, live or retired",
|
|
1980
|
+
description=(
|
|
1981
|
+
"Read the anchors out of every declared prose file and out of its diffs: live "
|
|
1982
|
+
"ones a heading declares now, and retired ones a ship deleted while every entry "
|
|
1983
|
+
"citing them stayed. An address is spent once a heading used it (RK4's rule for "
|
|
1984
|
+
"ids), so this is the read that says which number a reopened family may take — "
|
|
1985
|
+
"and which top-level is free, which is what a reused block needs."
|
|
1986
|
+
),
|
|
1987
|
+
)
|
|
1988
|
+
anchors_parser.add_argument(
|
|
1989
|
+
"--family",
|
|
1990
|
+
default="",
|
|
1991
|
+
metavar="ANCHOR",
|
|
1992
|
+
help="only this subtree, e.g. XXXVII — omitted, one row per top-level family",
|
|
1993
|
+
)
|
|
1994
|
+
anchors_parser.add_argument(
|
|
1995
|
+
"--block",
|
|
1996
|
+
default="",
|
|
1997
|
+
metavar="LABEL",
|
|
1998
|
+
help=(
|
|
1999
|
+
"the subtree this block's prose already lives under, e.g. Q — the address a "
|
|
2000
|
+
"caller knows, since a prose file under an outline declares no block heading; "
|
|
2001
|
+
"refused with --family, and names both where a block spans two families"
|
|
2002
|
+
),
|
|
2003
|
+
)
|
|
2004
|
+
anchors_parser.add_argument(
|
|
2005
|
+
"--role",
|
|
2006
|
+
default="",
|
|
2007
|
+
help=(
|
|
2008
|
+
"list only this prose file's addresses (default: every declared one) — the "
|
|
2009
|
+
"free top-level is per namespace, so it stays the project's where no [refs] "
|
|
2010
|
+
"declares one and is that file's own where one does"
|
|
2011
|
+
),
|
|
2012
|
+
)
|
|
2013
|
+
anchors_parser.add_argument(
|
|
2014
|
+
"--next",
|
|
2015
|
+
dest="only_next",
|
|
2016
|
+
action="store_true",
|
|
2017
|
+
help=(
|
|
2018
|
+
"the free address alone, without the listing of spent ones — the `next-id` of "
|
|
2019
|
+
"anchors, and the read an `add --ref` makes every time"
|
|
2020
|
+
),
|
|
2021
|
+
)
|
|
2022
|
+
anchors_parser.add_argument(
|
|
2023
|
+
"--claims",
|
|
2024
|
+
action="store_true",
|
|
2025
|
+
help=(
|
|
2026
|
+
"only the addresses whose ownership is not the ordinary one: a heading binding "
|
|
2027
|
+
"nobody, and one binding a task no open line claims — the audit, over every "
|
|
2028
|
+
"family at once, since the rows it leaves out are the ones nobody reads"
|
|
2029
|
+
),
|
|
2030
|
+
)
|
|
2031
|
+
anchors_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
|
|
2032
|
+
anchors_parser.set_defaults(handler=_anchors, reads_only=True)
|
|
2033
|
+
# Two subjects, as `budget`'s four are (RK466): `--next` returned before the `--claims`
|
|
2034
|
+
# branch was reached, so a caller asking for the audit and the free address read the
|
|
2035
|
+
# address alone with nothing said about the other.
|
|
2036
|
+
answers(
|
|
2037
|
+
anchors_parser, ("only_next", "the free address"), ("claims", "the ownership audit")
|
|
2038
|
+
)
|
|
2039
|
+
|
|
2040
|
+
deps_parser = subcommands.add_parser(
|
|
2041
|
+
"deps",
|
|
2042
|
+
help="resolve one task's deps, naming the ones nothing can resolve",
|
|
2043
|
+
description=(
|
|
2044
|
+
"Resolve each dep against the roadmap and the changelog. A dep nothing now "
|
|
2045
|
+
"open will satisfy is reported as unresolvable rather than open — work "
|
|
2046
|
+
"outside the backlog, a task that retired, and a block label with nothing "
|
|
2047
|
+
"filed under it."
|
|
2048
|
+
),
|
|
2049
|
+
)
|
|
2050
|
+
deps_parser.add_argument("id", help="the task to resolve, e.g. RK5")
|
|
2051
|
+
deps_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
|
|
2052
|
+
deps_parser.set_defaults(handler=_deps, reads_only=True)
|
|
2053
|
+
|
|
2054
|
+
origin_parser = subcommands.add_parser(
|
|
2055
|
+
"origin",
|
|
2056
|
+
help="the commits that proposed and shipped a task, with the reasoning",
|
|
2057
|
+
description=(
|
|
2058
|
+
"Resolve a task's history from git. The pointer is derived, never stored: "
|
|
2059
|
+
"a hash written into the ledger would be rewritten by the first squash or "
|
|
2060
|
+
"amend, and a dead hash reads exactly like a live one. A leading § asks the "
|
|
2061
|
+
"same question of a rationale anchor instead — the dangling cross-reference a "
|
|
2062
|
+
"ship leaves in somebody else's prose, which no file records the answer to."
|
|
2063
|
+
),
|
|
2064
|
+
)
|
|
2065
|
+
origin_parser.add_argument(
|
|
2066
|
+
"id", help="the task to look up, e.g. RK1 — or §<anchor>, as the prose spells it"
|
|
2067
|
+
)
|
|
2068
|
+
origin_parser.add_argument(
|
|
2069
|
+
"--why",
|
|
2070
|
+
action="store_true",
|
|
2071
|
+
help="print the shipping commit's full message — the rationale the ledger drops",
|
|
2072
|
+
)
|
|
2073
|
+
origin_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
|
|
2074
|
+
origin_parser.set_defaults(handler=_origin, reads_only=True)
|
|
2075
|
+
|
|
2076
|
+
weight_parser = subcommands.add_parser(
|
|
2077
|
+
"weight",
|
|
2078
|
+
help="what comparable tasks cost, derived from the commits that shipped them",
|
|
2079
|
+
description=(
|
|
2080
|
+
"What a comparable task cost, so granularity is a query instead of a feel: a "
|
|
2081
|
+
"block whose last comparables shipped at 800+ lines is a block where the next "
|
|
2082
|
+
"line is probably two lines. Derived from the commit that wrote each ledger "
|
|
2083
|
+
"entry, so nothing stores it and `git show` refutes it. Two axes and no score — "
|
|
2084
|
+
"median to p90 lines vary 2.7× here and files, which is what an agent holds in "
|
|
2085
|
+
"context, 1.4×. An entry whose commit wrote several is named and left out "
|
|
2086
|
+
"rather than given a share of it, a divided cost being one no commit contains. "
|
|
2087
|
+
"This ranks nothing: every tier of `pick` is a fact, and a cheapness tier would "
|
|
2088
|
+
"defer the architectural tasks, which is where the leverage is."
|
|
2089
|
+
),
|
|
2090
|
+
)
|
|
2091
|
+
weight_parser.add_argument("--block", help="only this block's comparables, e.g. C")
|
|
2092
|
+
weight_parser.add_argument(
|
|
2093
|
+
"--records",
|
|
2094
|
+
action="store_true",
|
|
2095
|
+
help=(
|
|
2096
|
+
"every weighed entry, which the percentiles summarise: the evidence for the "
|
|
2097
|
+
"figure, wanted when you dispute it and not when you are sizing a line (RK264)"
|
|
2098
|
+
),
|
|
2099
|
+
)
|
|
2100
|
+
weight_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
|
|
2101
|
+
weight_parser.set_defaults(handler=_weight, reads_only=True)
|
|
2102
|
+
|
|
2103
|
+
remaining_parser = subcommands.add_parser(
|
|
2104
|
+
"remaining",
|
|
2105
|
+
help="how many sites a task's own declared query still matches",
|
|
2106
|
+
description=(
|
|
2107
|
+
"The mirror of `weight`, and derived the same way (RK492): that one says what a "
|
|
2108
|
+
"comparable task cost, from the commits that shipped it, and this says what one "
|
|
2109
|
+
"has left, from the repository as it is now. A migration declares the query in "
|
|
2110
|
+
"its rationale section — a fenced `roadkeep-remaining` block, one `<pathspec> :: "
|
|
2111
|
+
"<regex>` per line — and this runs it. Nothing is stored, so nothing goes stale: "
|
|
2112
|
+
"the first commit that closes a site changes the answer, which a number written "
|
|
2113
|
+
"onto a line could not. It is a count and never a verdict — the pattern is the "
|
|
2114
|
+
"author's, so a query answering 0 says the pattern stopped matching, and whether "
|
|
2115
|
+
"that is the work being done is a judgement this tool does not make."
|
|
2116
|
+
),
|
|
2117
|
+
)
|
|
2118
|
+
remaining_parser.add_argument("id", help="the task whose design declares the query, e.g. RK12")
|
|
2119
|
+
remaining_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
|
|
2120
|
+
remaining_parser.set_defaults(handler=_remaining, reads_only=True)
|
|
2121
|
+
|
|
2122
|
+
evidence_parser = subcommands.add_parser(
|
|
2123
|
+
"evidence",
|
|
2124
|
+
help="what this task's design says would prove it done, counted now",
|
|
2125
|
+
description=(
|
|
2126
|
+
"Run the criterion a design declares, against this tree, now. `remaining` "
|
|
2127
|
+
"with the sign flipped: a `roadkeep-evidence` fenced block names sites that "
|
|
2128
|
+
"must **exist** where the other names sites still to change, and both are one "
|
|
2129
|
+
"`<pathspec> :: <regex>` per line read by one grammar. Never a verdict — the "
|
|
2130
|
+
"pattern is the author's claim and the count is the answer, so 0 says the "
|
|
2131
|
+
"evidence is not there yet and whether that is the work being done is yours "
|
|
2132
|
+
"to judge. Nothing is stored, so nothing goes stale."
|
|
2133
|
+
),
|
|
2134
|
+
)
|
|
2135
|
+
evidence_parser.add_argument("id", help="the task whose design declares the criterion")
|
|
2136
|
+
evidence_parser.add_argument("--json", action="store_true", help=_JSON_HELP)
|
|
2137
|
+
evidence_parser.set_defaults(handler=_evidence, reads_only=True)
|
|
2138
|
+
|