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/graph.py ADDED
@@ -0,0 +1,395 @@
1
+ """The dependency graph, in both directions (RK13).
2
+
3
+ A blocked task and a ready one look identical on the page, and a task that unblocks half
4
+ the backlog looks exactly like one that unblocks nothing. Both are graph questions, and
5
+ an ad-hoc traversal rewritten per session is not merely expensive — it is wrong in ways
6
+ nothing checks, which is why the walk lives here with tests over the real files.
7
+
8
+ Four answers, and each one exists because collapsing it into another loses information:
9
+
10
+ * **The blocker chain.** "RK36 is blocked" is not actionable; "RK36 → RK14 → RK2, and RK2
11
+ is ready" names the task to start. A chain ends where the walk can go no further: a
12
+ ready blocker, an id in neither file, or work outside the backlog.
13
+ * **Transitive readiness.** Direct readiness (RK28) answers "can I start this now"; the
14
+ closure answers "what has to happen first", which is the question a reader of a blocked
15
+ line actually has.
16
+ * **Leverage, the reverse direction.** How many tasks a shipment unblocks *is* derivable,
17
+ and it is the only half of prioritisation a tool may supply — value is not derivable and
18
+ the tool does not guess at it (L4). Measured here, RK14 sits in 14 tasks' blocker sets
19
+ and most tasks sit in none: a gap no reading of the file makes visible.
20
+ * **Cycles.** A defect, not a shape: three tasks that wait on each other are three tasks
21
+ nothing can start. `deps` prints one; `lint` (RK14) is what will fail on it.
22
+
23
+ A block or a range dep is **expanded to its open members** before the walk, because
24
+ transitive readiness computed over a dep the traversal treats as opaque is wrong rather
25
+ than incomplete. How much work such a dep hides is its own report (RK35).
26
+ """
27
+
28
+ from __future__ import annotations
29
+
30
+ from dataclasses import dataclass
31
+
32
+ from roadkeep.backlog import Backlog, DepStatus, Readiness, Resolution, id_order
33
+ from roadkeep.config import Config
34
+ from roadkeep.kernel.schema import Task
35
+
36
+ #: How many chains and dependents an answer carries. Bounded because the value of a query
37
+ #: is that its output fits in a tool result; the counts stay exact either way.
38
+ SHOWN = 6
39
+
40
+
41
+ @dataclass(frozen=True, slots=True)
42
+ class Hop:
43
+ """One edge out of a task: what it waits on, and how the line named it."""
44
+
45
+ #: The id waited on, or the dep token itself when nothing can be walked into.
46
+ target: str
47
+ #: The token as written — `RK5`, `Block B`, `T451–T457`, `real design partners`.
48
+ via: str
49
+ status: DepStatus
50
+ #: What the resolver already said about this edge, carried where a status alone would
51
+ #: make the chain print something false (RK432). :func:`_terminal_detail` writes three
52
+ #: sentences from the status, and one of them — "outside the backlog: shipping cannot
53
+ #: satisfy it" — is wrong about a label the roadmap declares and nobody has filed under,
54
+ #: which shipping a first line under it is exactly what satisfies. Passing the
55
+ #: resolution's own words through removes a speller rather than adding a carrier; empty
56
+ #: everywhere the status is the whole of the answer.
57
+ detail: str = ""
58
+
59
+ @property
60
+ def walkable(self) -> bool:
61
+ """Only an open task of this project continues a chain."""
62
+ return self.status is DepStatus.OPEN
63
+
64
+ def __str__(self) -> str:
65
+ return self.target if self.via == self.target else f"{self.target} (via {self.via})"
66
+
67
+
68
+ @dataclass(frozen=True, slots=True)
69
+ class Chain:
70
+ """A path from a task to something that blocks it, and how the path ends."""
71
+
72
+ hops: tuple[Hop, ...]
73
+ #: Why the walk stopped: the last hop's status, or OPEN for a ready blocker.
74
+ end: DepStatus
75
+ detail: str
76
+
77
+ @property
78
+ def root(self) -> str:
79
+ return self.hops[-1].target if self.hops else ""
80
+
81
+ def render(self, start: str) -> str:
82
+ return " → ".join([start, *(str(hop) for hop in self.hops)])
83
+
84
+
85
+ @dataclass(frozen=True, slots=True)
86
+ class Leverage:
87
+ """What shipping one task would unblock, direct and transitive."""
88
+
89
+ direct: tuple[str, ...]
90
+ transitive: tuple[str, ...]
91
+ #: Open tasks other than this one — the denominator that makes the count mean something.
92
+ of: int
93
+
94
+ @property
95
+ def count(self) -> int:
96
+ return len(self.transitive)
97
+
98
+
99
+ @dataclass(frozen=True, slots=True)
100
+ class Graph:
101
+ """The backlog as edges, walked in both directions. Reads; never writes."""
102
+
103
+ backlog: Backlog
104
+ #: id → the hops it is waiting on. A satisfied dep is not an edge: it cannot block.
105
+ edges: dict[str, tuple[Hop, ...]]
106
+
107
+ @classmethod
108
+ def load(cls, config: Config) -> Graph:
109
+ return cls.of(Backlog.load(config))
110
+
111
+ @classmethod
112
+ def of(cls, backlog: Backlog) -> Graph:
113
+ edges = {
114
+ entry.task.id: _hops(backlog, entry.task) for entry in backlog.roadmap.entries
115
+ }
116
+ return cls(backlog=backlog, edges=edges)
117
+
118
+ # -- forward: what has to happen first ---------------------------------
119
+
120
+ def blockers(self, task_id: str) -> frozenset[str]:
121
+ """Every task in this one's transitive blocker set, itself excluded."""
122
+ return self.reach(task_id) - {task_id}
123
+
124
+ def reach(self, task_id: str) -> frozenset[str]:
125
+ """Everything walkable from here, *including* this task when a cycle returns.
126
+
127
+ Keeping the self-reaching case is what makes :meth:`cycles` two lines rather than
128
+ a second traversal with its own bugs.
129
+ """
130
+ seen: set[str] = set()
131
+ stack = [task_id]
132
+ while stack:
133
+ current = stack.pop()
134
+ for hop in self.edges.get(current, ()):
135
+ if not hop.walkable or hop.target in seen:
136
+ continue
137
+ seen.add(hop.target)
138
+ stack.append(hop.target)
139
+ return frozenset(seen)
140
+
141
+ def chains(self, task_id: str) -> tuple[Chain, ...]:
142
+ """Every blocking path, each ending where the walk can go no further.
143
+
144
+ Bounded by :data:`SHOWN`: a backlog with a wide dep graph has combinatorially many
145
+ paths, and a report nobody can read is the failure `deps` exists to fix.
146
+ """
147
+ found: list[Chain] = []
148
+ self._walk(task_id, (), set(), found)
149
+ return tuple(found[:SHOWN])
150
+
151
+ def _walk(
152
+ self, current: str, hops: tuple[Hop, ...], path: set[str], found: list[Chain]
153
+ ) -> None:
154
+ if len(found) >= SHOWN:
155
+ return
156
+ outgoing = self.edges.get(current, ())
157
+ if not outgoing:
158
+ if hops:
159
+ found.append(Chain(hops, DepStatus.OPEN, "open and ready to start"))
160
+ return
161
+ for hop in outgoing:
162
+ if not hop.walkable:
163
+ found.append(
164
+ Chain((*hops, hop), hop.status, hop.detail or _terminal_detail(hop))
165
+ )
166
+ continue
167
+ if hop.target in path or hop.target == current:
168
+ found.append(
169
+ Chain((*hops, hop), DepStatus.OPEN, "a cycle: this path returns here")
170
+ )
171
+ continue
172
+ self._walk(hop.target, (*hops, hop), path | {current}, found)
173
+
174
+ # -- reverse: what shipping this would unblock -------------------------
175
+
176
+ def leverage(self, task_id: str) -> Leverage:
177
+ """Which open tasks have this one in their blocker set.
178
+
179
+ Ordered by :func:`~roadkeep.backlog.id_order`, which is the one answer `pick`, `lint`
180
+ and `--fix` sort by (RK109) — and not by the text, which put `RK10` and `RK11` ahead of
181
+ `RK2`. Nothing read it while the whole roster was published: an unordered set spelled
182
+ in full is the same set. RK1301 cut the roster to a handful, and a handful taken off a
183
+ lexical sort is an arbitrary four rather than the lowest four — so the bound is what
184
+ made the ordering a fact anybody reads.
185
+ """
186
+ by_id = (lambda one: id_order(one, self.backlog.config.schema))
187
+ direct = tuple(
188
+ sorted(
189
+ (
190
+ other
191
+ for other, hops in self.edges.items()
192
+ if any(hop.target == task_id and hop.walkable for hop in hops)
193
+ ),
194
+ key=by_id,
195
+ )
196
+ )
197
+ transitive = tuple(
198
+ sorted(
199
+ (
200
+ other
201
+ for other in self.edges
202
+ if other != task_id and task_id in self.blockers(other)
203
+ ),
204
+ key=by_id,
205
+ )
206
+ )
207
+ return Leverage(direct=direct, transitive=transitive, of=len(self.edges) - 1)
208
+
209
+ # -- the defect ---------------------------------------------------------
210
+
211
+ def cycles(self) -> tuple[tuple[str, ...], ...]:
212
+ """Every group of tasks that wait on each other, ids sorted inside each group.
213
+
214
+ A group and not a path: a cycle is a property of the tasks, not of the node a walk
215
+ happened to enter it from, and the same cycle reported rotated twice would read as
216
+ two defects. Mutual reachability is the definition, so it is also the code.
217
+ """
218
+ looping = {node for node in self.edges if node in self.reach(node)}
219
+ out: list[tuple[str, ...]] = []
220
+ placed: set[str] = set()
221
+ for node in sorted(looping):
222
+ if node in placed:
223
+ continue
224
+ group = tuple(
225
+ sorted(
226
+ other
227
+ for other in looping
228
+ if other == node
229
+ or (other in self.reach(node) and node in self.reach(other))
230
+ )
231
+ )
232
+ placed.update(group)
233
+ out.append(group)
234
+ return tuple(out)
235
+
236
+ def cycle_of(self, task_id: str) -> tuple[str, ...]:
237
+ """The cycle this task is in, or an empty tuple. What `deps` reports per id."""
238
+ return next((c for c in self.cycles() if task_id in c), ())
239
+
240
+ # -- the answer a reader of one line wants -----------------------------
241
+
242
+ def readiness(self, task_id: str) -> Readiness:
243
+ entry = self.backlog.entry(task_id)
244
+ if entry is None:
245
+ raise KeyError(f"no open task {task_id}")
246
+ return self.backlog.readiness(entry.task)
247
+
248
+
249
+ @dataclass(frozen=True, slots=True)
250
+ class Dependencies:
251
+ """What one line is waiting on, and what waits on it (RK9, RK92).
252
+
253
+ The result `deps` had none of (RK1170): the door gathered six values off a backlog and a
254
+ graph and composed both registers from them, so neither reading had anything to be derived
255
+ *from* — which is the shape that task is about. Nothing here is stored: :meth:`of` reads
256
+ them together, and the two registers read this.
257
+ """
258
+
259
+ task_id: str
260
+ readiness: Readiness
261
+ resolutions: tuple[Resolution, ...]
262
+ blockers: tuple[str, ...]
263
+ chains: tuple[Chain, ...]
264
+ leverage: Leverage
265
+ #: The group nothing in can be started, where this id is in one. A defect and not a shape:
266
+ #: printed here, failed by `lint` (RK14).
267
+ cycle: tuple[str, ...] = ()
268
+
269
+ @classmethod
270
+ def of(cls, backlog: Backlog, task_id: str) -> Dependencies:
271
+ """Every reading of one id, off one backlog. Raises `KeyError` where no line holds it."""
272
+ entry = backlog.entry(task_id)
273
+ if entry is None:
274
+ raise KeyError(task_id)
275
+ graph = Graph.of(backlog)
276
+ return cls(
277
+ task_id=entry.task.id,
278
+ readiness=backlog.readiness(entry.task),
279
+ resolutions=tuple(backlog.resolve(entry.task)),
280
+ blockers=tuple(sorted(graph.blockers(task_id))),
281
+ chains=tuple(graph.chains(task_id)),
282
+ leverage=graph.leverage(task_id),
283
+ cycle=tuple(graph.cycle_of(task_id)),
284
+ )
285
+
286
+ def stated(self) -> str:
287
+ """Each dep with what became of it, then the readiness the set adds up to."""
288
+ from roadkeep.rendering import _leverage_rows # noqa: PLC0415 - RK260
289
+
290
+ if not self.resolutions:
291
+ return "\n".join(
292
+ [f"{self.task_id}: {self.readiness} (no deps)", *_leverage_rows(self.leverage)]
293
+ )
294
+ width = max(len(one.dep.id) for one in self.resolutions)
295
+ rows = [
296
+ f" {one.dep.id:<{width}} {one.status:<13}{one.kind:<9}{one.detail}"
297
+ for one in self.resolutions
298
+ ]
299
+ rows.append(f"{self.task_id}: {self.readiness}")
300
+ rows += [
301
+ f" chain {chain.render(self.task_id)} — {chain.detail}"
302
+ for chain in self.chains
303
+ ]
304
+ if self.cycle:
305
+ rows.append(
306
+ f" cycle {' ↔ '.join(self.cycle)}: nothing in this group can be started"
307
+ )
308
+ rows += _leverage_rows(self.leverage)
309
+ return "\n".join(rows)
310
+
311
+ def payload(self) -> dict[str, object]:
312
+ """The same answer as data, with each chain's path spelled from this id outward."""
313
+ return {
314
+ "id": self.task_id,
315
+ "readiness": str(self.readiness),
316
+ "deps": [
317
+ {
318
+ "dep": one.dep.id,
319
+ "kind": str(one.kind),
320
+ "status": str(one.status),
321
+ "detail": one.detail,
322
+ }
323
+ for one in self.resolutions
324
+ ],
325
+ "blockers": list(self.blockers),
326
+ "chains": [
327
+ {
328
+ "path": [self.task_id, *(hop.target for hop in chain.hops)],
329
+ "via": [hop.via for hop in chain.hops],
330
+ "end": str(chain.end),
331
+ "detail": chain.detail,
332
+ }
333
+ for chain in self.chains
334
+ ],
335
+ "unblocks": {
336
+ "direct": list(self.leverage.direct),
337
+ "transitive": list(self.leverage.transitive),
338
+ "count": self.leverage.count,
339
+ "of": self.leverage.of,
340
+ },
341
+ "cycle": list(self.cycle),
342
+ }
343
+
344
+
345
+ def _hops(backlog: Backlog, task: Task) -> tuple[Hop, ...]:
346
+ """One task's unsatisfied deps as edges, blocks and ranges expanded to members."""
347
+ schema = backlog.config.schema
348
+ out: list[Hop] = []
349
+ for dep in task.deps:
350
+ resolution = backlog.resolve_dep(dep)
351
+ if resolution.satisfied:
352
+ continue # a shipped dep, a finished block, a range with nothing open
353
+ kind = schema.classify_dep(dep)
354
+ if kind.collective:
355
+ members = backlog.expand(dep)
356
+ out.extend(
357
+ Hop(target=member, via=dep.id, status=DepStatus.OPEN) for member in members
358
+ )
359
+ if not members:
360
+ # An unsatisfied collective dep with nothing to expand into is still an
361
+ # edge, and this fired only for the block no heading declares (RK37). A
362
+ # heading written before its first line expands to nothing too, and so does
363
+ # one whose every line is in the store (RK432) — and dropping the edge left
364
+ # the dependent with a verdict and no chain under it at all. The token is
365
+ # the terminal, carrying the status and the sentence that say why the walk
366
+ # ends there.
367
+ out.append(
368
+ Hop(
369
+ target=dep.id,
370
+ via=dep.id,
371
+ status=resolution.status,
372
+ detail=resolution.detail,
373
+ )
374
+ )
375
+ continue
376
+ out.append(Hop(target=dep.id, via=dep.id, status=resolution.status))
377
+ return tuple(out)
378
+
379
+
380
+ def _terminal_detail(hop: Hop) -> str:
381
+ """The sentence a status alone implies, for the hops that carry none of their own.
382
+
383
+ Kept beside :attr:`Hop.detail` rather than replaced by it: a task dep's terminal hop is
384
+ one id and the status is the whole answer, so composing a second sentence per edge would
385
+ be words nobody reads. A collective token is where that stops holding, and there the
386
+ resolution's own words travel with the hop (RK432).
387
+ """
388
+ if hop.status is DepStatus.UNKNOWN:
389
+ return "in neither the roadmap nor the changelog"
390
+ if hop.status is DepStatus.DEFERRED:
391
+ # The one terminal end that is not terminal (RK92): the walk stops because the
392
+ # store holds no deps to follow, and saying "shipping cannot satisfy it" would
393
+ # name the chain unresolvable when what it needs is a `resume`.
394
+ return "set aside in the deferred store: a resume ends this chain"
395
+ return "outside the backlog: shipping cannot satisfy it"