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/claiming.py
ADDED
|
@@ -0,0 +1,1019 @@
|
|
|
1
|
+
"""What *taken* means, dated outside the repository (RK119).
|
|
2
|
+
|
|
3
|
+
`pick` (RK11) is a pure function of two files, so N callers reading an unchanged backlog get
|
|
4
|
+
N identical answers — and tier 1, which prefers a 🛠 line so one worker finishes what they
|
|
5
|
+
started, hands the second agent to ask exactly the line the first one is holding, with the
|
|
6
|
+
tier name saying so. The answer to that is that answering becomes a **write**: the marker
|
|
7
|
+
flips inside the same serialised transaction that chose the line
|
|
8
|
+
(:func:`roadkeep.picking.take`), so the next caller reads a file that has already moved.
|
|
9
|
+
|
|
10
|
+
That leaves the half a marker cannot carry. 🛠 says the work is under way; it does not say
|
|
11
|
+
whether the claim is still live, and a claim held by nobody is a task nobody can pick. So
|
|
12
|
+
**when** a claim was taken is recorded here — and here is deliberately the same place the
|
|
13
|
+
write lock lives (RK117), for the same three reasons:
|
|
14
|
+
|
|
15
|
+
* **Not a second store (L2).** It holds no fact about any task. What is durable is
|
|
16
|
+
*claimed* — the 🛠 the roadmap carries, which git moves between checkouts — and this file
|
|
17
|
+
only dates it. Delete it while nothing is running and every claim reads as expired, which
|
|
18
|
+
is precisely the behaviour before this existed: a 🛠 line nobody holds is offered again.
|
|
19
|
+
* **An expiry, not a lock.** Past `[claims] held` a claim is stepped over and the line is
|
|
20
|
+
offered as ordinary half-done work. There is no portable way to ask whether the worker is
|
|
21
|
+
still alive, and an agent that was killed must not take a task out of the backlog for
|
|
22
|
+
ever — a claim nobody can break is the failure, not the fix. How long that window is is
|
|
23
|
+
the one number here that is a judgement about how long work takes, so it is the project's
|
|
24
|
+
to declare (L6) and bounded at both ends where it is read (RK151).
|
|
25
|
+
* **No owner.** An owner field would be a schema change carrying a fact that lives outside
|
|
26
|
+
the repository; the identity behind a claim belongs in the commit. So a claim is
|
|
27
|
+
recognised and never attributed, which is why `pick` *names* the ids it stepped around
|
|
28
|
+
rather than only counting them: recognising one's own claim is the caller's to do, and it
|
|
29
|
+
cannot be done against a number.
|
|
30
|
+
|
|
31
|
+
What the registry holds is a **date**, and what that date *means* is three different things
|
|
32
|
+
depending on the line and the window — so :func:`survey` is the read that says which (RK161),
|
|
33
|
+
and where the file is. Every other question this tool answers is a command (L5); this was the
|
|
34
|
+
one that had to be answered by finding a temp file whose name is a digest.
|
|
35
|
+
|
|
36
|
+
What a claim *says its commit owns* is the one field here that is not about the line at all
|
|
37
|
+
(RK280), and :func:`departing` is what finally calls it (RK294): a scope declared and never
|
|
38
|
+
read back at the moment of committing is the advice `agents.md` already carried.
|
|
39
|
+
|
|
40
|
+
A claim is only ever read against a 🛠 line, so **the marker is what a claim follows** — which
|
|
41
|
+
:func:`follow` makes true in both directions (RK158) rather than leaving half of it to be
|
|
42
|
+
inferred by the read: a write that puts a line in progress dates a claim, and a write that
|
|
43
|
+
takes it out of progress drops one. Two doors change a claim without moving that marker at all
|
|
44
|
+
(RK156): `renumber` moves the *address* (:func:`rename`), and `defer` takes the line out of the
|
|
45
|
+
file the marker is read in, which the same rule then reads as a release. :func:`follow` is the
|
|
46
|
+
only thing that writes a *claim*, and every write it makes is a reconciliation against the lines
|
|
47
|
+
it was given (RK163) — one door, so the rule cannot come to have two behaviours. :func:`rename`
|
|
48
|
+
touches the same file and is not a second door to that rule: it moves an **address**, which is
|
|
49
|
+
the one thing about a claim the marker cannot express.
|
|
50
|
+
"""
|
|
51
|
+
|
|
52
|
+
from __future__ import annotations
|
|
53
|
+
|
|
54
|
+
import time
|
|
55
|
+
from collections.abc import Iterable, Mapping
|
|
56
|
+
from dataclasses import dataclass
|
|
57
|
+
from enum import StrEnum
|
|
58
|
+
from pathlib import Path
|
|
59
|
+
|
|
60
|
+
from roadkeep.backlog import Backlog
|
|
61
|
+
from roadkeep.config import PROSE_ROLES, ROLES, Config
|
|
62
|
+
from roadkeep.ids import CARRIERS
|
|
63
|
+
from roadkeep.kernel.document import Entry
|
|
64
|
+
from roadkeep.locking import exclusive
|
|
65
|
+
from roadkeep.kernel.schema import IN_PROGRESS, Task
|
|
66
|
+
from roadkeep.storing import Claim, Store, read, write
|
|
67
|
+
from roadkeep.storing import path as store_path
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
def window(config: Config) -> float:
|
|
71
|
+
"""This project's claim window, in seconds (RK151).
|
|
72
|
+
|
|
73
|
+
Orders of magnitude above the write lock's own :data:`~roadkeep.locking.STALE`, because
|
|
74
|
+
the two measure different spans: a lock covers one command and a claim covers the work.
|
|
75
|
+
Declared in minutes and used in seconds — the declaration is a judgement a person makes
|
|
76
|
+
about a backlog, and the arithmetic is nobody's to repeat at a call site.
|
|
77
|
+
"""
|
|
78
|
+
return config.held * 60.0
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
class AlreadyHeld(ValueError):
|
|
82
|
+
"""Taking a line a live claim already holds would be the two workers again (RK149).
|
|
83
|
+
|
|
84
|
+
Raised by the **marker write** and therefore by every door that names an id (RK160): a
|
|
85
|
+
pick was choosing anyway, so it steps around a live claim and answers with something else,
|
|
86
|
+
while a caller that said which id it wants has nothing to step to. What made this one
|
|
87
|
+
door's refusal rather than the rule's was that `status <id> 🛠` writes the same marker and
|
|
88
|
+
took the claim in the holder's name, silently — two workers on one line arriving through
|
|
89
|
+
the verb that exists to stop that.
|
|
90
|
+
|
|
91
|
+
So **nothing re-dates a live claim**, which is the invariant worth having: the window is
|
|
92
|
+
the expiry, not something a second call can postpone. Says what to do, because a claim
|
|
93
|
+
names nobody and this one may be the caller's own: the read is one call without the flag,
|
|
94
|
+
and the release is a marker.
|
|
95
|
+
"""
|
|
96
|
+
|
|
97
|
+
def __init__(self, task_id: str, since: str, marker: str) -> None:
|
|
98
|
+
self.task_id = task_id
|
|
99
|
+
super().__init__(
|
|
100
|
+
f"{task_id} was claimed {since} ago and a claim names nobody, so it may be "
|
|
101
|
+
f"yours: read it without --claim, or move the marker off {marker} to release it"
|
|
102
|
+
)
|
|
103
|
+
|
|
104
|
+
|
|
105
|
+
def since(age: float) -> str:
|
|
106
|
+
"""`14m`, `2h05m` — the figure a reader checks against how long the work should take.
|
|
107
|
+
|
|
108
|
+
One formatter, because two would eventually disagree about the same number in two answers.
|
|
109
|
+
"""
|
|
110
|
+
minutes = int(age // 60)
|
|
111
|
+
return f"{minutes}m" if minutes < 60 else f"{minutes // 60}h{minutes % 60:02d}m"
|
|
112
|
+
|
|
113
|
+
|
|
114
|
+
#: One registry row as it is on disk. Defined in :mod:`roadkeep.storing` and named here,
|
|
115
|
+
#: because the row is the store's to spell (RK330) and the *meaning* of its date is this
|
|
116
|
+
#: module's alone — a claim is a date read against a 🛠 line and a window.
|
|
117
|
+
Dating = Claim
|
|
118
|
+
|
|
119
|
+
|
|
120
|
+
@dataclass(frozen=True, slots=True)
|
|
121
|
+
class Held:
|
|
122
|
+
"""One claim a caller was not offered: which line, and how long it has been held."""
|
|
123
|
+
|
|
124
|
+
id: str
|
|
125
|
+
age: float
|
|
126
|
+
#: The paths this claim says are its commit's (RK280). Empty where none were declared,
|
|
127
|
+
#: which is every claim taken before the holder said — silence is not a claim to nothing.
|
|
128
|
+
paths: tuple[str, ...] = ()
|
|
129
|
+
|
|
130
|
+
@property
|
|
131
|
+
def since(self) -> str:
|
|
132
|
+
return since(self.age)
|
|
133
|
+
|
|
134
|
+
|
|
135
|
+
class State(StrEnum):
|
|
136
|
+
"""What the registry's entry for one id actually is (RK161).
|
|
137
|
+
|
|
138
|
+
Three, because the registry holds one thing and means three: a claim is a *date* read
|
|
139
|
+
against a 🛠 line and a window, so an entry outliving either is not a claim and is what an
|
|
140
|
+
operator is hunting when a listing is what they wanted.
|
|
141
|
+
"""
|
|
142
|
+
|
|
143
|
+
#: 🛠, inside the window: a line no answer will offer.
|
|
144
|
+
HELD = "held"
|
|
145
|
+
#: 🛠, past the window: stepped over, so the line is offered again as half-done work.
|
|
146
|
+
EXPIRED = "expired"
|
|
147
|
+
#: The marker moved on, or no line carries the id at all. Nothing reads it; the next
|
|
148
|
+
#: marker write reconciles it away.
|
|
149
|
+
STALE = "stale"
|
|
150
|
+
|
|
151
|
+
|
|
152
|
+
class Where(StrEnum):
|
|
153
|
+
"""Where the id is now — the *cause* a stale row used to report as its consequence (RK164).
|
|
154
|
+
|
|
155
|
+
"No line carries this id" is true of four different situations and useful in one of them.
|
|
156
|
+
The other three left the roadmap by a door and are recorded: the reader scanning this
|
|
157
|
+
column is deciding whether to act, and only the last of these is anything to act on.
|
|
158
|
+
"""
|
|
159
|
+
|
|
160
|
+
#: A line in the roadmap. Its own marker and block say the rest.
|
|
161
|
+
OPEN = "open"
|
|
162
|
+
SHIPPED = "shipped"
|
|
163
|
+
RETIRED = "retired"
|
|
164
|
+
PAUSED = "set aside"
|
|
165
|
+
#: In no governed file at all — the leftover, and the one row worth a second look. What
|
|
166
|
+
#: removed it is `gaps`' answer (RK31) and stays one command away: this resolves against
|
|
167
|
+
#: the files it already has open, and history is not one of them.
|
|
168
|
+
NOWHERE = "in no file at all"
|
|
169
|
+
|
|
170
|
+
|
|
171
|
+
@dataclass(frozen=True, slots=True)
|
|
172
|
+
class Dated:
|
|
173
|
+
"""One entry in the registry, and what the files make of it (RK161)."""
|
|
174
|
+
|
|
175
|
+
id: str
|
|
176
|
+
age: float
|
|
177
|
+
state: State
|
|
178
|
+
#: Where the id is now (RK164) — a roadmap line, or which door it left by.
|
|
179
|
+
where: Where = Where.OPEN
|
|
180
|
+
#: The marker the line carries, or empty where no line carries the id.
|
|
181
|
+
marker: str = ""
|
|
182
|
+
block: str = ""
|
|
183
|
+
#: The paths this row says its commit owns (RK280), in the order they were declared.
|
|
184
|
+
paths: tuple[str, ...] = ()
|
|
185
|
+
|
|
186
|
+
@property
|
|
187
|
+
def since(self) -> str:
|
|
188
|
+
return since(self.age)
|
|
189
|
+
|
|
190
|
+
@property
|
|
191
|
+
def placed(self) -> str:
|
|
192
|
+
"""Where this row is, in one column (RK164).
|
|
193
|
+
|
|
194
|
+
An open line says so with its own marker and block; anything else says which **door**
|
|
195
|
+
it left by, which is the cause and not the consequence — and the marker column is
|
|
196
|
+
dropped rather than left blank, a gap reading as something that failed.
|
|
197
|
+
|
|
198
|
+
On the record since RK1170: the listing and the row's payload are two readings of one
|
|
199
|
+
fact, and a function in the door was where only one of them could reach it.
|
|
200
|
+
"""
|
|
201
|
+
if self.where is Where.OPEN:
|
|
202
|
+
return f"{self.marker} Block {self.block}"
|
|
203
|
+
return str(self.where)
|
|
204
|
+
|
|
205
|
+
def payload(self) -> dict[str, object]:
|
|
206
|
+
"""The same row as data. `marker` and `block` are null rather than empty where no line
|
|
207
|
+
carries the id, so a consumer tells "absent" from "blank"."""
|
|
208
|
+
return {
|
|
209
|
+
"id": self.id,
|
|
210
|
+
"state": str(self.state),
|
|
211
|
+
"where": str(self.where),
|
|
212
|
+
"age": round(self.age),
|
|
213
|
+
"since": self.since,
|
|
214
|
+
"marker": self.marker or None,
|
|
215
|
+
"block": self.block or None,
|
|
216
|
+
"paths": list(self.paths),
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
def listed(self, pruned: bool = False) -> str:
|
|
220
|
+
"""One line of the registry listing (RK161, RK280).
|
|
221
|
+
|
|
222
|
+
The scope is **counted** here and named by `claim <id>`: this listing ranks nothing and
|
|
223
|
+
offers nothing, and four paths per row would make it the other command.
|
|
224
|
+
"""
|
|
225
|
+
scoped = f" {len(self.paths)} path(s)" if self.paths else ""
|
|
226
|
+
state = "pruned" if pruned else str(self.state)
|
|
227
|
+
return f" {state:<8} {self.id} claimed {self.since} ago {self.placed}{scoped}"
|
|
228
|
+
|
|
229
|
+
|
|
230
|
+
@dataclass(frozen=True, slots=True)
|
|
231
|
+
class Registry:
|
|
232
|
+
"""The claim registry read against the roadmap, as one answer (RK161).
|
|
233
|
+
|
|
234
|
+
A record since RK1170: the door held four values — the rows, what a `--prune` dropped, the
|
|
235
|
+
window and the file — and composed a header, a listing and a payload from them. Nothing
|
|
236
|
+
ranks and nothing is offered: `pick` decides what to work on, and a listing that answered
|
|
237
|
+
that would be a fourth tier nobody declared.
|
|
238
|
+
"""
|
|
239
|
+
|
|
240
|
+
rows: tuple[Dated, ...]
|
|
241
|
+
#: What `--prune` took out, and `()` where the flag was not passed. Named and not counted,
|
|
242
|
+
#: and present as an empty list when the flag was passed and dropped nothing (RK165): a
|
|
243
|
+
#: prune that hides its own effect is how "the registry is clean" gets read off a command
|
|
244
|
+
#: that emptied it.
|
|
245
|
+
dropped: tuple[Dated, ...] = ()
|
|
246
|
+
pruned: bool = False
|
|
247
|
+
#: The file itself. Named because the release is a marker and this is what an operator
|
|
248
|
+
#: deletes when a whole checkout's worth of claims outlived their workers (RK161).
|
|
249
|
+
registry: str = ""
|
|
250
|
+
#: This project's window, in minutes — the number the ages above are read against.
|
|
251
|
+
window: int = 0
|
|
252
|
+
|
|
253
|
+
@property
|
|
254
|
+
def held(self) -> int:
|
|
255
|
+
return sum(1 for one in self.rows if one.state is State.HELD)
|
|
256
|
+
|
|
257
|
+
def stated(self) -> str:
|
|
258
|
+
rows = [f"{len(self.rows)} dated, {self.held} held (window {self.window}m)"]
|
|
259
|
+
rows += [one.listed() for one in self.rows]
|
|
260
|
+
rows += [one.listed(pruned=True) for one in self.dropped]
|
|
261
|
+
if self.pruned and not self.dropped:
|
|
262
|
+
rows.append(" pruned nothing: every row is a claim")
|
|
263
|
+
rows.append(f" registry {self.registry}")
|
|
264
|
+
return chr(10).join(rows)
|
|
265
|
+
|
|
266
|
+
def payload(self) -> dict[str, object]:
|
|
267
|
+
return {
|
|
268
|
+
"window": self.window,
|
|
269
|
+
"registry": self.registry,
|
|
270
|
+
"held": self.held,
|
|
271
|
+
"claims": [one.payload() for one in self.rows],
|
|
272
|
+
"pruned": None if not self.pruned else [one.payload() for one in self.dropped],
|
|
273
|
+
}
|
|
274
|
+
|
|
275
|
+
|
|
276
|
+
def survey(backlog: Backlog) -> tuple[Dated, ...]:
|
|
277
|
+
"""Every dated id, oldest first, with what the files make of it (RK161).
|
|
278
|
+
|
|
279
|
+
The one question about a claim that was not a command: `pick` names the ready lines it
|
|
280
|
+
stepped around and its stalled list annotates a started one, so seeing *all* of them meant
|
|
281
|
+
two questions and a union — and neither reaches an entry on a line that is neither, which
|
|
282
|
+
is exactly the one somebody is looking for.
|
|
283
|
+
|
|
284
|
+
Takes the whole backlog and not the roadmap alone (RK164), because "no line carries this id"
|
|
285
|
+
is true of four situations and worth acting on in one: the ledger and the store say which
|
|
286
|
+
door the other three left by, and the reader scanning the column is deciding exactly that.
|
|
287
|
+
|
|
288
|
+
Oldest first, because the axis a reader is scanning is age: the entry most likely to belong
|
|
289
|
+
to a worker who is gone is the one at the top. It **ranks nothing and offers nothing** —
|
|
290
|
+
`pick` decides what to work on, and a listing that answered that would be a fourth tier
|
|
291
|
+
nobody declared. Deliberately not an MCP tool for the same reason: `pick` and `brief`
|
|
292
|
+
already name the claims an agent's own answer stepped around, and this is the read a person
|
|
293
|
+
makes about a checkout.
|
|
294
|
+
"""
|
|
295
|
+
config = backlog.config
|
|
296
|
+
dated = _read(config.root)
|
|
297
|
+
if not dated:
|
|
298
|
+
return ()
|
|
299
|
+
tasks = {entry.task.id: entry.task for entry in backlog.roadmap.entries}
|
|
300
|
+
elsewhere = (
|
|
301
|
+
(Where.SHIPPED, backlog.shipped()),
|
|
302
|
+
(Where.RETIRED, backlog.retired()),
|
|
303
|
+
(Where.PAUSED, backlog.deferred()),
|
|
304
|
+
)
|
|
305
|
+
now, held = time.time(), window(config)
|
|
306
|
+
rows = [
|
|
307
|
+
_row(task_id, now - row.when, tasks.get(task_id), elsewhere, held, row.paths)
|
|
308
|
+
for task_id, row in dated.items()
|
|
309
|
+
]
|
|
310
|
+
return tuple(sorted(rows, key=lambda row: -row.age))
|
|
311
|
+
|
|
312
|
+
|
|
313
|
+
def _row(
|
|
314
|
+
task_id: str,
|
|
315
|
+
age: float,
|
|
316
|
+
task: Task | None,
|
|
317
|
+
elsewhere: tuple[tuple[Where, object], ...],
|
|
318
|
+
held: float,
|
|
319
|
+
paths: tuple[str, ...] = (),
|
|
320
|
+
) -> Dated:
|
|
321
|
+
"""One registry entry as the two questions a reader is asking: is it a claim, and where."""
|
|
322
|
+
if task is None:
|
|
323
|
+
return Dated(
|
|
324
|
+
id=task_id,
|
|
325
|
+
age=age,
|
|
326
|
+
state=State.STALE,
|
|
327
|
+
where=next((name for name, ids in elsewhere if task_id in ids), Where.NOWHERE), # type: ignore[operator]
|
|
328
|
+
paths=paths,
|
|
329
|
+
)
|
|
330
|
+
if task.status != IN_PROGRESS:
|
|
331
|
+
state = State.STALE
|
|
332
|
+
else:
|
|
333
|
+
state = State.HELD if age < held else State.EXPIRED
|
|
334
|
+
return Dated(
|
|
335
|
+
id=task_id,
|
|
336
|
+
age=age,
|
|
337
|
+
state=state,
|
|
338
|
+
where=Where.OPEN,
|
|
339
|
+
marker=task.status,
|
|
340
|
+
block=task.block,
|
|
341
|
+
paths=paths,
|
|
342
|
+
)
|
|
343
|
+
|
|
344
|
+
|
|
345
|
+
@dataclass(frozen=True, slots=True)
|
|
346
|
+
class Pruning:
|
|
347
|
+
"""What a prune left and what it dropped (RK165). Both, because a filter that hides its
|
|
348
|
+
own effect is how "the registry is clean" gets read off a command that emptied it."""
|
|
349
|
+
|
|
350
|
+
kept: tuple[Dated, ...] = ()
|
|
351
|
+
dropped: tuple[Dated, ...] = ()
|
|
352
|
+
|
|
353
|
+
|
|
354
|
+
def prune(config: Config) -> Pruning:
|
|
355
|
+
"""Drop every row that is not a claim, and leave every row that is (RK165).
|
|
356
|
+
|
|
357
|
+
Loads the backlog inside its own lock (RK167), the way :func:`roadkeep.picking.take` does:
|
|
358
|
+
the read decides what is dropped, so a read outside the lock would decide from a state the
|
|
359
|
+
write no longer applies to. Re-entrant, so the dispatcher declaring the same thing about the
|
|
360
|
+
argv costs nothing twice — and a library caller gets the guarantee either way.
|
|
361
|
+
|
|
362
|
+
The reconciliation :func:`follow` performs, reachable without a marker to write. It exists
|
|
363
|
+
because the other remedy is the whole file: a checkout between tasks has no marker to move,
|
|
364
|
+
so clearing one row nobody can act on meant deleting the claims of every worker beside it —
|
|
365
|
+
a blast radius the size of the checkout for a problem the size of an id.
|
|
366
|
+
|
|
367
|
+
So it decides nothing new. What it keeps is what `follow` keeps: every id the roadmap still
|
|
368
|
+
carries at 🛠, which is a **live claim and an expired one alike** — an expired row is still a
|
|
369
|
+
statement about a started line, and the caller that wants it gone moves the marker. A live
|
|
370
|
+
claim is never dropped here; taking a line from a worker is a marker, and the door that
|
|
371
|
+
refuses it is the one RK160 closed.
|
|
372
|
+
"""
|
|
373
|
+
with exclusive(config.root):
|
|
374
|
+
rows = survey(Backlog.load(config))
|
|
375
|
+
dropped = tuple(row for row in rows if row.state is State.STALE)
|
|
376
|
+
if dropped:
|
|
377
|
+
gone = {row.id for row in dropped}
|
|
378
|
+
kept = {n: r for n, r in _read(config.root).items() if n not in gone}
|
|
379
|
+
_write(config.root, kept)
|
|
380
|
+
return Pruning(
|
|
381
|
+
kept=tuple(row for row in rows if row.state is not State.STALE), dropped=dropped
|
|
382
|
+
)
|
|
383
|
+
|
|
384
|
+
|
|
385
|
+
def path(root: Path | str) -> Path:
|
|
386
|
+
"""Where this checkout's claims are dated — in the shared store, beside its lock (RK330)."""
|
|
387
|
+
return store_path(root)
|
|
388
|
+
|
|
389
|
+
|
|
390
|
+
def live(config: Config, entries: Iterable[Entry]) -> tuple[Held, ...]:
|
|
391
|
+
"""The claims still held, over the lines given, in the order they were given.
|
|
392
|
+
|
|
393
|
+
Read *against the lines* and never alone: a claim is a statement about a 🛠 line, so an
|
|
394
|
+
id whose marker has moved on is not held — which is what makes every existing marker
|
|
395
|
+
door a release, with nothing to wire and nothing to forget to call.
|
|
396
|
+
"""
|
|
397
|
+
dated = _read(config.root)
|
|
398
|
+
if not dated:
|
|
399
|
+
return ()
|
|
400
|
+
now, held = time.time(), window(config)
|
|
401
|
+
return tuple(
|
|
402
|
+
Held(entry.task.id, now - row.when, row.paths)
|
|
403
|
+
for entry in entries
|
|
404
|
+
if entry.task.status == IN_PROGRESS
|
|
405
|
+
and (row := dated.get(entry.task.id)) is not None
|
|
406
|
+
and now - row.when < held
|
|
407
|
+
)
|
|
408
|
+
|
|
409
|
+
|
|
410
|
+
class Followed(StrEnum):
|
|
411
|
+
"""What a marker write did to the claim on its line (RK158). Printed, so it is not silent."""
|
|
412
|
+
|
|
413
|
+
CLAIMED = "claimed"
|
|
414
|
+
RELEASED = "released"
|
|
415
|
+
NEITHER = ""
|
|
416
|
+
|
|
417
|
+
|
|
418
|
+
def refuse_taken(
|
|
419
|
+
config: Config, task_id: str, marker: str, entries: Iterable[Entry]
|
|
420
|
+
) -> None:
|
|
421
|
+
"""Refuse a marker write that would take a claim this line already carries (RK160).
|
|
422
|
+
|
|
423
|
+
Called **before** the write and never from inside :func:`follow`, which runs after one: a
|
|
424
|
+
refusal that arrives once the file has moved is a refusal about a state that already
|
|
425
|
+
happened. Beside :func:`~roadkeep.authoring.refuse_reuse` in shape and for the same
|
|
426
|
+
reason — the check that a write is allowed belongs at the write, not at whichever caller
|
|
427
|
+
remembered it.
|
|
428
|
+
|
|
429
|
+
Only the in-progress marker. Writing any other one is how a claim is *released*, and a
|
|
430
|
+
release that could be refused is a line nobody can give back.
|
|
431
|
+
"""
|
|
432
|
+
if marker != IN_PROGRESS:
|
|
433
|
+
return
|
|
434
|
+
for one in live(config, entries):
|
|
435
|
+
if one.id == task_id:
|
|
436
|
+
raise AlreadyHeld(task_id, one.since, IN_PROGRESS)
|
|
437
|
+
|
|
438
|
+
|
|
439
|
+
def follow(
|
|
440
|
+
root: Path | str, task_id: str, marker: str, entries: Iterable[Entry]
|
|
441
|
+
) -> Followed:
|
|
442
|
+
"""Make the claim follow the marker, on any door that writes one (RK158).
|
|
443
|
+
|
|
444
|
+
A claim is *read* against 🛠, so the marker is already the thing a claim is about — and
|
|
445
|
+
until this existed, the door that writes exactly that marker was the one door that did not
|
|
446
|
+
date it: `status <id> 🛠` is a legitimate way to say "I am on this", and the next `pick`
|
|
447
|
+
read the line as work somebody abandoned and offered it with tier 1's own reason.
|
|
448
|
+
|
|
449
|
+
Both directions, because half of this rule was already implicit: writing 🛠 dates a claim
|
|
450
|
+
(again, if one had expired — a re-assertion is a new claim), and writing anything else
|
|
451
|
+
drops it, which is the release the read used to infer. `add` is deliberately not one of
|
|
452
|
+
these doors: the three ways to *start* work are the two `--claim` flags and this one, and a
|
|
453
|
+
line being created is not one the backlog was handing out.
|
|
454
|
+
|
|
455
|
+
**Every direction reconciles** (RK163), and that is the whole of what a write here does:
|
|
456
|
+
the entries are the truth, so what is kept is what they still carry at 🛠 — and the id being
|
|
457
|
+
followed is dated on top of that, or left out by having stopped being one of them. Dropping
|
|
458
|
+
a single key instead left every row *no door reported* in place, which a `git checkout`
|
|
459
|
+
creates and only a later claim used to clear. Nothing else writes a claim, for the reason
|
|
460
|
+
two entry points to one rule is how it comes to have two behaviours (RK159) —
|
|
461
|
+
:func:`rename` is not one of them, moving an address rather than following a marker.
|
|
462
|
+
|
|
463
|
+
It writes only when the result differs, so a project that never claims never gets a file:
|
|
464
|
+
a `status` on a backlog with no registry is a read and a comparison.
|
|
465
|
+
|
|
466
|
+
A **re-assertion keeps the paths** it was holding (RK280): the row is dated again, and the
|
|
467
|
+
scope the holder declared is a statement about the same work, not one the clock revokes.
|
|
468
|
+
A release drops the row and the paths with it, which is what makes a marker the only thing
|
|
469
|
+
that has to be remembered.
|
|
470
|
+
"""
|
|
471
|
+
dated = _read(root)
|
|
472
|
+
started = {entry.task.id for entry in entries if entry.task.status == IN_PROGRESS}
|
|
473
|
+
kept = {name: row for name, row in dated.items() if name in started}
|
|
474
|
+
if marker == IN_PROGRESS:
|
|
475
|
+
was = dated.get(task_id)
|
|
476
|
+
kept[task_id] = Dating(time.time(), was.paths if was is not None else ())
|
|
477
|
+
if kept != dated:
|
|
478
|
+
_write(root, kept)
|
|
479
|
+
if marker == IN_PROGRESS:
|
|
480
|
+
return Followed.CLAIMED
|
|
481
|
+
return Followed.RELEASED if task_id in dated else Followed.NEITHER
|
|
482
|
+
|
|
483
|
+
|
|
484
|
+
class NotHeld(ValueError):
|
|
485
|
+
"""Declaring a scope for a line nobody is holding (RK280).
|
|
486
|
+
|
|
487
|
+
Refused rather than taken, because taking is a **marker** and this door writes no marker:
|
|
488
|
+
a command that dated a claim as a side effect of naming files would be a second way to
|
|
489
|
+
start work, which is the shape RK158 spent a task removing. Says the door that does open.
|
|
490
|
+
"""
|
|
491
|
+
|
|
492
|
+
def __init__(self, task_id: str) -> None:
|
|
493
|
+
self.task_id = task_id
|
|
494
|
+
super().__init__(
|
|
495
|
+
f"no live claim on {task_id}: a scope is what a claim carries, so take the "
|
|
496
|
+
f"line first with `status {task_id} {IN_PROGRESS}` (or `pick --claim`)"
|
|
497
|
+
)
|
|
498
|
+
|
|
499
|
+
|
|
500
|
+
def scope(
|
|
501
|
+
config: Config, task_id: str, paths: Iterable[str], *, extend: bool = False
|
|
502
|
+
) -> tuple[str, ...]:
|
|
503
|
+
"""Record the paths a held line's commit owns, and answer them back (RK280).
|
|
504
|
+
|
|
505
|
+
The write that was missing. RK117 locks a scan-to-save span and RK119 says who holds a
|
|
506
|
+
line, and both did their job — no governed file corrupted, no id spent twice — while two
|
|
507
|
+
sessions each committed a tree holding the other's source, because the commit step is a
|
|
508
|
+
`git add -A` in a shell script and nothing in the contract could name what belonged to
|
|
509
|
+
whom. `agents.md` carried the remedy as advice ("a tree holding unrelated work wants the
|
|
510
|
+
task's paths staged"), which is where L1's argument says advice does not hold: it is an
|
|
511
|
+
analysis to make at the moment of committing, out of a `git status` that shows both
|
|
512
|
+
sessions' work and says nothing about which is which.
|
|
513
|
+
|
|
514
|
+
So the claim carries it, because the claim is the one thing that already knows a line is
|
|
515
|
+
being worked on and by one worker. What is stored is what the holder **said**, verbatim
|
|
516
|
+
and in order: this never asks the disk whether a path exists, and never derives a path
|
|
517
|
+
from the task's prose. A scope inferred from a sentence would be RK55's guessing put in
|
|
518
|
+
charge of what a commit contains.
|
|
519
|
+
|
|
520
|
+
The **third** writer of the registry, and the exception is the same one :func:`rename`
|
|
521
|
+
takes: it writes no date. Dating is `follow`'s, so nothing here can start work, postpone
|
|
522
|
+
an expiry or take a line from the worker holding it — the invariant RK160 closed stays
|
|
523
|
+
exactly where it was. Refused on a line no live claim holds, for the same reason.
|
|
524
|
+
|
|
525
|
+
Replaces rather than appends, and `extend` does not change that (RK307). A scope is the
|
|
526
|
+
answer to *what is this commit*, and a call that only ever grew one would make a corrected
|
|
527
|
+
answer unreachable without the file — which is RK165's argument, one row along. What
|
|
528
|
+
`extend` changes is where the answer is composed: the caller that found a tenth path after
|
|
529
|
+
declaring nine says *and this too* rather than retyping the nine, and the row is still
|
|
530
|
+
replaced, with the whole scope. Measured across one block here: three of five tasks needed
|
|
531
|
+
a second call, one of them ten paths long.
|
|
532
|
+
|
|
533
|
+
**One door and a parameter, not a second function** (RK159): the two are distinguishable
|
|
534
|
+
at the call site and identical at the write, so the invariants below — the refusal on a
|
|
535
|
+
line nobody holds, the untouched date, the collapse — are stated once and cannot come to
|
|
536
|
+
have two behaviours. The **existing paths come first**, because they were declared first
|
|
537
|
+
and the answer is read in the order it will be staged.
|
|
538
|
+
|
|
539
|
+
Duplicates collapse, order kept, because the answer is consumed by a `git add --` and a
|
|
540
|
+
path staged twice is noise in a contract meant to be read.
|
|
541
|
+
"""
|
|
542
|
+
named = tuple(one for one in paths if one)
|
|
543
|
+
with exclusive(config.root):
|
|
544
|
+
backlog = Backlog.load(config)
|
|
545
|
+
if not any(one.id == task_id for one in live(config, backlog.roadmap.entries)):
|
|
546
|
+
raise NotHeld(task_id)
|
|
547
|
+
dated = _read(config.root)
|
|
548
|
+
row = dated[task_id]
|
|
549
|
+
# Read inside the lock, like everything else this decides from: a scope composed from
|
|
550
|
+
# a row read outside it would drop whatever another call added in between.
|
|
551
|
+
wanted = tuple(dict.fromkeys((*row.paths, *named) if extend else named))
|
|
552
|
+
dated[task_id] = Dating(row.when, wanted)
|
|
553
|
+
_write(config.root, dated)
|
|
554
|
+
return wanted
|
|
555
|
+
|
|
556
|
+
|
|
557
|
+
def elsewhere(config: Config, task_id: str, entries: Iterable[Entry]) -> tuple[Held, ...]:
|
|
558
|
+
"""Every *other* live claim that has declared a scope, so a commit can leave it alone.
|
|
559
|
+
|
|
560
|
+
The half a claim could not answer before (RK280). A claim names nobody by design (RK119),
|
|
561
|
+
so no write can be refused on the grounds that it is somebody else's — the guard sees a
|
|
562
|
+
path and not a worker, and a session cannot be told it is not itself. What *is* decidable
|
|
563
|
+
is the reverse: given the id being committed, every path some other held line says is its
|
|
564
|
+
own. That is a list the caller subtracts, and it is why this closes at the commit rather
|
|
565
|
+
than at the write.
|
|
566
|
+
|
|
567
|
+
Claims with no scope are left out, and the omission is the honest one: silence is a
|
|
568
|
+
holder who has not said, not a holder claiming nothing, so a caller that treated it as
|
|
569
|
+
the second would be answering with a confidence the registry does not carry.
|
|
570
|
+
"""
|
|
571
|
+
return tuple(
|
|
572
|
+
one for one in live(config, entries) if one.id != task_id and one.paths
|
|
573
|
+
)
|
|
574
|
+
|
|
575
|
+
|
|
576
|
+
@dataclass(frozen=True, slots=True)
|
|
577
|
+
class Scope:
|
|
578
|
+
"""A dirty tree split by which claim speaks for each path (RK280, RK294).
|
|
579
|
+
|
|
580
|
+
Three lists and not one, because the caller does three different things with them:
|
|
581
|
+
stage :attr:`mine`, leave :attr:`theirs`, and *decide* about :attr:`loose`. The third is
|
|
582
|
+
the list the incident was made of — a path in neither scope is one `git add -A` takes
|
|
583
|
+
silently — so it is named rather than counted.
|
|
584
|
+
"""
|
|
585
|
+
|
|
586
|
+
#: What the claim being committed says its commit owns, in the order it was declared.
|
|
587
|
+
mine: tuple[str, ...] = ()
|
|
588
|
+
#: `(path, holder)` for every changed path some *other* live claim covers. The **changed**
|
|
589
|
+
#: path and never the declaration it fell under (RK495): what a caller leaves alone is a
|
|
590
|
+
#: file, and a holder who scoped `src/` would otherwise be reported as holding nothing.
|
|
591
|
+
theirs: tuple[tuple[str, str], ...] = ()
|
|
592
|
+
#: Changed paths no live claim covers at all — by name or by the directory above them, and
|
|
593
|
+
#: whose change this id does not already explain (`accounted`, RK1117).
|
|
594
|
+
loose: tuple[str, ...] = ()
|
|
595
|
+
#: Declared paths that would stage nothing right now (RK295) — in neither the dirty set
|
|
596
|
+
#: nor the index. A subset of :attr:`mine`, in the order it was declared, because this is
|
|
597
|
+
#: a reading *of* the declaration and not a fourth list beside it.
|
|
598
|
+
idle: tuple[str, ...] = ()
|
|
599
|
+
#: `(path, ids)` for a governed file whose change this id explains **and** that another
|
|
600
|
+
#: session's line arrived in or left (RK1120). Not a fourth kind of ownership: the file is
|
|
601
|
+
#: staged either way, so what this carries is the ids inside it that are nobody's business
|
|
602
|
+
#: here — the half :attr:`loose` cannot reach, a roadmap always naming this id.
|
|
603
|
+
shared: tuple[tuple[str, tuple[str, ...]], ...] = ()
|
|
604
|
+
#: Which of :attr:`loose` the **index** already carries (RK1197). Not a sixth list: a
|
|
605
|
+
#: staged loose path is the same finding one degree louder, because a `git commit` takes
|
|
606
|
+
#: it whether or not the author reads a diff — and the diff they are reading is the other
|
|
607
|
+
#: side. Measured twice in one session as a version literal another process staged.
|
|
608
|
+
staged: tuple[str, ...] = ()
|
|
609
|
+
|
|
610
|
+
@property
|
|
611
|
+
def spoken(self) -> bool:
|
|
612
|
+
"""Whether any live claim declared a path — the condition a volunteered read has.
|
|
613
|
+
|
|
614
|
+
`claim <id>` was *asked*, so it answers either way. A verb that reports this without
|
|
615
|
+
being asked has nothing to subtract the tree from when no claim spoke, and its whole
|
|
616
|
+
answer would be `git status` restated under a heading saying "loose".
|
|
617
|
+
"""
|
|
618
|
+
return bool(self.mine or self.theirs)
|
|
619
|
+
|
|
620
|
+
|
|
621
|
+
@dataclass(frozen=True, slots=True)
|
|
622
|
+
class Claimed:
|
|
623
|
+
"""One held line's scope as `claim <id>` answers it (RK280, RK294, RK342).
|
|
624
|
+
|
|
625
|
+
The result that read had none of (RK1170). `Scope` is the *subtraction* and is shared with
|
|
626
|
+
a departure; what this adds is the two things only this door has — the id it was asked
|
|
627
|
+
about, and what this task's own transactions already wrote — and the three registers that
|
|
628
|
+
were composed from all of it inside the handler.
|
|
629
|
+
"""
|
|
630
|
+
|
|
631
|
+
task_id: str
|
|
632
|
+
scope: Scope
|
|
633
|
+
#: The governed files this task's own transactions wrote (RK342), by the reading `ship`
|
|
634
|
+
#: makes off its own `save`. Named rather than folded into `mine`, for the reason a
|
|
635
|
+
#: departure keeps them apart (RK309): the scope is what the holder *said*, verbatim, and
|
|
636
|
+
#: these are not a declaration to be corrected but a record to be used.
|
|
637
|
+
wrote: tuple[str, ...] = ()
|
|
638
|
+
|
|
639
|
+
def porcelain(self) -> str:
|
|
640
|
+
"""Nothing but the paths, in `git add --` order.
|
|
641
|
+
|
|
642
|
+
This form is consumed by a shell, so a heading on it would be a filename — the
|
|
643
|
+
contract has to be safe to pipe. The written ones join it for the reason they join the
|
|
644
|
+
staging line: what the author does with both lists is the same `git add`.
|
|
645
|
+
"""
|
|
646
|
+
return chr(10).join(dict.fromkeys((*self.scope.mine, *self.wrote)))
|
|
647
|
+
|
|
648
|
+
def stated(self) -> str:
|
|
649
|
+
from roadkeep.rendering import _scope_rows # noqa: PLC0415 - RK260
|
|
650
|
+
|
|
651
|
+
idle = set(self.scope.idle)
|
|
652
|
+
rows = [f"{self.task_id} claims {len(self.scope.mine)} path(s)"]
|
|
653
|
+
# Annotated where it stands, and not listed again below (RK295): the mistyped path and
|
|
654
|
+
# the real one are two lines apart, and the eye reads the second as somebody else's
|
|
655
|
+
# unless the first says what is wrong with it.
|
|
656
|
+
rows += [
|
|
657
|
+
f" mine {one}{' (stages nothing right now)' if one in idle else ''}"
|
|
658
|
+
for one in self.scope.mine
|
|
659
|
+
]
|
|
660
|
+
rows += [
|
|
661
|
+
f" wrote {one} (this task's own transactions)" for one in self.wrote
|
|
662
|
+
]
|
|
663
|
+
rows += _scope_rows(self.scope, self.wrote)
|
|
664
|
+
if not self.scope.mine:
|
|
665
|
+
rows.append(
|
|
666
|
+
f" none declared: `claim {self.task_id} --path <p>` says what this "
|
|
667
|
+
f"commit owns"
|
|
668
|
+
)
|
|
669
|
+
return chr(10).join(rows)
|
|
670
|
+
|
|
671
|
+
def payload(self) -> dict[str, object]:
|
|
672
|
+
return {
|
|
673
|
+
"id": self.task_id,
|
|
674
|
+
"paths": list(self.scope.mine),
|
|
675
|
+
# Its own key and never merged into `paths` (RK309, RK342): a client that read them
|
|
676
|
+
# as one would be handed a scope this tool never received, and the two answer
|
|
677
|
+
# different questions.
|
|
678
|
+
"wrote": list(self.wrote),
|
|
679
|
+
"theirs": [
|
|
680
|
+
{"path": one, "claimed_by": who} for one, who in self.scope.theirs
|
|
681
|
+
],
|
|
682
|
+
"unclaimed": list(self.scope.loose),
|
|
683
|
+
# Which of them the index already carries (RK1197), the key a departure answers
|
|
684
|
+
# under the same name: a client acting on `unclaimed` decides, and one acting on
|
|
685
|
+
# this has already been committed to by a `git add`.
|
|
686
|
+
"unclaimed_staged": list(self.scope.staged),
|
|
687
|
+
# The same list a departure carries, and computed here since RK1122: the two
|
|
688
|
+
# readers of one contract answering differently was the defect.
|
|
689
|
+
"shared": [
|
|
690
|
+
{"path": one, "ids": list(named)} for one, named in self.scope.shared
|
|
691
|
+
],
|
|
692
|
+
"staging_nothing": list(self.scope.idle),
|
|
693
|
+
}
|
|
694
|
+
|
|
695
|
+
|
|
696
|
+
def split(
|
|
697
|
+
config: Config,
|
|
698
|
+
task_id: str,
|
|
699
|
+
entries: Iterable[Entry],
|
|
700
|
+
changed: Iterable[str],
|
|
701
|
+
tracked: Iterable[str] = (),
|
|
702
|
+
accounted: Iterable[str] = (),
|
|
703
|
+
shared: Iterable[tuple[str, tuple[str, ...]]] = (),
|
|
704
|
+
staged: Iterable[str] = (),
|
|
705
|
+
) -> Scope:
|
|
706
|
+
"""Split the changed paths by whose claim names them (RK280, RK295).
|
|
707
|
+
|
|
708
|
+
Pure over `changed` and `tracked`: git is the caller's to ask, because the two callers ask
|
|
709
|
+
it under different conditions — one was told to, the other only where a claim spoke. What
|
|
710
|
+
is shared, and the reason this is a function rather than a second composition at each call
|
|
711
|
+
site, is the *subtraction* — lists that have to stay disjoint and stay in the same order
|
|
712
|
+
in both answers.
|
|
713
|
+
|
|
714
|
+
`accounted` is the third subtraction and the one RK1117 moved here: paths whose change
|
|
715
|
+
**this id already explains**, so they are not reported as belonging to nobody. It used to
|
|
716
|
+
be done by each printer, filtering `loose` against what the caller called written — and the
|
|
717
|
+
two callers mean different things by that word. `claim <id>` means "its diff carries this
|
|
718
|
+
id" (:func:`written`), which is the predicate; `ship` means "this transaction wrote it",
|
|
719
|
+
which is not. So a governed file that a departure wrote *and* that was already dirty with
|
|
720
|
+
another session's work was reported as written and never as loose, and the `git add --`
|
|
721
|
+
line took both. Measured here: a filing of RK1116 landed inside RK1112's commit.
|
|
722
|
+
|
|
723
|
+
`tracked` is the index, and it is what makes :attr:`Scope.idle` a fact rather than a
|
|
724
|
+
guess: a declared path that is dirty stages itself, and one the index carries is a real
|
|
725
|
+
file whose name was not mistyped. A caller that omits it gets no idle reading at all
|
|
726
|
+
rather than one made against half the evidence — the empty default is the honest failure,
|
|
727
|
+
since every path would otherwise read as staging nothing.
|
|
728
|
+
|
|
729
|
+
`shared` is :func:`sharing`'s answer, passed in for the same reason `changed` is: it asks
|
|
730
|
+
git, and this function's purity is what lets one caller be told to answer and the other
|
|
731
|
+
answer only where a claim spoke. Carried through rather than composed by each caller so
|
|
732
|
+
the whole :class:`Scope` is assembled in one place — five lists that have to stay
|
|
733
|
+
consistent with each other, and two assemblies of them is how they come to differ.
|
|
734
|
+
|
|
735
|
+
All three lists ask :func:`_covers`, which is the whole of RK495: they used to, between
|
|
736
|
+
them, read a declared directory two ways — `idle` as the `git add --` it becomes, and the
|
|
737
|
+
other two as a filename — so a claim on `src/` printed the staging line that takes
|
|
738
|
+
`src/a.py` and, three lines below it, reported `src/a.py` as named by nobody.
|
|
739
|
+
"""
|
|
740
|
+
entries = tuple(entries)
|
|
741
|
+
rows = live(config, entries)
|
|
742
|
+
mine = next((one.paths for one in rows if one.id == task_id), ())
|
|
743
|
+
others = elsewhere(config, task_id, entries)
|
|
744
|
+
changed = frozenset(changed)
|
|
745
|
+
known = changed | frozenset(tracked)
|
|
746
|
+
theirs = tuple(
|
|
747
|
+
(one, other.id)
|
|
748
|
+
for one in sorted(changed)
|
|
749
|
+
for other in others
|
|
750
|
+
if any(_covers(declared, one) for declared in other.paths)
|
|
751
|
+
)
|
|
752
|
+
named = (*mine, *(one for other in others for one in other.paths))
|
|
753
|
+
explained = frozenset(accounted)
|
|
754
|
+
adrift = tuple(
|
|
755
|
+
one
|
|
756
|
+
for one in sorted(changed)
|
|
757
|
+
if one not in explained
|
|
758
|
+
and not any(_covers(declared, one) for declared in named)
|
|
759
|
+
)
|
|
760
|
+
return Scope(
|
|
761
|
+
mine=mine,
|
|
762
|
+
theirs=theirs,
|
|
763
|
+
loose=adrift,
|
|
764
|
+
# A subset of `loose` and in its order (RK1197), which is what keeps it from being a
|
|
765
|
+
# sixth list: the question is not *what else is staged* — `mine` is, and should be —
|
|
766
|
+
# but which of the paths nobody claims the next commit already carries.
|
|
767
|
+
staged=tuple(one for one in adrift if one in set(staged)),
|
|
768
|
+
idle=() if not known else tuple(one for one in mine if not _stages(one, known)),
|
|
769
|
+
shared=tuple(shared),
|
|
770
|
+
)
|
|
771
|
+
|
|
772
|
+
|
|
773
|
+
def _covers(declared: str, path: str) -> bool:
|
|
774
|
+
"""Does a scope that declared ``declared`` speak for ``path`` (RK495)?
|
|
775
|
+
|
|
776
|
+
One reading, asked by every list :func:`split` returns, because a scope is a `git add --`
|
|
777
|
+
argument and that command answers this question the same way whichever list is about to
|
|
778
|
+
quote it. A **directory** is a legitimate scope — git lists neither `status` nor
|
|
779
|
+
`ls-files` by one, so a declared `docs/` compared as a filename matches nothing at all —
|
|
780
|
+
and the trailing slash is the author's spelling rather than a fact, so it comes off before
|
|
781
|
+
the prefix is built and `src` covers what `src/` does.
|
|
782
|
+
|
|
783
|
+
Prefix and not `startswith` alone: `src/` must not answer for `srcfoo/a.py`, which is a
|
|
784
|
+
different directory whose name begins the same way.
|
|
785
|
+
|
|
786
|
+
And **either side may be the directory** (RK1137), which is RK495's question from the other
|
|
787
|
+
end. Git collapses an untracked tree to its topmost new directory — `?? .claude/skills/` —
|
|
788
|
+
so a claim naming the file the write created was compared against a shorter string and
|
|
789
|
+
matched nothing: RK1136's own ship reported that file as `loose` *and* its declaration as
|
|
790
|
+
staging nothing, two wrong lines about one path.
|
|
791
|
+
|
|
792
|
+
The trailing slash is what makes the third case safe rather than a widening. Git spells a
|
|
793
|
+
collapsed tree with one and a dirty **file** never carries one, so `declared.startswith(path)`
|
|
794
|
+
fires exactly where the listed path is a directory standing for everything under it — and a
|
|
795
|
+
claim on `src/a.py` still does not answer for a tracked `src/` holding somebody else's edit,
|
|
796
|
+
because git lists that as `src/other.py`.
|
|
797
|
+
"""
|
|
798
|
+
if path == declared or path.startswith(declared.rstrip("/") + "/"):
|
|
799
|
+
return True
|
|
800
|
+
return path.endswith("/") and declared.startswith(path)
|
|
801
|
+
|
|
802
|
+
|
|
803
|
+
def _stages(one: str, known: frozenset[str]) -> bool:
|
|
804
|
+
"""Would `git add -- <one>` put anything in the next commit (RK295)?
|
|
805
|
+
|
|
806
|
+
The same question :func:`_covers` answers, asked over the whole tree instead of about one
|
|
807
|
+
path: a declaration stages something exactly where it covers a path git already knows —
|
|
808
|
+
dirty or in the index. Kept as its own name because what it reports is about the
|
|
809
|
+
*declaration* (a scope that would stage nothing is a typo) and not about the file.
|
|
810
|
+
"""
|
|
811
|
+
return any(_covers(one, other) for other in known)
|
|
812
|
+
|
|
813
|
+
|
|
814
|
+
def writable(config: Config) -> tuple[str, ...]:
|
|
815
|
+
"""Every path a verb of this tool can leave bytes in, as the project spells them (RK342).
|
|
816
|
+
|
|
817
|
+
The governed files plus the projections RK188 refreshes with them. Narrow on purpose: the
|
|
818
|
+
claim of :func:`written` is that *this tool wrote it*, and a source file whose diff cites
|
|
819
|
+
the id is the author's work and not this tool's — calling it written would put the tool's
|
|
820
|
+
signature on somebody's code. So the candidate set is what a verb could have produced, and
|
|
821
|
+
the diff then says which of those this task's own transaction did.
|
|
822
|
+
"""
|
|
823
|
+
# Deferred: `exporting` reaches the write path, which reaches this module (RK260).
|
|
824
|
+
from roadkeep.exporting import DEFAULTS # noqa: PLC0415
|
|
825
|
+
|
|
826
|
+
out = [
|
|
827
|
+
config.relative(config.path(role)) for role in ROLES if config.has(role)
|
|
828
|
+
]
|
|
829
|
+
# A literal name only: a role's own file is already in the loop above, and listing it twice
|
|
830
|
+
# would report one path as two scopes (RK1110).
|
|
831
|
+
out += [kind.name for kind in DEFAULTS.values() if kind.name]
|
|
832
|
+
return tuple(dict.fromkeys(out))
|
|
833
|
+
|
|
834
|
+
|
|
835
|
+
def written(config: Config, task_id: str, changed: Iterable[str]) -> tuple[str, ...]:
|
|
836
|
+
"""The changed paths this task's own transactions wrote (RK342).
|
|
837
|
+
|
|
838
|
+
`ship` answers this off :meth:`~roadkeep.shipping.Departure.save`'s own return, which is
|
|
839
|
+
the better source and only exists inside a transaction. `claim <id>` is asked *between*
|
|
840
|
+
them, so the record it has is the files themselves: a claim moved a marker onto this line
|
|
841
|
+
and the projections were refreshed from it, and both diffs therefore name the id.
|
|
842
|
+
|
|
843
|
+
Two readings and not one, because the tool's signature is the whole point — a path is
|
|
844
|
+
written only where it is both something a verb could have produced (:func:`writable`) and
|
|
845
|
+
something whose diff carries this id (:func:`~roadkeep.history.carrying`). Either alone is
|
|
846
|
+
the repair RK342 names and refuses: every dirty governed file hands one session another's
|
|
847
|
+
`add`, and every dirty file carrying the id claims authorship of somebody's code.
|
|
848
|
+
|
|
849
|
+
A **third** since RK1126, and it is the same claim through the one carrier where the id is
|
|
850
|
+
not on the line: a rationale file edited inside this id's own section carries the id in no
|
|
851
|
+
changed line, because a heading is what carries one. So
|
|
852
|
+
:func:`~roadkeep.history.owned_edit` reads the span instead, and it is asked only of a prose
|
|
853
|
+
path that is dirty and that the first reading did not already name — two subprocesses on the
|
|
854
|
+
turn somebody edited a design, and none on any other.
|
|
855
|
+
"""
|
|
856
|
+
# Deferred for RK260's reason, and because git belongs on no path that did not ask.
|
|
857
|
+
from roadkeep.history import carrying, owned_edit # noqa: PLC0415
|
|
858
|
+
|
|
859
|
+
changed = frozenset(changed)
|
|
860
|
+
candidates = [one for one in writable(config) if one in changed]
|
|
861
|
+
named = set(carrying(config, task_id, candidates))
|
|
862
|
+
named.update(
|
|
863
|
+
config.relative(config.path(role))
|
|
864
|
+
for role in PROSE_ROLES
|
|
865
|
+
if config.has(role)
|
|
866
|
+
and (where := config.relative(config.path(role))) in changed
|
|
867
|
+
and where not in named
|
|
868
|
+
and owned_edit(config, "HEAD", task_id, role)
|
|
869
|
+
)
|
|
870
|
+
# In `writable`'s order and never in the order the two readings answered: the list is read
|
|
871
|
+
# against a `git add --` line, and a path's place in it is not a fact about which reading
|
|
872
|
+
# found it.
|
|
873
|
+
return tuple(one for one in candidates if one in named)
|
|
874
|
+
|
|
875
|
+
|
|
876
|
+
def departing(config: Config, task_id: str, entries: Iterable[Entry]) -> Scope | None:
|
|
877
|
+
"""The same split, asked at the moment a line leaves the roadmap (RK294).
|
|
878
|
+
|
|
879
|
+
RK280 gave a claim the paths its commit owns and gave `claim <id>` the read that names
|
|
880
|
+
what the tree holds for somebody else, and left it with no caller: the declaration was
|
|
881
|
+
asked for in `agents.md` and in the skill, which is advice about what to do at the moment
|
|
882
|
+
of committing — where the analysis is expensive and the author is already finishing. A
|
|
883
|
+
departure *is* that moment, and it holds the id.
|
|
884
|
+
|
|
885
|
+
`None` where **no live claim declared a path**, which is every project that has not
|
|
886
|
+
adopted this. Silence and not an empty answer: there is nothing to subtract the tree
|
|
887
|
+
from, so the honest report is no report — and the git process is not paid for either.
|
|
888
|
+
|
|
889
|
+
It derives nothing. A departure that filed the dirty paths under the id that is leaving
|
|
890
|
+
would answer the question the incident asked — which of these is mine — by assuming it,
|
|
891
|
+
and the two sessions this exists to separate would each get the other's files with the
|
|
892
|
+
tool's signature on it.
|
|
893
|
+
|
|
894
|
+
What this id **already explains** is asked here and not left to the printer (RK1117), and
|
|
895
|
+
asked of the tree *before* the transaction writes: a governed file dirty at this moment is
|
|
896
|
+
dirty from something else, and :func:`written` says whether that something names this id.
|
|
897
|
+
|
|
898
|
+
That reading is per **file**, and the roadmap is a file this task is always named in — the
|
|
899
|
+
marker that took the line is in the same diff — so RK1117 left the id inside it unreachable.
|
|
900
|
+
:attr:`Scope.shared` is that half (RK1120): for each carrier this id explains,
|
|
901
|
+
:func:`~roadkeep.history.ids_since` says which *other* ids gained or lost a line since HEAD,
|
|
902
|
+
which two parses answer and no textual reading can — an annotation refresh names every
|
|
903
|
+
dependent in an added line and moves none of them.
|
|
904
|
+
"""
|
|
905
|
+
entries = tuple(entries)
|
|
906
|
+
if not any(one.paths for one in live(config, entries)):
|
|
907
|
+
return None
|
|
908
|
+
# Imported here for the reason :mod:`roadkeep.provenance` does it (RK260): this is the
|
|
909
|
+
# only function in the file that asks git anything, and every other reader of a claim —
|
|
910
|
+
# `pick`, `brief`, every marker write — would otherwise pay for the wrapper.
|
|
911
|
+
from roadkeep.history import indexed, status # noqa: PLC0415
|
|
912
|
+
|
|
913
|
+
seen = status(config)
|
|
914
|
+
accounted = written(config, task_id, seen.changed)
|
|
915
|
+
return split(
|
|
916
|
+
config,
|
|
917
|
+
task_id,
|
|
918
|
+
entries,
|
|
919
|
+
seen.changed,
|
|
920
|
+
indexed(config),
|
|
921
|
+
accounted=accounted,
|
|
922
|
+
shared=sharing(config, task_id, accounted),
|
|
923
|
+
staged=seen.staged,
|
|
924
|
+
)
|
|
925
|
+
|
|
926
|
+
|
|
927
|
+
def sharing(
|
|
928
|
+
config: Config, task_id: str, accounted: Iterable[str]
|
|
929
|
+
) -> tuple[tuple[str, tuple[str, ...]], ...]:
|
|
930
|
+
"""Per governed file this id explains, the other ids whose line moved in it (RK1120).
|
|
931
|
+
|
|
932
|
+
Its own function since RK1122, because **both** readers of the commit contract want it and
|
|
933
|
+
only one had it: `claim <id>` computed no `shared` at all — an empty list on every call —
|
|
934
|
+
while being the read a commit is actually composed from, `--porcelain` existing to be piped
|
|
935
|
+
into `git add --`. A departure *must* answer, the claim being released after it; this one is
|
|
936
|
+
asked, so it answers either way, which makes it the cheaper place for the warning and not
|
|
937
|
+
the one to leave it out of.
|
|
938
|
+
|
|
939
|
+
Only the files this id already explains (`accounted`): one it does not is reported whole by
|
|
940
|
+
:attr:`Scope.loose`, and naming the ids inside it as well would be one fact under two
|
|
941
|
+
headings.
|
|
942
|
+
|
|
943
|
+
Every governed file that can hold a record, in the unit that file keeps it in (RK1125): a
|
|
944
|
+
carrier holds **lines** and :func:`~roadkeep.history.ids_since` reads them, a rationale file
|
|
945
|
+
holds **sections** and :func:`~roadkeep.history.designs_since` reads those. Restricting this
|
|
946
|
+
to the carriers left the prose file a departure wrote unreadable for the same reason the
|
|
947
|
+
roadmap was — one `section amend` puts this id in its diff, and everything else inside it
|
|
948
|
+
then went unnamed.
|
|
949
|
+
"""
|
|
950
|
+
# Deferred for RK260's reason, and because git belongs off every path that did not ask.
|
|
951
|
+
from roadkeep.history import designs_since, ids_since, resolves # noqa: PLC0415
|
|
952
|
+
|
|
953
|
+
readers = {
|
|
954
|
+
**dict.fromkeys(CARRIERS, ids_since),
|
|
955
|
+
**dict.fromkeys(PROSE_ROLES, designs_since),
|
|
956
|
+
}
|
|
957
|
+
explained = frozenset(accounted)
|
|
958
|
+
wanted = [
|
|
959
|
+
role
|
|
960
|
+
for role in readers
|
|
961
|
+
if config.has(role) and config.relative(config.path(role)) in explained
|
|
962
|
+
]
|
|
963
|
+
if not wanted:
|
|
964
|
+
# Nothing to compare, so nothing is asked of git at all — the common case on a tree
|
|
965
|
+
# holding only this task's work, and the reason the loop is not entered to find out.
|
|
966
|
+
return ()
|
|
967
|
+
# Once, and passed down (RK1124): whether git knows `HEAD` is a fact about the repository,
|
|
968
|
+
# and a `rev-parse` per role was 40.6ms of an answer already in hand.
|
|
969
|
+
known = resolves(config, "HEAD")
|
|
970
|
+
out: list[tuple[str, tuple[str, ...]]] = []
|
|
971
|
+
for role in wanted:
|
|
972
|
+
moved = readers[role](config, "HEAD", role, resolved=known) - {task_id}
|
|
973
|
+
if moved:
|
|
974
|
+
out.append((config.relative(config.path(role)), tuple(sorted(moved))))
|
|
975
|
+
return tuple(out)
|
|
976
|
+
|
|
977
|
+
|
|
978
|
+
def rename(root: Path | str, old: str, new: str) -> bool:
|
|
979
|
+
"""Carry a claim to the id its line was moved to (RK156). True where one moved.
|
|
980
|
+
|
|
981
|
+
The exception to "every marker door is a release": `renumber` does not move the marker,
|
|
982
|
+
it moves the **address**, so the registry keeps an id no line carries while the new one
|
|
983
|
+
reads as started work nobody holds — which is RK119's defect reopened by the one command
|
|
984
|
+
that exists because a merge spent an id twice. The date travels rather than restarting:
|
|
985
|
+
the work is the same age, and a claim that renewed itself on a rename would be an expiry
|
|
986
|
+
a rename could postpone for ever.
|
|
987
|
+
|
|
988
|
+
It re-addresses and does not reconcile, unlike :func:`follow` (RK163): the lines are not in
|
|
989
|
+
hand here, and a rename is rare while the next marker write is not — so a row this leaves
|
|
990
|
+
unpruned is cleared by the first `ship` or `status` after it.
|
|
991
|
+
"""
|
|
992
|
+
dated = _read(root)
|
|
993
|
+
row = dated.pop(old, None)
|
|
994
|
+
if row is None:
|
|
995
|
+
return False
|
|
996
|
+
dated[new] = row
|
|
997
|
+
_write(root, dated)
|
|
998
|
+
return True
|
|
999
|
+
|
|
1000
|
+
|
|
1001
|
+
def _read(root: Path | str) -> dict[str, Dating]:
|
|
1002
|
+
"""This checkout's claims, out of the shared store — empty where it cannot be read.
|
|
1003
|
+
|
|
1004
|
+
The grammar, the atomic replace and the "unreadable is empty" rule all belong to
|
|
1005
|
+
:mod:`roadkeep.storing` now (RK330); what stays here is the one table this module owns.
|
|
1006
|
+
"""
|
|
1007
|
+
return dict(read(root).claims)
|
|
1008
|
+
|
|
1009
|
+
|
|
1010
|
+
def _write(root: Path | str, dated: Mapping[str, Dating]) -> None:
|
|
1011
|
+
"""Replace the claims table, and leave every other table exactly as it was.
|
|
1012
|
+
|
|
1013
|
+
Read-modify-write, which is safe for the reason it is safe everywhere else here: every
|
|
1014
|
+
writer of the store runs under the checkout's exclusive lock (:func:`roadkeep.cli.dispatch`),
|
|
1015
|
+
so nothing can land between the read and the replace. A claim that dropped the write
|
|
1016
|
+
record on its way past would be the digest sidecar's data lost to the registry's write —
|
|
1017
|
+
the failure a shared file has and two files did not, closed at the one door that writes.
|
|
1018
|
+
"""
|
|
1019
|
+
write(root, Store(claims=dict(dated), writes=read(root).writes))
|