roadkeep 0.2.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (67) hide show
  1. roadkeep/__init__.py +79 -0
  2. roadkeep/adopting.py +2347 -0
  3. roadkeep/attesting.py +293 -0
  4. roadkeep/authoring.py +2117 -0
  5. roadkeep/backlog.py +767 -0
  6. roadkeep/blocking.py +1622 -0
  7. roadkeep/briefing.py +970 -0
  8. roadkeep/budgeting.py +2056 -0
  9. roadkeep/capturing.py +1699 -0
  10. roadkeep/claiming.py +1019 -0
  11. roadkeep/cli.py +638 -0
  12. roadkeep/commanding.py +487 -0
  13. roadkeep/config.py +1832 -0
  14. roadkeep/counting.py +376 -0
  15. roadkeep/criteria.py +933 -0
  16. roadkeep/deferring.py +708 -0
  17. roadkeep/describing.py +568 -0
  18. roadkeep/exporting.py +808 -0
  19. roadkeep/fixing.py +629 -0
  20. roadkeep/governing.py +934 -0
  21. roadkeep/graph.py +395 -0
  22. roadkeep/guarding.py +1028 -0
  23. roadkeep/history.py +2403 -0
  24. roadkeep/ids.py +301 -0
  25. roadkeep/installing.py +2145 -0
  26. roadkeep/kernel/__init__.py +24 -0
  27. roadkeep/kernel/document.py +1719 -0
  28. roadkeep/kernel/schema.py +2308 -0
  29. roadkeep/linting.py +4420 -0
  30. roadkeep/locking.py +209 -0
  31. roadkeep/markers.py +172 -0
  32. roadkeep/merging.py +1159 -0
  33. roadkeep/picking.py +772 -0
  34. roadkeep/provenance.py +789 -0
  35. roadkeep/queueing.py +752 -0
  36. roadkeep/ranking.py +139 -0
  37. roadkeep/referring.py +231 -0
  38. roadkeep/remaining.py +336 -0
  39. roadkeep/remedying.py +1989 -0
  40. roadkeep/rendering.py +1601 -0
  41. roadkeep/renumbering.py +503 -0
  42. roadkeep/repairing.py +295 -0
  43. roadkeep/reverting.py +144 -0
  44. roadkeep/scoping.py +708 -0
  45. roadkeep/screening.py +196 -0
  46. roadkeep/sections.py +4121 -0
  47. roadkeep/serving.py +2909 -0
  48. roadkeep/shipping.py +3993 -0
  49. roadkeep/showing.py +613 -0
  50. roadkeep/storing.py +224 -0
  51. roadkeep/verbs/__init__.py +26 -0
  52. roadkeep/verbs/adopting.py +974 -0
  53. roadkeep/verbs/authoring.py +566 -0
  54. roadkeep/verbs/declaring.py +335 -0
  55. roadkeep/verbs/linting.py +645 -0
  56. roadkeep/verbs/querying.py +2138 -0
  57. roadkeep/verbs/reading.py +307 -0
  58. roadkeep/verbs/refusing.py +146 -0
  59. roadkeep/verbs/sections.py +1433 -0
  60. roadkeep/verbs/shipping.py +819 -0
  61. roadkeep/weighing.py +380 -0
  62. roadkeep-0.2.0.dist-info/METADATA +453 -0
  63. roadkeep-0.2.0.dist-info/RECORD +67 -0
  64. roadkeep-0.2.0.dist-info/WHEEL +5 -0
  65. roadkeep-0.2.0.dist-info/entry_points.txt +2 -0
  66. roadkeep-0.2.0.dist-info/licenses/LICENSE +202 -0
  67. roadkeep-0.2.0.dist-info/top_level.txt +1 -0
roadkeep/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))