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/capturing.py ADDED
@@ -0,0 +1,1699 @@
1
+ """The report the losing session can write and the narration afterwards cannot (RK85).
2
+
3
+ Four projects drive this tool through agents, and the defects they find are found in
4
+ sessions that end. What reaches the maintainer is a sentence composed after the fact — in
5
+ exactly the genre this repository exists to distrust, since the 142-word roadmap line was
6
+ the same author writing the same way about a different subject.
7
+
8
+ **The asymmetry is that none of what identifies a defect is prose.** The argv, the exit
9
+ code, the engine that answered, `roadkeep.toml` as it was read and the offending
10
+ `file:line:column` are facts the process already holds. So the failing command is re-run
11
+ under observation and those facts are emitted; the two things a machine cannot supply —
12
+ what does not work, and why it matters — are *arguments*, validated here against this
13
+ repository's own schema. A report that arrives inside the limits was refused in the
14
+ session that made the claim, instead of in a maintainer's review of an issue.
15
+
16
+ Three boundaries this does not cross:
17
+
18
+ * **It is a capture, not a client.** No network in this path, nothing to authenticate, no
19
+ identity. It prints, and stops. Filing is a second command *a person runs* (RK87),
20
+ because auto-filing saves one command and stakes a private repository's contents on a
21
+ process in a state it did not anticipate, where an explicit hand-off stakes nothing. What
22
+ leaves is composed of :data:`PARTS` a reviewer can delete by name in the same terminal —
23
+ a deletion they can verify, not a scrubber promising to recognise a secret it has never
24
+ seen — and `gh issue create -F -` borrows an authentication the operator already made.
25
+ * **It re-runs, in this process.** A subprocess would be a second engine to be wrong about
26
+ — the whole reason RK79 comes first — so the command runs through the same
27
+ :func:`roadkeep.cli.main` this interpreter loaded, and the capture states which tree that
28
+ was. A crash is caught and kept: a traceback is the most identifying fact there is.
29
+
30
+ The price is one class of defect it cannot re-run, and RK341 is the record of that being
31
+ paid: an interpreter's stdio codecs are settled before its first line executes, so a re-run
32
+ here inherits *this* session's and not the field's. RK337 arrived that way — a
33
+ `UnicodeEncodeError` in an adopting project that exited 0 on the re-run, so the stored
34
+ capture blamed a module that opens its file `rb` and encodes nothing. What is recorded
35
+ instead is the :class:`Environment`: the variables that decide how a process reads and
36
+ writes text, and what the interpreter resolved them to. A fact the re-run cannot supply is
37
+ one the report has to carry.
38
+ * **It never writes the claim.** `symptom` and `why` come from the caller, and a capture
39
+ whose claim is over the limit is refused whole (L4). What is rendered for the maintainer
40
+ is the `add` command that files it — a command, not a sentence, and one whose id stays
41
+ derived where the backlog is.
42
+ """
43
+
44
+ from __future__ import annotations
45
+
46
+ import contextlib
47
+ import io
48
+ import json
49
+ import locale
50
+ import os
51
+ import re
52
+ import shlex
53
+ import sys
54
+ import tomllib
55
+ import traceback
56
+ from collections.abc import Mapping, Sequence
57
+ from dataclasses import dataclass, replace
58
+ from datetime import datetime, timezone
59
+ from hashlib import sha256
60
+ from pathlib import Path
61
+
62
+ from roadkeep import __version__
63
+ from roadkeep.config import Config, ConfigError, find_config
64
+ from roadkeep.provenance import STARTUP_CODECS, Engine, engine, invocation
65
+ from roadkeep.kernel.schema import Schema, Task, Violation
66
+
67
+ #: How much of the failing command's output is kept. A capture is read by a person, and a
68
+ #: `lint` over an adopted corpus prints hundreds of findings — the first of which is the
69
+ #: one being reported, and the rest of which is the corpus.
70
+ _MOST_OUTPUT_LINES = 40
71
+
72
+ #: `file:line[:column]`, the address every finding this tool prints leads with (RK15). The
73
+ #: column is optional because half of them have no column to name — a budget is about a
74
+ #: file and a dep is about a line. Matched over the captured output rather than passed in:
75
+ #: the caller reporting the defect is not the caller who knows which line was objected to.
76
+ _WHERE = re.compile(r"^(?P<file>[^\s:][^:]*):(?P<line>\d+)(?::(?P<column>\d+))?", re.MULTILINE)
77
+
78
+ #: The claim is checked against **this** repository's schema and never the reporting
79
+ #: project's: the line is destined for this backlog, so a project with a looser limit would
80
+ #: otherwise export a line the maintainer's own `add` refuses.
81
+ HOME = Schema()
82
+
83
+ #: A placeholder, so the two prose fields can be judged the way a real line is. The id and
84
+ #: the pointer are derived where the line is actually filed, and both are `add`'s to mint —
85
+ #: this exists only to make :meth:`Schema.validate` judge a whole line.
86
+ #:
87
+ #: Spelled by :attr:`HOME` and not written out (RK1000): `RK1` was a literal standing in for
88
+ #: a value the schema declares, so a default prefix or an `[ids] pad` that moved would leave
89
+ #: this judging a whole line against an id that project's own gate refuses.
90
+ _PLACEHOLDER = HOME.spell_id(HOME.prefixes[0], 1)
91
+
92
+ #: The exit code that means *the call was wrong*, which is this CLI's own contract — 0, 1 for
93
+ #: the gate, 2 for usage. Spelled here rather than imported, because `cli` imports this module
94
+ #: and the reverse is a cycle; a test holds the two numbers together (RK440).
95
+ _USAGE = 2
96
+
97
+ #: What a capture says about itself when its re-run never reached the rule being reported
98
+ #: (RK440). Two of Shio's three field reports carried a refusal that fires *before* the verb
99
+ #: does any work — a missing `--why`, an id the ledger already held — and were filed with
100
+ #: `reproduces: true` above output that has nothing to do with the claim.
101
+ #:
102
+ #: An annotation and never a refusal, for two reasons that both come out of this block. RK86
103
+ #: exists to make the capture the cheapest move a losing session has, and a report refused at
104
+ #: the end of that session is the session lost; and a precondition refusal is sometimes exactly
105
+ #: the defect — "it refuses a call that is legal" is a report this tool has no way to tell from
106
+ #: a mistyped argv, having no model to judge the claim against the evidence (L4). So the shape
107
+ #: is stated and the verdict is left to the reader, which is the one division of labour a
108
+ #: capture is built on.
109
+ _STOPPED = (
110
+ "usage — the re-run was refused before the verb ran, so nothing below is evidence "
111
+ "about the symptom unless that refusal is itself the defect"
112
+ )
113
+
114
+ #: The same fact said to the one reader who can still act on it (RK440). The capture carries
115
+ #: the annotation for the maintainer who reads it later; this is for the session that just took
116
+ #: it, which is the only place a mistyped argv can be corrected while the defect is still in
117
+ #: reach. It names the move, as every finding this tool prints does (RK420) — and it is a
118
+ #: notice and not a non-zero exit, because `report` reporting on its own capture is exactly the
119
+ #: second step RK86 measured nobody taking.
120
+ STOPPED_NOTICE = (
121
+ "the re-run exited 2 (usage) and never reached the verb — if that refusal is not the "
122
+ "defect, correct the command after `--` and take the capture again"
123
+ )
124
+
125
+
126
+ @dataclass(frozen=True, slots=True)
127
+ class Failure:
128
+ """What the observed command did, with nothing about it interpreted."""
129
+
130
+ argv: tuple[str, ...]
131
+ exit_code: int
132
+ output: str
133
+ #: Present when the command raised instead of exiting — the single most identifying
134
+ #: fact a capture can carry, and the one a narration never reproduces.
135
+ traceback: str | None = None
136
+
137
+ @property
138
+ def command(self) -> str:
139
+ return shlex.join(("roadkeep", *self.argv))
140
+
141
+ @property
142
+ def where(self) -> str | None:
143
+ """The first `file:line:column` the output named, or ``None``."""
144
+ found = _WHERE.search(self.output)
145
+ return found.group(0) if found else None
146
+
147
+ @property
148
+ def stopped(self) -> bool:
149
+ """Whether the re-run was refused before the verb did any work (RK440).
150
+
151
+ Read off the **exit code** and never off the message. This CLI's contract is 0, 1 for
152
+ a gate finding and 2 for usage, so the one number already separates "the tool applied
153
+ its rule and I disagree" from "the tool never got that far" — where a list of refusal
154
+ sentences to match would be a second declaration of that contract, drifting one
155
+ reworded message at a time, and would miss precisely the two Shio filed: neither came
156
+ from argparse, and both exited 2.
157
+ """
158
+ return self.exit_code == _USAGE
159
+
160
+
161
+ #: The parts of a capture that carry the *reporting* project rather than the defect, each
162
+ #: droppable by name (RK87). Deletion and not filtering: a redaction a reviewer performs by
163
+ #: naming a section is one they can verify by reading the output, where a scrubber that
164
+ #: promises to find secrets is a promise nobody can check against a repository it never saw.
165
+ #: `symptom`, `why`, `block` and the exit code are never droppable — without them there is
166
+ #: no claim, and an empty report is worse than no report.
167
+ PARTS = (
168
+ "command",
169
+ "engine",
170
+ "where",
171
+ "config",
172
+ "source",
173
+ "document",
174
+ "output",
175
+ "traceback",
176
+ "environment",
177
+ )
178
+
179
+ #: The variables a capture records, and the only reason it records any (RK341). Every one of
180
+ #: them decides how a *process* reads and writes text, which is a class of defect whose entire
181
+ #: cause sits outside the repository: RK337 was a `UnicodeEncodeError` in the field that exited
182
+ #: 0 on the re-run, so the stored capture blamed a module that opens its file `rb` and encodes
183
+ #: nothing, and the diagnosis had to be re-derived by reading rather than replayed.
184
+ #:
185
+ #: An allow-list, and short. `os.environ` is a disclosure — tokens, hostnames, paths, the
186
+ #: things RK87 exists to keep out of a tracker — and the answer RK87 gives to a disclosure is a
187
+ #: reviewer who can read what leaves before it goes. A dump nobody can read is not that.
188
+ TEXT_VARIABLES = (
189
+ "PYTHONIOENCODING",
190
+ "PYTHONUTF8",
191
+ "PYTHONLEGACYWINDOWSSTDIO",
192
+ "LC_ALL",
193
+ "LC_CTYPE",
194
+ "LANG",
195
+ )
196
+
197
+ #: What a replay cannot be staged without (RK88). The tension RK87 leaves behind, named
198
+ #: rather than resolved: a capture that embeds nothing is safe and inert, and one that can
199
+ #: be re-run somewhere else is one that carried a file out of a repository. So the
200
+ #: embedding is opt-in, and a capture that was never asked for it says which part is
201
+ #: missing instead of failing halfway through a staging.
202
+ #:
203
+ #: `document` is not here because it is not always input: a defect in reading
204
+ #: `roadkeep.toml` has no governed file in it at all, and demanding one would make the
205
+ #: cheapest class of field report the one class that cannot be replayed. It is required
206
+ #: exactly when the failure named a file — see :attr:`Capture.missing`. What it then requires
207
+ #: is *the declared files*, not one of them (RK344): a staging short of what the command reads
208
+ #: is refused by :func:`_unstaged`, so carrying only the file a finding named satisfied this
209
+ #: check and failed the next one.
210
+ REPLAYABLE = ("command", "config")
211
+
212
+
213
+ @dataclass(frozen=True, slots=True)
214
+ class Environment:
215
+ """How the reporting process reads and writes text — what was asked for, and what happened.
216
+
217
+ The split is the whole value. `declared` is the request, and it is what a maintainer can
218
+ hand to somebody else to reproduce with; the rest is what the interpreter resolved, which
219
+ is the fact and is not always the request — `PYTHONUTF8=1` and `-X utf8` arrive at the same
220
+ place, `PYTHONIOENCODING` can name a codec the platform does not have, and a variable set
221
+ after the process started changes nothing at all.
222
+
223
+ `streams` is read at import (see :data:`roadkeep.provenance.STARTUP_CODECS`) and is the one
224
+ entry here that has to be taken at a moment rather than asked for: everything else is still
225
+ true when the capture is composed, and that one is gone by then.
226
+ """
227
+
228
+ #: The variables of :data:`TEXT_VARIABLES` this process actually has, in that order. Absent
229
+ #: ones are absent rather than empty: "not set" and "set to nothing" are different states,
230
+ #: and on Windows the second is how a variable is deleted.
231
+ declared: tuple[tuple[str, str], ...] = ()
232
+ #: `sys.flags.utf8_mode`, which is where `PYTHONUTF8` and `-X utf8` both end up.
233
+ utf8_mode: bool = False
234
+ #: `locale.getpreferredencoding(False)` — cp1252 on the machines this tool was written on,
235
+ #: and the default every un-hardened `open()` in a project takes.
236
+ locale: str = ""
237
+ #: `sys.getfilesystemencoding()`, which is what turns a filename into a `str` — and, with
238
+ #: `surrogateescape`, what puts a lone surrogate into one.
239
+ filesystem: str = ""
240
+ #: `name -> encoding/errors` for the three streams, as `main` found them.
241
+ streams: tuple[tuple[str, str], ...] = ()
242
+
243
+ def __str__(self) -> str:
244
+ rows = [
245
+ *((name, value) for name, value in self.declared),
246
+ ("utf8 mode", "on" if self.utf8_mode else "off"),
247
+ ("locale", self.locale),
248
+ ("filesystem", self.filesystem),
249
+ *((name, codec) for name, codec in self.streams),
250
+ ]
251
+ width = max(len(name) for name, _ in rows)
252
+ return "\n".join(f" {name:<{width}} {value}" for name, value in rows)
253
+
254
+ def as_dict(self) -> dict[str, object]:
255
+ return {
256
+ "declared": dict(self.declared),
257
+ "utf8_mode": self.utf8_mode,
258
+ "locale": self.locale,
259
+ "filesystem": self.filesystem,
260
+ "streams": dict(self.streams),
261
+ }
262
+
263
+ @property
264
+ def facts(self) -> dict[str, str]:
265
+ """One flat mapping, which is what a comparison needs (see :func:`_drifted`).
266
+
267
+ The three streams collapse to one entry called `stdio`: they are reconfigured together
268
+ by one caller, and reporting three names for one cause is three lines a reader has to
269
+ recombine.
270
+ """
271
+ return {
272
+ **dict(self.declared),
273
+ "utf8 mode": "on" if self.utf8_mode else "off",
274
+ "locale": self.locale,
275
+ "filesystem": self.filesystem,
276
+ "stdio": ", ".join(f"{name}={codec}" for name, codec in self.streams),
277
+ }
278
+
279
+
280
+ def environment() -> Environment:
281
+ """This process's text handling, read now — except the streams, read at import."""
282
+ return Environment(
283
+ declared=tuple((name, os.environ[name]) for name in TEXT_VARIABLES if name in os.environ),
284
+ utf8_mode=bool(sys.flags.utf8_mode),
285
+ locale=locale.getpreferredencoding(False),
286
+ filesystem=sys.getfilesystemencoding(),
287
+ streams=STARTUP_CODECS,
288
+ )
289
+
290
+
291
+ def _read(recorded: object) -> Environment | None:
292
+ """One stored capture's `environment` back as the class, or `None` where it has none.
293
+
294
+ Forgiving by design: this reads corpus files written by older versions of this tool, and a
295
+ capture that predates the field is a capture with no environment rather than a broken one.
296
+ """
297
+ if not isinstance(recorded, Mapping):
298
+ return None
299
+ declared = recorded.get("declared")
300
+ streams = recorded.get("streams")
301
+ return Environment(
302
+ declared=tuple(declared.items()) if isinstance(declared, Mapping) else (),
303
+ utf8_mode=bool(recorded.get("utf8_mode")),
304
+ locale=str(recorded.get("locale", "")),
305
+ filesystem=str(recorded.get("filesystem", "")),
306
+ streams=tuple(streams.items()) if isinstance(streams, Mapping) else (),
307
+ )
308
+
309
+
310
+ def _drifted(recorded: object) -> tuple[str, ...]:
311
+ """Which of a capture's recorded text-handling facts this process does not share.
312
+
313
+ Named rather than counted, and one-directional: a variable the capture recorded and this
314
+ process does not have has drifted, and one *this* process adds is not the capture's
315
+ business — a replay is asked whether the recorded conditions still hold, not whether the
316
+ two machines are the same machine.
317
+ """
318
+ stored = _read(recorded)
319
+ if stored is None:
320
+ return ()
321
+ here = environment().facts
322
+ return tuple(name for name, value in stored.facts.items() if here.get(name, "") != value)
323
+
324
+
325
+ #: A version inside the engine line a capture stamps — `roadkeep 0.1.645 (3153c8…`. Read
326
+ #: out of the string rather than stored beside it, because every capture ever taken carries
327
+ #: this field and a second one would reach only the reports filed after it (RK443's rule).
328
+ _STAMPED = re.compile(r"^roadkeep (?P<version>\d+(?:\.\d+)*)")
329
+
330
+
331
+ def _aged(recorded: object) -> str:
332
+ """How far the engine that took this capture is behind the one replaying it (RK1078).
333
+
334
+ The cheap fact already in the payload, and the one triage was paying a session for. Four
335
+ captures arrived from one Shio session against plugin 0.1.645 while the checkout stood at
336
+ 0.1.676, and **three of the four named work that was already shipped** — an id occupancy
337
+ check (RK1051, 0.1.648), a wrapped-entry correction (RK1049, 0.1.646) and a refusal's
338
+ second clause (RK1057). The reporter was right every time about what they saw; the engine
339
+ they saw it with was the stale copy the marketplace had not refreshed.
340
+
341
+ A sentence and not a boolean, for :attr:`Replay.drifted`'s reason: this qualifies a
342
+ verdict rather than being one. A capture that does not reproduce *and* was taken thirty
343
+ patch versions back is a closed report, and one that does not reproduce against the same
344
+ version is a defect that went away for some other reason — two different next steps, and
345
+ the difference is a string comparison this reader can make for nothing.
346
+
347
+ `""` where there is nothing to compare: no engine recorded, an unparseable stamp, or the
348
+ same version. Never a guess about which is newer than which beyond the ordering the
349
+ numbers give — a commit is stamped too and this deliberately does not read it, two
350
+ checkouts at one version being a question `engines` answers and this one cannot.
351
+ """
352
+ stamp = _STAMPED.match(str(recorded or ""))
353
+ if stamp is None:
354
+ return ""
355
+ taken = tuple(int(part) for part in stamp.group("version").split("."))
356
+ here = tuple(int(part) for part in __version__.split("."))
357
+ if taken >= here:
358
+ return ""
359
+ return (
360
+ f"taken on {stamp.group('version')} and replayed on {__version__}: work shipped "
361
+ f"between them is work this capture could not have seen"
362
+ )
363
+
364
+
365
+ @dataclass(frozen=True, slots=True)
366
+ class Capture:
367
+ """One defect, as the session that hit it can state it."""
368
+
369
+ #: The caller's, never composed here (L4), and refused before this exists.
370
+ symptom: str
371
+ why: str
372
+ block: str
373
+ failure: Failure
374
+ #: Which tree answered (RK79). Without it a stale plugin cache and a real defect are
375
+ #: the same report, and the maintainer pays the difference.
376
+ engine: Engine
377
+ #: The reporting project's configuration, as it was read. A limit that is wrong is a
378
+ #: defect whose evidence is this file.
379
+ config: str | None = None
380
+ config_path: str | None = None
381
+ #: The input line the engine objected to, verbatim, and where it lives.
382
+ source: str | None = None
383
+ #: Where this capture was aimed: the repository a defect in **roadkeep** is filed against,
384
+ #: from `--to` or `[report] upstream` (RK1161). In the artefact for RK89's reason — a capture
385
+ #: is evidence, and where it was sent is part of it — and read back by `capture filed`, so the
386
+ #: stamp that records delivery elsewhere does not ask for a repository the config declares.
387
+ #:
388
+ #: `None` where the reporting project declared none, which keeps the refusal that reading
389
+ #: replaces: a bare id no governed file holds is still a link to nothing.
390
+ upstream: str | None = None
391
+ #: `path -> contents` for the governed files, embedded only when the caller asked (RK88):
392
+ #: they are the input half of a test, and they are also files leaving a repository.
393
+ #:
394
+ #: Every file the config **declares**, and not the one the finding named (RK344). One file
395
+ #: was the smaller disclosure and it stopped being a staging: `lint` — the command the fault
396
+ #: offer suggests most — reads all of them, so a capture of it from an ordinary three-file
397
+ #: project stages two files short and is refused. The governed documents are also the least
398
+ #: sensitive files a project has, being the ones this tool exists to write. Never anything
399
+ #: else in the repository, and still never without `--embed`.
400
+ documents: tuple[tuple[str, str], ...] = ()
401
+ #: How the reporting process reads and writes text (RK341) — the half of the input that is
402
+ #: not in the repository and that a re-run in this interpreter silently supplies from
403
+ #: wherever it happens to be running.
404
+ environment: Environment | None = None
405
+ #: Parts the operator deleted before this went anywhere (RK87). Held rather than
406
+ #: applied to the data, so one capture can be read whole in the terminal and emitted
407
+ #: redacted — and *named* in the output, because a report missing a section without
408
+ #: saying so is one a maintainer reads as a section that was empty.
409
+ hidden: frozenset[str] = frozenset()
410
+
411
+ def without(self, *parts: str) -> Capture:
412
+ """The same capture with those parts omitted from everything it renders."""
413
+ unknown = [part for part in parts if part not in PARTS]
414
+ if unknown:
415
+ raise ValueError(
416
+ f"no such part of a capture: {', '.join(unknown)} — "
417
+ f"the parts are {', '.join(PARTS)}"
418
+ )
419
+ return replace(self, hidden=self.hidden | frozenset(parts))
420
+
421
+ def shows(self, part: str) -> bool:
422
+ return part not in self.hidden
423
+
424
+ @property
425
+ def title(self) -> str:
426
+ """What a tracker would put in its subject line: the claim, already inside 120."""
427
+ return self.symptom
428
+
429
+ @property
430
+ def filing(self) -> str:
431
+ """The command that files this in the maintainer's backlog, id left derived."""
432
+ return shlex.join(
433
+ [
434
+ *shlex.split(invocation()),
435
+ "add",
436
+ "--block",
437
+ self.block,
438
+ "--symptom",
439
+ self.symptom,
440
+ "--why",
441
+ self.why,
442
+ ]
443
+ )
444
+
445
+ def _head(self) -> list[str]:
446
+ """The labelled facts, in the order a reader needs them to decide what this is."""
447
+ fields = [
448
+ ("command", self.failure.command if self.shows("command") else None),
449
+ ("exit", str(self.failure.exit_code)),
450
+ # Beside the exit code it is derived from, and above the evidence it qualifies
451
+ # (RK440): a reader who meets this after the output has already read the output
452
+ # as the thing the symptom claims.
453
+ ("stopped", _STOPPED if self.failure.stopped else None),
454
+ ("engine", str(self.engine) if self.shows("engine") else None),
455
+ ("where", self.failure.where if self.shows("where") else None),
456
+ ("config", self.config_path if self.shows("config") else None),
457
+ # Named, because a capture that quietly drops a section is one a maintainer
458
+ # reads as evidence that did not exist.
459
+ ("omitted", ", ".join(sorted(self.hidden)) if self.hidden else None),
460
+ ]
461
+ return [f" {label:<8} {value}" for label, value in fields if value]
462
+
463
+ def _blocks(self) -> list[str]:
464
+ """The verbatim evidence, each under a heading that says what it is."""
465
+ parts = [
466
+ ("source", "the line it objected to", self.source),
467
+ ("traceback", "traceback", self.failure.traceback),
468
+ ("output", "output", self.failure.output.rstrip() or "(nothing)"),
469
+ ("config", "roadkeep.toml as it was read", self.config),
470
+ *(("document", f"{path} as it was read", text) for path, text in self.documents),
471
+ (
472
+ "environment",
473
+ "how this process reads and writes text",
474
+ str(self.environment) if self.environment is not None else None,
475
+ ),
476
+ ]
477
+ lines: list[str] = []
478
+ for part, title, text in parts:
479
+ if self.shows(part) and text is not None:
480
+ lines += ["", f"--- {title} ---", text.rstrip()]
481
+ return lines
482
+
483
+ def __str__(self) -> str:
484
+ return "\n".join(
485
+ [
486
+ # The program name and the verb no longer sit together here (RK1142): `filed`
487
+ # made that pair a command, and a title shaped like one is a line a reader may
488
+ # type. `test_no_message_spells_an_invocation_it_did_not_derive` is what
489
+ # noticed — it holds every literal invocation to being derived — and this was
490
+ # never an invocation at all, so the fix is the wording and not a derivation.
491
+ "A roadkeep field report — what the session that hit this knew, before it ended",
492
+ "",
493
+ f" symptom {self.symptom}",
494
+ f" why {self.why}",
495
+ f" block {self.block}",
496
+ "",
497
+ *self._head(),
498
+ *self._blocks(),
499
+ "",
500
+ "File it:",
501
+ f" {self.filing}",
502
+ ]
503
+ )
504
+
505
+ @property
506
+ def missing(self) -> tuple[str, ...]:
507
+ """The parts a replay would need and does not have (RK88)."""
508
+ held = {
509
+ "command": bool(self.failure.argv),
510
+ "config": self.config is not None,
511
+ "document": bool(self.documents),
512
+ }
513
+ needed = list(REPLAYABLE)
514
+ if self.shows("where") and self.failure.where:
515
+ # The failure named a file, so that file is half the input.
516
+ needed.append("document")
517
+ return tuple(part for part in needed if not (self.shows(part) and held[part]))
518
+
519
+ @property
520
+ def replayable(self) -> bool:
521
+ return not self.missing
522
+
523
+ def as_dict(self) -> dict[str, object]:
524
+ """The capture as a corpus file holds it — redaction applied, not recorded around.
525
+
526
+ A dropped part is absent here exactly as it is absent from the printed text: one
527
+ artefact, one set of contents, so what a reviewer approved is what gets stored and
528
+ replayed. `reproduces` is this repository's standing expectation, and the only
529
+ field a *reader* of the capture writes: flipping it is how a fix is recorded.
530
+ """
531
+ data: dict[str, object] = {
532
+ "symptom": self.symptom,
533
+ "why": self.why,
534
+ "block": self.block,
535
+ "exit": self.failure.exit_code,
536
+ "reproduces": True,
537
+ }
538
+ # Written only when it is true (RK440), so every capture already on disk reads back
539
+ # unchanged. It sits beside `reproduces` and does not touch it: the argv *does*
540
+ # reproduce — the same command earns the same refusal, which is what `replay` asserts
541
+ # — and what is in doubt is whether that refusal is the symptom above it.
542
+ if self.failure.stopped:
543
+ data["stopped"] = "usage"
544
+ # One row per key, so the two rules — the part is shown, and there is something to
545
+ # store — are stated once instead of at every field. `document` is two rows because it
546
+ # is two keys and one decision: a path without the file it names is not evidence.
547
+ rows: tuple[tuple[str, str, object], ...] = (
548
+ ("command", "argv", list(self.failure.argv)),
549
+ ("engine", "engine", str(self.engine)),
550
+ ("where", "where", self.failure.where),
551
+ ("output", "output", self.failure.output),
552
+ ("traceback", "traceback", self.failure.traceback),
553
+ ("config", "config", self.config),
554
+ ("source", "source", self.source),
555
+ # Not a redactable part of its own: it is this project's own configuration value and
556
+ # the tracker body already names it, so `config` is the part that governs it.
557
+ ("config", "upstream", self.upstream),
558
+ # `path -> contents`, so a capture that carries three files is three entries and
559
+ # not three parallel lists a reader has to zip back together.
560
+ ("document", "documents", dict(self.documents) or None),
561
+ (
562
+ "environment",
563
+ "environment",
564
+ self.environment.as_dict() if self.environment is not None else None,
565
+ ),
566
+ )
567
+ for part, key, value in rows:
568
+ if self.shows(part) and value is not None:
569
+ data[key] = value
570
+ if self.hidden:
571
+ data["omitted"] = sorted(self.hidden)
572
+ return data
573
+
574
+
575
+ #: What every failure ends with (RK86). Conditional and never an admission: this tool has
576
+ #: no way to know whether the rule it just applied was the right one, and no model to guess
577
+ #: (L4). What it can do is make the capture the cheapest next move instead of the invisible
578
+ #: one — an agent that meets a wrong limit otherwise has exactly one option left, which is
579
+ #: to work around the tool quietly, and that loses the sessions with the most to say.
580
+ _OFFER = "If roadkeep itself is what is wrong here, capture it before the session ends:"
581
+
582
+
583
+ def offer(argv: Sequence[str]) -> str:
584
+ """The two lines a fault closes with: the sentence, and the command to run.
585
+
586
+ The failing argv is already substituted, because the move has to cost nothing to take.
587
+ The two prose fields stay as ellipses — they are the caller's, and this composes no
588
+ part of a claim.
589
+
590
+ *Which* failures close with it is `cli._may_offer`'s and never this function's: a verdict a
591
+ read was asked for is not one (RK271), and the caller is the only place that knows whether
592
+ the exit code it is holding is an answer or a fall.
593
+ """
594
+ if _transient(argv):
595
+ return "\n".join([_OFFER, f" {_MERGE_OFFER}"])
596
+ return "\n".join(
597
+ [
598
+ _OFFER,
599
+ f' {invocation()} report --symptom "…" --why "…" -- {shlex.join(argv)}',
600
+ ]
601
+ )
602
+
603
+
604
+ #: git's own name for the files it hands a merge driver. Matched rather than assumed from the
605
+ #: verb, because `merge` run by hand takes three real paths and the offer is good there.
606
+ _TEMPORARY = ".merge_file_"
607
+
608
+ #: What the offer says where the argv cannot be re-run (RK484). Not a command, because there
609
+ #: is none: the three inputs are gone, and printing one that fails is the defect being fixed.
610
+ #: What is durable is the merge — git holds both commits — so that is what is asked for.
611
+ _MERGE_OFFER = (
612
+ "the three inputs were git's own temporary files and are already deleted, so there is "
613
+ "no argv to re-run: file it with the two revisions instead — `git rev-parse HEAD "
614
+ "MERGE_HEAD` names them, and both are in this repository"
615
+ )
616
+
617
+
618
+ def _transient(argv: Sequence[str]) -> bool:
619
+ """Whether this argv names files that will not exist by the time anybody reads it.
620
+
621
+ Measured end to end: a real `git merge` reaching the driver closed with `report … --
622
+ merge .merge_file_tbx68e …`, and the three files were gone before the line finished
623
+ printing. The one verb where RK86's offer is worth most is the one where it was never
624
+ takeable.
625
+ """
626
+ return argv[:1] == ["merge"] and any(one.startswith(_TEMPORARY) for one in argv)
627
+
628
+
629
+ def body(found: Capture) -> str:
630
+ """The capture as a tracker takes it: the same text, fenced so nothing is re-rendered.
631
+
632
+ Byte-for-byte what the terminal showed, because that is the whole claim RK87 makes —
633
+ a reviewer approves what they read, and a body composed differently from the preview
634
+ is a body nobody reviewed.
635
+ """
636
+ return "\n".join(["```", str(found), "```"])
637
+
638
+
639
+ def handoff(found: Capture, upstream: str) -> str:
640
+ """The command *somebody else* runs to file it. Never run here (L2, and RK87).
641
+
642
+ `gh` borrows an authentication the operator already made, on a machine that already
643
+ trusts it. The alternative is this tool holding a token — a credential, a config key
644
+ to leak it through, and a socket in a package whose whole promise is that the store is
645
+ the repository and nothing talks to anything.
646
+ """
647
+ return "\n".join(
648
+ [
649
+ "Nothing was sent. To file it, after reading what is above:",
650
+ f" {invocation()} report … --issue | gh issue create -R {upstream} "
651
+ f"-t {shlex.quote(found.title)} -F -",
652
+ ]
653
+ )
654
+
655
+
656
+ def check(symptom: str, why: str, block: str) -> tuple[Violation, ...]:
657
+ """Judge the claim against this repository's schema, before anything is run."""
658
+ task = Task(
659
+ id=_PLACEHOLDER,
660
+ status=HOME.markers[0],
661
+ block=block,
662
+ symptom=symptom,
663
+ why=why,
664
+ ref=_PLACEHOLDER,
665
+ )
666
+ return HOME.validate(task)
667
+
668
+
669
+ def observe(argv: Sequence[str]) -> Failure:
670
+ """Re-run one roadkeep command in this process and keep everything it did.
671
+
672
+ Both streams into one buffer, in the order they were written: a capture that separates
673
+ them loses which finding preceded the traceback, and that order is the diagnosis.
674
+ """
675
+ from roadkeep.cli import main # here, because the CLI is what builds a capture
676
+
677
+ buffer = io.StringIO()
678
+ trace: str | None = None
679
+ code = 0
680
+ with contextlib.redirect_stdout(buffer), contextlib.redirect_stderr(buffer):
681
+ try:
682
+ code = main(list(argv))
683
+ except SystemExit as exit_: # argparse's own refusals leave this way
684
+ code = exit_.code if isinstance(exit_.code, int) else 2
685
+ except Exception:
686
+ # A crash *is* the report. `Exception` and not `BaseException`: an interrupt is
687
+ # the user asking for the session back, and a capture is not worth taking it.
688
+ trace = traceback.format_exc()
689
+ code = 1
690
+ return Failure(
691
+ argv=tuple(argv), exit_code=code, output=_tail(buffer.getvalue()), traceback=trace
692
+ )
693
+
694
+
695
+ def capture(
696
+ symptom: str,
697
+ why: str,
698
+ block: str,
699
+ argv: Sequence[str],
700
+ root: str | Path = ".",
701
+ embed: bool = False,
702
+ upstream: str | None = None,
703
+ ) -> Capture:
704
+ """Run the failing command and compose the report. The claim is already validated.
705
+
706
+ ``embed`` carries the governed files, which is what makes the capture a test somewhere
707
+ else (RK88) and also what makes them files leaving a repository (RK87) — so it is asked
708
+ for, never assumed.
709
+ """
710
+ failure = observe(argv)
711
+ config_path, config = _configuration(root)
712
+ return Capture(
713
+ symptom=symptom,
714
+ why=why,
715
+ block=block,
716
+ failure=failure,
717
+ engine=engine(),
718
+ config=config,
719
+ config_path=config_path,
720
+ source=_source(failure.where, root),
721
+ documents=_documents(root) if embed else (),
722
+ environment=environment(),
723
+ upstream=upstream,
724
+ )
725
+
726
+
727
+ @dataclass(frozen=True, slots=True)
728
+ class Replay:
729
+ """One capture re-run against the tree that is here now (RK88).
730
+
731
+ The question a field report cannot otherwise answer. *Reproduces* is the recorded exit
732
+ code and the recorded address both turning up again — not an output comparison, because
733
+ a message this repository improved is not a defect that came back.
734
+ """
735
+
736
+ reproduces: bool
737
+ recorded_exit: int
738
+ exit_code: int
739
+ output: str
740
+ #: Non-empty when nothing was run: the capture was never made replayable, and saying so
741
+ #: is the whole answer. A staging that guessed at the missing half would be a test whose
742
+ #: input this repository invented, which is the thing RK88 exists to avoid.
743
+ missing: tuple[str, ...] = ()
744
+ #: Governed files the staged config declares that the capture did not carry (RK343). A
745
+ #: second reason not to run, and a different one: :attr:`missing` is a *part* the capture
746
+ #: lacks, and this is a file the project had and the capture never held a copy of.
747
+ unstaged: tuple[str, ...] = ()
748
+ #: Which of the capture's recorded text-handling facts this process does not share (RK341),
749
+ #: and `None` where it recorded none to compare. Not a verdict of its own: it is the reason
750
+ #: a verdict may be about a different machine than the one the defect was on.
751
+ drifted: tuple[str, ...] | None = None
752
+ #: How far behind the engine that took the capture is, or `""` where there is nothing to
753
+ #: compare (RK1078). The fourth reason a verdict may be about something other than the
754
+ #: symptom, and the one that decides whether a report is closed rather than live.
755
+ aged: str = ""
756
+ #: Whether the capture's own re-run was refused before the verb ran (RK440), read back
757
+ #: here so the reader who *triages* gets the annotation and not only the one who took it
758
+ #: (RK443). The third reason not to trust a verdict, and the third to be stated beside
759
+ #: the sentence rather than folded into :attr:`reproduces`: this one reproduces by
760
+ #: construction — the same argv earns the same refusal every time — so the boolean is
761
+ #: right and what it is about is the refusal rather than the symptom above it.
762
+ #:
763
+ #: Derived from the recorded `exit` and never from a stored field, which is what makes it
764
+ #: reach the two captures Shio filed before RK440 existed — the whole population this is
765
+ #: about. The corpus gate is deliberately **not** wired to it: refusing such an entry
766
+ #: would fail this repository's own suite on captures that are honest records of a
767
+ #: mistyped argv, and which of the two a capture is takes meaning this tool has none of.
768
+ stopped: bool = False
769
+
770
+ @property
771
+ def ran(self) -> bool:
772
+ return not (self.missing or self.unstaged)
773
+
774
+ def __str__(self) -> str:
775
+ if self.missing:
776
+ return f"not replayable: the capture has no {', '.join(self.missing)}"
777
+ if self.unstaged:
778
+ # Said differently from the above on purpose: the capture is not incomplete, the
779
+ # *staging* is — and what to do about it is to take the capture again, not to stop
780
+ # redacting it.
781
+ # Naming the flag to a reader who cannot pass it (RK481): they hold a finished
782
+ # capture and the session that took it is gone, so the door is *asking* rather
783
+ # than running — which is a thing this reader can actually do, and the reason
784
+ # RK313 gives for closing on something rather than on the fact alone. The
785
+ # instruction lives where it can be followed: `report` says it as it writes.
786
+ return (
787
+ f"not replayable: the config declares {', '.join(self.unstaged)}, "
788
+ f"which the capture does not carry — ask for one taken with `--embed`"
789
+ )
790
+ verdict = "still reproduces" if self.reproduces else "no longer reproduces"
791
+ said = f"{verdict}: recorded exit {self.recorded_exit}, now {self.exit_code}"
792
+ # First of the three, and the only one that qualifies what the verdict is *about*
793
+ # rather than what it was reached under (RK443). Said on both verdicts, because a
794
+ # capture that stopped at a usage refusal is one whose evidence never reached the
795
+ # rule either way — and said first, since a reader who meets it after the caveat
796
+ # about environments has already read the sentence as being about the symptom.
797
+ if self.stopped:
798
+ return (
799
+ f"{said} — the capture's own re-run was refused before the verb ran, so "
800
+ f"this repeats that refusal and not the symptom it was filed under"
801
+ )
802
+ # A *negative* verdict is an inference from an absence, and an unstaged environment is
803
+ # another absence — so the two are said together or the first reads as a fix (RK341).
804
+ # A positive one needs no caveat: the run just demonstrated it.
805
+ if self.drifted:
806
+ return f"{said}, under a different {', '.join(self.drifted)} than the capture recorded"
807
+ # Before the environment clause and only where the verdict is negative: a capture
808
+ # that still reproduces is live whatever version took it, and one that does not is
809
+ # the case triage was reading the package to decide (RK1078).
810
+ if self.aged and not self.reproduces:
811
+ return f"{said} — {self.aged}"
812
+ if self.drifted is None and not self.reproduces:
813
+ return f"{said}, and the capture records no environment to have staged"
814
+ return said
815
+
816
+
817
+ def agrees(self, expected: bool) -> bool:
818
+ """Whether this run said what the capture recorded (RK89).
819
+
820
+ `expected` is the capture's own `reproduces`, which is a fact about the file and not
821
+ about the run — so it is a parameter, and the verdict below is what the two together
822
+ mean rather than something either half holds.
823
+ """
824
+ return self.ran and self.reproduces == expected
825
+
826
+ def stated(self, where: str, expected: bool) -> str:
827
+ rows = [f"{where} {self}"]
828
+ if self.ran and not self.agrees(expected):
829
+ # The whole point of the corpus: a verdict that moved is either a fix to record or
830
+ # a regression to answer, and both want the file updated in the same commit.
831
+ rows.append(
832
+ f" recorded reproduces = {str(expected).lower()}: "
833
+ f"update the capture, or the tree stopped agreeing with it"
834
+ )
835
+ return chr(10).join(rows)
836
+
837
+ def payload(self, where: str, expected: bool) -> dict[str, object]:
838
+ return {
839
+ "path": where,
840
+ "ran": self.ran,
841
+ "missing": list(self.missing),
842
+ # A second reason not to run, kept apart from the first (RK343): a part the capture
843
+ # lacks is a redaction, and a file it never carried is a capture to take again.
844
+ "unstaged": list(self.unstaged),
845
+ "reproduces": self.reproduces,
846
+ "expected": expected,
847
+ "recorded_exit": self.recorded_exit,
848
+ "exit": self.exit_code,
849
+ # `null` and not `[]` where the capture recorded no environment (RK341): "nothing
850
+ # drifted" and "nothing to compare" are different answers, and a reader that cannot
851
+ # tell them apart is the defect this closes.
852
+ "drifted": None if self.drifted is None else list(self.drifted),
853
+ # The third reason not to trust the verdict (RK443), beside the other two and never
854
+ # folded into `reproduces` — this one reproduces by construction, and what it is
855
+ # about is the refusal rather than the symptom the capture was filed under.
856
+ "stopped": self.stopped,
857
+ # The fourth (RK1078), and the one that decides whether a report is closed rather
858
+ # than live: an empty string is "nothing to compare", which is a different answer
859
+ # from "the same version".
860
+ "aged": self.aged,
861
+ }
862
+
863
+
864
+ def replay(recorded: Mapping[str, object], workdir: str | Path) -> Replay:
865
+ """Stage the capture's own inputs in ``workdir`` and run its argv against them.
866
+
867
+ The reporter's repository is never needed and never reached: what is written is the
868
+ `roadkeep.toml` and the one file the capture carries, and the `-C` in the recorded argv
869
+ is repointed at the staging. Everything else in that argv is passed through untouched —
870
+ a replay that rewrote the flags would be testing a command nobody ran.
871
+
872
+ And a staging that is not the project answers nothing (RK343). Measured on `list --block Z`:
873
+ exit 2 recorded and exit 2 replayed, where the second 2 was `No such file or directory` and
874
+ the verdict was `still reproduces`. Every declared file is checked for before the run,
875
+ because after it the exit code has already collapsed the two causes into one number — and
876
+ what closed the gap on the other side is `--embed` carrying all of them (RK344).
877
+
878
+ What this **cannot** stage is the environment (RK341), and the reason is two boundaries
879
+ this deliberately keeps. :func:`observe` runs the argv through the `main` this interpreter
880
+ already loaded, because a subprocess would be a second engine to be wrong about (RK79) —
881
+ and an interpreter's stdio codecs are settled before its first line runs, so no assignment
882
+ here reaches them. It then redirects both streams into a `StringIO`, which has no codec at
883
+ all, so the encoding path is not even on the route a replay takes. Hence the *comparison*:
884
+ the recorded facts are held against this process's, and a verdict reached under different
885
+ ones says so rather than reading as a fix.
886
+ """
887
+ carried = _carried(recorded)
888
+ held = {"command": recorded.get("argv"), "config": recorded.get("config"), "document": carried}
889
+ needed = list(REPLAYABLE) + (["document"] if recorded.get("where") else [])
890
+ missing = tuple(part for part in needed if not held[part])
891
+ recorded_exit = int(recorded.get("exit", 0) or 0)
892
+ stored = recorded.get("environment")
893
+ drifted = _drifted(stored) if stored is not None else None
894
+ # From the engine line every capture stamps (RK1078), so this reaches every report ever
895
+ # filed rather than only the ones taken after the field existed.
896
+ aged = _aged(recorded.get("engine"))
897
+ # From the recorded exit code and never from a stored field (RK443), which is what makes
898
+ # this reach the reports filed before RK440 wrote one: every capture ever taken carries
899
+ # `exit`, and 2 is this CLI's own word for "the call was wrong".
900
+ stopped = recorded_exit == _USAGE
901
+ if missing:
902
+ # Keyword arguments from here down: four optional fields in one constructor is where a
903
+ # positional call starts assigning one reason to another's slot.
904
+ return Replay(
905
+ False, recorded_exit, 0, "", missing=missing, drifted=drifted,
906
+ stopped=stopped, aged=aged
907
+ )
908
+
909
+ root = Path(workdir)
910
+ (root / "roadkeep.toml").write_text(str(recorded["config"]), encoding="utf-8")
911
+ for name, text in carried.items():
912
+ document = root / name
913
+ document.parent.mkdir(parents=True, exist_ok=True)
914
+ # `newline=""`: the round-trip invariant is about bytes, and a translated line
915
+ # ending is a different file from the one that failed.
916
+ with document.open("w", encoding="utf-8", newline="") as handle:
917
+ handle.write(text)
918
+
919
+ # Before the run and not after it (RK343): the exit code is the whole of the evidence
920
+ # wherever the failure named no address, and a staging the command cannot read produces the
921
+ # same 2 as a usage error and the same 1 as a finding. Nothing was going to be learned, so
922
+ # nothing is claimed.
923
+ unstaged = _unstaged(root)
924
+ if unstaged:
925
+ return Replay(
926
+ False, recorded_exit, 0, "", drifted=drifted, unstaged=unstaged,
927
+ stopped=stopped, aged=aged
928
+ )
929
+
930
+ failure = observe(_repointed([str(part) for part in recorded["argv"]], root))
931
+ where = recorded.get("where")
932
+ reproduces = failure.exit_code == recorded_exit and (
933
+ where is None or str(where) in failure.output
934
+ )
935
+ return Replay(
936
+ reproduces,
937
+ recorded_exit,
938
+ failure.exit_code,
939
+ failure.output,
940
+ drifted=drifted,
941
+ stopped=stopped,
942
+ aged=aged,
943
+ )
944
+
945
+
946
+ def _unstaged(root: Path) -> tuple[str, ...]:
947
+ """The governed files the staged config declares and the capture never carried (RK343).
948
+
949
+ Asked of :meth:`Config.missing`, which is the reader `lint` already uses to report
950
+ `file.missing` — one rule and one implementation, so a role added to the format is staged
951
+ and surveyed by the same list. Loaded from the written path rather than discovered, because
952
+ a search upward from a scratch directory can find somebody else's project.
953
+
954
+ A config that does not parse declares nothing, deliberately. A defect in *reading*
955
+ `roadkeep.toml` is this repository's own first corpus entry: it has no governed file in its
956
+ input at all, and demanding files from a config nobody could read would refuse to replay
957
+ the one class of report that needs none.
958
+ """
959
+ try:
960
+ config = Config.load(root / "roadkeep.toml")
961
+ except (ConfigError, tomllib.TOMLDecodeError, OSError):
962
+ return ()
963
+ return tuple(config.relative(config.path(role)) for role in config.missing())
964
+
965
+
966
+ def _carried(recorded: Mapping[str, object]) -> dict[str, str]:
967
+ """`path -> contents` for the files one stored capture holds, in either spelling.
968
+
969
+ `documents` is what a capture written since RK344 carries. `document`/`document_path` is
970
+ what every one before it carries, and reading both is what keeps a report already on
971
+ somebody's disk runnable — a corpus that only accepts the current format is a corpus that
972
+ loses the field reports it exists to keep.
973
+ """
974
+ documents = recorded.get("documents")
975
+ if isinstance(documents, Mapping):
976
+ return {str(name): str(text) for name, text in documents.items()}
977
+ single, name = recorded.get("document"), recorded.get("document_path")
978
+ return {str(name): str(single)} if single and name else {}
979
+
980
+ #: Where a capture lands before anybody decides what to do with it (RK89). A fifth path in
981
+ #: a repository that declared four — and one the repository never has to see, because the
982
+ #: same run teaches git to ignore it.
983
+ REPORTS = Path(".roadkeep") / "reports"
984
+
985
+ #: The line appended to `.gitignore`, and every spelling that already covers it. Nothing
986
+ #: here enters a history, a diff, or a review by somebody who never installed this tool.
987
+ IGNORE_RULE = ".roadkeep/"
988
+ _COVERED = frozenset({".roadkeep", ".roadkeep/", "/.roadkeep", "/.roadkeep/", ".roadkeep/**"})
989
+
990
+
991
+ #: A stamp naming a task in **another** repository: `owner/repo#ID` (RK1160). One spelling, and
992
+ #: it is the one every tracker already uses for a cross-repository reference, so an author who
993
+ #: types it is typing what they would paste into an issue.
994
+ #:
995
+ #: The id half is deliberately loose — a prefix and a number, with the optional suffix RK110
996
+ #: reads — because it belongs to a backlog whose `[ids]` this project cannot see. What is strict
997
+ #: is the **shape**: a qualifier without a repository is a local id with punctuation in it, and
998
+ #: this must never accept one, since the whole point is that it clears a row nothing checks.
999
+ DELIVERED = re.compile(r"^(?P<repo>[A-Za-z0-9._-]+/[A-Za-z0-9._-]+)#(?P<id>[A-Za-z]+\d+[a-z]?)$")
1000
+
1001
+
1002
+ def delivered(stamp: str) -> str:
1003
+ """The repository a stamp names, or `""` where it names an id of this project's own.
1004
+
1005
+ The reading RK1160 needed, and the reason it is a *shape* and not a lookup: a capture of a
1006
+ defect in this tool belongs in this tool's backlog and never in the project that hit it
1007
+ (`report --to OWNER/REPO`), so the id it was filed as is one no governed file here holds. Both
1008
+ readers resolved that stamp against the local backlog, so the row never cleared, and the two
1009
+ ways to silence it were a stamp from the wrong repository or deleting the evidence.
1010
+
1011
+ A qualified stamp is therefore *filed by construction*: this cannot check another backlog and
1012
+ does not pretend to, so what it verifies is that the author named where the work went.
1013
+ """
1014
+ found = DELIVERED.match(stamp.strip())
1015
+ return found["repo"] if found else ""
1016
+
1017
+
1018
+ @dataclass(frozen=True, slots=True)
1019
+ class Held:
1020
+ """One capture the report directory already holds, and the claim it states (RK1139)."""
1021
+
1022
+ path: Path
1023
+ #: The capture's own `symptom`, which is verbatim what `add --symptom` would receive — so
1024
+ #: an author who ran the pre-filled command produces an exact match and anything else
1025
+ #: reads as unfiled. Conservative in the safe direction: it nags rather than reassures.
1026
+ symptom: str
1027
+ #: The id this capture was filed as, where :func:`stamp` wrote one (RK1141). The reading
1028
+ #: that does not depend on prose: an author who reworded the symptom still clears the row,
1029
+ #: and a capture filed before this existed falls back to the match above.
1030
+ filed: str = ""
1031
+ #: Where it was aimed, where the capture recorded one (RK1161) — what lets a stamp of a bare
1032
+ #: id become the delivery it was, instead of asking for a repository twice declared.
1033
+ upstream: str = ""
1034
+
1035
+
1036
+ def stamp(path: str | Path, task_id: str) -> bool:
1037
+ """Write into a capture the id it was filed as (RK1141). True where it landed.
1038
+
1039
+ The fact lives in the **artefact**, which is the reading RK89 chose for everything in that
1040
+ directory: a capture is evidence, and what happened to it is part of the evidence. RK1139
1041
+ counted captures and cleared a row by an exact symptom match — right for an author who ran
1042
+ the pre-filled `add`, and permanent for one who reworded the sentence, which left this
1043
+ repository holding a row that could never reach zero.
1044
+
1045
+ Never a condition of the write that calls it. `add` has already placed the line and saved
1046
+ the governed files by the time this runs, so a capture that cannot be stamped costs the
1047
+ link and never the task — the rule :func:`~roadkeep.claiming.follow` keeps for a claim, for
1048
+ the same reason: the durable half is in the repository and this is the transient one.
1049
+
1050
+ Keeps every other key exactly as it was, because a capture is what a replay runs from: the
1051
+ payload is re-serialised from what was read, and a file this cannot parse is left alone.
1052
+ """
1053
+ target = Path(path)
1054
+ try:
1055
+ payload = json.loads(target.read_text(encoding="utf-8"))
1056
+ if not isinstance(payload, dict):
1057
+ return False
1058
+ payload["filed"] = task_id
1059
+ target.write_text(
1060
+ json.dumps(payload, indent=2, ensure_ascii=False) + "\n", encoding="utf-8"
1061
+ )
1062
+ except (OSError, ValueError):
1063
+ return False
1064
+ return True
1065
+
1066
+
1067
+ #: What a door names where the capture did not record where it was aimed (RK1395). A placeholder
1068
+ #: and never a guess: an id no local file holds is a delivery or a typo, and the two are told
1069
+ #: apart by the author alone — so the command asks for the half this project cannot know and
1070
+ #: fills in every other, which is the shape :func:`~roadkeep.verbs.adopting._capture_filed`'s
1071
+ #: own refusal already prints.
1072
+ UNKNOWN_REPOSITORY = "owner/repo"
1073
+
1074
+
1075
+ def qualifying(path: str, stamp: str, upstream: str = "") -> str:
1076
+ """The command that turns a stamp this project cannot resolve into the delivery it is.
1077
+
1078
+ One composer for the two readers that report the state (RK1395). Measured on a live adopting
1079
+ project: Turing holds a capture carrying `filed: "RK1128"` — a shipped **roadkeep** id, since
1080
+ a defect in this tool is filed in this tool's backlog — and no `upstream`, that project
1081
+ declaring none and the capture predating RK1161. So `stats` printed `2 unfiled` over a path
1082
+ answered months earlier and the sweep called it a link to nothing, while every part of the
1083
+ argv that closes it except the repository was already on disk.
1084
+
1085
+ `upstream` is used where the capture recorded one, which is the asymmetry RK1149 took out of
1086
+ the refusals: a fact the artefact carries is never a field to type again. Where it recorded
1087
+ none the repository is :data:`UNKNOWN_REPOSITORY`, because that half genuinely is the
1088
+ author's — and a command with one obvious blank is a thing to complete, where a sentence
1089
+ about a stamp is a thing to work out.
1090
+ """
1091
+ return shlex.join(
1092
+ [
1093
+ *shlex.split(invocation()),
1094
+ "capture",
1095
+ "filed",
1096
+ path,
1097
+ "--as",
1098
+ f"{upstream or UNKNOWN_REPOSITORY}#{stamp}",
1099
+ ]
1100
+ )
1101
+
1102
+
1103
+ @dataclass(frozen=True, slots=True)
1104
+ class Read:
1105
+ """One capture, and what this project can honestly say about it (RK1162).
1106
+
1107
+ Three states and not two, because `filed` was two facts wearing one number: a stamp
1108
+ resolved against this project's own ids is a **resolution**, and a stamp naming another
1109
+ repository is a **claim** nothing here can check — which is what RK1160 made the row clear
1110
+ on. A tuple growing a third position would have carried the distinction and named neither.
1111
+ """
1112
+
1113
+ path: Path
1114
+ filed: bool
1115
+ #: The repository a delivery names, or `""` for a capture this project resolved itself.
1116
+ elsewhere: str = ""
1117
+ #: The stamp as it was written, where this project could not resolve it (RK1395) — the half
1118
+ #: that turns "unfiled" from a verdict into a command. `""` for a capture with no stamp at
1119
+ #: all and for one that resolved, neither of which has anything to qualify.
1120
+ stamp: str = ""
1121
+ #: Where the capture recorded it was aimed, so the door names the real repository rather
1122
+ #: than the placeholder wherever the artefact already knows it.
1123
+ aimed: str = ""
1124
+
1125
+ def door(self, where: str) -> str:
1126
+ """The command that closes this row, or `""` where there is none to name.
1127
+
1128
+ Takes the spelling rather than reading :attr:`path`, so the argv carries the same
1129
+ project-relative path the row above it does — a door naming an absolute path where the
1130
+ report names a relative one is two addresses for one file.
1131
+ """
1132
+ return qualifying(where, self.stamp, self.aimed) if self.stamp else ""
1133
+
1134
+
1135
+ @dataclass(frozen=True, slots=True)
1136
+ class Filed:
1137
+ """Which task a capture on disk was stamped as, and whether this project can check it.
1138
+
1139
+ A record since RK1170. Two values and a branch, which is small — and is exactly the shape
1140
+ the task is about: `elsewhere` decides both what the report says and what the payload
1141
+ carries, and the door was making that decision twice.
1142
+ """
1143
+
1144
+ #: The capture, as this project spells it.
1145
+ where: str
1146
+ #: The stamp that was written — a bare id, or `owner/repo#id` where the capture recorded
1147
+ #: an upstream and this backlog holds no such line (RK1161).
1148
+ filed: str
1149
+ #: The repository a delivery names, or `""` where this project resolved the id itself.
1150
+ elsewhere: str = ""
1151
+ #: What the caller typed, which is what tells a qualified stamp from a bare one.
1152
+ asked: str = ""
1153
+
1154
+ def stated(self) -> str:
1155
+ rows = [f"{self.where} now names {self.filed}"]
1156
+ if self.elsewhere:
1157
+ # Said out loud, because this is the one stamp nothing here can check: the row
1158
+ # clears on the author's word that the work went there, and a reader should see
1159
+ # which claim it is.
1160
+ qualified = "" if self.filed == self.asked else " — the capture recorded where it went"
1161
+ rows.append(
1162
+ f" delivered to {self.elsewhere}, which this project cannot read — taken "
1163
+ f"as filed{qualified}"
1164
+ )
1165
+ return chr(10).join(rows)
1166
+
1167
+ def payload(self) -> dict[str, object]:
1168
+ """`delivered` beside the stamp where there is one (RK1162).
1169
+
1170
+ The stamp carries the repository and a consumer would otherwise recover it by parsing
1171
+ a `#`, which is a second reader of a shape this module already parsed. **Absent** and
1172
+ not null, for `_remedy_json`'s reason: a key that is always there and usually null is
1173
+ one a client learns to skip.
1174
+ """
1175
+ return {
1176
+ "path": self.where,
1177
+ "filed": self.filed,
1178
+ **({"delivered": self.elsewhere} if self.elsewhere else {}),
1179
+ }
1180
+
1181
+
1182
+ @dataclass(frozen=True, slots=True)
1183
+ class Debt:
1184
+ """The captures a project holds that its backlog has not answered for (RK1139).
1185
+
1186
+ A record and no longer a bare tuple read twice (RK1170): `stats` composed both registers
1187
+ from the same list, and each half called the reader again — so a project with captures paid
1188
+ the glob and the parse of three governed files once per register that asked.
1189
+ """
1190
+
1191
+ held: tuple[Read, ...] = ()
1192
+
1193
+ @property
1194
+ def unfiled(self) -> tuple[Path, ...]:
1195
+ return tuple(one.path for one in self.held if not one.filed)
1196
+
1197
+ def stated(self, config: Config, width: int) -> list[str]:
1198
+ """The captures this project owes an entry for, and the total behind them (RK1143).
1199
+
1200
+ Rows **only where one is unfiled**, which is not the rule the counts beside this follow
1201
+ — they print at zero because a field that appears only when it is non-zero is one a
1202
+ reader stops looking for. Two differences decide it. `uncounted` is about the file the
1203
+ command reports on and a capture is not; and a row that says nothing is owed is never
1204
+ the next step, which is RK1121's finding one command over — measured here, where
1205
+ `captures 2 2 filed` printed on every run of a tree with no debt at all, for ever,
1206
+ because nothing deletes a capture.
1207
+
1208
+ The **total rides on the row** rather than being lost with it: the number a reader wants
1209
+ beside "one is unfiled" is how many there are. What silence costs is that the directory
1210
+ has files at all, and that is what :meth:`payload` keeps — a key costs a client nothing
1211
+ to skip, where a line costs every reader the same attention on every run.
1212
+ """
1213
+ unfiled = self.unfiled
1214
+ if not unfiled:
1215
+ return []
1216
+ rows = [f" {'captures':<{width}} {len(self.held):>4} {len(unfiled)} unfiled"]
1217
+ # Named and not only counted: this is the list the tool asks every project to hold its
1218
+ # debt in, and a count with nothing behind it is the silent file again.
1219
+ for one in self.held:
1220
+ if one.filed:
1221
+ continue
1222
+ where = config.relative(one.path)
1223
+ rows.append(f" {'unfiled':<{width}} {where}")
1224
+ # And the command, where the stamp makes one derivable (RK1395). Only there: a
1225
+ # capture with no stamp has no id to qualify, so the row is the whole of what can
1226
+ # be said about it, and an offer with a blank where the id goes is the sentence
1227
+ # again. The one case this reaches was measured — a shipped roadkeep id written
1228
+ # into an adopting project's capture, read as unanswered by this row for months.
1229
+ door = one.door(where)
1230
+ if door:
1231
+ rows.append(f" {'':<{width}} {door}")
1232
+ return rows
1233
+
1234
+ def payload(self, config: Config) -> dict[str, object]:
1235
+ """The three states, told apart (RK1162).
1236
+
1237
+ `filed` counted a stamp this project resolved and a stamp nothing here can check as one
1238
+ number, so a consumer reading `filed: 2` could not tell two closed rows from one closed
1239
+ row and one somebody says is closed elsewhere.
1240
+ """
1241
+ return {
1242
+ "kept": len(self.held),
1243
+ # Resolutions only: `kept` is still the total, and a client that added `filed` to
1244
+ # `delivered` gets what this key used to mean.
1245
+ "filed": sum(1 for one in self.held if one.filed and not one.elsewhere),
1246
+ "delivered": [
1247
+ {"path": config.relative(one.path), "repository": one.elsewhere}
1248
+ for one in self.held
1249
+ if one.elsewhere
1250
+ ],
1251
+ "unfiled": [config.relative(one) for one in self.unfiled],
1252
+ }
1253
+
1254
+
1255
+ def debt(config: Config) -> Debt:
1256
+ """Each capture this project holds, and whether the backlog already states its claim.
1257
+
1258
+ The reading RK1139 asked for, and the cheap order matters: the directory is globbed first,
1259
+ so a project with no captures — which is every project that has never hit a defect in this
1260
+ tool — pays one `glob` and never the parse of three governed files.
1261
+
1262
+ "Filed" is an **exact symptom match**, because the capture's symptom is verbatim what
1263
+ `add --symptom` receives: an author who ran the pre-filled command produces one, and an
1264
+ author who reworded it reads as unfiled. Wrong in the direction that nags.
1265
+ """
1266
+ from roadkeep.backlog import Backlog # noqa: PLC0415 - RK260
1267
+
1268
+ held = captures(config.root)
1269
+ if not held:
1270
+ return Debt()
1271
+ backlog = Backlog.load(config)
1272
+ documents = [
1273
+ one for one in (backlog.roadmap, backlog.ledger, backlog.store) if one is not None
1274
+ ]
1275
+ stated = {entry.task.symptom for one in documents for entry in one.entries}
1276
+ ids = {entry.task.id for one in documents for entry in one.entries}
1277
+ # The stamp first and the prose second (RK1141): an author who ran the pre-filled `add`
1278
+ # cleared this row by the act that closed it, and one who reworded the symptom is why the
1279
+ # match alone left a row that could never reach zero. An id no file holds does not clear it
1280
+ # — a stamp naming a task that was renumbered away is a link and not an outcome.
1281
+ # **Unless the stamp names another repository** (RK1160): a capture of a defect in this tool
1282
+ # belongs in this tool's backlog, so its id is one no governed file here will ever hold, and
1283
+ # both readings above left a row that could only be silenced by a stamp from the wrong
1284
+ # repository or by deleting the evidence. Filed by construction, because this cannot read
1285
+ # that backlog and does not pretend to.
1286
+ return Debt(
1287
+ tuple(
1288
+ Read(
1289
+ path=one.path,
1290
+ filed=bool(delivered(one.filed))
1291
+ or (one.filed in ids if one.filed else one.symptom in stated),
1292
+ elsewhere=delivered(one.filed),
1293
+ # Carried only where this project failed to resolve it (RK1395): a stamp that
1294
+ # resolved is not a row, and one that qualified is a delivery. What is left is
1295
+ # the state the two readers called unfiled and could not act on.
1296
+ stamp="" if one.filed in ids or delivered(one.filed) else one.filed,
1297
+ aimed=one.upstream,
1298
+ )
1299
+ for one in held
1300
+ )
1301
+ )
1302
+
1303
+
1304
+ #: Why one capture on disk is not deletable, keyed by the state that decided it (RK1394).
1305
+ #: A table because the verb's whole output is these sentences: a sweep that removed three files
1306
+ #: and said nothing about the four it left is one whose reader has to re-derive the reading, and
1307
+ #: the reason a capture survives is the only thing they cannot see by listing the directory.
1308
+ KEPT_BECAUSE = {
1309
+ "unfiled": (
1310
+ "no `filed` stamp, so nothing says this was ever answered — `capture filed <path> "
1311
+ "--as ID` records it, and rotation is what a capture that never gets one waits for"
1312
+ ),
1313
+ "open": (
1314
+ "filed as {id}, which this backlog still holds open — the capture is the evidence "
1315
+ "for a line nobody has shipped"
1316
+ ),
1317
+ "elsewhere": (
1318
+ "delivered to {repo}, which this project cannot read — filed by construction and "
1319
+ "never provably spent, so the evidence stays"
1320
+ ),
1321
+ # The one kept state whose reason ends in a complete argv (RK1395, RK420). The others
1322
+ # cannot: `unfiled` has no id to qualify, `open` is waiting on a ship and `elsewhere` is
1323
+ # already as answered as this project can see. Here the id is in the artefact and only the
1324
+ # repository is missing, so the sentence is followed by the command that supplies it.
1325
+ "unknown": (
1326
+ "filed as {id}, which no governed file holds — a link to nothing is not a delivery, "
1327
+ "so this is read as unfiled; where it named another backlog, {door}"
1328
+ ),
1329
+ }
1330
+
1331
+ #: The one state that is deletable, said in the same shape so the report reads as one table.
1332
+ SPENT_BECAUSE = "filed as {id}, which the ledger records as shipped"
1333
+
1334
+
1335
+ @dataclass(frozen=True, slots=True)
1336
+ class Verdict:
1337
+ """One capture and what the ledger says about it (RK1394)."""
1338
+
1339
+ path: Path
1340
+ #: A key of :data:`KEPT_BECAUSE`, or `""` where the ledger proved this spent.
1341
+ state: str
1342
+ #: The stamp that decided it, for the sentence — a bare id, or `owner/repo#id`.
1343
+ filed: str = ""
1344
+ #: Where the capture recorded it was aimed (RK1395), so the one reason that ends in a
1345
+ #: command names the real repository wherever the artefact already carries it.
1346
+ aimed: str = ""
1347
+
1348
+ @property
1349
+ def spent(self) -> bool:
1350
+ return not self.state
1351
+
1352
+ def because(self, where: str) -> str:
1353
+ """The reason, with the address the reader is looking at substituted into it.
1354
+
1355
+ A method and no longer a property (RK1395): the `unknown` reason ends in the command
1356
+ that closes it, and a command has to name the file by the same spelling the row above
1357
+ it does — which is the project's and not this record's to know.
1358
+ """
1359
+ template = SPENT_BECAUSE if self.spent else KEPT_BECAUSE[self.state]
1360
+ return template.format(
1361
+ id=self.filed,
1362
+ repo=delivered(self.filed),
1363
+ door=qualifying(where, self.filed, self.aimed),
1364
+ )
1365
+
1366
+
1367
+ @dataclass(frozen=True, slots=True)
1368
+ class Sweep:
1369
+ """What a retention pass would remove, and what it refuses to (RK1394).
1370
+
1371
+ Read whole before anything is unlinked, and the two halves are reported together on both
1372
+ runs: a delete that printed only what it took leaves a reader unable to tell an empty
1373
+ directory from one holding four captures nothing can close. The reasons are the product —
1374
+ three of the four states end in a command, and the fourth is the boundary the task named.
1375
+ """
1376
+
1377
+ read: tuple[Verdict, ...] = ()
1378
+ #: True where the files were actually unlinked, which is what separates the two sentences.
1379
+ swept: bool = False
1380
+ #: Captures this could not remove, `path -> what the filesystem said`. Never an exception:
1381
+ #: the reading is already done and correct, and a locked file is a thing to name.
1382
+ refused: tuple[tuple[Path, str], ...] = ()
1383
+
1384
+ @property
1385
+ def spent(self) -> tuple[Verdict, ...]:
1386
+ return tuple(one for one in self.read if one.spent)
1387
+
1388
+ @property
1389
+ def kept(self) -> tuple[Verdict, ...]:
1390
+ return tuple(one for one in self.read if not one.spent)
1391
+
1392
+ def stated(self, config: Config) -> str:
1393
+ # The header counts what *went*, which on a run that hit a locked file is not what was
1394
+ # spent: a total taken from the reading would say three were removed with one of them
1395
+ # still on disk two lines below.
1396
+ gone = len(self.spent) - len(self.refused)
1397
+ rows = [
1398
+ f"{len(self.read)} capture(s), "
1399
+ f"{gone if self.swept else len(self.spent)} {'swept' if self.swept else 'spent'}, "
1400
+ f"{len(self.kept)} kept"
1401
+ ]
1402
+ stuck = {path for path, _ in self.refused}
1403
+ for one in self.read:
1404
+ if one.path in stuck:
1405
+ # Its own mark and its own row below, because this one is neither: the reading
1406
+ # proved it spent and the directory still holds it.
1407
+ mark = "refused"
1408
+ elif not one.spent:
1409
+ mark = "kept"
1410
+ else:
1411
+ mark = "removed" if self.swept else "spent"
1412
+ where = config.relative(one.path)
1413
+ rows.append(f" {mark:<8} {where}")
1414
+ rows.append(f" {one.because(where)}")
1415
+ for path, complaint in self.refused:
1416
+ rows.append(f" refused {config.relative(path)}: {complaint}")
1417
+ if self.spent and not self.swept:
1418
+ # The door every finding names (RK420). Said only where there is something to
1419
+ # take, because an offer to delete nothing is a line every clean run pays for.
1420
+ rows.append(f" delete {invocation()} capture sweep")
1421
+ return chr(10).join(rows)
1422
+
1423
+ def payload(self, config: Config) -> dict[str, object]:
1424
+ return {
1425
+ "kept": len(self.read),
1426
+ "swept": self.swept,
1427
+ "captures": [
1428
+ {
1429
+ "path": config.relative(one.path),
1430
+ "spent": one.spent,
1431
+ # `""` where the ledger proved it spent, so a consumer reads one key for
1432
+ # the verdict and never infers it from the presence of a reason.
1433
+ "state": one.state,
1434
+ "filed": one.filed,
1435
+ "because": one.because(config.relative(one.path)),
1436
+ }
1437
+ for one in self.read
1438
+ ],
1439
+ "refused": [
1440
+ {"path": config.relative(path), "because": complaint}
1441
+ for path, complaint in self.refused
1442
+ ],
1443
+ }
1444
+
1445
+
1446
+ def sweep(config: Config, delete: bool = False) -> Sweep:
1447
+ """Read every capture against the ledger, and remove only what shipped (RK1394).
1448
+
1449
+ The retention :func:`keep` parks, keyed on the fact the artefact already carries. `filed` is
1450
+ exact where an age is not: an id this ledger resolves to a **shipped** line says the capture
1451
+ is answered by the repository's own record, where "older than thirty days" says only that
1452
+ time passed — and a capture is evidence, so the weaker key is the wrong one to delete on.
1453
+
1454
+ Four states and one of them deletable, which is the shape of the population that argued it.
1455
+ This repository held three captures, all three stamped with ids the changelog records; an
1456
+ adopting project held two that were never filed, no longer reproduce, and are `not
1457
+ replayable: the capture has no document` — so neither the gate nor a stamp can close them,
1458
+ and an exact sweep leaves them rather than guess. A stamp naming another repository is the
1459
+ third: filed by construction (RK1160), and by the same reasoning never provably *spent*,
1460
+ since this project cannot read that backlog. Rotation is the fallback for the first, and it
1461
+ is deliberately not this verb — a bound on age deletes the two an exact reading protects.
1462
+
1463
+ The reading is complete before anything is unlinked, so a file that cannot be removed is
1464
+ named beside a verdict that is still right about all of them.
1465
+ """
1466
+ from roadkeep.backlog import Backlog # noqa: PLC0415 - RK260
1467
+
1468
+ held = captures(config.root)
1469
+ if not held:
1470
+ return Sweep(swept=delete)
1471
+ backlog = Backlog.load(config)
1472
+ ledger = backlog.ledger
1473
+ shipped = {entry.task.id for entry in ledger.entries} if ledger is not None else set()
1474
+ elsewhere_ids = {
1475
+ entry.task.id
1476
+ for document in (backlog.roadmap, backlog.store)
1477
+ if document is not None
1478
+ for entry in document.entries
1479
+ }
1480
+ read = tuple(_verdict(one, shipped, elsewhere_ids) for one in held)
1481
+ if not delete:
1482
+ return Sweep(read=read)
1483
+ refused: list[tuple[Path, str]] = []
1484
+ for one in read:
1485
+ if not one.spent:
1486
+ continue
1487
+ try:
1488
+ one.path.unlink()
1489
+ except OSError as error:
1490
+ refused.append((one.path, str(error)))
1491
+ return Sweep(read=read, swept=True, refused=tuple(refused))
1492
+
1493
+
1494
+ def _verdict(one: Held, shipped: set[str], open_ids: set[str]) -> Verdict:
1495
+ """Which of the four states this capture is in, decided by the stamp and the ledger."""
1496
+ if not one.filed:
1497
+ return Verdict(path=one.path, state="unfiled")
1498
+ if delivered(one.filed):
1499
+ return Verdict(path=one.path, state="elsewhere", filed=one.filed)
1500
+ if one.filed in shipped:
1501
+ return Verdict(path=one.path, state="", filed=one.filed)
1502
+ state = "open" if one.filed in open_ids else "unknown"
1503
+ # `aimed` only here, because `unknown` is the only reason that composes a command (RK1395)
1504
+ # and a field carried where nothing reads it is a field somebody later has to check.
1505
+ return Verdict(path=one.path, state=state, filed=one.filed, aimed=one.upstream)
1506
+
1507
+
1508
+ def captures(root: str | Path = ".") -> tuple[Held, ...]:
1509
+ """Every capture on disk, in filename order — which is time order (RK1139).
1510
+
1511
+ A capture was write-only: `report` printed `kept <path>`, and nothing listed, counted or
1512
+ contradicted it. Measured directly — a session ran `report` twice, read that line as
1513
+ "filed", and reported the work done; `stats` answered `total 2` and was right, which is
1514
+ what made the mistake invisible. This is the reader that lets a count disagree.
1515
+
1516
+ Read defensively, one file at a time: a capture is evidence somebody may have hand-edited,
1517
+ and a directory that cannot be parsed must not stop a query. What a file without a
1518
+ `symptom` is is not a capture this can say anything about, so it is skipped rather than
1519
+ counted as unfiled — a number that included junk would be a number nobody trusts.
1520
+ """
1521
+ directory = Path(root) / REPORTS
1522
+ out: list[Held] = []
1523
+ for path in sorted(directory.glob("*.json")):
1524
+ try:
1525
+ payload = json.loads(path.read_text(encoding="utf-8"))
1526
+ except (OSError, ValueError):
1527
+ continue
1528
+ symptom = payload.get("symptom") if isinstance(payload, dict) else None
1529
+ if isinstance(symptom, str) and symptom:
1530
+ stamped = payload.get("filed")
1531
+ aimed = payload.get("upstream")
1532
+ out.append(
1533
+ Held(
1534
+ path=path,
1535
+ symptom=symptom,
1536
+ filed=stamped if isinstance(stamped, str) else "",
1537
+ upstream=aimed if isinstance(aimed, str) else "",
1538
+ )
1539
+ )
1540
+ return tuple(out)
1541
+
1542
+
1543
+ @dataclass(frozen=True, slots=True)
1544
+ class Kept:
1545
+ """One capture on disk, and what had to be said about getting it there."""
1546
+
1547
+ path: Path
1548
+ #: `None` when git was already told to ignore the directory or has just been told.
1549
+ #: A sentence when it could not be — never an exception, because the capture is the
1550
+ #: point and an unwritable `.gitignore` is a thing to mention, not to fail over.
1551
+ complaint: str | None = None
1552
+
1553
+
1554
+ def keep(found: Capture, root: str | Path = ".") -> Kept:
1555
+ """Write the capture before it is printed (RK89).
1556
+
1557
+ Evidence that lives for the length of one stdout depends on the caller taking a second
1558
+ step, and RK86 is this block's own record of second steps not being taken. So this is
1559
+ unconditional and has no flag: a capture nobody pruned costs kilobytes, and a capture
1560
+ nobody kept costs the only session that could have identified the defect.
1561
+
1562
+ Retention is :func:`sweep`'s, and only the exact half of it (RK1394): a capture whose
1563
+ `filed` id the ledger records as shipped is answered by the repository's own record and is
1564
+ deleted, and every other state is named and left. Rotation, dedup by argv and an age limit
1565
+ are still open, and they are the fallbacks for the capture that never gets a stamp — each
1566
+ easier to add to a directory with files in it than to reconstruct from sessions that ended.
1567
+
1568
+ What is written is what was produced: `--without` applied, `--embed` or not. One
1569
+ artefact and one set of contents, so the file on disk is the text that was reviewed.
1570
+ """
1571
+ base = Path(root)
1572
+ directory = base / REPORTS
1573
+ directory.mkdir(parents=True, exist_ok=True)
1574
+ path = directory / _filename(found)
1575
+ path.write_text(
1576
+ json.dumps(found.as_dict(), indent=2, ensure_ascii=False) + "\n", encoding="utf-8"
1577
+ )
1578
+ return Kept(path=path, complaint=_ignore(base))
1579
+
1580
+
1581
+ def _filename(found: Capture) -> str:
1582
+ """Sortable, and it says what failed. Uniqueness is the clock plus the claim's digest:
1583
+ two captures of one command in one second are still two captures."""
1584
+ stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
1585
+ digest = sha256(f"{found.symptom}{found.failure.command}".encode()).hexdigest()[:8]
1586
+ return f"{stamp}-{_slug(_subcommand(found.failure.argv))}-{digest}.json"
1587
+
1588
+
1589
+ def _subcommand(argv: Sequence[str]) -> str:
1590
+ """Which command failed, asked of the parser rather than guessed from the argv.
1591
+
1592
+ The first non-flag word is the *value* of `-C` half the time, and a filename naming a
1593
+ directory instead of a command is a directory listing nobody can read.
1594
+ """
1595
+ from roadkeep.cli import build_parser
1596
+
1597
+ with contextlib.redirect_stderr(io.StringIO()):
1598
+ try:
1599
+ known, _ = build_parser().parse_known_args(list(argv))
1600
+ except SystemExit:
1601
+ return "run"
1602
+ return getattr(known, "command", None) or "run"
1603
+
1604
+
1605
+ def _slug(word: str) -> str:
1606
+ kept = [character if character.isalnum() else "-" for character in word.lower()]
1607
+ return "".join(kept).strip("-") or "run"
1608
+
1609
+
1610
+ def _ignore(root: Path) -> str | None:
1611
+ """Teach git to ignore the directory, once, without touching a line already there.
1612
+
1613
+ Append-only and never rendered: `.gitignore` is not a governed file, it does not
1614
+ round-trip, and reordering somebody's ignore rules to add one is the kind of write
1615
+ this tool refuses everywhere else.
1616
+ """
1617
+ path = root / ".gitignore"
1618
+ try:
1619
+ existing = path.read_text(encoding="utf-8") if path.is_file() else ""
1620
+ except (OSError, UnicodeDecodeError) as error:
1621
+ return f"could not read {path}: {error}"
1622
+ if any(line.strip() in _COVERED for line in existing.splitlines()):
1623
+ return None
1624
+ prefix = "" if not existing or existing.endswith("\n") else "\n"
1625
+ try:
1626
+ with path.open("a", encoding="utf-8", newline="") as handle:
1627
+ handle.write(f"{prefix}{IGNORE_RULE}\n")
1628
+ except OSError as error:
1629
+ # The capture is already on disk. This is a sentence, not a failure.
1630
+ return f"could not add {IGNORE_RULE} to {path}: {error}"
1631
+ return None
1632
+
1633
+
1634
+ def _repointed(argv: list[str], root: Path) -> list[str]:
1635
+ """The recorded argv with its `-C` aimed at the staging, and nothing else touched."""
1636
+ out = list(argv)
1637
+ for index, word in enumerate(out[:-1]):
1638
+ if word in ("-C", "--directory"):
1639
+ out[index + 1] = str(root)
1640
+ if not any(word in ("-C", "--directory") for word in out):
1641
+ out = ["-C", str(root), *out]
1642
+ return out
1643
+
1644
+
1645
+ def _tail(output: str) -> str:
1646
+ lines = output.splitlines()
1647
+ if len(lines) <= _MOST_OUTPUT_LINES:
1648
+ return output
1649
+ dropped = len(lines) - _MOST_OUTPUT_LINES
1650
+ # Stated, because a truncated listing that does not say so reads as a complete one.
1651
+ return "\n".join([f"… {dropped} earlier line(s) not kept", *lines[-_MOST_OUTPUT_LINES:]])
1652
+
1653
+
1654
+ def _configuration(root: str | Path) -> tuple[str | None, str | None]:
1655
+ found = find_config(Path(root))
1656
+ if found is None:
1657
+ return None, None
1658
+ try:
1659
+ return str(found), found.read_text(encoding="utf-8")
1660
+ except OSError:
1661
+ return str(found), None
1662
+
1663
+
1664
+ def _documents(root: str | Path) -> tuple[tuple[str, str], ...]:
1665
+ """Every governed file the config declares, whole and verbatim — never the project (RK344).
1666
+
1667
+ Declared and not discovered: what leaves is the list a reader can check against the
1668
+ `roadkeep.toml` printed beside it, which is the form of disclosure RK87 asks for. A file
1669
+ that is declared and absent is simply not carried — that is a finding of its own
1670
+ (`file.missing`), and inventing an empty one would stage a project the reporter did not have.
1671
+ """
1672
+ try:
1673
+ config = Config.discover(root)
1674
+ except (ConfigError, tomllib.TOMLDecodeError, OSError):
1675
+ # The config is the defect. There is nothing declared to carry, and `_unstaged` reads
1676
+ # that same unparseable file back to the same conclusion.
1677
+ return ()
1678
+ carried: list[tuple[str, str]] = []
1679
+ for role in config.paths:
1680
+ path = config.path(role)
1681
+ try:
1682
+ carried.append((config.relative(path), path.read_text(encoding="utf-8")))
1683
+ except (OSError, UnicodeDecodeError):
1684
+ continue
1685
+ return tuple(carried)
1686
+
1687
+
1688
+ def _source(where: str | None, root: str | Path) -> str | None:
1689
+ """The line the engine named, read back verbatim — never reconstructed."""
1690
+ if where is None:
1691
+ return None
1692
+ name, _, rest = where.partition(":")
1693
+ number = int(rest.partition(":")[0])
1694
+ path = Path(root) / name
1695
+ try:
1696
+ lines = path.read_text(encoding="utf-8").splitlines()
1697
+ except (OSError, UnicodeDecodeError):
1698
+ return None
1699
+ return lines[number - 1] if 1 <= number <= len(lines) else None