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/backlog.py
ADDED
|
@@ -0,0 +1,767 @@
|
|
|
1
|
+
"""Resolving a dep against the backlog it names (RK28).
|
|
2
|
+
|
|
3
|
+
A dep is a claim about other work, and there are five different answers to "is it
|
|
4
|
+
done?" — shipped, still open, *set aside*, no such task, and *unanswerable*. Collapsing
|
|
5
|
+
the last one into "still open" is what makes a permanently blocked task read like the next
|
|
6
|
+
one to start, which is the whole reason this module exists rather than a boolean.
|
|
7
|
+
|
|
8
|
+
The fifth is the same honesty one state further in (RK92). A deferred dep is none of the
|
|
9
|
+
other four: not shipped, not open — the store is not the roadmap — not unknown, since it
|
|
10
|
+
is recorded and findable, and not unresolvable, which is `retire`'s "never" and a pause
|
|
11
|
+
can end. Read as open, a task is offered whose blocker nobody is working; read as
|
|
12
|
+
unresolvable, a task is buried that unblocks the moment the dep resumes. So it is
|
|
13
|
+
:attr:`DepStatus.DEFERRED`, and the task waiting on it is
|
|
14
|
+
:attr:`Readiness.PAUSED` — blocked for now, which is neither of the two blocked already
|
|
15
|
+
told apart.
|
|
16
|
+
|
|
17
|
+
The interesting case is the one the corpora already write. Shio has `(deps: Block P)`
|
|
18
|
+
and Turing has `(deps: real design partners)`: real work does wait on a whole block,
|
|
19
|
+
and on things that are not tracked work at all. So:
|
|
20
|
+
|
|
21
|
+
* a **task** dep resolves against the roadmap and the ledger;
|
|
22
|
+
* a **block** dep resolves against that block's :class:`Stage` and against nothing else
|
|
23
|
+
(RK432). "Nothing open" was two states and only one of them means waiting is over: a
|
|
24
|
+
heading `block add` wrote before its first line resolved as done, so a task waiting on
|
|
25
|
+
work nobody had filed was offered as ready. What makes a block finished is the ledger
|
|
26
|
+
filing something under the label, never the heading — which every organised file gets at
|
|
27
|
+
declaration time. `empty` and `unknown` are one answer about the *dep* and two facts
|
|
28
|
+
about the *label*, and :attr:`Standing.sentence` is what says which;
|
|
29
|
+
* an **external** dep is :attr:`DepStatus.UNRESOLVABLE` forever, and a task carrying
|
|
30
|
+
one is never *ready*, it is blocked outside the backlog. Naming that is the
|
|
31
|
+
difference between an answer and a guess.
|
|
32
|
+
"""
|
|
33
|
+
|
|
34
|
+
from __future__ import annotations
|
|
35
|
+
|
|
36
|
+
from dataclasses import dataclass
|
|
37
|
+
from enum import StrEnum
|
|
38
|
+
|
|
39
|
+
from roadkeep.config import Config
|
|
40
|
+
from roadkeep.kernel.document import Document, Entry
|
|
41
|
+
from roadkeep.kernel.schema import Dep, DepKind, Schema, Task
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
class Where(StrEnum):
|
|
45
|
+
"""Which absence an id is (RK240) — the question three refusals ask after "not here".
|
|
46
|
+
|
|
47
|
+
Not a readiness and not a dep status: those rank work, and this only says where to
|
|
48
|
+
look. The three are told apart because only the last one is a typo — an id that
|
|
49
|
+
shipped, one that was abandoned and one nobody ever wrote are three different next
|
|
50
|
+
actions, and a refusal that says "no such task" for all three sends two of the three
|
|
51
|
+
authors to search a file that is right.
|
|
52
|
+
"""
|
|
53
|
+
|
|
54
|
+
#: The roadmap carries it as an open line.
|
|
55
|
+
OPEN = "open"
|
|
56
|
+
#: The deferred store holds it (RK1213). Here for the reason :attr:`Stage.PAUSED` is one
|
|
57
|
+
#: level up (RK92, RK429): a pause is not an absence, and reading it as one loses the very
|
|
58
|
+
#: fact a `resume` would change. It was the fourth state this enum did not have, so
|
|
59
|
+
#: `amend`, `restate` and `status` refused a paused line in the words a typo gets, while
|
|
60
|
+
#: `sentence` said *no file mentions it* about a line the store carries verbatim.
|
|
61
|
+
PAUSED = "paused"
|
|
62
|
+
#: The ledger carries it, shipped or retired — :attr:`Whereabouts.marker` says which.
|
|
63
|
+
RECORDED = "recorded"
|
|
64
|
+
NOWHERE = "nowhere"
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
@dataclass(frozen=True, slots=True)
|
|
68
|
+
class Whereabouts:
|
|
69
|
+
"""Where an id actually is, in one type and one sentence (RK240).
|
|
70
|
+
|
|
71
|
+
Two modules composed this independently and in the same words — `deferring` for
|
|
72
|
+
`resume`'s :class:`~roadkeep.deferring.NotSetAside`, `sections` for `anchor.unknown` —
|
|
73
|
+
which is a resolution copied rather than called: the copy is what goes stale when the
|
|
74
|
+
other is corrected. It lives here because the fact is about an **id**, and this module
|
|
75
|
+
is where an id's state is already read from every file that can hold one.
|
|
76
|
+
|
|
77
|
+
A type rather than the string both callers printed, because one of them *acts* on the
|
|
78
|
+
state: `sections._unknown` offers `record amend` only for an id the ledger holds, and
|
|
79
|
+
deciding that from the truthiness of a sentence is a branch that reads prose. So the
|
|
80
|
+
marker is carried, :attr:`sentence` is the one spelling, and the door is chosen from
|
|
81
|
+
:attr:`Where`.
|
|
82
|
+
"""
|
|
83
|
+
|
|
84
|
+
where: Where
|
|
85
|
+
#: The ledger's marker where it holds the id — ✅ or 🗑 — and empty otherwise.
|
|
86
|
+
marker: str = ""
|
|
87
|
+
|
|
88
|
+
@classmethod
|
|
89
|
+
def of(cls, config: Config, task_id: str) -> Whereabouts:
|
|
90
|
+
"""Read the files, roadmap first, and the ledger only where it can still answer.
|
|
91
|
+
|
|
92
|
+
The order is the answer's own, and it is :meth:`Standing.of`'s (RK1213): open work,
|
|
93
|
+
then paused work, then the ledger — so the reading for an id and the reading for the
|
|
94
|
+
label it sits under cannot disagree about the same state. A project that declares no
|
|
95
|
+
changelog or no store simply has fewer answers rather than a different order.
|
|
96
|
+
"""
|
|
97
|
+
if config.document("roadmap").by_id().get(task_id) is not None:
|
|
98
|
+
return cls(Where.OPEN)
|
|
99
|
+
if config.has("deferred") and config.path("deferred").is_file():
|
|
100
|
+
if config.document("deferred").by_id().get(task_id) is not None:
|
|
101
|
+
return cls(Where.PAUSED)
|
|
102
|
+
if config.has("changelog") and config.path("changelog").is_file():
|
|
103
|
+
recorded = config.document("changelog").by_id().get(task_id)
|
|
104
|
+
if recorded is not None:
|
|
105
|
+
return cls(Where.RECORDED, recorded.task.status)
|
|
106
|
+
return cls(Where.NOWHERE)
|
|
107
|
+
|
|
108
|
+
@property
|
|
109
|
+
def recorded(self) -> bool:
|
|
110
|
+
return self.where is Where.RECORDED
|
|
111
|
+
|
|
112
|
+
@property
|
|
113
|
+
def paused(self) -> bool:
|
|
114
|
+
return self.where is Where.PAUSED
|
|
115
|
+
|
|
116
|
+
@property
|
|
117
|
+
def sentence(self) -> str:
|
|
118
|
+
"""The clause a refusal appends after naming where the id is not.
|
|
119
|
+
|
|
120
|
+
The paused one names its verb (RK1213), and it is the only one of the four that can:
|
|
121
|
+
a shipped id has no way back and a typo has nothing to go back to, while a pause is
|
|
122
|
+
one command from open — which is RK91's whole argument for the store existing.
|
|
123
|
+
"""
|
|
124
|
+
if self.where is Where.OPEN:
|
|
125
|
+
return "it is open in the roadmap"
|
|
126
|
+
if self.where is Where.PAUSED:
|
|
127
|
+
return "the deferred store holds it — `resume` brings it back"
|
|
128
|
+
if self.where is Where.RECORDED:
|
|
129
|
+
return f"the changelog records it as {self.marker}"
|
|
130
|
+
return "no file mentions it"
|
|
131
|
+
|
|
132
|
+
|
|
133
|
+
class NotOpen(ValueError):
|
|
134
|
+
"""Only an open task can be written to, and the ways of not being one differ.
|
|
135
|
+
|
|
136
|
+
Lives here rather than in the command that first needed it (RK6) because "is this
|
|
137
|
+
id open?" is a question about every file that can hold one, and reporting
|
|
138
|
+
"no such task" for one that shipped yesterday sends the reader to the wrong file.
|
|
139
|
+
|
|
140
|
+
**Below :class:`Whereabouts` and composed from it** (RK1213). It carried a bare
|
|
141
|
+
`shipped: bool`, so the three states it could not spell collapsed into one: a paused id
|
|
142
|
+
was refused in the words a typo gets, and the door back — `resume` — was named by
|
|
143
|
+
nothing, on the one absence that has a door. A second bool would have been the same
|
|
144
|
+
question asked twice, so the answer is the type RK240 already built to answer it, and the
|
|
145
|
+
sentence has one spelling for every caller that asks.
|
|
146
|
+
"""
|
|
147
|
+
|
|
148
|
+
def __init__(self, task_id: str, where: str, found: Whereabouts) -> None:
|
|
149
|
+
self.task_id = task_id
|
|
150
|
+
self.found = found
|
|
151
|
+
detail = (
|
|
152
|
+
"it is already in the changelog"
|
|
153
|
+
if found.recorded
|
|
154
|
+
else found.sentence
|
|
155
|
+
if found.paused
|
|
156
|
+
else "nothing there carries that id"
|
|
157
|
+
)
|
|
158
|
+
super().__init__(f"no open task {task_id} in {where}: {detail}")
|
|
159
|
+
|
|
160
|
+
@property
|
|
161
|
+
def shipped(self) -> bool:
|
|
162
|
+
"""Kept as the reading it always was, now derived rather than passed."""
|
|
163
|
+
return self.found.recorded
|
|
164
|
+
|
|
165
|
+
|
|
166
|
+
class Stage(StrEnum):
|
|
167
|
+
"""Which state a **block** is in (RK429) — :class:`Where` for a label.
|
|
168
|
+
|
|
169
|
+
A block is discovered and never registered, so "nothing open in Block C" was the one
|
|
170
|
+
answer four different facts produced: the work is done, its lines were all set aside,
|
|
171
|
+
the heading was opened before any line, or the letter is a typo. One sentence for four
|
|
172
|
+
states, and only the last is a mistake — which is why a query that collapses them sends
|
|
173
|
+
three of the four readers to grep the ledger this tool exists to replace.
|
|
174
|
+
|
|
175
|
+
The discriminator between `finished` and `empty` is **entries under the label** and
|
|
176
|
+
never the heading: `block add` writes the heading into every organised file at
|
|
177
|
+
declaration time, so a heading proves the label was declared and nothing more. The
|
|
178
|
+
gate made that choice first, for a queue token (`priority.block-empty` against
|
|
179
|
+
`priority.block-unstarted`), and reads it from here since RK434 —
|
|
180
|
+
:func:`~roadkeep.linting._dead_block` maps a stage to a code and a tier, and decides no
|
|
181
|
+
state of its own.
|
|
182
|
+
|
|
183
|
+
:attr:`PAUSED` is here for the reason :attr:`Readiness.PAUSED` is (RK92): a block
|
|
184
|
+
whose every line was deferred is not finished and not empty, and reading it as either
|
|
185
|
+
loses the one fact about it that a `resume` would change.
|
|
186
|
+
"""
|
|
187
|
+
|
|
188
|
+
#: Nothing open and the ledger records work, on a label `[blocks] standing` declares
|
|
189
|
+
#: (RK1180): the block is **caught up** rather than finished. A category that receives work
|
|
190
|
+
#: forever — realignment of what already shipped, a triage lane — is empty only in the sense
|
|
191
|
+
#: that nobody has filed the next one yet, and reading that as completion made one such block
|
|
192
|
+
#: declared, emptied and dropped three times in a session, each drop followed within the hour
|
|
193
|
+
#: by a finding that re-declared it. The churn in the file was not the cost: a host project
|
|
194
|
+
#: hangs a block-completion sweep off the signal, designed to run once per capability.
|
|
195
|
+
CURRENT = "caught up"
|
|
196
|
+
#: The roadmap carries open lines under it. Nothing here is about them.
|
|
197
|
+
LIVE = "live"
|
|
198
|
+
#: Nothing open, and the ledger records entries filed under the label. Not "shipped":
|
|
199
|
+
#: a retirement is filed there too, and the ledger having the last word is the claim.
|
|
200
|
+
FINISHED = "finished"
|
|
201
|
+
#: Nothing open, and the deferred store holds lines under it. Checked before the
|
|
202
|
+
#: ledger, because a block that shipped half its work and set the rest aside has work.
|
|
203
|
+
PAUSED = "paused"
|
|
204
|
+
#: Declared, and no file files a task line under it — a heading before its lines.
|
|
205
|
+
EMPTY = "empty"
|
|
206
|
+
#: No heading in the roadmap or the ledger. The only one that is a typo, and the same
|
|
207
|
+
#: oracle every other refusal about a label uses, so the four answers cannot disagree.
|
|
208
|
+
UNKNOWN = "unknown"
|
|
209
|
+
|
|
210
|
+
|
|
211
|
+
@dataclass(frozen=True, slots=True)
|
|
212
|
+
class Standing:
|
|
213
|
+
"""What became of a block, in one type and one sentence (RK429).
|
|
214
|
+
|
|
215
|
+
The block analogue of :class:`Whereabouts`, and here for its reason: the fact is about
|
|
216
|
+
a label, and this module is already where a label is read from every file that can
|
|
217
|
+
declare one. Not :class:`~roadkeep.blocking.Standing`, which is what one heading stands
|
|
218
|
+
over inside one file.
|
|
219
|
+
|
|
220
|
+
:attr:`sentence` is the one spelling, so `brief`, `pick` and `list` answer a finished
|
|
221
|
+
block in the same words; callers that *act* on the state branch on :attr:`stage`, never
|
|
222
|
+
on the prose — a `list` that read the sentence to decide its exit code would be the
|
|
223
|
+
second reader of a rule this states once.
|
|
224
|
+
|
|
225
|
+
**Every count is taken whatever the state is.** An early return would make `recorded`
|
|
226
|
+
read 0 for a live block the ledger files thirty entries under, and a payload whose
|
|
227
|
+
fields are only true in the branch that needed them is one a caller reads wrongly
|
|
228
|
+
exactly once.
|
|
229
|
+
"""
|
|
230
|
+
|
|
231
|
+
#: The label as the caller typed it, for a payload that has to name what was asked.
|
|
232
|
+
label: str
|
|
233
|
+
stage: Stage
|
|
234
|
+
#: The label as this project spells one — `Block C`, or whatever `heading_word` says.
|
|
235
|
+
named: str
|
|
236
|
+
#: Open lines the roadmap files under it.
|
|
237
|
+
open: int = 0
|
|
238
|
+
#: Entries the ledger files under it — shipped **and** retired, which is what a ledger
|
|
239
|
+
#: records. The count is the evidence for `finished`, so it is carried and not recomputed.
|
|
240
|
+
recorded: int = 0
|
|
241
|
+
#: Lines the deferred store holds under it (RK92) — the work a `resume` brings back.
|
|
242
|
+
paused: int = 0
|
|
243
|
+
|
|
244
|
+
@classmethod
|
|
245
|
+
def of(cls, backlog: Backlog, label: str) -> Standing:
|
|
246
|
+
"""Read every file that can file a line under a label, and rank what they say.
|
|
247
|
+
|
|
248
|
+
The order is the answer's own: open work outranks paused work, which outranks a
|
|
249
|
+
ledger, because each of those is a reason the one below it is not the whole story.
|
|
250
|
+
A block that shipped nine lines and deferred the tenth is not finished.
|
|
251
|
+
"""
|
|
252
|
+
named = backlog.config.schema.block_named(label)
|
|
253
|
+
if label not in backlog.declared_blocks():
|
|
254
|
+
return cls(label, Stage.UNKNOWN, named)
|
|
255
|
+
counts = {
|
|
256
|
+
"open": len(backlog.open_in_block(label)),
|
|
257
|
+
"recorded": 0 if backlog.ledger is None else len(backlog.ledger.block(label)),
|
|
258
|
+
"paused": 0 if backlog.store is None else len(backlog.store.block(label)),
|
|
259
|
+
}
|
|
260
|
+
if counts["open"]:
|
|
261
|
+
stage = Stage.LIVE
|
|
262
|
+
elif counts["paused"]:
|
|
263
|
+
stage = Stage.PAUSED
|
|
264
|
+
elif counts["recorded"]:
|
|
265
|
+
# Which kind of block this is, asked of the project and not guessed from the counts
|
|
266
|
+
# (RK1180, L6): the numbers are identical for a project that finished and a standing
|
|
267
|
+
# category that is caught up, and only the plan knows which it is looking at.
|
|
268
|
+
stage = (
|
|
269
|
+
Stage.CURRENT if label in backlog.config.standing else Stage.FINISHED
|
|
270
|
+
)
|
|
271
|
+
else:
|
|
272
|
+
stage = Stage.EMPTY
|
|
273
|
+
return cls(label, stage, named, **counts)
|
|
274
|
+
|
|
275
|
+
@property
|
|
276
|
+
def settled(self) -> bool:
|
|
277
|
+
"""Whether this is one of the states an empty answer needs explaining by.
|
|
278
|
+
|
|
279
|
+
`live` is not: a listing that came back empty under a live block was emptied by
|
|
280
|
+
the filter, and a sentence about the block would answer a question nobody asked.
|
|
281
|
+
Neither is `unknown`, which every surface already refuses in its own words.
|
|
282
|
+
"""
|
|
283
|
+
return self.stage in (Stage.FINISHED, Stage.CURRENT, Stage.PAUSED, Stage.EMPTY)
|
|
284
|
+
|
|
285
|
+
@property
|
|
286
|
+
def sentence(self) -> str:
|
|
287
|
+
"""What to print where "nothing is open in Block C" used to be the whole answer."""
|
|
288
|
+
if self.stage is Stage.LIVE:
|
|
289
|
+
return f"{self.named} has {self.open} open"
|
|
290
|
+
if self.stage is Stage.FINISHED:
|
|
291
|
+
return (
|
|
292
|
+
f"{self.named} is finished: nothing open, and the ledger records "
|
|
293
|
+
f"{self.recorded} filed under it"
|
|
294
|
+
)
|
|
295
|
+
if self.stage is Stage.CURRENT:
|
|
296
|
+
# "Caught up" and never "finished" (RK1180): the same two numbers, and the word is
|
|
297
|
+
# the one a reader acts on — a sweep meant to run once per capability runs off it.
|
|
298
|
+
return (
|
|
299
|
+
f"{self.named} is caught up: nothing open, and the ledger records "
|
|
300
|
+
f"{self.recorded} filed under it — a standing category, which fills again"
|
|
301
|
+
)
|
|
302
|
+
if self.stage is Stage.PAUSED:
|
|
303
|
+
return (
|
|
304
|
+
f"{self.named} has nothing open: {self.paused} set aside, which a "
|
|
305
|
+
f"resume brings back"
|
|
306
|
+
)
|
|
307
|
+
if self.stage is Stage.EMPTY:
|
|
308
|
+
# "No task line" and not "nothing has ever been filed": a marker-bearing line
|
|
309
|
+
# the parser rejected sits under the heading and is reported by `audit`, and an
|
|
310
|
+
# absolute claim here would contradict the note printed on the next line.
|
|
311
|
+
return f"{self.named} is empty: the heading is declared and no task line is filed under it"
|
|
312
|
+
return f"no heading declares {self.named}"
|
|
313
|
+
|
|
314
|
+
def payload(self) -> dict[str, object]:
|
|
315
|
+
"""What became of the block a query was scoped to (RK429).
|
|
316
|
+
|
|
317
|
+
The counts ride with the state because they are its evidence: `finished` is a claim about
|
|
318
|
+
the ledger, and a payload asserting it without saying how many entries it read is one a
|
|
319
|
+
caller has to verify with a second command.
|
|
320
|
+
|
|
321
|
+
Here since RK1170, with `delivered`: four payloads publish this record, and a builder in
|
|
322
|
+
`rendering.py` was the fifth place the fact was spelled — where one of its keys had
|
|
323
|
+
quietly been written twice.
|
|
324
|
+
"""
|
|
325
|
+
return {
|
|
326
|
+
"block": self.label,
|
|
327
|
+
"state": str(self.stage),
|
|
328
|
+
"sentence": self.sentence,
|
|
329
|
+
"open": self.open,
|
|
330
|
+
"recorded": self.recorded,
|
|
331
|
+
"paused": self.paused,
|
|
332
|
+
}
|
|
333
|
+
|
|
334
|
+
|
|
335
|
+
class DepStatus(StrEnum):
|
|
336
|
+
"""How a single dep resolved."""
|
|
337
|
+
|
|
338
|
+
SHIPPED = "shipped"
|
|
339
|
+
OPEN = "open"
|
|
340
|
+
#: Held in the deferred store (RK92). Recorded, so not unknown; revivable, so not
|
|
341
|
+
#: unresolvable; and not in the roadmap, so not open — the state `retire` has no
|
|
342
|
+
#: door for and `resume` is the way out of.
|
|
343
|
+
DEFERRED = "deferred"
|
|
344
|
+
#: An id of this project that exists in neither file. A lint error (RK8), not a
|
|
345
|
+
#: rendering choice: nothing downstream can tell whether it is done.
|
|
346
|
+
UNKNOWN = "unknown"
|
|
347
|
+
#: Nothing the roadmap now holds open will satisfy it (RK432). Three things are that:
|
|
348
|
+
#: an external dep, by construction; a retired task, by decision; and a label with
|
|
349
|
+
#: nothing filed under it, because there is no line to ship. Widened from "outside the
|
|
350
|
+
#: backlog" when the third joined — a heading with no lines is declared *inside* the
|
|
351
|
+
#: backlog, and what lifts the dependent is a first `add` under the label rather than
|
|
352
|
+
#: a `ship` of anything now open.
|
|
353
|
+
UNRESOLVABLE = "unresolvable"
|
|
354
|
+
|
|
355
|
+
|
|
356
|
+
class Readiness(StrEnum):
|
|
357
|
+
"""Whether a task can be started, and if not, in which of four senses."""
|
|
358
|
+
|
|
359
|
+
READY = "ready"
|
|
360
|
+
BLOCKED = "blocked"
|
|
361
|
+
#: Blocked by something that is not an open line, so no `ship` of anything the roadmap
|
|
362
|
+
#: now holds lifts it — what does is a `retire`, an `amend --dep`, or a first `add`
|
|
363
|
+
#: under a label declared before its lines (RK432). `pick` (RK11) must not offer these
|
|
364
|
+
#: as next work.
|
|
365
|
+
OUTSIDE = "blocked-outside"
|
|
366
|
+
#: Blocked on work somebody set aside (RK92). Not offered either — nobody is working
|
|
367
|
+
#: the blocker — but unlike :attr:`OUTSIDE` the block lifts on a `resume`, so what has
|
|
368
|
+
#: to change is a decision and not this line.
|
|
369
|
+
PAUSED = "blocked-paused"
|
|
370
|
+
#: Not startable because it is **done** (RK324) — the ledger's answer, never
|
|
371
|
+
#: :meth:`Backlog.readiness`'s, which is asked only about lines the roadmap still holds.
|
|
372
|
+
#: A fifth state rather than a reading of `ready`: every other value here says work
|
|
373
|
+
#: remains, so a shipped id described with one of them is an invitation to redo it.
|
|
374
|
+
SHIPPED = "shipped"
|
|
375
|
+
|
|
376
|
+
|
|
377
|
+
#: Which :class:`DepStatus` each *settled* :class:`Stage` is (RK432) — the whole of what a
|
|
378
|
+
#: block dep resolves to. A table and not four branches, because the resolver had grown its
|
|
379
|
+
#: own copy of the walk :meth:`Standing.of` already makes, and a mapping is what a test can
|
|
380
|
+
#: check for totality. :attr:`Stage.LIVE` is absent on purpose: it is the one stage whose
|
|
381
|
+
#: detail is not the standing's sentence, so :meth:`Backlog._resolve_block` answers it.
|
|
382
|
+
#:
|
|
383
|
+
#: `empty` and `unknown` share an answer because the question a status settles is whether
|
|
384
|
+
#: waiting is over, and under neither label is there work to wait for. Which of the two it
|
|
385
|
+
#: is stays on the printed line, :attr:`Standing.sentence` being the detail.
|
|
386
|
+
_SATISFIES = {
|
|
387
|
+
Stage.FINISHED: DepStatus.SHIPPED,
|
|
388
|
+
# A dep that shipped is shipped whichever kind of block it sat under (RK1180): the label's
|
|
389
|
+
# kind decides what an *empty* block means and never what a recorded line means.
|
|
390
|
+
Stage.CURRENT: DepStatus.SHIPPED,
|
|
391
|
+
Stage.PAUSED: DepStatus.DEFERRED,
|
|
392
|
+
Stage.EMPTY: DepStatus.UNRESOLVABLE,
|
|
393
|
+
Stage.UNKNOWN: DepStatus.UNRESOLVABLE,
|
|
394
|
+
}
|
|
395
|
+
|
|
396
|
+
|
|
397
|
+
@dataclass(frozen=True, slots=True)
|
|
398
|
+
class Resolution:
|
|
399
|
+
"""One dep, what it names, how it resolved, and a sentence a human can read."""
|
|
400
|
+
|
|
401
|
+
dep: Dep
|
|
402
|
+
kind: DepKind
|
|
403
|
+
status: DepStatus
|
|
404
|
+
detail: str
|
|
405
|
+
|
|
406
|
+
@property
|
|
407
|
+
def satisfied(self) -> bool:
|
|
408
|
+
return self.status is DepStatus.SHIPPED
|
|
409
|
+
|
|
410
|
+
|
|
411
|
+
@dataclass(frozen=True, slots=True)
|
|
412
|
+
class Backlog:
|
|
413
|
+
"""The roadmap and the ledger, read once, resolved together.
|
|
414
|
+
|
|
415
|
+
Both files are needed for any question about status: the roadmap knows what is
|
|
416
|
+
open and only the ledger knows what shipped. Loading them separately at each
|
|
417
|
+
call site is how two commands come to disagree.
|
|
418
|
+
"""
|
|
419
|
+
|
|
420
|
+
config: Config
|
|
421
|
+
roadmap: Document
|
|
422
|
+
ledger: Document | None = None
|
|
423
|
+
#: The deferred store (RK96), read for the same reason the ledger is (RK92): a dep
|
|
424
|
+
#: whose target is paused resolves against a file neither of the other two is, and
|
|
425
|
+
#: loading it only where somebody remembered to is how a fifth status comes to mean
|
|
426
|
+
#: "unknown" in every command that forgot.
|
|
427
|
+
store: Document | None = None
|
|
428
|
+
|
|
429
|
+
@classmethod
|
|
430
|
+
def load(cls, config: Config) -> Backlog:
|
|
431
|
+
return cls(
|
|
432
|
+
config=config,
|
|
433
|
+
roadmap=config.document("roadmap"),
|
|
434
|
+
ledger=_present(config, "changelog"),
|
|
435
|
+
store=_present(config, "deferred"),
|
|
436
|
+
)
|
|
437
|
+
|
|
438
|
+
@classmethod
|
|
439
|
+
def during(
|
|
440
|
+
cls,
|
|
441
|
+
config: Config,
|
|
442
|
+
*,
|
|
443
|
+
roadmap: Document,
|
|
444
|
+
ledger: Document | None = None,
|
|
445
|
+
store: Document | None = None,
|
|
446
|
+
) -> Backlog:
|
|
447
|
+
"""A backlog mid-write: the documents this transaction creates, the rest from disk.
|
|
448
|
+
|
|
449
|
+
A door and not a convenience (RK92). Every caller that resolves against a state not
|
|
450
|
+
yet on disk used to build the dataclass by hand, which meant naming each file it
|
|
451
|
+
cared about — so a file added later was absent in exactly the commands that never
|
|
452
|
+
heard of it, and a deferred dep read as a missing id inside `ship` while reading
|
|
453
|
+
correctly outside it. Named files override; the others are read.
|
|
454
|
+
"""
|
|
455
|
+
return cls(
|
|
456
|
+
config=config,
|
|
457
|
+
roadmap=roadmap,
|
|
458
|
+
ledger=ledger if ledger is not None else _present(config, "changelog"),
|
|
459
|
+
store=store if store is not None else _present(config, "deferred"),
|
|
460
|
+
)
|
|
461
|
+
|
|
462
|
+
# -- lookups -----------------------------------------------------------
|
|
463
|
+
|
|
464
|
+
def entry(self, task_id: str) -> Entry | None:
|
|
465
|
+
return self.roadmap.by_id().get(task_id)
|
|
466
|
+
|
|
467
|
+
def shipped(self) -> frozenset[str]:
|
|
468
|
+
"""Ids the ledger marks ✅ — never merely *present* in it.
|
|
469
|
+
|
|
470
|
+
A retired line lives in the same file (RK32), so reading the ledger as a set of
|
|
471
|
+
ids would make "this was abandoned" resolve as "this is done" — a dep satisfied
|
|
472
|
+
by the record of its own cancellation.
|
|
473
|
+
"""
|
|
474
|
+
if self.ledger is None:
|
|
475
|
+
return frozenset()
|
|
476
|
+
marker = self.config.schema.shipped_marker
|
|
477
|
+
return frozenset(
|
|
478
|
+
task_id
|
|
479
|
+
for task_id, entry in self.ledger.by_id().items()
|
|
480
|
+
if entry.task.status == marker
|
|
481
|
+
)
|
|
482
|
+
|
|
483
|
+
def partial(self, task_id: str) -> str:
|
|
484
|
+
"""Which half the ledger says landed, where this id shipped in halves (RK121, RK396).
|
|
485
|
+
|
|
486
|
+
Empty for every other id, which is what makes it a *detail* and not a status: a
|
|
487
|
+
partial is an open line whose ledger entry names the delivered part, so the answer
|
|
488
|
+
about whether to start work stays the line's and this only says what already exists.
|
|
489
|
+
"""
|
|
490
|
+
if self.ledger is None:
|
|
491
|
+
return ""
|
|
492
|
+
entry = self.ledger.by_id().get(task_id)
|
|
493
|
+
if entry is None or entry.task.status != self.config.schema.shipped_marker:
|
|
494
|
+
return ""
|
|
495
|
+
return entry.task.part or ""
|
|
496
|
+
|
|
497
|
+
def deferred(self) -> dict[str, Entry]:
|
|
498
|
+
"""Ids the store holds, with the line that says why they were set aside.
|
|
499
|
+
|
|
500
|
+
Every line in it, and not the ones carrying ⏸: the store's own status *is* ⏸ and
|
|
501
|
+
the schema refuses any other there (RK96), so filtering by marker would be this
|
|
502
|
+
module re-deciding what the file already guarantees.
|
|
503
|
+
"""
|
|
504
|
+
return {} if self.store is None else dict(self.store.by_id())
|
|
505
|
+
|
|
506
|
+
def retired(self) -> dict[str, Entry]:
|
|
507
|
+
"""Ids the ledger marks 🗑, with the line that says why they left."""
|
|
508
|
+
if self.ledger is None:
|
|
509
|
+
return {}
|
|
510
|
+
marker = self.config.schema.retired_marker
|
|
511
|
+
return {
|
|
512
|
+
task_id: entry
|
|
513
|
+
for task_id, entry in self.ledger.by_id().items()
|
|
514
|
+
if entry.task.status == marker
|
|
515
|
+
}
|
|
516
|
+
|
|
517
|
+
def open_in_block(self, label: str) -> tuple[str, ...]:
|
|
518
|
+
return tuple(e.task.id for e in self.roadmap.block(label))
|
|
519
|
+
|
|
520
|
+
def declared_blocks(self) -> frozenset[str]:
|
|
521
|
+
"""Every block label a heading declares, across both files.
|
|
522
|
+
|
|
523
|
+
The ledger counts: a block whose last task shipped keeps its heading there
|
|
524
|
+
and may have lost the one in the roadmap. This is the only record that a
|
|
525
|
+
block exists at all — nothing registers one — which is why an undeclared
|
|
526
|
+
block and a finished one are otherwise indistinguishable.
|
|
527
|
+
"""
|
|
528
|
+
return frozenset(
|
|
529
|
+
heading.label
|
|
530
|
+
for document in (self.roadmap, self.ledger)
|
|
531
|
+
if document is not None
|
|
532
|
+
for heading in document.headings
|
|
533
|
+
if heading.label
|
|
534
|
+
)
|
|
535
|
+
|
|
536
|
+
def standing(self, label: str) -> Standing:
|
|
537
|
+
"""Which of :class:`Stage`'s four states this label is in (RK429).
|
|
538
|
+
|
|
539
|
+
The read every query makes after its own count comes back empty — and the gate's,
|
|
540
|
+
resolving a queue entry that names a block (RK434), which is where the second copy
|
|
541
|
+
of this walk had already drifted: it never opened the store, so a paused block was
|
|
542
|
+
reported as an unstarted one. A method here rather than the same four lines at each
|
|
543
|
+
call site: the files it joins are the three this class holds open.
|
|
544
|
+
"""
|
|
545
|
+
return Standing.of(self, label)
|
|
546
|
+
|
|
547
|
+
# -- resolving ---------------------------------------------------------
|
|
548
|
+
|
|
549
|
+
def resolve_dep(self, dep: Dep) -> Resolution:
|
|
550
|
+
"""One dep, resolved by what it names. Four kinds, four resolvers."""
|
|
551
|
+
kind = self.config.schema.classify_dep(dep)
|
|
552
|
+
resolver = {
|
|
553
|
+
DepKind.EXTERNAL: self._resolve_external,
|
|
554
|
+
DepKind.RANGE: self._resolve_range,
|
|
555
|
+
DepKind.BLOCK: self._resolve_block,
|
|
556
|
+
DepKind.TASK: self._resolve_task,
|
|
557
|
+
}[kind]
|
|
558
|
+
return resolver(dep, kind)
|
|
559
|
+
|
|
560
|
+
def _resolve_external(self, dep: Dep, kind: DepKind) -> Resolution:
|
|
561
|
+
return Resolution(
|
|
562
|
+
dep,
|
|
563
|
+
kind,
|
|
564
|
+
DepStatus.UNRESOLVABLE,
|
|
565
|
+
"outside the backlog: nothing here will ever mark this done",
|
|
566
|
+
)
|
|
567
|
+
|
|
568
|
+
def _resolve_range(self, dep: Dep, kind: DepKind) -> Resolution:
|
|
569
|
+
still_open = self._open_in_range(dep)
|
|
570
|
+
if still_open:
|
|
571
|
+
return Resolution(dep, kind, DepStatus.OPEN, _open_detail(still_open))
|
|
572
|
+
# A range with no open members is satisfied, not unknown: ids are
|
|
573
|
+
# non-contiguous by design, so "nothing open in T451–T457" is the answer.
|
|
574
|
+
return Resolution(dep, kind, DepStatus.SHIPPED, "nothing open in the range")
|
|
575
|
+
|
|
576
|
+
def _resolve_block(self, dep: Dep, kind: DepKind) -> Resolution:
|
|
577
|
+
"""What the label's own :class:`Stage` says, in this module's other vocabulary.
|
|
578
|
+
|
|
579
|
+
This asked two questions of its own — is there a heading, is anything open — which
|
|
580
|
+
is :meth:`Standing.of`'s walk with two of its settled answers missing, and the
|
|
581
|
+
missing pair were the interesting ones (RK432). A heading `block add` wrote before
|
|
582
|
+
a single line was filed under it resolved as `shipped`, so `pick` offered the
|
|
583
|
+
dependent, `brief` printed a checkmark beside a blocker that did not exist yet, and
|
|
584
|
+
the annotation cached that checkmark into the file — RK28's failure one level up
|
|
585
|
+
from the id it was written about.
|
|
586
|
+
|
|
587
|
+
`paused` is :attr:`DepStatus.DEFERRED` for RK92's three clauses, each of which
|
|
588
|
+
holds of a label with nothing open and a line in the store: recorded, so not
|
|
589
|
+
unknown; revivable, so not unresolvable; not in the roadmap, so not open. It
|
|
590
|
+
outranks the ledger in :meth:`Standing.of`, so a block that shipped nine lines and
|
|
591
|
+
set the tenth aside resolves deferred and not shipped — the pause is the fact a
|
|
592
|
+
dependent's own line cannot show.
|
|
593
|
+
|
|
594
|
+
`live` is the one stage :data:`_SATISFIES` does not carry, because its detail is
|
|
595
|
+
not the standing's: the sentence is a header and names no ids, and the ids are the
|
|
596
|
+
actionable half of an open dep. That is the one deliberate second read of the block
|
|
597
|
+
— :class:`Standing` counted those lines and kept only the count.
|
|
598
|
+
"""
|
|
599
|
+
label = self.config.schema.block_of_dep(dep)
|
|
600
|
+
standing = self.standing(label)
|
|
601
|
+
if standing.stage is Stage.LIVE:
|
|
602
|
+
return Resolution(
|
|
603
|
+
dep,
|
|
604
|
+
kind,
|
|
605
|
+
DepStatus.OPEN,
|
|
606
|
+
f"{standing.named}: {_open_detail(self.open_in_block(label))}",
|
|
607
|
+
)
|
|
608
|
+
return Resolution(dep, kind, _SATISFIES[standing.stage], standing.sentence)
|
|
609
|
+
|
|
610
|
+
def _resolve_task(self, dep: Dep, kind: DepKind) -> Resolution:
|
|
611
|
+
# A **partial** is read before the ledger (RK396). `ship --part` writes an entry and
|
|
612
|
+
# deliberately leaves the line open at ⏳, so membership stopped meaning the work is
|
|
613
|
+
# finished — and the dependent was annotated ✅ by the half that landed rather than by
|
|
614
|
+
# the half it waits on, which is the one thing this annotation exists to prevent.
|
|
615
|
+
#
|
|
616
|
+
# Narrowed to the qualifier the entry carries, and not to "open line wins", because
|
|
617
|
+
# an id in both files with *no* qualifier is a ship that crashed between its writes:
|
|
618
|
+
# there the intended end state is shipped, `deps.stale` on the dependents is part of
|
|
619
|
+
# what makes that middle state loud (RK118), and reading it as open would quietly
|
|
620
|
+
# complete the transaction's story in the one file that had not been written yet.
|
|
621
|
+
landed = self.partial(dep.id)
|
|
622
|
+
open_line = self.entry(dep.id)
|
|
623
|
+
if landed and open_line is not None:
|
|
624
|
+
where = f" in Block {open_line.task.block}" if open_line.task.block else ""
|
|
625
|
+
return Resolution(
|
|
626
|
+
dep, kind, DepStatus.OPEN, f"open{where}, the {landed} in the changelog"
|
|
627
|
+
)
|
|
628
|
+
if dep.id in self.shipped():
|
|
629
|
+
return Resolution(dep, kind, DepStatus.SHIPPED, "in the changelog")
|
|
630
|
+
gone = self.retired().get(dep.id)
|
|
631
|
+
if gone is not None:
|
|
632
|
+
# Unresolvable and not unknown: the record exists and says the work will not
|
|
633
|
+
# happen, so waiting is over in the one direction that never satisfies. What
|
|
634
|
+
# has to change is this line, and the retired line's own sentence says how.
|
|
635
|
+
return Resolution(
|
|
636
|
+
dep, kind, DepStatus.UNRESOLVABLE, f"retired — {_clip(gone.task.why)}"
|
|
637
|
+
)
|
|
638
|
+
found = self.entry(dep.id)
|
|
639
|
+
if found is not None:
|
|
640
|
+
detail = f"open in Block {found.task.block}" if found.task.block else "open"
|
|
641
|
+
return Resolution(dep, kind, DepStatus.OPEN, detail)
|
|
642
|
+
paused = self.deferred().get(dep.id)
|
|
643
|
+
if paused is not None:
|
|
644
|
+
# Checked after the roadmap and before "unknown" (RK92): the store is the one
|
|
645
|
+
# place a recorded id can be that is neither open nor terminal, and reporting
|
|
646
|
+
# it as a gap in the files would send the reader looking for a typo.
|
|
647
|
+
return Resolution(
|
|
648
|
+
dep, kind, DepStatus.DEFERRED, f"set aside — {_clip(paused.task.why)}"
|
|
649
|
+
)
|
|
650
|
+
return Resolution(
|
|
651
|
+
dep, kind, DepStatus.UNKNOWN, "in neither the roadmap nor the changelog"
|
|
652
|
+
)
|
|
653
|
+
|
|
654
|
+
def expand(self, dep: Dep) -> tuple[str, ...]:
|
|
655
|
+
"""The open tasks a collective dep names, in file order; empty for the other kinds.
|
|
656
|
+
|
|
657
|
+
`Block P` is one token and resolved to forty-eight open tasks in Shio; `T451–T457`
|
|
658
|
+
is one token and names seven. Public and here rather than inside the graph because
|
|
659
|
+
two callers need the same answer: the traversal, which would otherwise walk into a
|
|
660
|
+
dep it treats as opaque, and the gate, which says out loud what the abbreviation
|
|
661
|
+
costs whoever counts deps to judge how blocked a line is (RK35).
|
|
662
|
+
"""
|
|
663
|
+
schema = self.config.schema
|
|
664
|
+
kind = schema.classify_dep(dep)
|
|
665
|
+
if kind is DepKind.BLOCK:
|
|
666
|
+
label = schema.block_of_dep(dep)
|
|
667
|
+
return self.open_in_block(label) if label else ()
|
|
668
|
+
return self._open_in_range(dep) if kind is DepKind.RANGE else ()
|
|
669
|
+
|
|
670
|
+
def _open_in_range(self, dep: Dep) -> tuple[str, ...]:
|
|
671
|
+
"""The still-open ids a range dep names — bounded by its numbers *and* its track.
|
|
672
|
+
|
|
673
|
+
One implementation, because `resolve_dep` and `open_for` used to hold two and a
|
|
674
|
+
range that counted one family in one of them would have been a dep whose detail
|
|
675
|
+
line disagreed with its status.
|
|
676
|
+
"""
|
|
677
|
+
schema = self.config.schema
|
|
678
|
+
bounds = schema.range_of_dep(dep)
|
|
679
|
+
family = schema.family_of_dep(dep)
|
|
680
|
+
if bounds is None or family is None:
|
|
681
|
+
return ()
|
|
682
|
+
first, last = bounds
|
|
683
|
+
return tuple(
|
|
684
|
+
entry.task.id
|
|
685
|
+
for entry in self.roadmap.entries
|
|
686
|
+
# `number_of` against the *one* family, not all of them: `C14–C20` counts in
|
|
687
|
+
# cursarei's product track and must not be satisfied by `V15` shipping.
|
|
688
|
+
if (number := number_of(entry.task.id, schema, family)) is not None
|
|
689
|
+
and first <= number <= last
|
|
690
|
+
)
|
|
691
|
+
|
|
692
|
+
def resolve(self, task: Task) -> tuple[Resolution, ...]:
|
|
693
|
+
return tuple(self.resolve_dep(dep) for dep in task.deps)
|
|
694
|
+
|
|
695
|
+
def readiness(self, task: Task) -> Readiness:
|
|
696
|
+
"""Ready, or blocked in one of the three senses that differ (RK28, RK92).
|
|
697
|
+
|
|
698
|
+
Ordered by how permanent the answer is, so a line with two kinds of blocker
|
|
699
|
+
reports the one nothing on this backlog's own path resolves: unresolvable outranks
|
|
700
|
+
paused, because no line the roadmap now holds satisfies it while a paused one
|
|
701
|
+
resumes; and paused outranks blocked, because an open blocker is somebody's next
|
|
702
|
+
task while a deferred one is a decision nobody has revisited.
|
|
703
|
+
"""
|
|
704
|
+
resolutions = self.resolve(task)
|
|
705
|
+
if any(r.status is DepStatus.UNRESOLVABLE for r in resolutions):
|
|
706
|
+
return Readiness.OUTSIDE
|
|
707
|
+
if all(r.satisfied for r in resolutions):
|
|
708
|
+
return Readiness.READY
|
|
709
|
+
if any(r.status is DepStatus.DEFERRED for r in resolutions):
|
|
710
|
+
return Readiness.PAUSED
|
|
711
|
+
return Readiness.BLOCKED
|
|
712
|
+
|
|
713
|
+
|
|
714
|
+
def number_of(task_id: str, schema: Schema, family: str | None = None) -> int | None:
|
|
715
|
+
"""The numeric part of an id of this project, or None if it is not one.
|
|
716
|
+
|
|
717
|
+
Public because a range dep is bounded by numbers: `C14–C20` asks which open lines fall
|
|
718
|
+
between two of them, and that is a question about the number alone.
|
|
719
|
+
|
|
720
|
+
Takes the :class:`~roadkeep.kernel.schema.Schema` and not `prefixes` plus a flag (RK109). The
|
|
721
|
+
shape is one declaration — the families (RK74), the width and the sub-letter (RK106) —
|
|
722
|
+
and a signature that let a caller pass two thirds of it is how the ordering came to
|
|
723
|
+
read a `D1` its own gate refuses. ``family`` narrows the answer to one track, because
|
|
724
|
+
`C14–C20` counts in cursarei's product track and must not be satisfied by `V15`.
|
|
725
|
+
"""
|
|
726
|
+
parsed = schema.parse_id(task_id)
|
|
727
|
+
if parsed is None or (family is not None and parsed.family != family):
|
|
728
|
+
return None
|
|
729
|
+
return parsed.number
|
|
730
|
+
|
|
731
|
+
|
|
732
|
+
def id_order(task_id: str, schema: Schema) -> tuple[int, int, str, str]:
|
|
733
|
+
"""How ids sort — the one answer `pick`, `lint` and `--fix` all order by (RK109).
|
|
734
|
+
|
|
735
|
+
"Lowest id" is a numeric comparison, and three call sites each wrote it as
|
|
736
|
+
``number_of(...) or 0``, which put anything unreadable *first*: the split task a
|
|
737
|
+
project deliberately numbered after `T24` would have been offered ahead of `T1`. Here
|
|
738
|
+
an id this project cannot read sorts **last**, by its own text, because a string the
|
|
739
|
+
gate refuses is not a claim on the front of the queue — and `T24b` sorts directly after
|
|
740
|
+
`T24`, the sub-letter being the tie-break it was written to be.
|
|
741
|
+
"""
|
|
742
|
+
parsed = schema.parse_id(task_id)
|
|
743
|
+
if parsed is None:
|
|
744
|
+
return (1, 0, "", task_id)
|
|
745
|
+
return (0, parsed.number, parsed.sub, task_id)
|
|
746
|
+
|
|
747
|
+
|
|
748
|
+
def _present(config: Config, role: str) -> Document | None:
|
|
749
|
+
"""One optional governed file, or None where it is undeclared or not written yet.
|
|
750
|
+
|
|
751
|
+
A declared file that is not on disk yet is absent, not empty — `init` (RK18) creates
|
|
752
|
+
it, and refusing every question until then would be an obstacle.
|
|
753
|
+
"""
|
|
754
|
+
if not config.has(role) or not config.path(role).is_file():
|
|
755
|
+
return None
|
|
756
|
+
return config.document(role)
|
|
757
|
+
|
|
758
|
+
|
|
759
|
+
def _clip(sentence: str, limit: int = 90) -> str:
|
|
760
|
+
"""One line of detail. The whole sentence is one `show <id>` away."""
|
|
761
|
+
return sentence if len(sentence) <= limit else sentence[: limit - 1].rstrip() + "…"
|
|
762
|
+
|
|
763
|
+
|
|
764
|
+
def _open_detail(still_open: tuple[str, ...]) -> str:
|
|
765
|
+
"""`n open: a, b, c …` — bounded, because a detail line nobody reads is noise."""
|
|
766
|
+
shown = ", ".join(still_open[:4])
|
|
767
|
+
return f"{len(still_open)} open: {shown}" + (" …" if len(still_open) > 4 else "")
|