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/storing.py
ADDED
|
@@ -0,0 +1,224 @@
|
|
|
1
|
+
"""The one grammar for everything this tool keeps outside the documents (RK330).
|
|
2
|
+
|
|
3
|
+
Three features needed state a governed file cannot hold, and each invented an encoding for
|
|
4
|
+
it: `claiming` (RK119) wrote `<id> <epoch>` with tab-separated paths and parsed it by hand,
|
|
5
|
+
skipping any line it could not read; `attesting` (RK175) wrote JSON; `locking` (RK117) put
|
|
6
|
+
its whole state in a filename. Each was right alone, and the third was the trend — a fourth
|
|
7
|
+
feature would have invented a fourth, and no two of them could be held to one property test.
|
|
8
|
+
|
|
9
|
+
So the two that hold *rows* share this one, and the lock does not: its state is the
|
|
10
|
+
existence of a file, which is the one atomic primitive both platforms give (`O_CREAT |
|
|
11
|
+
O_EXCL`), and a lock that had to be parsed to be taken would be a lock with a race in it.
|
|
12
|
+
What it shares instead is :func:`~roadkeep.locking.sidecar` — one answer to "which checkout
|
|
13
|
+
is this", which is what kept a third spelling of it from appearing here.
|
|
14
|
+
|
|
15
|
+
**Exactly one writer**, which is what makes the grammar cheap. `roadkeep.toml` cannot be
|
|
16
|
+
governed because a person wrote its comments and chose its spellings (RK325); a file only
|
|
17
|
+
this tool writes has a canonical rendering, so L3's parse-render-compare is a property test
|
|
18
|
+
over :func:`render` rather than a negotiation with somebody's formatting. TOML is what that
|
|
19
|
+
costs: `tomllib` reads and does not write, and the runtime has zero dependencies on purpose
|
|
20
|
+
(`agents.md`), so the renderer below is the price — paid once, for a store several features
|
|
21
|
+
share, and not for the queue.
|
|
22
|
+
|
|
23
|
+
Two boundaries keep it from becoming the database L2 refuses:
|
|
24
|
+
|
|
25
|
+
* **No fact about a task.** Status, deps and order live in the documents, which is why the
|
|
26
|
+
priority queue went to the roadmap and not here. What this holds is *when* a claim was
|
|
27
|
+
taken, *what* its commit says it owns, and the digest of bytes a verb left — three things
|
|
28
|
+
that are true of a checkout and of no task.
|
|
29
|
+
* **Transient stays transient.** It lives in the temp directory beside the lock, keyed by
|
|
30
|
+
the resolved root, and deleting it while nothing is running loses nothing: every claim
|
|
31
|
+
reads as expired and every file as unrecorded, which is the behaviour before any of this
|
|
32
|
+
existed. A committed store is a second decision, and this one does not presume it.
|
|
33
|
+
|
|
34
|
+
Which is also the answer to the format change itself. A session upgrading across it loses
|
|
35
|
+
the dates it was holding, and that is the same loss as a temp directory swept between two
|
|
36
|
+
commands — the 🛠 lines are still in the roadmap, and they are offered again as half-done
|
|
37
|
+
work. Nothing reads the old spellings, because a reader kept for one release is the second
|
|
38
|
+
grammar this exists to remove.
|
|
39
|
+
|
|
40
|
+
Every failure is silence, on the argument :mod:`roadkeep.guarding` already makes: an
|
|
41
|
+
unreadable sidecar loses a date and never a task, so a `pick` is not refused because a temp
|
|
42
|
+
file went missing.
|
|
43
|
+
"""
|
|
44
|
+
|
|
45
|
+
from __future__ import annotations
|
|
46
|
+
|
|
47
|
+
import os
|
|
48
|
+
import tomllib
|
|
49
|
+
from collections.abc import Mapping
|
|
50
|
+
from dataclasses import dataclass, field
|
|
51
|
+
from pathlib import Path
|
|
52
|
+
|
|
53
|
+
from roadkeep.locking import sidecar
|
|
54
|
+
|
|
55
|
+
#: The sidecar's suffix. One file, because the point of the exercise is one door: two files
|
|
56
|
+
#: sharing a renderer would still be two things to find, and the writers are already
|
|
57
|
+
#: serialised by the same lock (:func:`roadkeep.cli.dispatch`).
|
|
58
|
+
SUFFIX = "state"
|
|
59
|
+
|
|
60
|
+
#: What a rendered store opens with. Not decoration: a person who finds this in a temp
|
|
61
|
+
#: directory is deciding whether deleting it costs them anything, and the answer is here
|
|
62
|
+
#: rather than in the documentation of a tool they may not have.
|
|
63
|
+
HEADER = (
|
|
64
|
+
"# roadkeep transient state for this checkout. Written only by roadkeep; safe to\n"
|
|
65
|
+
"# delete while nothing is running — every claim then reads as expired and every\n"
|
|
66
|
+
"# governed file as unrecorded. Nothing here is a fact about a task (RK330).\n"
|
|
67
|
+
)
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
@dataclass(frozen=True, slots=True)
|
|
71
|
+
class Claim:
|
|
72
|
+
"""One held line as it is on disk: when it was taken, and what it says it will touch."""
|
|
73
|
+
|
|
74
|
+
when: float
|
|
75
|
+
paths: tuple[str, ...] = ()
|
|
76
|
+
|
|
77
|
+
|
|
78
|
+
@dataclass(frozen=True, slots=True)
|
|
79
|
+
class Store:
|
|
80
|
+
"""Everything one checkout keeps outside its documents.
|
|
81
|
+
|
|
82
|
+
Two tables and one type, so a third feature extends *this* rather than opening a fourth
|
|
83
|
+
file. Both default empty, because the store is allowed to be missing and a caller that
|
|
84
|
+
had to distinguish "absent" from "empty" would be reading durability into a temp file.
|
|
85
|
+
"""
|
|
86
|
+
|
|
87
|
+
#: Task id → the claim on it. See :mod:`roadkeep.claiming` for what a date means.
|
|
88
|
+
claims: Mapping[str, Claim] = field(default_factory=dict)
|
|
89
|
+
#: Role → digest of the bytes the last verb left, ``None`` where the file was absent.
|
|
90
|
+
#: Absence is a value: a governed file deleted by a shell command is the change
|
|
91
|
+
#: :mod:`roadkeep.attesting` most wants to state (RK175).
|
|
92
|
+
writes: Mapping[str, str | None] = field(default_factory=dict)
|
|
93
|
+
|
|
94
|
+
|
|
95
|
+
def path(root: Path | str) -> Path:
|
|
96
|
+
"""Where this checkout's transient state lives — outside it, keyed by its resolved path."""
|
|
97
|
+
return sidecar(root, SUFFIX)
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
def read(root: Path | str) -> Store:
|
|
101
|
+
"""The store as it is on disk, or an empty one where it cannot be read.
|
|
102
|
+
|
|
103
|
+
Unreadable is *empty* and never an error, for the reason the hand-parsed registry had
|
|
104
|
+
the same rule: the file is transient, and refusing to answer a query because a temp file
|
|
105
|
+
is half-written would make the answer depend on the one thing allowed to disappear.
|
|
106
|
+
"""
|
|
107
|
+
try:
|
|
108
|
+
raw = path(root).read_text(encoding="utf-8")
|
|
109
|
+
except OSError:
|
|
110
|
+
return Store()
|
|
111
|
+
return parse(raw)
|
|
112
|
+
|
|
113
|
+
|
|
114
|
+
def write(root: Path | str, store: Store) -> None:
|
|
115
|
+
"""Replace the store in one step, and never fail the command that was answering.
|
|
116
|
+
|
|
117
|
+
Written aside and renamed because the *readers* take no lock — `pick` is a query (RK117)
|
|
118
|
+
— so a reader catching a half-written file would lose the tail of it, which is claims
|
|
119
|
+
read as expired and lines handed out twice. Best-effort: an OSError here loses a date,
|
|
120
|
+
never a task.
|
|
121
|
+
"""
|
|
122
|
+
target = path(root)
|
|
123
|
+
staged = target.parent / f"{target.name}.writing"
|
|
124
|
+
try:
|
|
125
|
+
staged.write_text(render(store), encoding="utf-8")
|
|
126
|
+
os.replace(staged, target)
|
|
127
|
+
except OSError:
|
|
128
|
+
pass
|
|
129
|
+
|
|
130
|
+
|
|
131
|
+
def parse(raw: str) -> Store:
|
|
132
|
+
"""Read a rendered store back, keeping every row this grammar can type.
|
|
133
|
+
|
|
134
|
+
A row it cannot is dropped and never raised, which is :func:`read`'s rule one level
|
|
135
|
+
down: a claim whose date is not a number says nothing about a task, and the file it is
|
|
136
|
+
in is one a caller is allowed to delete.
|
|
137
|
+
"""
|
|
138
|
+
try:
|
|
139
|
+
data = tomllib.loads(raw)
|
|
140
|
+
except ValueError: # TOMLDecodeError is one, and a half-written file is not an error.
|
|
141
|
+
return Store()
|
|
142
|
+
claims: dict[str, Claim] = {}
|
|
143
|
+
for task_id, row in _table(data.get("claims")).items():
|
|
144
|
+
if not isinstance(row, dict) or not isinstance(row.get("when"), (int, float)):
|
|
145
|
+
continue
|
|
146
|
+
paths = row.get("paths", [])
|
|
147
|
+
claims[task_id] = Claim(
|
|
148
|
+
when=float(row["when"]),
|
|
149
|
+
paths=tuple(one for one in paths if isinstance(one, str) and one)
|
|
150
|
+
if isinstance(paths, list)
|
|
151
|
+
else (),
|
|
152
|
+
)
|
|
153
|
+
writes = {
|
|
154
|
+
role: (None if value == ABSENT else value)
|
|
155
|
+
for role, value in _table(data.get("writes")).items()
|
|
156
|
+
if isinstance(value, str)
|
|
157
|
+
}
|
|
158
|
+
return Store(claims=claims, writes=writes)
|
|
159
|
+
|
|
160
|
+
|
|
161
|
+
#: How a file that is not on disk is spelled. TOML has no null and the distinction is load
|
|
162
|
+
#: bearing — an omitted role means *never recorded*, which is not a finding, while a
|
|
163
|
+
#: recorded absence means a verb watched the file go (RK175). The empty string is free for
|
|
164
|
+
#: it: no digest is empty.
|
|
165
|
+
ABSENT = ""
|
|
166
|
+
|
|
167
|
+
|
|
168
|
+
def render(store: Store) -> str:
|
|
169
|
+
"""The store's one canonical spelling — the thing L3's round-trip is a property of.
|
|
170
|
+
|
|
171
|
+
Sorted throughout, so two runs that hold the same rows produce the same bytes and a
|
|
172
|
+
person reading the file finds an id where they left it. Paths keep the order they were
|
|
173
|
+
declared in: that order is what a `git add --` consumes (RK280), so it is data.
|
|
174
|
+
"""
|
|
175
|
+
out = [HEADER]
|
|
176
|
+
for task_id, claim in sorted(store.claims.items()):
|
|
177
|
+
out.append(f"\n[claims.{_key(task_id)}]\n")
|
|
178
|
+
out.append(f"when = {claim.when:.6f}\n")
|
|
179
|
+
if claim.paths:
|
|
180
|
+
out.append("paths = [" + ", ".join(_string(p) for p in claim.paths) + "]\n")
|
|
181
|
+
if store.writes:
|
|
182
|
+
out.append("\n[writes]\n")
|
|
183
|
+
for role, digest in sorted(store.writes.items()):
|
|
184
|
+
out.append(f"{_key(role)} = {_string(ABSENT if digest is None else digest)}\n")
|
|
185
|
+
return "".join(out)
|
|
186
|
+
|
|
187
|
+
|
|
188
|
+
def _table(value: object) -> dict[str, object]:
|
|
189
|
+
"""One declared table, or nothing — a store whose `claims` is a string holds no claims."""
|
|
190
|
+
return {k: v for k, v in value.items() if isinstance(k, str)} if isinstance(value, dict) else {}
|
|
191
|
+
|
|
192
|
+
|
|
193
|
+
def _key(name: str) -> str:
|
|
194
|
+
"""A task id or a role as a TOML key: bare where it can be, quoted where it cannot.
|
|
195
|
+
|
|
196
|
+
Ids are `[ids] pattern`'s to shape and roles are the project's to name (L6), so neither
|
|
197
|
+
is this module's to constrain — and a store that refused a key would take a checkout out
|
|
198
|
+
of service over the spelling of a temp file.
|
|
199
|
+
"""
|
|
200
|
+
ok = name and all(c.isalnum() and c.isascii() or c in "-_" for c in name)
|
|
201
|
+
return name if ok else _string(name)
|
|
202
|
+
|
|
203
|
+
|
|
204
|
+
def _string(value: str) -> str:
|
|
205
|
+
"""A TOML basic string. Enough escaping for a path and a digest, and no more.
|
|
206
|
+
|
|
207
|
+
A Windows path carries backslashes and the registry's old grammar used a tab as its
|
|
208
|
+
separator, so both have reached this data; anything else TOML forbids unescaped is a
|
|
209
|
+
typo somebody still gets to read back, rather than a file that stops parsing.
|
|
210
|
+
"""
|
|
211
|
+
body = value.replace("\\", "\\\\").replace('"', '\\"')
|
|
212
|
+
return '"' + "".join(_escaped(c) for c in body) + '"'
|
|
213
|
+
|
|
214
|
+
|
|
215
|
+
def _escaped(char: str) -> str:
|
|
216
|
+
"""One character as TOML will read it back — control codes and U+007F spelled out."""
|
|
217
|
+
if char in _SHORT:
|
|
218
|
+
return _SHORT[char]
|
|
219
|
+
if char < " " or char == "\x7f":
|
|
220
|
+
return f"\\u{ord(char):04x}"
|
|
221
|
+
return char
|
|
222
|
+
|
|
223
|
+
|
|
224
|
+
_SHORT = {"\n": "\\n", "\r": "\\r", "\t": "\\t", "\b": "\\b", "\f": "\\f"}
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
"""One module per verb family, and where a handler lives is what its verb does (RK494).
|
|
2
|
+
|
|
3
|
+
`cli.py` grew to 8,489 lines holding the parser, the handlers and every printer. RK493 took
|
|
4
|
+
the printers; this takes the handlers, which were the part with no name — each reached
|
|
5
|
+
through `set_defaults(handler=…)` and grouped by nothing, so 82 concepts shared one
|
|
6
|
+
docstring while every other module in the package is one gerund its own docstring is the
|
|
7
|
+
authority on.
|
|
8
|
+
|
|
9
|
+
The names are the domain modules' own, and where a handler lives is derived from what its
|
|
10
|
+
verb does: the command that writes a task line sits in :mod:`roadkeep.verbs.authoring`,
|
|
11
|
+
beside the module it calls. Two more hold what a verb needs before it has an answer —
|
|
12
|
+
:mod:`roadkeep.verbs.refusing` for the exit codes and the one translation of a raised error
|
|
13
|
+
into one, and :mod:`roadkeep.verbs.reading` for the prose that arrives on a pipe or a path.
|
|
14
|
+
|
|
15
|
+
The import direction is `build_parser` importing these, never the other way, which is why
|
|
16
|
+
RK493 was a dep: a handler still reaching a printer left in `cli.py` would import the module
|
|
17
|
+
that imports it. Two of them genuinely need the parser — `repair` runs whole commands back
|
|
18
|
+
through it and `merge` names the flag its own parser declared — and both take it through a
|
|
19
|
+
function-level import, which is how :mod:`roadkeep.serving` and :mod:`roadkeep.capturing`
|
|
20
|
+
already reach the same two names.
|
|
21
|
+
|
|
22
|
+
What did not move, and why this is a split and not a rewrite: `build_parser` stays one
|
|
23
|
+
function, because :mod:`roadkeep.serving` derives every MCP tool, its description and its
|
|
24
|
+
stdin declaration from that one object; and `dispatch` stays one, because RK489's rule is
|
|
25
|
+
that one place refuses two answers.
|
|
26
|
+
"""
|