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.
Files changed (67) hide show
  1. roadkeep/__init__.py +79 -0
  2. roadkeep/adopting.py +2347 -0
  3. roadkeep/attesting.py +293 -0
  4. roadkeep/authoring.py +2117 -0
  5. roadkeep/backlog.py +767 -0
  6. roadkeep/blocking.py +1622 -0
  7. roadkeep/briefing.py +970 -0
  8. roadkeep/budgeting.py +2056 -0
  9. roadkeep/capturing.py +1699 -0
  10. roadkeep/claiming.py +1019 -0
  11. roadkeep/cli.py +638 -0
  12. roadkeep/commanding.py +487 -0
  13. roadkeep/config.py +1832 -0
  14. roadkeep/counting.py +376 -0
  15. roadkeep/criteria.py +933 -0
  16. roadkeep/deferring.py +708 -0
  17. roadkeep/describing.py +568 -0
  18. roadkeep/exporting.py +808 -0
  19. roadkeep/fixing.py +629 -0
  20. roadkeep/governing.py +934 -0
  21. roadkeep/graph.py +395 -0
  22. roadkeep/guarding.py +1028 -0
  23. roadkeep/history.py +2403 -0
  24. roadkeep/ids.py +301 -0
  25. roadkeep/installing.py +2145 -0
  26. roadkeep/kernel/__init__.py +24 -0
  27. roadkeep/kernel/document.py +1719 -0
  28. roadkeep/kernel/schema.py +2308 -0
  29. roadkeep/linting.py +4420 -0
  30. roadkeep/locking.py +209 -0
  31. roadkeep/markers.py +172 -0
  32. roadkeep/merging.py +1159 -0
  33. roadkeep/picking.py +772 -0
  34. roadkeep/provenance.py +789 -0
  35. roadkeep/queueing.py +752 -0
  36. roadkeep/ranking.py +139 -0
  37. roadkeep/referring.py +231 -0
  38. roadkeep/remaining.py +336 -0
  39. roadkeep/remedying.py +1989 -0
  40. roadkeep/rendering.py +1601 -0
  41. roadkeep/renumbering.py +503 -0
  42. roadkeep/repairing.py +295 -0
  43. roadkeep/reverting.py +144 -0
  44. roadkeep/scoping.py +708 -0
  45. roadkeep/screening.py +196 -0
  46. roadkeep/sections.py +4121 -0
  47. roadkeep/serving.py +2909 -0
  48. roadkeep/shipping.py +3993 -0
  49. roadkeep/showing.py +613 -0
  50. roadkeep/storing.py +224 -0
  51. roadkeep/verbs/__init__.py +26 -0
  52. roadkeep/verbs/adopting.py +974 -0
  53. roadkeep/verbs/authoring.py +566 -0
  54. roadkeep/verbs/declaring.py +335 -0
  55. roadkeep/verbs/linting.py +645 -0
  56. roadkeep/verbs/querying.py +2138 -0
  57. roadkeep/verbs/reading.py +307 -0
  58. roadkeep/verbs/refusing.py +146 -0
  59. roadkeep/verbs/sections.py +1433 -0
  60. roadkeep/verbs/shipping.py +819 -0
  61. roadkeep/weighing.py +380 -0
  62. roadkeep-0.2.0.dist-info/METADATA +453 -0
  63. roadkeep-0.2.0.dist-info/RECORD +67 -0
  64. roadkeep-0.2.0.dist-info/WHEEL +5 -0
  65. roadkeep-0.2.0.dist-info/entry_points.txt +2 -0
  66. roadkeep-0.2.0.dist-info/licenses/LICENSE +202 -0
  67. roadkeep-0.2.0.dist-info/top_level.txt +1 -0
