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/attesting.py
ADDED
|
@@ -0,0 +1,293 @@
|
|
|
1
|
+
"""Which governed bytes a verb actually left, so an approved shell write is recorded (RK175).
|
|
2
|
+
|
|
3
|
+
RK128 closed the *silence* at the shell boundary: a `Bash` command naming a governed path is
|
|
4
|
+
surfaced and the user answers. What it could not close is what happens after they say yes.
|
|
5
|
+
`review` (RK60) then runs `lint` narrowed to the lines the turn changed, and a hand-edit
|
|
6
|
+
producing a **conforming** line passes every one of those checks — the annotations are right
|
|
7
|
+
because nothing was inserted, the pointer resolves because the anchor existed, and a reworded
|
|
8
|
+
`why` is a legal `why`. The file changed, no verb wrote it, and every gate agrees it is correct.
|
|
9
|
+
|
|
10
|
+
RK128's third option was to compare the governed files against `git` and refuse a change no
|
|
11
|
+
verb made. That is not what this does, for the reason the option was left open: a user who
|
|
12
|
+
approved a `sed` made a choice, and re-litigating it at the end of the turn spends the
|
|
13
|
+
approval the `ask` exists to collect. The defect in the symptom is narrower and it is real —
|
|
14
|
+
**no record of who wrote it** — so what is built is the record, not a second refusal.
|
|
15
|
+
|
|
16
|
+
The mechanism is one digest per governed file, taken where every write already passes:
|
|
17
|
+
|
|
18
|
+
* **The baseline is the last verb, not `HEAD`.** Against `HEAD` this would report the whole
|
|
19
|
+
turn's legitimate work — every `add` and every `ship` — and a report that fires on the
|
|
20
|
+
normal path is one nobody reads. Against what the last verb left, the only thing that
|
|
21
|
+
differs is bytes that arrived some other way, which is exactly the claim being made.
|
|
22
|
+
* **Recorded in :func:`roadkeep.cli.dispatch`, under the lock.** One choke point, and the
|
|
23
|
+
one both surfaces share: the MCP server dispatches parsed args in-process and never goes
|
|
24
|
+
through `main` (RK24), so a record kept anywhere else is one the write path walks around.
|
|
25
|
+
A query never attests, which is what keeps a `list` between two hand-edits from silently
|
|
26
|
+
adopting the second one as the baseline.
|
|
27
|
+
* **Not a second store (L2), and not a lock.** It holds no fact about any task: it is a
|
|
28
|
+
digest, it lives in the temp directory beside the write lock (RK117) and the claim
|
|
29
|
+
registry (RK119) under the same resolved-root key, and deleting it while nothing is
|
|
30
|
+
running loses nothing — every file simply reads as attested until the next verb runs.
|
|
31
|
+
|
|
32
|
+
Two rules that keep it honest. **Every failure is silence**, on the guard's own argument
|
|
33
|
+
(:mod:`roadkeep.guarding`): an unreadable sidecar must not block a turn, and `lint` still
|
|
34
|
+
judges the file. And **reporting re-baselines** — the current bytes become the new record —
|
|
35
|
+
so one unattested change is stated once and the turn ends on the next attempt, rather than
|
|
36
|
+
the same fact blocking every turn until somebody commits.
|
|
37
|
+
|
|
38
|
+
Which is what :func:`survey` is for (RK200). Re-baselining makes the `Stop` block a report a
|
|
39
|
+
turn receives once and can never ask for again, so the question "which governed files did no
|
|
40
|
+
verb write" had exactly one answer at exactly one moment — the arrangement RK161 ended for
|
|
41
|
+
claims, and L5 says every question is a command. It reads the same two dictionaries and
|
|
42
|
+
**moves nothing**: a query that changed the answer to the next query would launder the write
|
|
43
|
+
this module exists to name, which is the rule a query already obeys here. The three states are
|
|
44
|
+
what the pair of dictionaries actually says — recorded and equal, recorded and different, or
|
|
45
|
+
never recorded, the last being the silence :func:`unattested` returns and not a finding.
|
|
46
|
+
|
|
47
|
+
What this cannot say is *who*. There is no owner here for the same reason there is none on a
|
|
48
|
+
claim: the identity behind a write lives outside the repository, and the commit is where it
|
|
49
|
+
belongs. The claim made is only that the bytes were not put there by a verb.
|
|
50
|
+
"""
|
|
51
|
+
|
|
52
|
+
from __future__ import annotations
|
|
53
|
+
|
|
54
|
+
import hashlib
|
|
55
|
+
from dataclasses import dataclass
|
|
56
|
+
from enum import StrEnum
|
|
57
|
+
from pathlib import Path
|
|
58
|
+
|
|
59
|
+
from roadkeep.config import Config
|
|
60
|
+
from roadkeep.provenance import served_by
|
|
61
|
+
from roadkeep.remedying import Door
|
|
62
|
+
from roadkeep.storing import Store, path, read, write
|
|
63
|
+
|
|
64
|
+
#: What this module's rows are called inside the shared store (RK330). One file beside the
|
|
65
|
+
#: lock, one grammar, and this is the table — a second encoding for a second sidecar was
|
|
66
|
+
#: what made a fourth feature's fourth encoding the obvious next move.
|
|
67
|
+
TABLE = "writes"
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
@dataclass(frozen=True, slots=True)
|
|
71
|
+
class Unattested:
|
|
72
|
+
"""The governed files whose current bytes no verb wrote."""
|
|
73
|
+
|
|
74
|
+
#: Role and path, as this project spells it — a report quoting an absolute path is a
|
|
75
|
+
#: report about one machine.
|
|
76
|
+
files: tuple[tuple[str, str], ...]
|
|
77
|
+
#: The prefix this session's tools arrive under, or `""` where it has none (RK479). The
|
|
78
|
+
#: same field :class:`~roadkeep.guarding.Review` carries, and this was the last of the
|
|
79
|
+
#: four messages that block a turn still naming one route for every session — on the one
|
|
80
|
+
#: that is shown *once*, because reporting re-baselines. A field and not a call: one hook
|
|
81
|
+
#: process serves every repository a session touches, so it is a fact about this project.
|
|
82
|
+
served: str = ""
|
|
83
|
+
|
|
84
|
+
def __str__(self) -> str:
|
|
85
|
+
named = ", ".join(path for _, path in self.files)
|
|
86
|
+
plural = "s" if len(self.files) > 1 else ""
|
|
87
|
+
return "\n".join(
|
|
88
|
+
[
|
|
89
|
+
f"{named} changed since the last roadkeep verb wrote {'them' if plural else 'it'}, "
|
|
90
|
+
f"so whatever produced the current bytes was not one — an approved shell "
|
|
91
|
+
f"command, an editor, or a checkout. The line{plural} may be perfectly valid; "
|
|
92
|
+
f"what was missing is any record of who wrote {'them' if plural else 'it'}, "
|
|
93
|
+
f"and this is that record.",
|
|
94
|
+
"",
|
|
95
|
+
"Nothing is undone and nothing is asked back: the approval stands. Say which "
|
|
96
|
+
"command changed the file and end the turn again — this blocks once, and the "
|
|
97
|
+
"bytes that are there now are the new baseline.",
|
|
98
|
+
"",
|
|
99
|
+
# The second clause names no route on purpose: the refusal it points at has
|
|
100
|
+
# spelled both since RK24, so this line has one command to get right — and
|
|
101
|
+
# since RK488 it does not spell that one either, `Door.named` being the one
|
|
102
|
+
# reader of which spelling this session has.
|
|
103
|
+
f"`{Door(('lint',), '').named(self.served)}` judges the format; the verbs "
|
|
104
|
+
f"that write it are in the refusal every governed edit already prints.",
|
|
105
|
+
]
|
|
106
|
+
)
|
|
107
|
+
|
|
108
|
+
|
|
109
|
+
def attest(config: Config) -> None:
|
|
110
|
+
"""Record every governed file as the verb that just ran left it.
|
|
111
|
+
|
|
112
|
+
Called for its effect and never for an answer, so it raises nothing: a temp directory
|
|
113
|
+
that cannot be written is a missing record, not a failed write.
|
|
114
|
+
"""
|
|
115
|
+
_store(config, _digests(config))
|
|
116
|
+
|
|
117
|
+
|
|
118
|
+
def unattested(config: Config) -> Unattested | None:
|
|
119
|
+
"""The governed files whose bytes differ from what the last verb left, or ``None``.
|
|
120
|
+
|
|
121
|
+
Silence where nothing was ever recorded: a checkout in which no verb has run this
|
|
122
|
+
session has no baseline to differ from, and reporting every file in it would report the
|
|
123
|
+
history the project arrived with rather than anything this turn did.
|
|
124
|
+
"""
|
|
125
|
+
recorded = _recorded(config)
|
|
126
|
+
if not recorded:
|
|
127
|
+
return None
|
|
128
|
+
current = _digests(config)
|
|
129
|
+
found = tuple(
|
|
130
|
+
(role, config.relative(path))
|
|
131
|
+
for role, path in config.paths.items()
|
|
132
|
+
if role in recorded and recorded[role] != current.get(role)
|
|
133
|
+
)
|
|
134
|
+
if not found:
|
|
135
|
+
return None
|
|
136
|
+
_store(config, current)
|
|
137
|
+
return Unattested(files=found, served=served_by(config.root))
|
|
138
|
+
|
|
139
|
+
|
|
140
|
+
class State(StrEnum):
|
|
141
|
+
"""What the record says about one governed file (RK200).
|
|
142
|
+
|
|
143
|
+
Three, because the digest sidecar holds one thing and means three: a role it never
|
|
144
|
+
recorded is not a file that drifted, and reporting the two as one figure would count the
|
|
145
|
+
history a fresh checkout arrived with as something this turn did.
|
|
146
|
+
"""
|
|
147
|
+
|
|
148
|
+
#: The bytes on disk are the ones the last verb left.
|
|
149
|
+
ATTESTED = "attested"
|
|
150
|
+
#: They are not — an approved shell command, an editor, or a checkout. The row to act on.
|
|
151
|
+
UNATTESTED = "unattested"
|
|
152
|
+
#: No verb has run against this role, so there is nothing to differ from. Not a finding.
|
|
153
|
+
UNRECORDED = "unrecorded"
|
|
154
|
+
|
|
155
|
+
|
|
156
|
+
#: Unattested first: the axis a reader is scanning is what to act on, and the one row worth a
|
|
157
|
+
#: second look is the one a listing must not bury under the files that are fine.
|
|
158
|
+
_ORDER = (State.UNATTESTED, State.UNRECORDED, State.ATTESTED)
|
|
159
|
+
|
|
160
|
+
|
|
161
|
+
@dataclass(frozen=True, slots=True)
|
|
162
|
+
class Attested:
|
|
163
|
+
"""One governed file as the record and the disk together describe it (RK200)."""
|
|
164
|
+
|
|
165
|
+
role: str
|
|
166
|
+
#: As this project spells it — a report quoting an absolute path is one about a machine.
|
|
167
|
+
path: str
|
|
168
|
+
state: State
|
|
169
|
+
#: Whether the file is on disk at all: an absent one is `attested` where the record agrees
|
|
170
|
+
#: it is absent, and that reads as agreement rather than as a file nobody can find.
|
|
171
|
+
present: bool
|
|
172
|
+
|
|
173
|
+
def listed(self) -> str:
|
|
174
|
+
"""One row of the report. `(absent)` is said rather than left to the state column,
|
|
175
|
+
which answers a different question: whether the record and the disk agree."""
|
|
176
|
+
absent = "" if self.present else " (absent)"
|
|
177
|
+
return f" {str(self.state):<12} {self.role:<12} {self.path}{absent}"
|
|
178
|
+
|
|
179
|
+
def payload(self) -> dict[str, object]:
|
|
180
|
+
return {
|
|
181
|
+
"role": self.role,
|
|
182
|
+
"path": self.path,
|
|
183
|
+
"state": str(self.state),
|
|
184
|
+
"present": self.present,
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
|
|
188
|
+
@dataclass(frozen=True, slots=True)
|
|
189
|
+
class Survey:
|
|
190
|
+
"""Every governed role read against the record, and where the record lives (RK200).
|
|
191
|
+
|
|
192
|
+
A record and no longer a bare tuple (RK1170): the two registers were composed in the door
|
|
193
|
+
from a count, a path and a list, and none of the three was a fact the tuple carried.
|
|
194
|
+
"""
|
|
195
|
+
|
|
196
|
+
rows: tuple[Attested, ...]
|
|
197
|
+
#: The file itself, named for the reason the claim registry is (RK161): it is what an
|
|
198
|
+
#: operator deletes, and it lives outside the repository where nothing points at it.
|
|
199
|
+
record: str
|
|
200
|
+
|
|
201
|
+
@property
|
|
202
|
+
def unattested(self) -> int:
|
|
203
|
+
return sum(1 for row in self.rows if row.state is State.UNATTESTED)
|
|
204
|
+
|
|
205
|
+
@property
|
|
206
|
+
def unrun(self) -> bool:
|
|
207
|
+
"""Whether no verb has run in this checkout at all."""
|
|
208
|
+
return all(row.state is State.UNRECORDED for row in self.rows)
|
|
209
|
+
|
|
210
|
+
def stated(self) -> str:
|
|
211
|
+
rows = [f"{len(self.rows)} governed, {self.unattested} unattested"]
|
|
212
|
+
rows += [row.listed() for row in self.rows]
|
|
213
|
+
if self.unrun:
|
|
214
|
+
# The silence `unattested` returns, said out loud: a caller who cannot tell "no
|
|
215
|
+
# verb has run" from "nothing drifted" reads a fresh checkout as a clean one.
|
|
216
|
+
rows.append(" no verb has run in this checkout, so there is nothing to differ from")
|
|
217
|
+
rows.append(f" record {self.record}")
|
|
218
|
+
return "\n".join(rows)
|
|
219
|
+
|
|
220
|
+
def payload(self) -> dict[str, object]:
|
|
221
|
+
return {
|
|
222
|
+
"record": self.record,
|
|
223
|
+
"governed": len(self.rows),
|
|
224
|
+
"unattested": self.unattested,
|
|
225
|
+
"files": [row.payload() for row in self.rows],
|
|
226
|
+
}
|
|
227
|
+
|
|
228
|
+
|
|
229
|
+
def survey(config: Config) -> tuple[Attested, ...]:
|
|
230
|
+
"""Every declared role against the record, the rows to act on first (RK200).
|
|
231
|
+
|
|
232
|
+
The read :func:`unattested` was not. It takes no lock and **writes nothing** — the same
|
|
233
|
+
rule a query already obeys here, and the one thing that separates asking from the `Stop`
|
|
234
|
+
block, which consumes the fact it reports. Silence is not one of its answers either: a
|
|
235
|
+
checkout where no verb has run says so, per role, rather than returning nothing and
|
|
236
|
+
leaving the caller to guess whether that meant clean.
|
|
237
|
+
"""
|
|
238
|
+
recorded = _recorded(config)
|
|
239
|
+
current = _digests(config)
|
|
240
|
+
rows = [
|
|
241
|
+
Attested(
|
|
242
|
+
role=role,
|
|
243
|
+
path=config.relative(path),
|
|
244
|
+
state=_state(role, recorded, current),
|
|
245
|
+
present=current.get(role) is not None,
|
|
246
|
+
)
|
|
247
|
+
for role, path in config.paths.items()
|
|
248
|
+
]
|
|
249
|
+
return tuple(sorted(rows, key=lambda row: _ORDER.index(row.state)))
|
|
250
|
+
|
|
251
|
+
|
|
252
|
+
def _state(
|
|
253
|
+
role: str, recorded: dict[str, str | None], current: dict[str, str | None]
|
|
254
|
+
) -> State:
|
|
255
|
+
if role not in recorded:
|
|
256
|
+
return State.UNRECORDED
|
|
257
|
+
return State.ATTESTED if recorded[role] == current.get(role) else State.UNATTESTED
|
|
258
|
+
|
|
259
|
+
|
|
260
|
+
def record_path(root: Path | str) -> Path:
|
|
261
|
+
"""Where this checkout's digests live — in the shared store, outside the repository."""
|
|
262
|
+
return path(root)
|
|
263
|
+
|
|
264
|
+
|
|
265
|
+
def _digests(config: Config) -> dict[str, str | None]:
|
|
266
|
+
"""One digest per declared role, ``None`` for a file that is not on disk.
|
|
267
|
+
|
|
268
|
+
Absence is a value and not a gap: a governed file *deleted* by a shell command is the
|
|
269
|
+
change this most wants to state, and a dictionary that simply omitted it would read as
|
|
270
|
+
agreement with whatever was recorded before.
|
|
271
|
+
"""
|
|
272
|
+
out: dict[str, str | None] = {}
|
|
273
|
+
for role, path in config.paths.items():
|
|
274
|
+
try:
|
|
275
|
+
out[role] = hashlib.sha256(Path(path).read_bytes()).hexdigest()
|
|
276
|
+
except OSError:
|
|
277
|
+
out[role] = None
|
|
278
|
+
return out
|
|
279
|
+
|
|
280
|
+
|
|
281
|
+
def _recorded(config: Config) -> dict[str, str | None]:
|
|
282
|
+
"""The digests the last verb left, out of the shared store's own table (RK330)."""
|
|
283
|
+
return dict(read(config.root).writes)
|
|
284
|
+
|
|
285
|
+
|
|
286
|
+
def _store(config: Config, digests: dict[str, str | None]) -> None:
|
|
287
|
+
"""Replace this module's table, and leave the claims beside it exactly as they were.
|
|
288
|
+
|
|
289
|
+
Read-modify-write under the checkout's exclusive lock, which is where every writer of
|
|
290
|
+
the store runs (:func:`roadkeep.cli.dispatch`) — and where this one in particular runs,
|
|
291
|
+
the record being taken after the handler and before the lock is given up.
|
|
292
|
+
"""
|
|
293
|
+
write(config.root, Store(claims=read(config.root).claims, writes=digests))
|