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