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