roadkeep 0.2.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- roadkeep/__init__.py +79 -0
- roadkeep/adopting.py +2347 -0
- roadkeep/attesting.py +293 -0
- roadkeep/authoring.py +2117 -0
- roadkeep/backlog.py +767 -0
- roadkeep/blocking.py +1622 -0
- roadkeep/briefing.py +970 -0
- roadkeep/budgeting.py +2056 -0
- roadkeep/capturing.py +1699 -0
- roadkeep/claiming.py +1019 -0
- roadkeep/cli.py +638 -0
- roadkeep/commanding.py +487 -0
- roadkeep/config.py +1832 -0
- roadkeep/counting.py +376 -0
- roadkeep/criteria.py +933 -0
- roadkeep/deferring.py +708 -0
- roadkeep/describing.py +568 -0
- roadkeep/exporting.py +808 -0
- roadkeep/fixing.py +629 -0
- roadkeep/governing.py +934 -0
- roadkeep/graph.py +395 -0
- roadkeep/guarding.py +1028 -0
- roadkeep/history.py +2403 -0
- roadkeep/ids.py +301 -0
- roadkeep/installing.py +2145 -0
- roadkeep/kernel/__init__.py +24 -0
- roadkeep/kernel/document.py +1719 -0
- roadkeep/kernel/schema.py +2308 -0
- roadkeep/linting.py +4420 -0
- roadkeep/locking.py +209 -0
- roadkeep/markers.py +172 -0
- roadkeep/merging.py +1159 -0
- roadkeep/picking.py +772 -0
- roadkeep/provenance.py +789 -0
- roadkeep/queueing.py +752 -0
- roadkeep/ranking.py +139 -0
- roadkeep/referring.py +231 -0
- roadkeep/remaining.py +336 -0
- roadkeep/remedying.py +1989 -0
- roadkeep/rendering.py +1601 -0
- roadkeep/renumbering.py +503 -0
- roadkeep/repairing.py +295 -0
- roadkeep/reverting.py +144 -0
- roadkeep/scoping.py +708 -0
- roadkeep/screening.py +196 -0
- roadkeep/sections.py +4121 -0
- roadkeep/serving.py +2909 -0
- roadkeep/shipping.py +3993 -0
- roadkeep/showing.py +613 -0
- roadkeep/storing.py +224 -0
- roadkeep/verbs/__init__.py +26 -0
- roadkeep/verbs/adopting.py +974 -0
- roadkeep/verbs/authoring.py +566 -0
- roadkeep/verbs/declaring.py +335 -0
- roadkeep/verbs/linting.py +645 -0
- roadkeep/verbs/querying.py +2138 -0
- roadkeep/verbs/reading.py +307 -0
- roadkeep/verbs/refusing.py +146 -0
- roadkeep/verbs/sections.py +1433 -0
- roadkeep/verbs/shipping.py +819 -0
- roadkeep/weighing.py +380 -0
- roadkeep-0.2.0.dist-info/METADATA +453 -0
- roadkeep-0.2.0.dist-info/RECORD +67 -0
- roadkeep-0.2.0.dist-info/WHEEL +5 -0
- roadkeep-0.2.0.dist-info/entry_points.txt +2 -0
- roadkeep-0.2.0.dist-info/licenses/LICENSE +202 -0
- roadkeep-0.2.0.dist-info/top_level.txt +1 -0
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
|