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/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
+ """