roadkeep/commanding.py ADDED
@@ -0,0 +1,487 @@
1
+ """The command surface as data, so nothing outside a terminal declares it twice (RK1401).
2
+
3
+ `--help` is the only reader of the parser this package builds, and it is text: a usage line
4
+ wrapped to a console width, arguments grouped the way `argparse` groups them, sentences
5
+ folded at whatever column the terminal is. Anything that wants the *facts* — a reference
6
+ page, a completion list, a table in an area a browser serves — either scrapes that output or
7
+ types the verbs again, and both go stale in the commit after the one that wrote them.
8
+
9
+ The package already holds every fact such a reader wants. Each verb declares its help
10
+ sentence beside the argument, `reads_only` and `writes_when` say whether running it changes
11
+ a file (RK117, RK167), and :data:`~roadkeep.serving.TOOLS` says which of them an agent is
12
+ sent and which of their arguments it may set (RK1360). `cost --tools` proves that surface can
13
+ be walked as data, because pricing a served description is exactly that walk. What no read
14
+ did was **print** it.
15
+
16
+ **Nothing here is a second statement of the surface.** The verbs come off the subparser tree,
17
+ the sentence off the `help=` its author already wrote, the default off the action, and the
18
+ exposure off the tool table `tools/list` answers from. The one thing this module decides is
19
+ what a *reader outside the process* needs each fact called — which is :class:`Argument`'s
20
+ fields and nothing else.
21
+
22
+ This is :mod:`roadkeep.describing` for the other half of the contract. That module answers
23
+ what `roadkeep.toml` may declare; this one answers what may be typed. Both name the build
24
+ that gave the answer, for the same reason: what is published is what **this** copy accepts,
25
+ so a flag a reader's copy does not have is an upgrade rather than a mistake.
26
+
27
+ A read about the tool and never about a governed file, so it costs a session nothing until it
28
+ is called (L5) and it answers on a tree with no configuration at all — which is the caller who
29
+ most needs it, since deciding to adopt comes before there is anything to configure.
30
+ """
31
+
32
+ from __future__ import annotations
33
+
34
+ import argparse
35
+ from collections.abc import Mapping, Sequence
36
+ from dataclasses import dataclass
37
+
38
+ from roadkeep.config import Config
39
+
40
+ __all__ = ["Argument", "Command", "Listing", "commands", "payload", "stated"]
41
+
42
+ #: The one action every parser declares and no reader asked about: `--help` is argparse's,
43
+ #: not this tool's, and a reference page listing it once per verb would spend a row on the
44
+ #: fact that this is a command-line program.
45
+ _UNASKED = frozenset({"help"})
46
+
47
+
48
+ def _rendered(value: object) -> str:
49
+ """A default as a reader outside Python needs it spelled.
50
+
51
+ :func:`roadkeep.describing._rendered`'s rule for the other half of the contract, and
52
+ deliberately the same one: a project reading both should not have to learn that a boolean
53
+ is `true` in a config listing and `True` in a command listing.
54
+ """
55
+ if isinstance(value, bool):
56
+ return "true" if value else "false"
57
+ if isinstance(value, str):
58
+ return f'"{value}"'
59
+ if isinstance(value, tuple | list):
60
+ return "[" + ", ".join(_rendered(one) for one in value) + "]"
61
+ return str(value)
62
+
63
+
64
+ @dataclass(frozen=True, slots=True)
65
+ class Argument:
66
+ """One thing a verb takes, as a reader outside the process needs it.
67
+
68
+ Keyed by :attr:`dest` rather than by spelling, because that is what the rest of this
69
+ package is keyed by: `writes_when` names a dest, a tool exposes a dest, and a flag
70
+ carrying two spellings — `--status`/`--marker`, `--reason`/`--why` (RK399, RK1038) — is
71
+ one argument under both, which a reader keyed on the first spelling would report as two.
72
+ """
73
+
74
+ #: Every spelling, in the order the parser declares them, so a caller can print the
75
+ #: primary and still recognise the alias somebody else's skill was written against. A
76
+ #: positional carries the one name `--help` calls it by.
77
+ spelling: tuple[str, ...]
78
+ dest: str
79
+ #: Whether it is taken by position. The difference is not decoration: `show RK1` and
80
+ #: `show --id RK1` is the mistake RK1254 was filed for, so which of the two a verb wants
81
+ #: is the fact a reference page exists to state.
82
+ positional: bool
83
+ #: What its value is called — the metavar the parser declares, or `""` where the argument
84
+ #: takes no value at all and is a switch.
85
+ takes: str
86
+ #: Whether it may be given more than once, however the parser says so — an append action
87
+ #: or an `nargs` that consumes several.
88
+ repeatable: bool
89
+ required: bool
90
+ #: What the verb uses when it is not given, rendered — or `None`, which says there is no
91
+ #: default rather than that the default is empty.
92
+ default: str | None
93
+ #: The closed set of values, where the parser declares one; empty otherwise.
94
+ choices: tuple[str, ...]
95
+ #: The sentence the parser already carries. Harvested and never restated, which is the
96
+ #: whole of why it is worth publishing: a second copy is the one that goes stale.
97
+ help: str
98
+ #: Whether an agent on **this** project may set it over the served surface (RK1360). Per
99
+ #: project and not per build, because `[files]` and `[ids]` decide it (L6). Spelled the
100
+ #: way :meth:`~roadkeep.serving.Tool.exposed` spells it, and deliberately not `served`:
101
+ #: that word is taken across this package for the prefix a session's tools arrive under
102
+ #: (RK1246), and one field answering for two facts is what `tests/carrying.py` exists to
103
+ #: refuse.
104
+ exposed: bool = False
105
+ #: Whether the served surface passes it on every call without exposing it — which is how
106
+ #: a flag becomes a tool (RK150), and a different fact from being withheld.
107
+ always: bool = False
108
+
109
+ @property
110
+ def primary(self) -> str:
111
+ """The spelling `--help` leads with, which is what a reference page prints."""
112
+ return self.spelling[0] if self.spelling else self.dest
113
+
114
+
115
+ @dataclass(frozen=True, slots=True)
116
+ class Command:
117
+ """One verb this build declares, and what running it costs.
118
+
119
+ A **group** — `section`, `block`, `record` — is one of these too, carrying no arguments
120
+ and reaching nothing. Published rather than filtered out, because `section --help` is a
121
+ real door and a listing that skipped it would leave the nesting to be inferred from the
122
+ spaces in its children's paths.
123
+ """
124
+
125
+ #: The subcommand path, space-separated where it is nested (`"section add"`). The argv is
126
+ #: this split, which is the same thing :class:`~roadkeep.serving.Tool` means by it.
127
+ path: str
128
+ help: str
129
+ description: str
130
+ arguments: tuple[Argument, ...]
131
+ #: Whether running it changes a governed file. The parser's own claim (RK117) and never a
132
+ #: table beside it: `lint` is a read and `lint --fix` is not, which a boolean alone gets
133
+ #: backwards and :attr:`turns_on` is the other half of.
134
+ writes: bool
135
+ #: The dests that turn a declared read into a write (RK167, RK307). Empty on a verb that
136
+ #: writes either way, where the question does not arise.
137
+ turns_on: tuple[str, ...] = ()
138
+ #: Whether it reaches a handler at all. False for a group, whose whole content is the
139
+ #: verbs under it.
140
+ runs: bool = True
141
+ #: The protocol names this command is served under, in :data:`~roadkeep.serving.TOOLS`
142
+ #: order. Several where `always` has put two tools on one command (RK150) — `brief` and
143
+ #: the `--claim` that writes — and empty where the CLI keeps a verb to itself.
144
+ tools: tuple[str, ...] = ()
145
+ #: Whether **this** project is sent it, which is a narrower question than having a tool at
146
+ #: all: a verb whose vocabulary the project never declared is withheld (RK1360).
147
+ published: bool = False
148
+ #: The role a withheld tool needs, so the answer names the `declare` that opens it rather
149
+ #: than leaving an absence for a reader to explain.
150
+ needs: str = ""
151
+ #: Which verb family declares it — `authoring`, `querying`, `sections` and three more, the
152
+ #: modules under `verbs/` that `cli.build_parser` calls in order (RK1402).
153
+ #:
154
+ #: **Derived from where the handler lives**, not declared a second time beside the parser.
155
+ #: A verb's family is already a fact about this package's layout — `agents.md` says a module
156
+ #: per verb family and the dispatch calls them in order — so a table here would be that
157
+ #: layout restated, and wrong the first time a verb moves between two of them. A group has
158
+ #: no handler and takes the family its children share.
159
+ family: str = ""
160
+
161
+ @property
162
+ def depth(self) -> int:
163
+ return self.path.count(" ")
164
+
165
+ @property
166
+ def leaf(self) -> str:
167
+ """The last word of the path — what `--help` lists it under, one level up."""
168
+ return self.path.rsplit(" ", 1)[-1]
169
+
170
+
171
+ @dataclass(frozen=True, slots=True)
172
+ class Listing:
173
+ """Every verb, and the build that answered — which is half of what makes it usable."""
174
+
175
+ commands: tuple[Command, ...]
176
+ version: str
177
+ #: The config this project's exposure was read against, or `None` where there is none —
178
+ #: in which case :attr:`Command.published` is what a default project would be sent.
179
+ source: str | None = None
180
+
181
+ def under(self, path: str) -> tuple[Command, ...]:
182
+ """One command's own children, for a listing that groups the way `--help` does."""
183
+ return tuple(
184
+ one
185
+ for one in self.commands
186
+ if one.path.startswith(f"{path} ") and one.depth == path.count(" ") + 1
187
+ )
188
+
189
+ def top(self) -> tuple[Command, ...]:
190
+ return tuple(one for one in self.commands if one.depth == 0)
191
+
192
+
193
+ def _takes(action: argparse.Action) -> str:
194
+ """What one argument's value is called, or `""` where it takes none.
195
+
196
+ argparse's own two conventions, kept rather than unified: an optional's value is the
197
+ metavar or the dest upper-cased, a positional's is the metavar or the dest as written.
198
+ Printing a third spelling here would name an argument something `--help` never calls it.
199
+ """
200
+ if action.nargs == 0:
201
+ return ""
202
+ if action.metavar:
203
+ return action.metavar if isinstance(action.metavar, str) else action.metavar[0]
204
+ return action.dest if not action.option_strings else action.dest.upper()
205
+
206
+
207
+ def _repeatable(action: argparse.Action) -> bool:
208
+ """Whether it may be given more than once, however the parser declares it."""
209
+ if isinstance(action, argparse._AppendAction | argparse._AppendConstAction): # noqa: SLF001
210
+ return True
211
+ return action.nargs in {"*", "+"} or isinstance(action.nargs, int) and action.nargs > 1
212
+
213
+
214
+ def _required(action: argparse.Action) -> bool:
215
+ """Whether omitting it is refused — which argparse states one way for each kind."""
216
+ if action.option_strings:
217
+ return bool(action.required)
218
+ return action.nargs not in {"?", "*"}
219
+
220
+
221
+ def _arguments(
222
+ parser: argparse.ArgumentParser, exposed: Sequence[str], always: Sequence[str]
223
+ ) -> tuple[Argument, ...]:
224
+ """Every argument one verb declares, in its own declaration order.
225
+
226
+ A subparser action is not one of these: it is how the next verb is reached, and naming it
227
+ here would offer a command as a value — `_positionals`' rule in :mod:`roadkeep.cli`, for
228
+ its reason.
229
+ """
230
+ out: list[Argument] = []
231
+ for action in parser._actions: # noqa: SLF001 - argparse exposes no public reader
232
+ if action.dest in _UNASKED or isinstance(action, argparse._SubParsersAction): # noqa: SLF001
233
+ continue
234
+ default = action.default
235
+ out.append(
236
+ Argument(
237
+ spelling=tuple(action.option_strings) or (_takes(action),),
238
+ dest=action.dest,
239
+ positional=not action.option_strings,
240
+ takes=_takes(action),
241
+ repeatable=_repeatable(action),
242
+ required=_required(action),
243
+ # `SUPPRESS` is argparse saying the attribute is not set at all, which is a
244
+ # different fact from a default of nothing and is published as the absence.
245
+ default=(
246
+ None
247
+ if default is None or default is argparse.SUPPRESS
248
+ else _rendered(default)
249
+ ),
250
+ choices=tuple(str(one) for one in action.choices or ()),
251
+ help=action.help or "",
252
+ exposed=action.dest in exposed,
253
+ always=action.dest in always,
254
+ )
255
+ )
256
+ return tuple(out)
257
+
258
+
259
+ def _serving(config: Config) -> Mapping[str, tuple[list[str], list[str], list[str], bool, str]]:
260
+ """The served surface indexed by command path: names, exposed dests, always, published.
261
+
262
+ Read off :data:`~roadkeep.serving.TOOLS` and never listed again, which is the same trade
263
+ :attr:`~roadkeep.serving.Tool.writes` makes: exposure is a decision that surface already
264
+ states, and a second table here would answer about a surface that has moved.
265
+
266
+ A path may carry several tools, so every field accumulates: `brief` is two of them over
267
+ one command (RK150), and reporting the first would say the query is read-only while the
268
+ argument that writes is exposed.
269
+ """
270
+ from roadkeep.serving import TOOLS # noqa: PLC0415 - RK260
271
+
272
+ out: dict[str, tuple[list[str], list[str], list[str], bool, str]] = {}
273
+ for tool in TOOLS:
274
+ names, exposed, always, published, needs = out.setdefault(
275
+ tool.command, ([], [], [], False, tool.needs)
276
+ )
277
+ names.append(tool.name)
278
+ exposed.extend(tool.exposed(config))
279
+ always.extend(tool.always)
280
+ # Published where **any** tool over this command is: the two halves of `brief` are one
281
+ # verb, and a path a project is sent under either name is one it has.
282
+ out[tool.command] = (
283
+ names,
284
+ exposed,
285
+ always,
286
+ published or tool.published(config),
287
+ needs,
288
+ )
289
+ return out
290
+
291
+
292
+ def commands(config: Config, verb: str | None = None) -> Listing:
293
+ """Every verb this build declares, with what this project is served (RK1401).
294
+
295
+ ``verb`` narrows to one path, spelled as the answer spells it (`"section add"`). A name
296
+ this build does not have is refused rather than answered empty, that answer being read as
297
+ evidence that the verb was removed — which is the one conclusion a reader on an older copy
298
+ must not draw.
299
+ """
300
+ from roadkeep import __version__ # noqa: PLC0415 - RK260
301
+ from roadkeep.serving import _parsers # noqa: PLC0415 - RK260
302
+ from roadkeep.verbs.declaring import writes_when # noqa: PLC0415 - RK1171
303
+
304
+ parsers = _parsers()
305
+ if verb is not None and verb not in parsers:
306
+ known = ", ".join(repr(one) for one in sorted(parsers) if " " not in one)
307
+ raise KeyError(
308
+ f"no command {verb!r} in roadkeep {__version__}: this build declares {known} — "
309
+ f"a nested one is spelled as its path, e.g. 'section add'"
310
+ )
311
+ served = _serving(config)
312
+ out: list[Command] = []
313
+ for path, parser in parsers.items():
314
+ if verb is not None and path != verb:
315
+ continue
316
+ names, exposed, always, published, needs = served.get(path, ([], [], [], False, ""))
317
+ # A group reaches no handler, so `reads_only` is absent on it — and absent is what
318
+ # every writing verb also looks like. The two are told apart by the handler, which is
319
+ # the only thing that makes a path runnable.
320
+ runs = parser.get_default("handler") is not None
321
+ out.append(
322
+ Command(
323
+ path=path,
324
+ help=_help_of(parsers, path),
325
+ description=parser.description or "",
326
+ arguments=_arguments(parser, exposed, always),
327
+ writes=runs and not parser.get_default("reads_only"),
328
+ turns_on=writes_when(parser),
329
+ runs=runs,
330
+ tools=tuple(names),
331
+ published=published,
332
+ needs=needs,
333
+ family=_family(parsers, path),
334
+ )
335
+ )
336
+ return Listing(
337
+ commands=tuple(out),
338
+ version=__version__,
339
+ source=None if config.source is None else config.relative(config.source),
340
+ )
341
+
342
+
343
+ def _family(parsers: Mapping[str, argparse.ArgumentParser], path: str) -> str:
344
+ """Which module under `verbs/` declares this command (RK1402).
345
+
346
+ Read off the handler's own module rather than declared beside the parser: `agents.md`
347
+ already says this package is a module per verb family and `build_parser` calls them in
348
+ order, so a second statement here would be that layout restated — and stale the first time
349
+ a verb moves. What comes back is the module's last component, `querying` and not
350
+ `roadkeep.verbs.querying`, because the package path is not a fact a reader of the reference
351
+ needs.
352
+
353
+ A group's family is what its children share. `section` reaches no handler, and taking the
354
+ first child's answer would be a guess where two disagreed — so a split group answers with
355
+ nothing rather than with one of two families, which is the same rule `Key.set` follows
356
+ where several addresses declared a value.
357
+ """
358
+ handler = parsers[path].get_default("handler")
359
+ if handler is not None:
360
+ return getattr(handler, "__module__", "").rpartition(".")[2]
361
+ under = {
362
+ _family(parsers, one)
363
+ for one in parsers
364
+ if one.startswith(f"{path} ") and one.count(" ") == path.count(" ") + 1
365
+ }
366
+ return under.pop() if len(under) == 1 else ""
367
+
368
+
369
+ def _help_of(parsers: Mapping[str, argparse.ArgumentParser], path: str) -> str:
370
+ """The one-line sentence a verb is listed under, which its **parent** holds.
371
+
372
+ argparse keeps `help=` on the subparsers action that created the child and never on the
373
+ child itself, so a verb asked for its own help string answers with nothing. Read back off
374
+ the parent's choices rather than restated here, for this module's whole rule: the sentence
375
+ is the one its author wrote at the `add_parser` call.
376
+ """
377
+ from roadkeep.serving import _root # noqa: PLC0415 - RK260
378
+
379
+ parent, _, leaf = path.rpartition(" ")
380
+ # The root is cached for the life of the process (RK202) and is the same object the index
381
+ # was walked from, so reaching it here is a lookup and not a second build.
382
+ holder = parsers.get(parent) if parent else _root()
383
+ if holder is None:
384
+ return ""
385
+ for action in holder._actions: # noqa: SLF001 - argparse exposes no public reader
386
+ if isinstance(action, argparse._SubParsersAction): # noqa: SLF001
387
+ for choice in action._choices_actions: # noqa: SLF001
388
+ if choice.dest == leaf:
389
+ return choice.help or ""
390
+ return ""
391
+
392
+
393
+ def stated(found: Listing) -> str:
394
+ """The surface as a reader is told it: one block per verb, nested under its group."""
395
+ rows = [
396
+ f"{len(found.commands)} command(s) this build declares",
397
+ f" build roadkeep {found.version} — what is listed is what *this* copy takes, "
398
+ f"which is how a flag it predates is told from a typo",
399
+ ]
400
+ for one in found.commands:
401
+ rows.extend(_block(one))
402
+ return "\n".join(rows)
403
+
404
+
405
+ def _block(one: Command) -> list[str]:
406
+ """One verb as a reader is told it, indented by how deep its path is."""
407
+ pad = " " * one.depth
408
+ kind = "group" if not one.runs else ("writes" if one.writes else "reads")
409
+ rows = [f"{pad}{one.path:<22} {kind:<7} {one.help}"]
410
+ if one.turns_on:
411
+ turns = ", ".join(f"--{dest.replace('_', '-')}" for dest in one.turns_on)
412
+ rows.append(f"{pad} writes when {turns} is given")
413
+ if one.tools:
414
+ # Named, and said as withheld where the project has not declared the role: an absence
415
+ # a reader cannot explain is what sends them to the source (RK1360).
416
+ where = "served" if one.published else f"withheld until `declare {one.needs}`"
417
+ rows.append(f"{pad} {where} as {', '.join(one.tools)}")
418
+ for argument in one.arguments:
419
+ rows.append(f"{pad} {_argument_row(argument)}")
420
+ return rows
421
+
422
+
423
+ def _argument_row(one: Argument) -> str:
424
+ """One argument on one line — what it is spelled, what it takes, and what it costs."""
425
+ spelled = ", ".join(one.spelling)
426
+ value = f" {one.takes}" if one.takes and not one.positional else ""
427
+ notes = []
428
+ if one.required:
429
+ notes.append("required")
430
+ if one.repeatable:
431
+ notes.append("repeatable")
432
+ if one.default is not None and not one.required:
433
+ notes.append(f"default {one.default}")
434
+ if one.choices:
435
+ notes.append("one of " + ", ".join(one.choices))
436
+ if one.always:
437
+ notes.append("always passed by the served tool")
438
+ elif one.exposed:
439
+ notes.append("exposed")
440
+ marked = f"({'; '.join(notes)})" if notes else ""
441
+ head = f"{spelled + value:<34}{marked}".rstrip()
442
+ return f"{head}\n {one.help}".rstrip() if one.help else head
443
+
444
+
445
+ def payload(found: Listing) -> dict[str, object]:
446
+ """The same answer as data — what a reference page and a completion list read."""
447
+ return {
448
+ "version": found.version,
449
+ "source": found.source,
450
+ "commands": [
451
+ {
452
+ "command": one.path,
453
+ # Which module under `verbs/` declares it (RK1402) — what a reference page is
454
+ # one of, so the generator groups by this rather than by a list it keeps.
455
+ "family": one.family,
456
+ "help": one.help,
457
+ "description": one.description,
458
+ "writes": one.writes,
459
+ # The dests that make a read a write (RK167). `[]` and never omitted: a
460
+ # consumer reading a missing key cannot tell "never" from "this build is
461
+ # older than the answer".
462
+ "writes_when": list(one.turns_on),
463
+ "runs": one.runs,
464
+ "tools": list(one.tools),
465
+ "published": one.published,
466
+ "needs": one.needs,
467
+ "arguments": [
468
+ {
469
+ "dest": argument.dest,
470
+ "spelling": list(argument.spelling),
471
+ "primary": argument.primary,
472
+ "positional": argument.positional,
473
+ "takes": argument.takes,
474
+ "repeatable": argument.repeatable,
475
+ "required": argument.required,
476
+ "default": argument.default,
477
+ "choices": list(argument.choices),
478
+ "help": argument.help,
479
+ "exposed": argument.exposed,
480
+ "always": argument.always,
481
+ }
482
+ for argument in one.arguments
483
+ ],
484
+ }
485
+ for one in found.commands
486
+ ],
487
+ }