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/locking.py
ADDED
|
@@ -0,0 +1,209 @@
|
|
|
1
|
+
"""Serialising the write path, so an id is spent by whoever minted it (RK117).
|
|
2
|
+
|
|
3
|
+
`next_id` (RK4) is *derived* — one past the highest id anywhere — and that is right: a
|
|
4
|
+
counter file would be a second source of truth, and it would drift the first time somebody
|
|
5
|
+
edited the roadmap by hand. What was missing is that the answer is computed at one moment
|
|
6
|
+
and spent at another. Two agents adding in the same checkout both scan a tree whose highest
|
|
7
|
+
is RK115, are both told RK116, and both write it.
|
|
8
|
+
|
|
9
|
+
So what is made indivisible here is **the whole span from scan to save**, not the scan.
|
|
10
|
+
A mutating command reads its own inputs and lives for milliseconds, so putting every one of
|
|
11
|
+
them behind a single exclusive lock costs nothing measurable and closes the window entirely.
|
|
12
|
+
The query surface never takes it, which is what keeps `pick` and `brief` answering during a
|
|
13
|
+
write — and what keeps `guard` (RK22), which runs before every write in the session, from
|
|
14
|
+
waiting on the write it was called about.
|
|
15
|
+
|
|
16
|
+
Three things this is not:
|
|
17
|
+
|
|
18
|
+
* **Not a second store (L2).** It holds no fact about any task: it is transient, it lives
|
|
19
|
+
outside the repository entirely, and deleting it while nothing is running loses nothing.
|
|
20
|
+
* **Not a promise about other writers.** A lock orders the processes that agree to take it.
|
|
21
|
+
An editor, a `git checkout` or a hand edit takes nothing — those are :class:`StaleFile`'s
|
|
22
|
+
subject (RK116), and the two mechanisms are complementary rather than alternatives.
|
|
23
|
+
* **Not waited on forever.** The holder may have been killed, and a lock nobody will ever
|
|
24
|
+
release is an unusable checkout. There is no portable way to ask whether a pid is alive,
|
|
25
|
+
so abandonment is judged by **age**: past :data:`STALE` seconds the lock is reaped and the
|
|
26
|
+
waiter proceeds. The wait is much shorter than that, deliberately — a caller learns in
|
|
27
|
+
seconds that the checkout is busy, and only a lock old enough that no command could still
|
|
28
|
+
be running is taken away from whoever left it.
|
|
29
|
+
"""
|
|
30
|
+
|
|
31
|
+
from __future__ import annotations
|
|
32
|
+
|
|
33
|
+
import contextlib
|
|
34
|
+
import hashlib
|
|
35
|
+
import os
|
|
36
|
+
import tempfile
|
|
37
|
+
import time
|
|
38
|
+
from collections.abc import Iterator
|
|
39
|
+
from pathlib import Path
|
|
40
|
+
|
|
41
|
+
#: How long a lock may be held before it is read as abandoned rather than held. Three
|
|
42
|
+
#: orders of magnitude above what a mutating command takes, because reaping a lock somebody
|
|
43
|
+
#: still holds is the one failure worse than waiting — it hands two writers one checkout,
|
|
44
|
+
#: which is the defect rather than the fix.
|
|
45
|
+
STALE = 60.0
|
|
46
|
+
#: How long a command waits before it refuses. Far **below** :data:`STALE`, and the gap is
|
|
47
|
+
#: the whole design: a waiter that gave up only when it was also entitled to reap would
|
|
48
|
+
#: never refuse at all, and would steal the lock of every command slower than it expected.
|
|
49
|
+
#: So a busy checkout is reported in seconds, and an abandoned one is cleared in a minute.
|
|
50
|
+
WAIT = 5.0
|
|
51
|
+
#: How often the waiter looks. Small enough that ordinary contention is invisible.
|
|
52
|
+
POLL = 0.05
|
|
53
|
+
|
|
54
|
+
#: How many times this process has taken the lock. `report` and `replay` re-enter
|
|
55
|
+
#: :func:`roadkeep.cli.main` in the same process to run the command they are about (RK85),
|
|
56
|
+
#: and a lock that deadlocked on that would make the capture tool unusable against exactly
|
|
57
|
+
#: the commands worth capturing. Re-entrant here rather than remembered at those two call
|
|
58
|
+
#: sites, because the hazard is a property of the lock and not of its callers.
|
|
59
|
+
_depth = 0
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
class LockBusy(RuntimeError):
|
|
63
|
+
"""Another roadkeep process is writing to this checkout and did not finish (RK117).
|
|
64
|
+
|
|
65
|
+
Reported and never worked around: proceeding is the duplicate id this exists to stop.
|
|
66
|
+
Names the file, because a lock whose holder died is deleted by hand in the one case the
|
|
67
|
+
age rule is too slow for.
|
|
68
|
+
"""
|
|
69
|
+
|
|
70
|
+
def __init__(self, path: Path, holder: str = "") -> None:
|
|
71
|
+
self.path = path
|
|
72
|
+
self.holder = holder
|
|
73
|
+
who = f" ({holder})" if holder else ""
|
|
74
|
+
super().__init__(
|
|
75
|
+
f"another roadkeep process is writing to this checkout{who} and did not "
|
|
76
|
+
f"release its lock within {WAIT:.0f}s — re-run the command, or delete "
|
|
77
|
+
f"{path} if nothing is running"
|
|
78
|
+
)
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
def sidecar(root: Path | str, suffix: str) -> Path:
|
|
82
|
+
"""One transient file belonging to this checkout, living outside it.
|
|
83
|
+
|
|
84
|
+
In the temp directory and not in the repository, because a file the tool creates in a
|
|
85
|
+
project's root is a file every adopting project has to add to its `.gitignore` before
|
|
86
|
+
the first `git status` reads as dirty. Keyed by the *resolved* root so two checkouts of
|
|
87
|
+
one project are independent — which is the scope the defect has: two agents in one
|
|
88
|
+
working tree. The digest carries the directory's name in front of it so a human looking
|
|
89
|
+
at a temp directory can tell which project the file belongs to.
|
|
90
|
+
|
|
91
|
+
Shared with :mod:`roadkeep.storing` (RK330) rather than copied: two transient files keyed
|
|
92
|
+
by one checkout through two digests would be two answers to "which project is this", and
|
|
93
|
+
the one that drifts is whichever was written second. This is what the lock has in common
|
|
94
|
+
with the store and all it has — its own state is the *existence* of a file, which is the
|
|
95
|
+
one thing both platforms make atomic, and a lock that had to be parsed to be taken would
|
|
96
|
+
be a lock with the race in it that this module exists to close.
|
|
97
|
+
"""
|
|
98
|
+
resolved = Path(root).resolve()
|
|
99
|
+
digest = hashlib.sha256(str(resolved).encode("utf-8")).hexdigest()[:16]
|
|
100
|
+
return Path(tempfile.gettempdir()) / f"roadkeep-{resolved.name}-{digest}.{suffix}"
|
|
101
|
+
|
|
102
|
+
|
|
103
|
+
def lock_path(root: Path | str) -> Path:
|
|
104
|
+
"""Where this checkout's lock lives — outside it, keyed by its resolved path."""
|
|
105
|
+
return sidecar(root, "lock")
|
|
106
|
+
|
|
107
|
+
|
|
108
|
+
@contextlib.contextmanager
|
|
109
|
+
def exclusive(root: Path | str) -> Iterator[Path]:
|
|
110
|
+
"""Hold this checkout's write lock for the whole of a mutating command.
|
|
111
|
+
|
|
112
|
+
Around the *command* and not around the write, which is the only placement that helps:
|
|
113
|
+
the id is decided by a scan at the start and spent by a save at the end, and a lock
|
|
114
|
+
taken between them would be held for the half of the span that was never in doubt.
|
|
115
|
+
"""
|
|
116
|
+
global _depth
|
|
117
|
+
target = lock_path(root)
|
|
118
|
+
if _depth:
|
|
119
|
+
# Already ours. Nothing to claim and — crucially — nothing to release either, or
|
|
120
|
+
# the inner command would hand the outer one's lock to whoever is waiting.
|
|
121
|
+
_depth += 1
|
|
122
|
+
try:
|
|
123
|
+
yield target
|
|
124
|
+
finally:
|
|
125
|
+
_depth -= 1
|
|
126
|
+
return
|
|
127
|
+
|
|
128
|
+
token = _claim(target)
|
|
129
|
+
_depth = 1
|
|
130
|
+
try:
|
|
131
|
+
yield target
|
|
132
|
+
finally:
|
|
133
|
+
_depth = 0
|
|
134
|
+
_release(target, token)
|
|
135
|
+
|
|
136
|
+
|
|
137
|
+
def _claim(target: Path) -> str:
|
|
138
|
+
"""Create the lock exclusively, waiting for one that is held and reaping one that is not.
|
|
139
|
+
|
|
140
|
+
`O_CREAT | O_EXCL` is the whole mechanism: it is one atomic syscall on both POSIX and
|
|
141
|
+
Windows, so two processes reaching it together produce exactly one winner. Nothing here
|
|
142
|
+
reads the file to decide — a check followed by a create is the race this replaces.
|
|
143
|
+
"""
|
|
144
|
+
token = _token()
|
|
145
|
+
deadline = time.monotonic() + WAIT
|
|
146
|
+
while True:
|
|
147
|
+
try:
|
|
148
|
+
handle = os.open(target, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
|
|
149
|
+
except FileExistsError:
|
|
150
|
+
if _abandoned(target):
|
|
151
|
+
_reap(target)
|
|
152
|
+
continue
|
|
153
|
+
if time.monotonic() >= deadline:
|
|
154
|
+
raise LockBusy(target, _holder(target)) from None
|
|
155
|
+
time.sleep(POLL)
|
|
156
|
+
continue
|
|
157
|
+
with os.fdopen(handle, "w", encoding="utf-8") as writer:
|
|
158
|
+
writer.write(token)
|
|
159
|
+
return token
|
|
160
|
+
|
|
161
|
+
|
|
162
|
+
def _token() -> str:
|
|
163
|
+
"""What is written into the lock: enough to name the holder, and to recognise it later.
|
|
164
|
+
|
|
165
|
+
The pid alone would be ambiguous across a reap — a reaped lock retaken by a process that
|
|
166
|
+
happens to reuse the pid would be released by the wrong one. The claim time makes it
|
|
167
|
+
unique in practice, and it is the thing a reader most wants to see anyway.
|
|
168
|
+
"""
|
|
169
|
+
return f"pid {os.getpid()} at {time.time():.6f}\n"
|
|
170
|
+
|
|
171
|
+
|
|
172
|
+
def _holder(target: Path) -> str:
|
|
173
|
+
"""What the lock says about who holds it, or nothing if it cannot be read."""
|
|
174
|
+
try:
|
|
175
|
+
return target.read_text(encoding="utf-8").strip()
|
|
176
|
+
except OSError:
|
|
177
|
+
return ""
|
|
178
|
+
|
|
179
|
+
|
|
180
|
+
def _abandoned(target: Path) -> bool:
|
|
181
|
+
"""Is this lock older than any command that could still be running?
|
|
182
|
+
|
|
183
|
+
False when the file is gone: it was released or reaped between the failed create and
|
|
184
|
+
this call, and the caller's next attempt is the one that finds out.
|
|
185
|
+
"""
|
|
186
|
+
try:
|
|
187
|
+
return time.time() - target.stat().st_mtime > STALE
|
|
188
|
+
except OSError:
|
|
189
|
+
return False
|
|
190
|
+
|
|
191
|
+
|
|
192
|
+
def _reap(target: Path) -> None:
|
|
193
|
+
with contextlib.suppress(OSError):
|
|
194
|
+
target.unlink()
|
|
195
|
+
|
|
196
|
+
|
|
197
|
+
def _release(target: Path, token: str) -> None:
|
|
198
|
+
"""Give up the lock, but only while it is still the one this process took.
|
|
199
|
+
|
|
200
|
+
The check matters because reaping exists: a holder slow enough to be declared abandoned
|
|
201
|
+
would otherwise delete the lock of whoever reaped it, and hand a third process a
|
|
202
|
+
checkout two are writing to. Reading before unlinking leaves a window of microseconds
|
|
203
|
+
where that is still possible; what it removes is the case where it is *certain*.
|
|
204
|
+
"""
|
|
205
|
+
try:
|
|
206
|
+
if target.read_text(encoding="utf-8") == token:
|
|
207
|
+
target.unlink()
|
|
208
|
+
except OSError:
|
|
209
|
+
pass
|
roadkeep/markers.py
ADDED
|
@@ -0,0 +1,172 @@
|
|
|
1
|
+
"""The dep annotation as derived data, never as typed data (RK8).
|
|
2
|
+
|
|
3
|
+
`(deps: RK1 ✅)` is a **cache of another line's status**, and it is the one field in the
|
|
4
|
+
format that can be wrong without anybody editing it: the moment RK1 ships, every line
|
|
5
|
+
that named it says something false, and the failure is silent in the worst direction — a
|
|
6
|
+
ready task reads as blocked, so `pick` (RK11) skips it and the backlog quietly stalls.
|
|
7
|
+
|
|
8
|
+
So the annotation is derived on every write, from the resolver that already answers the
|
|
9
|
+
question (RK28). Three rules, and the second is what keeps derivation from becoming churn:
|
|
10
|
+
|
|
11
|
+
* **Shipped is always annotated ✅** — a task in the ledger, a block the ledger has
|
|
12
|
+
finished, a range with no open member: one answer, because all three mean "waiting on
|
|
13
|
+
this is over". Nothing open was two states and only one of them is this one (RK432).
|
|
14
|
+
This is the annotation a reader acts on and the only one that goes stale by itself.
|
|
15
|
+
* **An annotation that exists is kept true; one that was never written is not invented.**
|
|
16
|
+
Shio annotates `⏳` and `📋` deps and those follow their target's marker, while this
|
|
17
|
+
project writes a bare `(deps: RK14)` for open work and keeps it bare. Deriving a marker
|
|
18
|
+
onto every open dep would rewrite half a backlog to say what `deps <id>` answers better.
|
|
19
|
+
* **Unresolvable or unknown → left exactly as written.** Derivation never invents a status
|
|
20
|
+
it cannot read, and never deletes one it did not write; an unknown id is a lint error
|
|
21
|
+
(RK14), not a rendering choice. The rule is about a dep naming **one** line, whose marker
|
|
22
|
+
could be the author's reading of it. A `Block X` or a range names many, so its marker was
|
|
23
|
+
derived by construction and is dropped wherever the collection is not settled (RK432) —
|
|
24
|
+
including a label no heading declares, where a ✅ is the false claim the resolver refuses
|
|
25
|
+
and this rule used to keep in the file.
|
|
26
|
+
|
|
27
|
+
:func:`refresh` applies this to a whole document, and it is deliberately *whole-file*: any
|
|
28
|
+
write is an opportunity to make every annotation true, and a tool that refreshed only the
|
|
29
|
+
line it touched would leave the file in a state where some annotations are derived and
|
|
30
|
+
some are remembered. What it will not do is write a line that the schema would then
|
|
31
|
+
refuse — a derived ✅ makes a line two characters longer, so a line already at the cap is
|
|
32
|
+
reported (:class:`~roadkeep.kernel.schema.SchemaError`) and the whole write is refused. That
|
|
33
|
+
report names the line's id and `file:line` (RK348): it is a dependent's sentence and never
|
|
34
|
+
the one the caller passed, so a bare count sends the author to shorten the wrong prose.
|
|
35
|
+
"""
|
|
36
|
+
|
|
37
|
+
from __future__ import annotations
|
|
38
|
+
|
|
39
|
+
from dataclasses import dataclass, replace
|
|
40
|
+
|
|
41
|
+
from roadkeep.backlog import Backlog, DepStatus
|
|
42
|
+
from roadkeep.kernel.document import Document, Entry
|
|
43
|
+
from roadkeep.kernel.schema import Dep, SchemaError, Task
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
@dataclass(frozen=True, slots=True)
|
|
47
|
+
class Refresh:
|
|
48
|
+
"""The document with every annotation derived, and whose lines that changed."""
|
|
49
|
+
|
|
50
|
+
document: Document
|
|
51
|
+
changed: tuple[str, ...] = ()
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
def derive(backlog: Backlog, task: Task) -> Task:
|
|
55
|
+
"""The same task with every dep annotation re-derived from the backlog."""
|
|
56
|
+
return replace(task, deps=tuple(_annotate(backlog, dep) for dep in task.deps))
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
def refresh(backlog: Backlog) -> Refresh:
|
|
60
|
+
"""Re-derive every annotation in the roadmap. Refuses rather than write a bad line.
|
|
61
|
+
|
|
62
|
+
Returns the document unsaved: the caller is usually mid-transaction (`ship` has a
|
|
63
|
+
ledger entry to write in the same breath), and a refresh that saved on its own would
|
|
64
|
+
make the third of three edits the first one on disk.
|
|
65
|
+
"""
|
|
66
|
+
document = backlog.roadmap
|
|
67
|
+
changed: list[str] = []
|
|
68
|
+
# Every line this write would overflow, and not the first one found (RK1152). A `ship` that
|
|
69
|
+
# ticks three dependents used to refuse three times: each refusal named one line, the author
|
|
70
|
+
# amended it, and the next was discovered only by re-running the command. The scan is
|
|
71
|
+
# unaffected by collecting rather than raising — `derive` reads the backlog and not the
|
|
72
|
+
# document being rebuilt — so the second overflow is as true as the first.
|
|
73
|
+
refused: list[tuple[Entry, SchemaError]] = []
|
|
74
|
+
for entry in backlog.roadmap.entries:
|
|
75
|
+
derived = derive(backlog, entry.task)
|
|
76
|
+
if document.schema.render(derived) == entry.raw:
|
|
77
|
+
continue
|
|
78
|
+
# Only what this write would change is validated: a violation elsewhere in the
|
|
79
|
+
# file is `lint`'s to report, not this command's to refuse.
|
|
80
|
+
try:
|
|
81
|
+
document.schema.check(derived)
|
|
82
|
+
except SchemaError as error:
|
|
83
|
+
refused.append((entry, error))
|
|
84
|
+
continue
|
|
85
|
+
current = next(e for e in document.entries if e.lineno == entry.lineno)
|
|
86
|
+
document = document.replace_task(current, derived)
|
|
87
|
+
changed.append(entry.task.id)
|
|
88
|
+
if refused:
|
|
89
|
+
raise _naming_the_lines(backlog, refused) from None
|
|
90
|
+
return Refresh(document=document, changed=tuple(changed))
|
|
91
|
+
|
|
92
|
+
|
|
93
|
+
def _naming_the_lines(
|
|
94
|
+
backlog: Backlog, refused: list[tuple[Entry, SchemaError]]
|
|
95
|
+
) -> SchemaError:
|
|
96
|
+
"""The refusal, addressed to the line it is about and not to the caller's text (RK348, RK1152).
|
|
97
|
+
|
|
98
|
+
A length reported as a bare number reads as *your sentence is too long*, and here it never is:
|
|
99
|
+
the sentence that went over belongs to a **dependent**, and it went over because this write
|
|
100
|
+
re-derived its `(deps: …)` annotation and a ✅ costs two characters. RK348 put the id and the
|
|
101
|
+
`file:line` in the message and put them at the **end**, after the remedy — so the sentence
|
|
102
|
+
still opened `delete 1 character` about the string the caller had just typed, and the clause
|
|
103
|
+
that redirects it arrived once the reader had already acted. Measured on Shio: `ship DD34`
|
|
104
|
+
refused three times, three amends, each next line found by re-running the command.
|
|
105
|
+
|
|
106
|
+
So the address **leads**, and the command that closes it is named the way every `lint` finding
|
|
107
|
+
names one (RK14/15): the edit is `amend <the dependent> --why …`, never a shorter `--why` here.
|
|
108
|
+
What the limit is survives after it, because a refusal that only says what to type teaches
|
|
109
|
+
nobody why the field exists. The repair itself stays the author's — trimming a dependent's
|
|
110
|
+
`why` to make room for a marker nobody typed is a real edit, and only discovering *which*
|
|
111
|
+
line by elimination was the defect.
|
|
112
|
+
|
|
113
|
+
Every refused line in one error, so one edit round closes what took three.
|
|
114
|
+
"""
|
|
115
|
+
from roadkeep.provenance import invocation # noqa: PLC0415 - RK260, the refusal path only
|
|
116
|
+
|
|
117
|
+
where = backlog.roadmap.path
|
|
118
|
+
violations = []
|
|
119
|
+
for entry, error in refused:
|
|
120
|
+
address = (
|
|
121
|
+
f"{backlog.config.relative(where)}:{entry.lineno}"
|
|
122
|
+
if where is not None
|
|
123
|
+
else f"line {entry.lineno}"
|
|
124
|
+
)
|
|
125
|
+
lead = f"on {entry.task.id}'s line ({address}), not on the text passed here — "
|
|
126
|
+
said = (
|
|
127
|
+
f" — `{invocation()} amend {entry.task.id} --why …` is the edit: this write "
|
|
128
|
+
f"re-derives that line's dep annotation, and a marker is two characters wider"
|
|
129
|
+
)
|
|
130
|
+
violations += [
|
|
131
|
+
replace(one, message=f"{lead}{one.message}{said}") for one in error.violations
|
|
132
|
+
]
|
|
133
|
+
return SchemaError(tuple(violations))
|
|
134
|
+
|
|
135
|
+
|
|
136
|
+
def _annotate(backlog: Backlog, dep: Dep) -> Dep:
|
|
137
|
+
resolution = backlog.resolve_dep(dep)
|
|
138
|
+
if resolution.status is DepStatus.SHIPPED:
|
|
139
|
+
return replace(dep, marker=backlog.config.schema.shipped_marker)
|
|
140
|
+
if resolution.status is DepStatus.DEFERRED:
|
|
141
|
+
# Written whether or not one was typed, which is ✅'s rule and not the open set's
|
|
142
|
+
# (RK92): a paused blocker is the one state the dependent's own line cannot show,
|
|
143
|
+
# and an unannotated dep on it reads as ordinary open work somebody is doing.
|
|
144
|
+
#
|
|
145
|
+
# On a **block** it claims what `Stage.PAUSED` claims and not what a ⏸ on a line
|
|
146
|
+
# does (RK432): not that every member was set aside, but that the label is at the
|
|
147
|
+
# stage with nothing open and something waiting on a `resume`. That is the reading
|
|
148
|
+
# the resolution's own sentence spells on the row above it, so the marker
|
|
149
|
+
# summarises rather than overstates — which is the test the rule below applies.
|
|
150
|
+
return replace(dep, marker=backlog.config.schema.deferred_marker)
|
|
151
|
+
if resolution.kind.collective:
|
|
152
|
+
# A block or a range is many lines with many markers, so a marker on one is dropped
|
|
153
|
+
# rather than replaced: any single one would claim too much. Reached now for every
|
|
154
|
+
# state the collection is not settled in, and not only for `open` (RK432) — a
|
|
155
|
+
# heading declared before its first line used to derive ✅ here, and leaving it to
|
|
156
|
+
# the preserve rule below would freeze in the file the exact false statement this
|
|
157
|
+
# resolver stopped making. Nothing of the author's is lost: a collective annotation
|
|
158
|
+
# is derived by construction, there being no single line it could have been typed
|
|
159
|
+
# about, which is why the rule below is about a dep naming one.
|
|
160
|
+
return dep if dep.marker is None else replace(dep, marker=None)
|
|
161
|
+
if resolution.status is DepStatus.OPEN:
|
|
162
|
+
if dep.marker is None and not backlog.partial(dep.id):
|
|
163
|
+
return dep # unannotated open work stays unannotated
|
|
164
|
+
# Written whether or not one was typed where the blocker shipped in halves (RK396),
|
|
165
|
+
# for the reason RK92 writes the paused one: the ledger already records that part of
|
|
166
|
+
# this dep landed, and an unannotated dep reads as work nobody has started on — which
|
|
167
|
+
# is the reading that sends somebody to pick up the half that is still open.
|
|
168
|
+
entry = backlog.entry(dep.id)
|
|
169
|
+
return replace(dep, marker=entry.task.status if entry is not None else None)
|
|
170
|
+
# UNKNOWN and UNRESOLVABLE: nothing to read, so nothing is written — including the
|
|
171
|
+
# marker an author typed, which is preserved rather than judged.
|
|
172
|
+
return dep
|