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/ids.py
ADDED
|
@@ -0,0 +1,301 @@
|
|
|
1
|
+
"""Deriving the next id (RK4).
|
|
2
|
+
|
|
3
|
+
Real backlogs are non-contiguous: an epic claims a sub-range, a superseded task is
|
|
4
|
+
retired and its id is never reused, and a block's header range says nothing about what
|
|
5
|
+
comes next. So the next id is **one past the highest id anywhere**, and the two words
|
|
6
|
+
that matter are *highest* and *anywhere*.
|
|
7
|
+
|
|
8
|
+
* **Highest, not first-free.** Filling the hole left by a retired id makes two
|
|
9
|
+
different tasks share a number in the history — a `git log -S RK7` that returns two
|
|
10
|
+
unrelated designs is worse than a gap.
|
|
11
|
+
* **Anywhere.** The changelog holds shipped ids, `agents.md` mentions ids in prose, and
|
|
12
|
+
either is enough to make a "free" id a collision. Every file in
|
|
13
|
+
:meth:`Config.id_sources` is scanned as text, not as a task list.
|
|
14
|
+
|
|
15
|
+
A counter file would be a second source of truth, and it would drift the first time
|
|
16
|
+
someone edited the roadmap by hand. The maximum is derivable, so it is derived — and
|
|
17
|
+
the result carries *where* it came from, because an id is the one decision that cannot
|
|
18
|
+
be taken back once it is committed.
|
|
19
|
+
"""
|
|
20
|
+
|
|
21
|
+
from __future__ import annotations
|
|
22
|
+
|
|
23
|
+
import re
|
|
24
|
+
from collections.abc import Sequence
|
|
25
|
+
from dataclasses import dataclass
|
|
26
|
+
from pathlib import Path
|
|
27
|
+
|
|
28
|
+
from roadkeep.config import Config
|
|
29
|
+
from roadkeep.kernel.schema import Schema
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
@dataclass(frozen=True, slots=True)
|
|
33
|
+
class IdRef:
|
|
34
|
+
"""One occurrence of an id, and where it was found."""
|
|
35
|
+
|
|
36
|
+
id: str
|
|
37
|
+
number: int
|
|
38
|
+
path: Path
|
|
39
|
+
lineno: int
|
|
40
|
+
#: Which family it belongs to (RK74). Carried rather than re-derived, because the
|
|
41
|
+
#: maximum `next_id` takes is a maximum *within* a family and the scan is the only
|
|
42
|
+
#: place that already knows which one matched.
|
|
43
|
+
family: str = ""
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
def id_scanner(schema: Schema) -> re.Pattern[str]:
|
|
47
|
+
"""`<prefix><n>` as it appears in running text, spelled the way this project spells it.
|
|
48
|
+
|
|
49
|
+
Three named groups, always: `family`, the `number` the maximum is taken over, and the
|
|
50
|
+
`sub` letter — empty where `[ids] suffix` declares none, so a caller reads the same
|
|
51
|
+
shape whatever the project wrote.
|
|
52
|
+
|
|
53
|
+
Takes the schema and not the prefixes alone (RK106), because padding and the
|
|
54
|
+
sub-letter are two more declarations about what an id *is*: a scan that knew only the
|
|
55
|
+
family would read `T24b` as no id at all, and the number a document already spends is
|
|
56
|
+
exactly what the next one must clear. It asks the schema to *join* them too (RK109) —
|
|
57
|
+
this used to assemble its own copy, and a scan spelling an id differently from the gate
|
|
58
|
+
is how a number the pattern refuses stays invisible to the counter that would clear it.
|
|
59
|
+
"""
|
|
60
|
+
return re.compile(rf"\b{schema.id_groups}\b")
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
def scan(config: Config) -> tuple[IdRef, ...]:
|
|
64
|
+
"""Every id occurrence in every configured source, in file order.
|
|
65
|
+
|
|
66
|
+
A source that does not exist is skipped rather than raised: `init` (RK18) creates
|
|
67
|
+
the files, and refusing to answer "what is the next id" because a strategy file is
|
|
68
|
+
absent would be an obstacle rather than a guardrail.
|
|
69
|
+
"""
|
|
70
|
+
pattern = id_scanner(config.schema)
|
|
71
|
+
found: list[IdRef] = []
|
|
72
|
+
# The reservations first, as occurrences of the config itself (RK1031): an epic id owns a
|
|
73
|
+
# sub-range and is never written as a line, so a scan over the files alone would hand the
|
|
74
|
+
# next `add` an address the project has already spoken for. `source` is the file that
|
|
75
|
+
# declares them, which is what makes the provenance a reader can act on.
|
|
76
|
+
declared_at = _declared_at(config)
|
|
77
|
+
for token in config.reserved:
|
|
78
|
+
match = pattern.fullmatch(token)
|
|
79
|
+
if match is not None:
|
|
80
|
+
found.append(
|
|
81
|
+
IdRef(
|
|
82
|
+
id=token,
|
|
83
|
+
number=int(match.group("number")),
|
|
84
|
+
path=config.source or config.root,
|
|
85
|
+
lineno=declared_at.get(token, 0),
|
|
86
|
+
family=match.group("family"),
|
|
87
|
+
)
|
|
88
|
+
)
|
|
89
|
+
for path in config.id_sources():
|
|
90
|
+
if not path.is_file():
|
|
91
|
+
continue
|
|
92
|
+
with path.open("r", encoding="utf-8", newline="") as handle:
|
|
93
|
+
for lineno, line in enumerate(handle, start=1):
|
|
94
|
+
for match in pattern.finditer(line):
|
|
95
|
+
found.append(
|
|
96
|
+
IdRef(
|
|
97
|
+
id=match.group(0),
|
|
98
|
+
number=int(match.group("number")),
|
|
99
|
+
path=path,
|
|
100
|
+
lineno=lineno,
|
|
101
|
+
family=match.group("family"),
|
|
102
|
+
)
|
|
103
|
+
)
|
|
104
|
+
return tuple(found)
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
def _declared_at(config: Config) -> dict[str, int]:
|
|
108
|
+
"""Which line of `roadkeep.toml` each reservation is written on (RK1031).
|
|
109
|
+
|
|
110
|
+
A refusal names `file:line` and a reader clicks it, so `roadkeep.toml:0` would be the one
|
|
111
|
+
address in this tool that opens nothing. Read off the text rather than tracked through
|
|
112
|
+
the parse: `tomllib` keeps no positions, and a config that spells its list across four
|
|
113
|
+
lines is the shape a project with four epics writes.
|
|
114
|
+
"""
|
|
115
|
+
if not config.reserved or config.source is None:
|
|
116
|
+
return {}
|
|
117
|
+
try:
|
|
118
|
+
text = config.source.read_text(encoding="utf-8")
|
|
119
|
+
except OSError:
|
|
120
|
+
return {}
|
|
121
|
+
found: dict[str, int] = {}
|
|
122
|
+
for lineno, line in enumerate(text.splitlines(), start=1):
|
|
123
|
+
for token in config.reserved:
|
|
124
|
+
if token not in found and f'"{token}"' in line:
|
|
125
|
+
found[token] = lineno
|
|
126
|
+
return found
|
|
127
|
+
|
|
128
|
+
|
|
129
|
+
def highest(config: Config, family: str | None = None) -> IdRef | None:
|
|
130
|
+
"""The largest id, with its provenance. None when that family has no ids yet.
|
|
131
|
+
|
|
132
|
+
``family`` defaults to every one the project declares, which is the same answer as
|
|
133
|
+
before for the projects that declare one. It is passed by :func:`next_id`, where the
|
|
134
|
+
maximum has to be per family (RK74): two tracks sharing a counter are two tracks that
|
|
135
|
+
renumber each other, and cursarei's `C##` reaching 40 must not push `V##` past its 05.
|
|
136
|
+
"""
|
|
137
|
+
refs = [ref for ref in scan(config) if family is None or ref.family == family]
|
|
138
|
+
if not refs:
|
|
139
|
+
return None
|
|
140
|
+
return max(refs, key=lambda ref: ref.number)
|
|
141
|
+
|
|
142
|
+
|
|
143
|
+
#: The roles whose files carry an id as a **line** — a task, an entry, a paused line. Every
|
|
144
|
+
#: other occurrence of an id anywhere is a mention in a sentence, and the scan cannot tell
|
|
145
|
+
#: the two apart because every id starts as one (RK431).
|
|
146
|
+
CARRIERS = ("roadmap", "changelog", "deferred")
|
|
147
|
+
|
|
148
|
+
|
|
149
|
+
def carried(config: Config) -> frozenset[str]:
|
|
150
|
+
"""Every id some governed file holds as a line rather than names in a sentence.
|
|
151
|
+
|
|
152
|
+
Read off the parsed documents and not off the scan: the scan is deliberately textual
|
|
153
|
+
(that is what makes `agents.md` count), and what is wanted here is the complement —
|
|
154
|
+
the ids that are *occupied*, which only a parse can say.
|
|
155
|
+
"""
|
|
156
|
+
# The reservations are among them (RK1031): a reserved id is *taken*, so a design naming
|
|
157
|
+
# one names work this project has spoken for rather than promising an address. What it is
|
|
158
|
+
# not is a line, which is why `lint` still reports one that becomes a line.
|
|
159
|
+
out: set[str] = set(config.reserved)
|
|
160
|
+
for role in CARRIERS:
|
|
161
|
+
if not config.has(role) or not config.path(role).is_file():
|
|
162
|
+
continue
|
|
163
|
+
out.update(config.document(role).by_id())
|
|
164
|
+
return frozenset(out)
|
|
165
|
+
|
|
166
|
+
|
|
167
|
+
@dataclass(frozen=True, slots=True)
|
|
168
|
+
class Promise:
|
|
169
|
+
"""An id a sentence named and no line ever took (RK431)."""
|
|
170
|
+
|
|
171
|
+
#: The id the prose promised — one below :attr:`derived`, and the number the author
|
|
172
|
+
#: probably meant this task to have.
|
|
173
|
+
id: str
|
|
174
|
+
#: Where the sentence is, relative to the project root, as `file:line`.
|
|
175
|
+
where: str
|
|
176
|
+
#: The id handed out instead, because the mention had already raised the maximum.
|
|
177
|
+
derived: str
|
|
178
|
+
|
|
179
|
+
@property
|
|
180
|
+
def sentence(self) -> str:
|
|
181
|
+
"""The one spelling, so `add` and `next-id` say it in the same words."""
|
|
182
|
+
return (
|
|
183
|
+
f"{self.id} is named at {self.where} and no line carries it, so {self.derived} "
|
|
184
|
+
f"was derived past it: if that sentence promised this task, it now names an id "
|
|
185
|
+
f"nothing will occupy"
|
|
186
|
+
)
|
|
187
|
+
|
|
188
|
+
|
|
189
|
+
@dataclass(frozen=True, slots=True)
|
|
190
|
+
class Derivation:
|
|
191
|
+
"""The next id, and the promise deriving it stepped over (RK431)."""
|
|
192
|
+
|
|
193
|
+
id: str
|
|
194
|
+
#: None on the overwhelming majority of derivations, where the highest id is a line.
|
|
195
|
+
promise: Promise | None = None
|
|
196
|
+
|
|
197
|
+
def stated(self) -> str:
|
|
198
|
+
"""The id and nothing else.
|
|
199
|
+
|
|
200
|
+
Stdout here is the id, because this command exists to be captured in a shell — a
|
|
201
|
+
second line in that capture is a broken id, which is why the promise goes to stderr.
|
|
202
|
+
"""
|
|
203
|
+
return self.id
|
|
204
|
+
|
|
205
|
+
def notice(self) -> list[str]:
|
|
206
|
+
"""The promise deriving this stepped over, for **stderr** (RK431)."""
|
|
207
|
+
return [] if self.promise is None else [f"roadkeep: {self.promise.sentence}"]
|
|
208
|
+
|
|
209
|
+
def payload(self, config: Config, family: str) -> dict[str, object]:
|
|
210
|
+
"""The same answer with where the maximum was found, so it can be audited."""
|
|
211
|
+
from roadkeep.rendering import _promise_json # noqa: PLC0415 - RK260
|
|
212
|
+
|
|
213
|
+
top = highest(config, family)
|
|
214
|
+
return {
|
|
215
|
+
"next": self.id,
|
|
216
|
+
"prefix": family,
|
|
217
|
+
"prefixes": list(config.schema.prefixes),
|
|
218
|
+
"highest": None
|
|
219
|
+
if top is None
|
|
220
|
+
else {
|
|
221
|
+
"id": top.id,
|
|
222
|
+
"file": config.relative(top.path),
|
|
223
|
+
"line": top.lineno,
|
|
224
|
+
},
|
|
225
|
+
# Beside `highest` and not folded into it (RK431): that field says which
|
|
226
|
+
# occurrence set the maximum, and this says the occurrence was a sentence rather
|
|
227
|
+
# than a line — which is the whole difference nothing recorded.
|
|
228
|
+
"promise": _promise_json(self.promise),
|
|
229
|
+
"sources": [
|
|
230
|
+
config.relative(path) for path in config.id_sources() if path.is_file()
|
|
231
|
+
],
|
|
232
|
+
}
|
|
233
|
+
|
|
234
|
+
|
|
235
|
+
def derivation(config: Config, family: str | None = None) -> Derivation:
|
|
236
|
+
"""The next id, and whether the number below it was a promise nobody kept (RK431).
|
|
237
|
+
|
|
238
|
+
Shipping SH207 meant recording a defect it had uncovered, and the ledger entry said
|
|
239
|
+
*"filed as SH614"* — the id `next-id` had just reported. `add` then handed the new task
|
|
240
|
+
**SH615**, because the entry had by then been written into a file the scan reads, so
|
|
241
|
+
the highest id in the corpus was the one the sentence had promised. Nothing
|
|
242
|
+
malfunctioned: the deriver cannot tell an id that was *declared* from one merely
|
|
243
|
+
*mentioned*, and every id starts as a mention.
|
|
244
|
+
|
|
245
|
+
The cost is quiet — the `add` succeeds, the number looks unremarkable, and the only
|
|
246
|
+
signal is a prose reference to an id nothing will occupy, in a file the guard forbids
|
|
247
|
+
hand-editing. It is also a gap `gaps` cannot cover: that verb explains an id in neither
|
|
248
|
+
file, and this one *is* in one.
|
|
249
|
+
|
|
250
|
+
So the derivation says so, and does nothing else. It does not reserve the number
|
|
251
|
+
(a second source of truth, which is the counter file this module exists without) and
|
|
252
|
+
it does not refuse: which of the two ids the author wanted is a judgement about the
|
|
253
|
+
meaning of a sentence, and this tool has no model of one (L4).
|
|
254
|
+
"""
|
|
255
|
+
chosen = family or config.schema.prefix
|
|
256
|
+
if chosen not in config.schema.prefixes:
|
|
257
|
+
raise UnknownFamily(chosen, config.schema.prefixes)
|
|
258
|
+
top = highest(config, chosen)
|
|
259
|
+
number = top.number + 1 if top else 1
|
|
260
|
+
identifier = config.schema.spell_id(chosen, number)
|
|
261
|
+
if top is None or top.id in carried(config):
|
|
262
|
+
return Derivation(identifier)
|
|
263
|
+
return Derivation(
|
|
264
|
+
identifier,
|
|
265
|
+
Promise(
|
|
266
|
+
id=top.id,
|
|
267
|
+
where=f"{config.relative(top.path)}:{top.lineno}",
|
|
268
|
+
derived=identifier,
|
|
269
|
+
),
|
|
270
|
+
)
|
|
271
|
+
|
|
272
|
+
|
|
273
|
+
def next_id(config: Config, family: str | None = None) -> str:
|
|
274
|
+
"""One past the highest id *in this family*, never the first unused number.
|
|
275
|
+
|
|
276
|
+
``family`` is the caller's declaration, defaulting to the first the project declares.
|
|
277
|
+
Nothing infers it: the letter is which track the work belongs to, and a tool that
|
|
278
|
+
guessed it from a block heading would be holding an opinion about someone else's
|
|
279
|
+
backlog (RK74).
|
|
280
|
+
|
|
281
|
+
Spelled by :meth:`Schema.spell_id`, so a project that declared a width gets `D10` and
|
|
282
|
+
not the `D1` its own gate would refuse a moment later (RK106).
|
|
283
|
+
|
|
284
|
+
The id alone, for the callers that only need one. :func:`derivation` is the same answer
|
|
285
|
+
with the promise it may have stepped over (RK431), and is what the two doors that
|
|
286
|
+
*report* a derived id call.
|
|
287
|
+
"""
|
|
288
|
+
return derivation(config, family).id
|
|
289
|
+
|
|
290
|
+
|
|
291
|
+
class UnknownFamily(ValueError):
|
|
292
|
+
"""An id was asked for under a prefix this project does not number."""
|
|
293
|
+
|
|
294
|
+
def __init__(self, family: str, declared: Sequence[str]) -> None:
|
|
295
|
+
self.family = family
|
|
296
|
+
self.declared = tuple(declared)
|
|
297
|
+
super().__init__(
|
|
298
|
+
f"{family!r} is not a family this project numbers "
|
|
299
|
+
f"({', '.join(declared)}): an id minted outside them is an id "
|
|
300
|
+
f"nothing else in the backlog can read"
|
|
301
|
+
)
|