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/history.py
ADDED
|
@@ -0,0 +1,2403 @@
|
|
|
1
|
+
"""Reaching the reasoning behind a shipped decision (RK31).
|
|
2
|
+
|
|
3
|
+
Shipping deletes the rationale section, the ledger keeps one line, and the argument
|
|
4
|
+
survives only in a commit message. That is not a bad place to keep it — it is the one
|
|
5
|
+
place that cannot drift from the code — but it is unreachable in practice: answering
|
|
6
|
+
"why is this like this" costs a `git log -S` over the whole history, so the question
|
|
7
|
+
goes unasked and the design gets re-litigated instead.
|
|
8
|
+
|
|
9
|
+
**The pointer is derived, not stored.** The obvious design — write the shipping commit's
|
|
10
|
+
hash into the ledger entry — is wrong, and the objection is decisive: `squash`, `amend`
|
|
11
|
+
and `rebase` rewrite that hash, and a dead hash reads exactly like a live one. A stored
|
|
12
|
+
pointer would rot silently, which is worse than no pointer at all.
|
|
13
|
+
|
|
14
|
+
So resolve it from git on demand. The commit that shipped a task is, by construction,
|
|
15
|
+
the commit that **added its id to the ledger**, and the commit that proposed it is the
|
|
16
|
+
one that added the id to the roadmap. Both are found with `git log -S` scoped to one
|
|
17
|
+
file, both are correct after any history rewrite, and neither costs a byte in the
|
|
18
|
+
documents. It also works retroactively: every task shipped before this module existed
|
|
19
|
+
is already addressable.
|
|
20
|
+
"""
|
|
21
|
+
|
|
22
|
+
from __future__ import annotations
|
|
23
|
+
|
|
24
|
+
import re
|
|
25
|
+
import shutil
|
|
26
|
+
import subprocess
|
|
27
|
+
from collections.abc import Sequence
|
|
28
|
+
from dataclasses import dataclass, replace
|
|
29
|
+
from pathlib import Path
|
|
30
|
+
|
|
31
|
+
from roadkeep.config import PROSE_ROLES, Config
|
|
32
|
+
from roadkeep.kernel.document import Document
|
|
33
|
+
from roadkeep.kernel.schema import ARROW, REF_SEPARATOR, Schema, split_ref
|
|
34
|
+
from roadkeep.sections import Section, anchored, find, owners
|
|
35
|
+
|
|
36
|
+
_UNIT = "\x1f" # between fields
|
|
37
|
+
_RECORD = "\x1e" # between commits — a body may hold newlines, so lines will not do
|
|
38
|
+
_FORMAT = _UNIT.join(["%H", "%h", "%aI", "%an", "%s", "%b"]) + _RECORD
|
|
39
|
+
_TIMEOUT = 20
|
|
40
|
+
#: What `-z` separates paths by, on both ends of `check-ignore` (RK213).
|
|
41
|
+
_NUL = chr(0)
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
class HistoryUnavailable(RuntimeError):
|
|
45
|
+
"""No git, or no repository — the answer is absent rather than negative."""
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
@dataclass(frozen=True, slots=True)
|
|
49
|
+
class Commit:
|
|
50
|
+
sha: str
|
|
51
|
+
short: str
|
|
52
|
+
date: str
|
|
53
|
+
author: str
|
|
54
|
+
subject: str
|
|
55
|
+
body: str
|
|
56
|
+
|
|
57
|
+
@property
|
|
58
|
+
def reasoning(self) -> str:
|
|
59
|
+
"""Subject plus body: the part a ledger line cannot hold."""
|
|
60
|
+
return f"{self.subject}\n\n{self.body}".strip()
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
@dataclass(frozen=True, slots=True)
|
|
64
|
+
class Origin:
|
|
65
|
+
"""Where a task entered the backlog, and where it left it."""
|
|
66
|
+
|
|
67
|
+
task_id: str
|
|
68
|
+
proposed_in: Commit | None
|
|
69
|
+
shipped_in: Commit | None
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
def git_available() -> bool:
|
|
73
|
+
return shutil.which("git") is not None
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
def _run(root: Path, *args: str, fed: Sequence[str] = ()) -> str:
|
|
77
|
+
return _bytes(root, *args, fed=fed).decode("utf-8", errors="replace")
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
def _bytes(root: Path, *args: str, fed: Sequence[str] = ()) -> bytes:
|
|
81
|
+
"""The raw output, because one caller reads a file and not a report (RK84).
|
|
82
|
+
|
|
83
|
+
Bytes and not ``text=True``: universal newlines would translate CRLF to LF, and a
|
|
84
|
+
baseline that read the file at a revision through that translation would report every
|
|
85
|
+
ending as changed — on the two things `lint` measures in bytes, the round-trip (L3)
|
|
86
|
+
and a budget (RK30). Text callers decode here instead, which is the same string
|
|
87
|
+
`text=True` gave them minus the rewriting.
|
|
88
|
+
|
|
89
|
+
``fed`` is the revisions a `--stdin` call reads, and it is the one thing here that is
|
|
90
|
+
**not** argv (RK1315). A list handed as arguments is bounded by the operating system:
|
|
91
|
+
measured on this repository at the commit that crossed it — 802 ledger entries, 798
|
|
92
|
+
distinct commits, 32,718 characters of shas alone against Windows' 32,767 — where
|
|
93
|
+
`weigh` stopped answering with `HistoryUnavailable`, which its caller reports as an
|
|
94
|
+
absent answer. So the verb that says what a comparable task cost failed at exactly the
|
|
95
|
+
ledger size that makes the question worth asking, and POSIX reaches its own `ARG_MAX`
|
|
96
|
+
later rather than never. Fed on stdin the list has no ceiling and the call count does
|
|
97
|
+
not grow with the file, which is the property `costs_of` was written for.
|
|
98
|
+
"""
|
|
99
|
+
if not git_available():
|
|
100
|
+
raise HistoryUnavailable("git is not on PATH")
|
|
101
|
+
try:
|
|
102
|
+
# Fixed argv and shell=False: nothing here interpolates into a shell.
|
|
103
|
+
result = subprocess.run(
|
|
104
|
+
["git", "-C", str(root), *args],
|
|
105
|
+
capture_output=True,
|
|
106
|
+
timeout=_TIMEOUT,
|
|
107
|
+
check=False,
|
|
108
|
+
# `b"\n".join` and not a text `input`: this call is byte-oriented on purpose,
|
|
109
|
+
# and a rev is ASCII — encoding it here keeps the one decode at the boundary.
|
|
110
|
+
input=b"\n".join(one.encode("utf-8") for one in fed) if fed else None,
|
|
111
|
+
)
|
|
112
|
+
except (OSError, subprocess.TimeoutExpired) as error:
|
|
113
|
+
raise HistoryUnavailable(str(error)) from error
|
|
114
|
+
if result.returncode != 0:
|
|
115
|
+
raise HistoryUnavailable(
|
|
116
|
+
result.stderr.decode("utf-8", errors="replace").strip() or "git failed"
|
|
117
|
+
)
|
|
118
|
+
return result.stdout
|
|
119
|
+
|
|
120
|
+
|
|
121
|
+
def _parse(output: str) -> tuple[Commit, ...]:
|
|
122
|
+
commits: list[Commit] = []
|
|
123
|
+
for record in output.split(_RECORD):
|
|
124
|
+
record = record.strip("\n")
|
|
125
|
+
if not record:
|
|
126
|
+
continue
|
|
127
|
+
fields = record.split(_UNIT)
|
|
128
|
+
if len(fields) < 6:
|
|
129
|
+
continue
|
|
130
|
+
sha, short, date, author, subject, body = fields[:6]
|
|
131
|
+
commits.append(
|
|
132
|
+
Commit(
|
|
133
|
+
sha=sha,
|
|
134
|
+
short=short,
|
|
135
|
+
date=date,
|
|
136
|
+
author=author,
|
|
137
|
+
subject=subject,
|
|
138
|
+
body=body.strip(),
|
|
139
|
+
)
|
|
140
|
+
)
|
|
141
|
+
return tuple(commits)
|
|
142
|
+
|
|
143
|
+
|
|
144
|
+
def commits_touching(
|
|
145
|
+
root: Path, needle: str, path: Path | None = None, *, literal: bool = True
|
|
146
|
+
) -> tuple[Commit, ...]:
|
|
147
|
+
"""Commits whose diff mentions ``needle`` at all, oldest first.
|
|
148
|
+
|
|
149
|
+
Two deliberate choices:
|
|
150
|
+
|
|
151
|
+
* **Not `--grep`.** Putting the id in the commit subject is a convention an author
|
|
152
|
+
can forget; a commit that moved a task's line *must* contain the id in its diff.
|
|
153
|
+
* **`-G`, not `-S`.** `-S` counts occurrences and reports only a *net* change, so
|
|
154
|
+
rewording a line — the id present before and after — is invisible to it. `-G`
|
|
155
|
+
matches any diff that mentions the id, which is what "every commit that touched
|
|
156
|
+
this task" means.
|
|
157
|
+
|
|
158
|
+
One thing neither flag can recover: if a task is proposed and shipped inside one
|
|
159
|
+
commit, the roadmap ends the commit as it began and there is no diff to find. The
|
|
160
|
+
squash destroyed that fact; the shipping commit, which is the one carrying the
|
|
161
|
+
reasoning, still resolves.
|
|
162
|
+
|
|
163
|
+
``literal`` off hands the needle to git as the pattern it already is, for the one
|
|
164
|
+
caller with a shape rather than a string to find (RK212): a heading is spelled two ways
|
|
165
|
+
across live outline projects — `### VIII.1` in Shio and Turing, `### §I.1` in
|
|
166
|
+
claude-tray — and an escaped literal would answer for one of them and silently miss the
|
|
167
|
+
other, which a reader would read as "nobody ever wrote it".
|
|
168
|
+
"""
|
|
169
|
+
args = ["log", "--reverse", f"--format={_FORMAT}"]
|
|
170
|
+
if not literal:
|
|
171
|
+
# git reads `-G` as a *basic* regex, where `?` is a literal character rather than a
|
|
172
|
+
# quantifier — so the optional sigil below would be searched for as a `?`.
|
|
173
|
+
args.append("--extended-regexp")
|
|
174
|
+
args += ["-G", re.escape(needle) if literal else needle]
|
|
175
|
+
if path is not None:
|
|
176
|
+
args += ["--", str(path)]
|
|
177
|
+
return _parse(_run(root, *args))
|
|
178
|
+
|
|
179
|
+
|
|
180
|
+
def check_ignore(root: Path, paths: Sequence[str]) -> frozenset[str]:
|
|
181
|
+
"""Which of these paths the repository has declared it will never track (RK213).
|
|
182
|
+
|
|
183
|
+
`check-ignore` and not a table of directory names, because the repository already
|
|
184
|
+
carries the declaration: the same `.gitignore`, `.git/info/exclude` and
|
|
185
|
+
`core.excludesFile` a developer's own `git status` reads, so the gate and the author
|
|
186
|
+
cannot disagree about what is tracked here (L6, answered by the project rather than by
|
|
187
|
+
this tool). Exit 1 means *none matched*, which is an answer and not a failure — the only
|
|
188
|
+
reason this cannot go through :func:`_run`.
|
|
189
|
+
|
|
190
|
+
`-z` on both ends: a path holding a quote or a non-ASCII byte arrives as itself rather
|
|
191
|
+
than as git's escaped rendering, which is :func:`tracked_at`'s reason one command along.
|
|
192
|
+
"""
|
|
193
|
+
if not paths:
|
|
194
|
+
return frozenset()
|
|
195
|
+
if not git_available():
|
|
196
|
+
raise HistoryUnavailable("git is not on PATH")
|
|
197
|
+
try:
|
|
198
|
+
result = subprocess.run(
|
|
199
|
+
["git", "-C", str(root), "check-ignore", "--stdin", "-z"],
|
|
200
|
+
input=_NUL.join(paths).encode("utf-8"),
|
|
201
|
+
capture_output=True,
|
|
202
|
+
timeout=_TIMEOUT,
|
|
203
|
+
check=False,
|
|
204
|
+
)
|
|
205
|
+
except (OSError, subprocess.TimeoutExpired) as error:
|
|
206
|
+
raise HistoryUnavailable(str(error)) from error
|
|
207
|
+
if result.returncode not in (0, 1):
|
|
208
|
+
raise HistoryUnavailable(
|
|
209
|
+
result.stderr.decode("utf-8", errors="replace").strip() or "git failed"
|
|
210
|
+
)
|
|
211
|
+
listed = result.stdout.decode("utf-8", errors="replace")
|
|
212
|
+
return frozenset(name for name in listed.split(_NUL) if name)
|
|
213
|
+
|
|
214
|
+
|
|
215
|
+
#: What `check-attr` answers where a path has no value for the attribute at all.
|
|
216
|
+
UNSPECIFIED = "unspecified"
|
|
217
|
+
|
|
218
|
+
|
|
219
|
+
def check_attr(root: Path, attribute: str, paths: Sequence[str]) -> dict[str, str]:
|
|
220
|
+
"""What git resolves `attribute` to for each of these paths (RK273).
|
|
221
|
+
|
|
222
|
+
`check-attr` and not a read of `<root>/.gitattributes`, because that file is not where the
|
|
223
|
+
answer lives: git consults a `.gitattributes` in every directory from the path upward, then
|
|
224
|
+
`$GIT_DIR/info/attributes`, then `core.attributesFile`, with the deepest rule winning. A
|
|
225
|
+
read of the root file alone reports files unsent that git sends — measured, with
|
|
226
|
+
`.git/info/attributes` carrying the line. The repository already holds the declaration, so
|
|
227
|
+
it is asked rather than guessed at, the same choice :func:`check_ignore` makes (L6).
|
|
228
|
+
|
|
229
|
+
The value is git's own word: a driver's name where one is set, or :data:`UNSPECIFIED`,
|
|
230
|
+
`set`, `unset`. Richer than the boolean a string comparison yields — a path sent to a
|
|
231
|
+
*different* driver is a deliberate act, and invisible to a read looking only for one name.
|
|
232
|
+
|
|
233
|
+
`-z`, for the reason :func:`check_ignore` gives one command along: a path holding a quote
|
|
234
|
+
or a non-ASCII byte arrives as itself and not as git's escaped rendering. The paths go as
|
|
235
|
+
arguments rather than down `--stdin`, because a project declares a handful of governed
|
|
236
|
+
files and that keeps this on :func:`_bytes` — the package's one place with a timeout, an
|
|
237
|
+
encoding and a single failure type.
|
|
238
|
+
"""
|
|
239
|
+
if not paths:
|
|
240
|
+
return {}
|
|
241
|
+
listed = _bytes(root, "check-attr", "-z", attribute, "--", *paths).decode(
|
|
242
|
+
"utf-8", errors="replace"
|
|
243
|
+
)
|
|
244
|
+
# Triples, `<path>\0<attribute>\0<value>\0`, so the walk is by threes and not by lines —
|
|
245
|
+
# a value is one field of a record here, never a line of output.
|
|
246
|
+
fields = [field for field in listed.split(_NUL) if field != ""]
|
|
247
|
+
return {
|
|
248
|
+
fields[index]: fields[index + 2]
|
|
249
|
+
for index in range(0, len(fields) - 2, 3)
|
|
250
|
+
if fields[index + 1] == attribute
|
|
251
|
+
}
|
|
252
|
+
|
|
253
|
+
|
|
254
|
+
@dataclass(frozen=True, slots=True)
|
|
255
|
+
class Change:
|
|
256
|
+
"""One changed line, numbered **on the side it exists on**.
|
|
257
|
+
|
|
258
|
+
Which side matters, and getting it wrong is what makes a diff-based check cry wolf: a
|
|
259
|
+
deleted paragraph has no line number in the file as it is now, so attributing it to
|
|
260
|
+
the new-side position lands it in whichever section happens to precede the hole.
|
|
261
|
+
"""
|
|
262
|
+
|
|
263
|
+
lineno: int
|
|
264
|
+
text: str
|
|
265
|
+
#: True for a line the diff added (new side), False for one it removed (old side).
|
|
266
|
+
added: bool
|
|
267
|
+
|
|
268
|
+
|
|
269
|
+
@dataclass(frozen=True, slots=True)
|
|
270
|
+
class Touched:
|
|
271
|
+
"""Every line a diff changed in one file (RK36)."""
|
|
272
|
+
|
|
273
|
+
changes: tuple[Change, ...] = ()
|
|
274
|
+
|
|
275
|
+
@property
|
|
276
|
+
def lines(self) -> tuple[str, ...]:
|
|
277
|
+
"""The changed text, either side — added, removed or reworded.
|
|
278
|
+
|
|
279
|
+
All three mean somebody had the line open, which is the only thing the check is
|
|
280
|
+
entitled to conclude: deciding whether the edit was *responsive* would be reading
|
|
281
|
+
prose (L4).
|
|
282
|
+
"""
|
|
283
|
+
return tuple(change.text for change in self.changes)
|
|
284
|
+
|
|
285
|
+
|
|
286
|
+
_HUNK_RE = re.compile(r"^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@")
|
|
287
|
+
|
|
288
|
+
|
|
289
|
+
def resolves(config: Config, rev: str) -> bool:
|
|
290
|
+
"""Does git know this revision? False for `HEAD` in a repository with no commits."""
|
|
291
|
+
try:
|
|
292
|
+
_run(config.root, "rev-parse", "--verify", "--quiet", f"{rev}^{{commit}}")
|
|
293
|
+
except HistoryUnavailable:
|
|
294
|
+
return False
|
|
295
|
+
return True
|
|
296
|
+
|
|
297
|
+
|
|
298
|
+
def revisions_of(
|
|
299
|
+
config: Config, path: Path, first: int, last: int
|
|
300
|
+
) -> tuple[Commit, ...]:
|
|
301
|
+
"""Every commit that touched these lines of this file, oldest first (RK1163).
|
|
302
|
+
|
|
303
|
+
`-L` and not `-G`, which is the difference between a *span* and a mention: a section's
|
|
304
|
+
heading appears in the diff of the commit that wrote it and of nothing else, so a body-only
|
|
305
|
+
`section amend` — the ordinary way a design is revised — is invisible to a needle. That is
|
|
306
|
+
RK1126's finding one module over, and it is the whole reason this reads a range.
|
|
307
|
+
|
|
308
|
+
The range is the section's own span, resolved through history by git rather than by this
|
|
309
|
+
reader: `-L` follows the lines as the file moves around them, which no line number stored
|
|
310
|
+
here could. `-s` suppresses the diffs, since what is wanted is the commits.
|
|
311
|
+
"""
|
|
312
|
+
where = str(path if not path.is_absolute() else path.relative_to(config.root))
|
|
313
|
+
return _parse(
|
|
314
|
+
_run(
|
|
315
|
+
config.root,
|
|
316
|
+
"log",
|
|
317
|
+
"--reverse",
|
|
318
|
+
"-s",
|
|
319
|
+
f"--format={_FORMAT}",
|
|
320
|
+
f"-L{first},{last}:{where}",
|
|
321
|
+
)
|
|
322
|
+
)
|
|
323
|
+
|
|
324
|
+
|
|
325
|
+
def precedes(config: Config, earlier: str, later: str) -> bool:
|
|
326
|
+
"""Whether one commit is an ancestor of another — the ordering dates cannot give (RK1163).
|
|
327
|
+
|
|
328
|
+
Two commits made in the same second carry the same ISO timestamp, so a date compare answers
|
|
329
|
+
*no* about a design that plainly predates a ship; and a rebase can order dates against the
|
|
330
|
+
history. What git already knows is the ancestry, which is the question actually being asked:
|
|
331
|
+
was this written before that landed.
|
|
332
|
+
|
|
333
|
+
A commit is its own ancestor, so an identical pair answers True and the caller excludes it —
|
|
334
|
+
a design revised *in* the shipping commit has read what changed, which is the one case this
|
|
335
|
+
must not report.
|
|
336
|
+
"""
|
|
337
|
+
if not earlier or not later:
|
|
338
|
+
return False
|
|
339
|
+
try:
|
|
340
|
+
_run(config.root, "merge-base", "--is-ancestor", earlier, later)
|
|
341
|
+
except HistoryUnavailable:
|
|
342
|
+
return False
|
|
343
|
+
return True
|
|
344
|
+
|
|
345
|
+
|
|
346
|
+
def touched_since(config: Config, rev: str, role: str) -> Touched:
|
|
347
|
+
"""The diff of one governed file from ``rev`` to the working tree.
|
|
348
|
+
|
|
349
|
+
`-U0`, because context lines would put a neighbouring section inside the span and the
|
|
350
|
+
whole value of this check is that it names the section somebody actually opened.
|
|
351
|
+
"""
|
|
352
|
+
if not config.has(role) or not config.path(role).is_file():
|
|
353
|
+
return Touched()
|
|
354
|
+
try:
|
|
355
|
+
relative = config.path(role).relative_to(config.root)
|
|
356
|
+
except ValueError:
|
|
357
|
+
relative = config.path(role)
|
|
358
|
+
output = _run(config.root, "diff", "--no-color", "-U0", rev, "--", str(relative))
|
|
359
|
+
return _read_diff(output)
|
|
360
|
+
|
|
361
|
+
|
|
362
|
+
def changed_paths(config: Config, rev: str) -> frozenset[str]:
|
|
363
|
+
"""Every path this working tree changed against ``rev``, repo-relative (RK1228).
|
|
364
|
+
|
|
365
|
+
The half `--since` already had for the governed files, asked of the **rest of the tree**:
|
|
366
|
+
`touched_since` diffs one governed file to attribute a change to a section, and this is
|
|
367
|
+
the mirror question — what source moved while the backlog stood still.
|
|
368
|
+
|
|
369
|
+
Names and not hunks, because the question is *did anything under this task change* and a
|
|
370
|
+
line count would invite a threshold nobody could defend. Repo-relative and forward-slashed,
|
|
371
|
+
which is the spelling a section's own prose uses and what `paths_in` resolves to.
|
|
372
|
+
|
|
373
|
+
Empty where git cannot answer, which keeps the note silent: this reports a coincidence
|
|
374
|
+
worth a sentence, and a repository with no history has no coincidence to report.
|
|
375
|
+
"""
|
|
376
|
+
try:
|
|
377
|
+
found = _run(config.root, "diff", "--name-only", rev)
|
|
378
|
+
except HistoryUnavailable:
|
|
379
|
+
return frozenset()
|
|
380
|
+
return frozenset(one.strip().replace("\\", "/") for one in found.splitlines() if one.strip())
|
|
381
|
+
|
|
382
|
+
|
|
383
|
+
def changed_lines(config: Config, rev: str, path: Path) -> frozenset[int] | None:
|
|
384
|
+
"""Line numbers this working tree changed in one file against ``rev`` (RK60).
|
|
385
|
+
|
|
386
|
+
``None`` means git cannot narrow this file — no history, no `git`, or a file it does not
|
|
387
|
+
track yet — and the caller then judges all of it, because a file nothing can diff is a
|
|
388
|
+
file nobody can be excused from.
|
|
389
|
+
|
|
390
|
+
A path and not a role, because the `Stop` gate also holds the instruction files a
|
|
391
|
+
`[budgets]` entry names (RK30), and those are governed by nothing.
|
|
392
|
+
"""
|
|
393
|
+
try:
|
|
394
|
+
relative = path.resolve().relative_to(config.root)
|
|
395
|
+
except ValueError:
|
|
396
|
+
relative = path
|
|
397
|
+
try:
|
|
398
|
+
if not _run(config.root, "ls-files", "--", str(relative)).strip():
|
|
399
|
+
return None # untracked: every line of it arrived without a commit
|
|
400
|
+
output = _run(config.root, "diff", "--no-color", "-U0", rev, "--", str(relative))
|
|
401
|
+
except HistoryUnavailable:
|
|
402
|
+
return None
|
|
403
|
+
return frozenset(
|
|
404
|
+
change.lineno for change in _read_diff(output).changes if change.added
|
|
405
|
+
)
|
|
406
|
+
|
|
407
|
+
|
|
408
|
+
def _read_diff(output: str) -> Touched:
|
|
409
|
+
"""Walk a `-U0` diff, numbering each changed line on its own side."""
|
|
410
|
+
changes: list[Change] = []
|
|
411
|
+
old = new = 0
|
|
412
|
+
for raw in output.splitlines():
|
|
413
|
+
hunk = _HUNK_RE.match(raw)
|
|
414
|
+
if hunk:
|
|
415
|
+
old, new = int(hunk.group(1)), int(hunk.group(3))
|
|
416
|
+
continue
|
|
417
|
+
if raw.startswith(("+++", "---")):
|
|
418
|
+
continue
|
|
419
|
+
if raw.startswith("+"):
|
|
420
|
+
changes.append(Change(lineno=new, text=raw[1:], added=True))
|
|
421
|
+
new += 1
|
|
422
|
+
elif raw.startswith("-"):
|
|
423
|
+
changes.append(Change(lineno=old, text=raw[1:], added=False))
|
|
424
|
+
old += 1
|
|
425
|
+
return Touched(changes=tuple(changes))
|
|
426
|
+
|
|
427
|
+
|
|
428
|
+
def content_at(config: Config, rev: str, role: str) -> str:
|
|
429
|
+
"""One governed file as of ``rev``, or empty when it was not there yet.
|
|
430
|
+
|
|
431
|
+
Needed because a removal has to be attributed to the section that *held* it, and that
|
|
432
|
+
section may no longer exist — which is exactly the case `ship` produces, and the one a
|
|
433
|
+
check must not report (RK36).
|
|
434
|
+
"""
|
|
435
|
+
if not config.has(role):
|
|
436
|
+
return ""
|
|
437
|
+
raw = blob_at(config, rev, config.path(role))
|
|
438
|
+
return "" if raw is None else raw.decode("utf-8", errors="replace")
|
|
439
|
+
|
|
440
|
+
|
|
441
|
+
def blob_at(config: Config, rev: str, path: Path) -> bytes | None:
|
|
442
|
+
"""One file's bytes as of ``rev``, or ``None`` when that tree did not carry it (RK84).
|
|
443
|
+
|
|
444
|
+
The two answers are kept apart because a baseline turns on the difference: an empty
|
|
445
|
+
file was there and said nothing, and an absent one is a file the change *added* — so
|
|
446
|
+
crediting it with the findings of a file it did not have would forgive every line of
|
|
447
|
+
it. Bytes, because the caller measuring a budget is counting them (RK30).
|
|
448
|
+
"""
|
|
449
|
+
try:
|
|
450
|
+
relative = path.resolve().relative_to(config.root)
|
|
451
|
+
except ValueError:
|
|
452
|
+
relative = path
|
|
453
|
+
try:
|
|
454
|
+
return _bytes(config.root, "show", f"{rev}:{relative.as_posix()}")
|
|
455
|
+
except HistoryUnavailable:
|
|
456
|
+
return None
|
|
457
|
+
|
|
458
|
+
|
|
459
|
+
def tracked_at(config: Config, rev: str) -> frozenset[str]:
|
|
460
|
+
"""Every path in the tree at ``rev``, as git spells them (RK84).
|
|
461
|
+
|
|
462
|
+
One `ls-tree` rather than a question per path: a ledger names 886 of them on the corpus
|
|
463
|
+
this was measured against, and a subprocess each is the difference between a check and
|
|
464
|
+
a thing nobody runs. `-z`, so a path holding a quote or a non-ASCII byte arrives as
|
|
465
|
+
itself instead of as git's escaped rendering of it.
|
|
466
|
+
"""
|
|
467
|
+
try:
|
|
468
|
+
output = _run(config.root, "ls-tree", "-r", "--name-only", "-z", rev)
|
|
469
|
+
except HistoryUnavailable:
|
|
470
|
+
return frozenset()
|
|
471
|
+
return frozenset(name for name in output.split("\0") if name)
|
|
472
|
+
|
|
473
|
+
|
|
474
|
+
def indexed(config: Config) -> frozenset[str]:
|
|
475
|
+
"""Every path the index carries, including one deleted from the working tree (RK217).
|
|
476
|
+
|
|
477
|
+
:func:`tracked_now` without its subtraction, because the two answer different questions.
|
|
478
|
+
*Does the repository still have this artefact* must not credit a file somebody deleted
|
|
479
|
+
and did not stage — that is the finding the path check exists for. *Is this a directory
|
|
480
|
+
the repository knows about* must: a ledger naming `lib/gone.py` after `lib/` was removed
|
|
481
|
+
is precisely the case worth reporting, and a listing that had already forgotten `lib/`
|
|
482
|
+
would make the token stop being a claim rather than become a finding.
|
|
483
|
+
"""
|
|
484
|
+
try:
|
|
485
|
+
listed = _run(config.root, "ls-files", "-z")
|
|
486
|
+
except HistoryUnavailable:
|
|
487
|
+
return frozenset()
|
|
488
|
+
return frozenset(name for name in listed.split(chr(0)) if name)
|
|
489
|
+
|
|
490
|
+
|
|
491
|
+
def tracked_now(config: Config) -> frozenset[str]:
|
|
492
|
+
"""Every tracked path the working tree still **has**, as git spells them (RK173).
|
|
493
|
+
|
|
494
|
+
:func:`tracked_at`'s answer for the run that has no revision, and asked for the same
|
|
495
|
+
reason: two processes rather than a walk of the repository or a stat per path, so a
|
|
496
|
+
check over a ledger naming hundreds of artefacts stays a check rather than a thing
|
|
497
|
+
nobody runs. Git's own list, so a build directory nobody committed cannot satisfy a
|
|
498
|
+
claim about the source.
|
|
499
|
+
|
|
500
|
+
Minus what git calls deleted, which is the whole reason this is not `ls-files` alone:
|
|
501
|
+
the index still carries a file removed from the tree and not yet staged, and crediting
|
|
502
|
+
one would forgive exactly the finding this check exists for — an artefact that was there
|
|
503
|
+
at the revision and is gone now. :func:`indexed` is the same listing without that
|
|
504
|
+
subtraction, for the caller asking the other question.
|
|
505
|
+
"""
|
|
506
|
+
listed = indexed(config)
|
|
507
|
+
if not listed:
|
|
508
|
+
return frozenset()
|
|
509
|
+
try:
|
|
510
|
+
removed = _run(config.root, "ls-files", "--deleted", "-z")
|
|
511
|
+
except HistoryUnavailable:
|
|
512
|
+
return frozenset()
|
|
513
|
+
gone = {name for name in removed.split(chr(0)) if name}
|
|
514
|
+
return frozenset(name for name in listed if name not in gone)
|
|
515
|
+
|
|
516
|
+
|
|
517
|
+
def dirty(config: Config) -> frozenset[str]:
|
|
518
|
+
"""Every path the working tree has changed, staged or not, untracked included (RK280).
|
|
519
|
+
|
|
520
|
+
What a `git add -A` would put in the next commit, which is the list a scope is subtracted
|
|
521
|
+
from — so it has to be exactly that list and not a tidier one: an untracked file is the
|
|
522
|
+
new test somebody's session just wrote, and leaving it out would answer *your commit is
|
|
523
|
+
clean* about the tree that carried the defect this exists for.
|
|
524
|
+
|
|
525
|
+
`status --porcelain -z` and not a diff: one process, git's own spelling on every platform,
|
|
526
|
+
and the rename case arrives as both its ends, which is the honest reading when the
|
|
527
|
+
question is what a commit would touch. Empty where git cannot answer, the rule every
|
|
528
|
+
reader here keeps — a checkout with no git is one this reports nothing about, never one
|
|
529
|
+
it refuses.
|
|
530
|
+
"""
|
|
531
|
+
return status(config).changed
|
|
532
|
+
|
|
533
|
+
|
|
534
|
+
def status(config: Config) -> Status:
|
|
535
|
+
"""The porcelain read once, split by which side of the index each path changed on (RK1197).
|
|
536
|
+
|
|
537
|
+
One process for both answers rather than two for one each: the columns are in the same
|
|
538
|
+
record git already sent, and asking twice would be this module doing what it tells its
|
|
539
|
+
callers not to.
|
|
540
|
+
"""
|
|
541
|
+
try:
|
|
542
|
+
listed = _run(config.root, "status", "--porcelain", "-z")
|
|
543
|
+
except HistoryUnavailable:
|
|
544
|
+
return Status()
|
|
545
|
+
return Status(*_read_status(listed))
|
|
546
|
+
|
|
547
|
+
|
|
548
|
+
@dataclass(frozen=True, slots=True)
|
|
549
|
+
class Status:
|
|
550
|
+
"""A working tree as `git status` describes it, both sides kept apart (RK1197)."""
|
|
551
|
+
|
|
552
|
+
#: Every path the tree has changed, staged or not, untracked included — what a `git add -A`
|
|
553
|
+
#: would put in the next commit, which is the list a scope is subtracted from.
|
|
554
|
+
changed: frozenset[str] = frozenset()
|
|
555
|
+
#: The subset whose **index** already differs from `HEAD`. The half that was thrown away:
|
|
556
|
+
#: a `git commit` takes these whether or not the author reads a diff, and the diff they are
|
|
557
|
+
#: reading is the other side. Measured twice in one session as a version literal another
|
|
558
|
+
#: process staged and this one would have committed.
|
|
559
|
+
staged: frozenset[str] = frozenset()
|
|
560
|
+
|
|
561
|
+
|
|
562
|
+
def carrying(config: Config, task_id: str, paths: Iterable[str]) -> tuple[str, ...]:
|
|
563
|
+
"""Which of these paths have this id **in their working-tree diff** (RK342).
|
|
564
|
+
|
|
565
|
+
The fact `claim <id>` was missing. A claim's own transaction writes governed files — the
|
|
566
|
+
marker moves in the roadmap, and every governed write carries the README refresh RK188
|
|
567
|
+
added — and the read-back then listed both as `loose`, which reads as *a file somebody
|
|
568
|
+
else touched*. So the author declares the governed paths by hand to silence it, and the
|
|
569
|
+
scope comes to carry paths that were never the work: the analysis this command exists to
|
|
570
|
+
make, made wrong, on the first call of every task.
|
|
571
|
+
|
|
572
|
+
**Not every dirty governed file**, which is the repair that was available and wrong: a
|
|
573
|
+
roadmap the tree holds may hold another session's `add`, and handing it to whoever asks
|
|
574
|
+
would be the two sessions RK294 separates each getting the other's files with this tool's
|
|
575
|
+
signature on it. The distinction the files themselves carry is the id — a line whose
|
|
576
|
+
marker this transaction moved is a changed line naming it, and a projection refreshed
|
|
577
|
+
from that line reproduces it.
|
|
578
|
+
|
|
579
|
+
Read off `git diff HEAD`, both sides, so a **removed** line counts: a ship takes the line
|
|
580
|
+
out, and a diff read for additions alone would answer "no" about the departure that is
|
|
581
|
+
most of the work. Whole-word, because `RK34` must not answer for `RK342` — the same care
|
|
582
|
+
:func:`cited_origin` takes with an anchor, and the same reason.
|
|
583
|
+
|
|
584
|
+
Empty where git cannot answer, the rule every reader here keeps.
|
|
585
|
+
"""
|
|
586
|
+
wanted = tuple(dict.fromkeys(paths))
|
|
587
|
+
if not wanted or not task_id:
|
|
588
|
+
return ()
|
|
589
|
+
try:
|
|
590
|
+
# `-U0`, so only the changed lines are read: a context line naming the id belongs to
|
|
591
|
+
# a neighbour this transaction did not touch, and counting it would claim the file
|
|
592
|
+
# for whichever task happens to sit next to the one that moved.
|
|
593
|
+
listed = _run(config.root, "diff", "HEAD", "-U0", "--", *wanted)
|
|
594
|
+
except HistoryUnavailable:
|
|
595
|
+
return ()
|
|
596
|
+
found: list[str] = []
|
|
597
|
+
current = ""
|
|
598
|
+
pattern = re.compile(rf"(?<![\w-]){re.escape(task_id)}(?![\w-])")
|
|
599
|
+
for line in listed.splitlines():
|
|
600
|
+
if line.startswith("+++ b/"):
|
|
601
|
+
current = line[6:]
|
|
602
|
+
elif line[:1] in "+-" and not line.startswith(("+++", "---")) and current:
|
|
603
|
+
if pattern.search(line):
|
|
604
|
+
found.append(current)
|
|
605
|
+
current = "" # one hit settles the file; the rest of its hunks are noise
|
|
606
|
+
# Answered in the caller's order and not git's, so two runs of the same tree read alike.
|
|
607
|
+
return tuple(one for one in wanted if one in set(found))
|
|
608
|
+
|
|
609
|
+
|
|
610
|
+
def _read_status(listed: str) -> tuple[frozenset[str], frozenset[str]]:
|
|
611
|
+
"""The paths out of `status --porcelain -z`, whose records are not one per NUL.
|
|
612
|
+
|
|
613
|
+
A rename spends **two** NUL-separated fields — `R <to>\\0<from>` — so a naive split reads
|
|
614
|
+
the origin as a record and its first two characters as a status code. Both ends are
|
|
615
|
+
kept, because both are paths the commit touches.
|
|
616
|
+
|
|
617
|
+
Two sets since RK1197, from the same records: `XY` is one column per side, and the first
|
|
618
|
+
is the index. `?` is not one of them — an untracked file is in neither the index nor
|
|
619
|
+
`HEAD`, so it changes the commit and is not something the commit already carries.
|
|
620
|
+
"""
|
|
621
|
+
changed: list[str] = []
|
|
622
|
+
staged: list[str] = []
|
|
623
|
+
fields = [field for field in listed.split(_NUL) if field]
|
|
624
|
+
index = 0
|
|
625
|
+
while index < len(fields):
|
|
626
|
+
record = fields[index]
|
|
627
|
+
index += 1
|
|
628
|
+
code, _, name = record[:2], record[2:3], record[3:]
|
|
629
|
+
if not name:
|
|
630
|
+
continue
|
|
631
|
+
changed.append(name)
|
|
632
|
+
# The **origin** of a rename is staged too, and by the same record: git states one
|
|
633
|
+
# code for the pair, so both ends take it.
|
|
634
|
+
renamed = code[0] in "RC" and index < len(fields)
|
|
635
|
+
origin = fields[index] if renamed else ""
|
|
636
|
+
if renamed:
|
|
637
|
+
changed.append(origin)
|
|
638
|
+
index += 1
|
|
639
|
+
if code[0] not in " ?":
|
|
640
|
+
staged.append(name)
|
|
641
|
+
if origin:
|
|
642
|
+
staged.append(origin)
|
|
643
|
+
return frozenset(changed), frozenset(staged)
|
|
644
|
+
|
|
645
|
+
|
|
646
|
+
@dataclass(frozen=True, slots=True)
|
|
647
|
+
class Cost:
|
|
648
|
+
"""What one commit changed: lines either side, and how many files (RK71).
|
|
649
|
+
|
|
650
|
+
Both, because the two live corpora disagree about which one an author pays. Lines are
|
|
651
|
+
what varies and files are what an agent holds in context, which is the comparison the
|
|
652
|
+
"no size field" non-goal argues from — median to p90, 2.7× against 1.4×, a ratio
|
|
653
|
+
holding where the ranges it was first stated as have not (RK367). A derivation that
|
|
654
|
+
reported one would be picking the axis for the reader.
|
|
655
|
+
"""
|
|
656
|
+
|
|
657
|
+
sha: str
|
|
658
|
+
short: str
|
|
659
|
+
lines: int
|
|
660
|
+
files: int
|
|
661
|
+
|
|
662
|
+
|
|
663
|
+
def added_ids(config: Config, role: str) -> dict[str, str]:
|
|
664
|
+
"""Which commit first added each id to one governed file: id → sha, oldest wins.
|
|
665
|
+
|
|
666
|
+
One `git log -U0` over the file, not one pickaxe per id: 69 ids is 69 processes, which
|
|
667
|
+
is the difference between a query and a thing nobody runs twice. The trade is that this
|
|
668
|
+
reads *added lines* rather than asking about an id, so an id the file never carried is
|
|
669
|
+
absent here where :func:`origin_of` would say so — which is why both exist.
|
|
670
|
+
"""
|
|
671
|
+
if not config.has(role):
|
|
672
|
+
return {}
|
|
673
|
+
try:
|
|
674
|
+
relative = config.path(role).relative_to(config.root)
|
|
675
|
+
except ValueError:
|
|
676
|
+
relative = config.path(role)
|
|
677
|
+
output = _run(
|
|
678
|
+
config.root,
|
|
679
|
+
"log",
|
|
680
|
+
"--reverse",
|
|
681
|
+
f"--format={_RECORD}%H",
|
|
682
|
+
"--no-color",
|
|
683
|
+
"-U0",
|
|
684
|
+
"--",
|
|
685
|
+
str(relative),
|
|
686
|
+
)
|
|
687
|
+
# The qualifier a **partial** entry carries inside the bold span (RK121, RK1175): a search
|
|
688
|
+
# for the bare id read `**RK1169 (the withheld reasons)**` as no id at all, so every partially
|
|
689
|
+
# shipped entry was reported as one no commit accounts for — permanently, since the qualifier
|
|
690
|
+
# stays until the completing ship. Optional here for the same reason the grammar has it.
|
|
691
|
+
bold = re.compile(rf"\*\*({config.schema.id_fragment})(?: \([^)]+\))?\*\*")
|
|
692
|
+
first: dict[str, str] = {}
|
|
693
|
+
for head, rows in _records(output):
|
|
694
|
+
added = "\n".join(
|
|
695
|
+
row for row in rows if row.startswith("+") and not row.startswith("+++")
|
|
696
|
+
)
|
|
697
|
+
for task_id in bold.findall(added):
|
|
698
|
+
first.setdefault(task_id, head.strip())
|
|
699
|
+
return first
|
|
700
|
+
|
|
701
|
+
|
|
702
|
+
def ids_since(
|
|
703
|
+
config: Config, rev: str, role: str, *, resolved: bool | None = None
|
|
704
|
+
) -> frozenset[str]:
|
|
705
|
+
"""Which ids this role's file **gained or lost a line for** since ``rev`` (RK1120).
|
|
706
|
+
|
|
707
|
+
Two parses and never a diff heuristic, which is the whole of why this is decidable. RK1117
|
|
708
|
+
subtracted whole *files* a departure could explain — the roadmap is always one, because
|
|
709
|
+
the marker write that took the line is in the same diff — so another session's added line
|
|
710
|
+
rode inside the staging the report printed. What tells them apart is not that a second id
|
|
711
|
+
*appears* in the change: an annotation refresh (RK8) rewrites every dependent's deps field
|
|
712
|
+
and names those ids in added lines, so a textual reading calls half the backlog somebody
|
|
713
|
+
else's. What it is, is a line **arriving or leaving**, which only two parses can answer.
|
|
714
|
+
|
|
715
|
+
The symmetric difference and not the additions, because both directions are a second
|
|
716
|
+
session's work: a line added here is theirs, and a line removed is a ship of theirs that
|
|
717
|
+
this commit would carry. The id being committed is the caller's to exclude — it is in this
|
|
718
|
+
set on every ordinary departure, that being the line leaving.
|
|
719
|
+
|
|
720
|
+
Empty where git cannot answer or the role is not declared, the rule every reader here
|
|
721
|
+
keeps: a report is worth less than a session, and this feeds a report. :func:`resolves` is
|
|
722
|
+
asked first and not left to the read below, because the two silences differ in the one way
|
|
723
|
+
that matters here: :func:`content_at` answers `""` both for a file a revision did not carry
|
|
724
|
+
and for a revision that does not exist, and comparing a *whole backlog* against nothing
|
|
725
|
+
reports every id in it as newly arrived — which on a directory that is not a repository is
|
|
726
|
+
every line the project has.
|
|
727
|
+
|
|
728
|
+
``resolved`` is that answer where the caller already has it (RK1124). Whether git knows a
|
|
729
|
+
revision is a fact about the **repository**, and asking it per role made a caller looping
|
|
730
|
+
over the carriers pay a `rev-parse` for something in hand: measured at 20.6ms each, 85.6ms
|
|
731
|
+
for the pair this repository declares, against the 43ms floor RK176 set for a whole
|
|
732
|
+
session-start read. A parameter and not a cache, the shape `plan(gauging=…)` already uses
|
|
733
|
+
for the one expensive question a caller may decline — a cache keyed on a revision would be
|
|
734
|
+
a second reader of git state with its own staleness, in a module that stores nothing.
|
|
735
|
+
"""
|
|
736
|
+
if not config.has(role):
|
|
737
|
+
return frozenset()
|
|
738
|
+
if not (resolves(config, rev) if resolved is None else resolved):
|
|
739
|
+
return frozenset()
|
|
740
|
+
schema = config.schema_for(role)
|
|
741
|
+
try:
|
|
742
|
+
before = Document.parse(content_at(config, rev, role), schema=schema)
|
|
743
|
+
now = config.document(role)
|
|
744
|
+
except (HistoryUnavailable, OSError, ValueError):
|
|
745
|
+
return frozenset()
|
|
746
|
+
return frozenset(before.by_id()) ^ frozenset(now.by_id())
|
|
747
|
+
|
|
748
|
+
|
|
749
|
+
def designs_since(
|
|
750
|
+
config: Config, rev: str, role: str, *, resolved: bool | None = None
|
|
751
|
+
) -> frozenset[str]:
|
|
752
|
+
"""Which designs this prose role's file **gained or lost a section for** since ``rev``.
|
|
753
|
+
|
|
754
|
+
:func:`ids_since`'s unit one file over (RK1125). A rationale file holds no task lines, so
|
|
755
|
+
that reading answers nothing about it — and the file a departure *wrote* is exactly where
|
|
756
|
+
the silence hurt: one `section amend` earlier in the session puts this id in the diff, the
|
|
757
|
+
file is then accounted for, and another session's new `### §RK-B` rides into the staging
|
|
758
|
+
with nothing said. That is RK1117's defect and RK1120's fix, in the other unit.
|
|
759
|
+
|
|
760
|
+
Labelled by the **id the heading names** where it names one, and by the anchor otherwise.
|
|
761
|
+
Under the id scheme those are the same string; under an outline the anchor is `XVI.12` and
|
|
762
|
+
the id lives in the title, so a label read off the anchor alone would report an address the
|
|
763
|
+
reader then has to resolve. :meth:`~roadkeep.sections.Section.names` is that reading and it
|
|
764
|
+
is the title's alone — a section quoting another id is discussing it, not being it.
|
|
765
|
+
|
|
766
|
+
Two consequences worth stating, and both are the roadmap's reading in this unit. A section
|
|
767
|
+
this project *moved* keeps its id, so it is not reported — the design did not arrive or
|
|
768
|
+
leave, its address changed, which is what `section move` is for. And a **subsection added
|
|
769
|
+
under a design that already existed** is that design changing rather than arriving, so it is
|
|
770
|
+
not reported either: exactly as an amended task line is not an id arriving on the roadmap
|
|
771
|
+
(RK1120), and for the same reason — this answers which work is in the file, not which
|
|
772
|
+
paragraph somebody edited.
|
|
773
|
+
"""
|
|
774
|
+
if role not in PROSE_ROLES or not config.has(role):
|
|
775
|
+
return frozenset()
|
|
776
|
+
if not (resolves(config, rev) if resolved is None else resolved):
|
|
777
|
+
return frozenset()
|
|
778
|
+
schema = config.schema_for(role)
|
|
779
|
+
try:
|
|
780
|
+
before = anchored(Document.parse(content_at(config, rev, role), schema=schema))
|
|
781
|
+
now = anchored(config.document(role))
|
|
782
|
+
except (HistoryUnavailable, OSError, ValueError):
|
|
783
|
+
return frozenset()
|
|
784
|
+
ids = config.schema.id_pattern()
|
|
785
|
+
return _labels(before, ids) ^ _labels(now, ids)
|
|
786
|
+
|
|
787
|
+
|
|
788
|
+
def owned_edit(config: Config, rev: str, task_id: str, role: str) -> bool:
|
|
789
|
+
"""Whether this tree's changes to a prose file are inside a section this id owns (RK1126).
|
|
790
|
+
|
|
791
|
+
The reading :func:`carrying` cannot make. It credits a path where an added or removed line
|
|
792
|
+
**names the id**, which on a rationale file means a heading — so `section amend <id>
|
|
793
|
+
--body` rewrites the paragraph under one, touches no line carrying the id, and the file the
|
|
794
|
+
author just edited came back as `loose (no claim names it)`. RK1117's sentence pointed at
|
|
795
|
+
the author's own work, and RK342's defect from the other side: withholding a path is as
|
|
796
|
+
wrong as handing it over, because the answer is then declared by hand and the scope carries
|
|
797
|
+
what was never the work.
|
|
798
|
+
|
|
799
|
+
Additions are read against the file **now** and removals against the file at ``rev``, which
|
|
800
|
+
is RK36's split and the reason this is not one span lookup: a deleted paragraph's line
|
|
801
|
+
numbers are the old file's, and judging them against the current parse attributes them to
|
|
802
|
+
whichever section now sits over the hole. :func:`~roadkeep.sections.owners` decides
|
|
803
|
+
ownership so the outline case answers too — there the id is in the heading's title and a
|
|
804
|
+
sub-anchor belongs to the id its first segment spells.
|
|
805
|
+
|
|
806
|
+
A blank line belongs to no section's prose, exactly as the gate reads it: counting one
|
|
807
|
+
would credit a file for the trailing newline of somebody else's paragraph.
|
|
808
|
+
"""
|
|
809
|
+
if role not in PROSE_ROLES or not config.has(role):
|
|
810
|
+
return False
|
|
811
|
+
ids = config.schema.id_pattern()
|
|
812
|
+
try:
|
|
813
|
+
edited = touched_since(config, rev, role)
|
|
814
|
+
now = anchored(config.document(role))
|
|
815
|
+
before = anchored(
|
|
816
|
+
Document.parse(content_at(config, rev, role), schema=config.schema_for(role))
|
|
817
|
+
)
|
|
818
|
+
except (HistoryUnavailable, OSError, ValueError):
|
|
819
|
+
return False
|
|
820
|
+
for change in edited.changes:
|
|
821
|
+
if not change.text.strip():
|
|
822
|
+
continue
|
|
823
|
+
for section in now if change.added else before:
|
|
824
|
+
if section.first <= change.lineno <= section.last and task_id in owners(
|
|
825
|
+
section, ids
|
|
826
|
+
):
|
|
827
|
+
return True
|
|
828
|
+
return False
|
|
829
|
+
|
|
830
|
+
|
|
831
|
+
def _labels(sections: Sequence[Section], ids: re.Pattern[str]) -> frozenset[str]:
|
|
832
|
+
"""Each section as **the task it belongs to**, or as its anchor where it belongs to none.
|
|
833
|
+
|
|
834
|
+
:func:`~roadkeep.sections.owners` and not a second reading of a heading (RK1127). Labelling
|
|
835
|
+
by the ids a *title* names left a sub-anchor labelled by its own address: `§RK2.1` is `RK2`'s
|
|
836
|
+
subsection and the anchor says so segment by segment, so the exclusion `- {task_id}` did not
|
|
837
|
+
remove it and a departure reported the design being shipped as somebody else's. `owners`
|
|
838
|
+
already answers this for the gate and for the drop — under the id scheme the anchor is the
|
|
839
|
+
id and a sub-anchor is its root's, and under an outline the id is in the title — so the one
|
|
840
|
+
thing left here is the fallback: a section belonging to no task is labelled by the anchor,
|
|
841
|
+
which is the only handle a reader has on prose that is nobody's.
|
|
842
|
+
"""
|
|
843
|
+
out: set[str] = set()
|
|
844
|
+
for section in sections:
|
|
845
|
+
out.update(owners(section, ids) or (section.anchor,))
|
|
846
|
+
return frozenset(out)
|
|
847
|
+
|
|
848
|
+
|
|
849
|
+
def costs_of(config: Config, shas: tuple[str, ...]) -> dict[str, Cost]:
|
|
850
|
+
"""The size of each named commit, across every file it touched, in one call.
|
|
851
|
+
|
|
852
|
+
`--no-walk`, so the list is the commit list and not a range: the commits that wrote a
|
|
853
|
+
ledger entry are scattered through history and a range would count what sits between
|
|
854
|
+
them. A binary file's numstat is `-`, and it counts as a file and no lines.
|
|
855
|
+
|
|
856
|
+
And the list arrives on **stdin** (RK1315), which is the one thing about this call that
|
|
857
|
+
is not free to be argv: as arguments it is bounded by the operating system, and this
|
|
858
|
+
repository crossed Windows' ceiling at 798 commits — 32,718 characters of shas, against
|
|
859
|
+
32,767 — so the read failed on size rather than on history. `--stdin` and not batching,
|
|
860
|
+
because batching trades the property stated above, *two git calls whatever the size of
|
|
861
|
+
the ledger*, for a number of calls that grows with the file.
|
|
862
|
+
"""
|
|
863
|
+
if not shas:
|
|
864
|
+
return {}
|
|
865
|
+
output = _run(
|
|
866
|
+
config.root,
|
|
867
|
+
"log",
|
|
868
|
+
"--no-walk",
|
|
869
|
+
f"--format={_RECORD}{_UNIT.join(['%H', '%h'])}",
|
|
870
|
+
"--numstat",
|
|
871
|
+
"--stdin",
|
|
872
|
+
fed=shas,
|
|
873
|
+
)
|
|
874
|
+
out: dict[str, Cost] = {}
|
|
875
|
+
for head, rows in _records(output):
|
|
876
|
+
sha, _, short = head.partition(_UNIT)
|
|
877
|
+
counted = [
|
|
878
|
+
changed for changed in (_numstat(row) for row in rows) if changed is not None
|
|
879
|
+
]
|
|
880
|
+
out[sha] = Cost(
|
|
881
|
+
sha=sha, short=short or sha[:7], lines=sum(counted), files=len(counted)
|
|
882
|
+
)
|
|
883
|
+
return out
|
|
884
|
+
|
|
885
|
+
|
|
886
|
+
def _numstat(row: str) -> int | None:
|
|
887
|
+
"""One numstat row as the lines it changed, or None when the row is not one.
|
|
888
|
+
|
|
889
|
+
A binary file reports `-` for both sides: it is a file that changed and no lines that
|
|
890
|
+
did, which is what the caller counts it as rather than dropping it.
|
|
891
|
+
"""
|
|
892
|
+
columns = row.split("\t")
|
|
893
|
+
if len(columns) != 3:
|
|
894
|
+
return None
|
|
895
|
+
added, removed = columns[0], columns[1]
|
|
896
|
+
return (int(added) if added.isdigit() else 0) + (
|
|
897
|
+
int(removed) if removed.isdigit() else 0
|
|
898
|
+
)
|
|
899
|
+
|
|
900
|
+
|
|
901
|
+
def _records(output: str) -> tuple[tuple[str, tuple[str, ...]], ...]:
|
|
902
|
+
"""Split a `--format=<record>…` log into (head line, following rows) pairs.
|
|
903
|
+
|
|
904
|
+
The record separator and not newlines, for :data:`_FORMAT`'s reason: a subject or a diff
|
|
905
|
+
line can hold anything, so only a byte no message carries can end a record.
|
|
906
|
+
"""
|
|
907
|
+
out: list[tuple[str, tuple[str, ...]]] = []
|
|
908
|
+
for record in output.split(_RECORD):
|
|
909
|
+
rows = record.strip("\n").splitlines()
|
|
910
|
+
if rows:
|
|
911
|
+
out.append((rows[0], tuple(rows[1:])))
|
|
912
|
+
return tuple(out)
|
|
913
|
+
|
|
914
|
+
|
|
915
|
+
def origin_of(config: Config, task_id: str) -> Origin:
|
|
916
|
+
"""The commit that proposed the task and the one that shipped it, if each exists."""
|
|
917
|
+
needle = f"**{task_id}**" # the bold id, so RK1 does not match RK10
|
|
918
|
+
proposed = _first_touching(config, needle, "roadmap")
|
|
919
|
+
shipped = _first_touching(config, needle, "changelog")
|
|
920
|
+
return Origin(task_id=task_id, proposed_in=proposed, shipped_in=shipped)
|
|
921
|
+
|
|
922
|
+
|
|
923
|
+
|
|
924
|
+
@dataclass(frozen=True, slots=True)
|
|
925
|
+
class Pending:
|
|
926
|
+
"""One open line, and the commits whose message already names it (RK1201).
|
|
927
|
+
|
|
928
|
+
Not "the work is done" — which of a task's commits completed it is a judgement, and this
|
|
929
|
+
tool has no model of one (L4). What this holds is the two facts a reader needs to decide:
|
|
930
|
+
the line is open, and something in the history says otherwise.
|
|
931
|
+
"""
|
|
932
|
+
|
|
933
|
+
id: str
|
|
934
|
+
marker: str
|
|
935
|
+
block: str
|
|
936
|
+
#: The commits naming this id, newest first. Read from the **message** and not from a
|
|
937
|
+
#: file's history: `origin` asks which commit touched the roadmap at this id, which is
|
|
938
|
+
#: about the *line*, and the question here is about the work.
|
|
939
|
+
commits: tuple[Commit, ...] = ()
|
|
940
|
+
#: Whether the ledger already holds an entry for it — true on a partial (RK121), which is
|
|
941
|
+
#: the state this deliberately does not report: a half recorded and a line still open is
|
|
942
|
+
#: exactly what a partial is, and reporting it would be reporting the feature.
|
|
943
|
+
recorded: bool = False
|
|
944
|
+
|
|
945
|
+
@property
|
|
946
|
+
def stale(self) -> bool:
|
|
947
|
+
return bool(self.commits) and not self.recorded
|
|
948
|
+
|
|
949
|
+
|
|
950
|
+
def pending(config: Config) -> tuple[Pending, ...]:
|
|
951
|
+
"""Every open line with commits naming it and no ledger entry (RK1201).
|
|
952
|
+
|
|
953
|
+
One `git log` for the whole backlog rather than one per id: the ids are matched against the
|
|
954
|
+
subjects that come back, so a backlog of forty costs the same read as a backlog of one.
|
|
955
|
+
|
|
956
|
+
Empty where git cannot answer, the rule every reader here keeps — a checkout with no git is
|
|
957
|
+
one this reports nothing about, never one it refuses.
|
|
958
|
+
"""
|
|
959
|
+
from roadkeep.backlog import Backlog # noqa: PLC0415 - RK260
|
|
960
|
+
|
|
961
|
+
backlog = Backlog.load(config)
|
|
962
|
+
open_lines = list(backlog.roadmap.entries)
|
|
963
|
+
if not open_lines:
|
|
964
|
+
return ()
|
|
965
|
+
recorded = (
|
|
966
|
+
{entry.task.id for entry in backlog.ledger.entries}
|
|
967
|
+
if backlog.ledger is not None
|
|
968
|
+
else set()
|
|
969
|
+
)
|
|
970
|
+
try:
|
|
971
|
+
# The module's own format and its own parser (RK1201): a second spelling of a commit
|
|
972
|
+
# here would be a second thing to keep true, and the one already there carries every
|
|
973
|
+
# field this needs.
|
|
974
|
+
listed = _parse(_run(config.root, "log", "--no-merges", f"--format={_FORMAT}"))
|
|
975
|
+
except HistoryUnavailable:
|
|
976
|
+
return ()
|
|
977
|
+
from roadkeep.ids import id_scanner # noqa: PLC0415 - RK260
|
|
978
|
+
|
|
979
|
+
naming: dict[str, list[Commit]] = {}
|
|
980
|
+
# The **scanner** and not `id_pattern` (RK106): one matches an id as a whole string and the
|
|
981
|
+
# other finds one inside running text, which is what a commit subject is.
|
|
982
|
+
pattern = id_scanner(config.schema)
|
|
983
|
+
for commit in listed:
|
|
984
|
+
for token in {found.group(0) for found in pattern.finditer(commit.subject)}:
|
|
985
|
+
naming.setdefault(token, []).append(commit)
|
|
986
|
+
|
|
987
|
+
# **The oldest commit naming an id is the one that filed it**, and it is dropped: `add` is
|
|
988
|
+
# what mints an id, so nothing could name one before the line existed. Measured before this
|
|
989
|
+
# was written — without it the sweep reported seven lines and every one was its own filing,
|
|
990
|
+
# where `docs: file RK1196` names the id and means the opposite of what the report said.
|
|
991
|
+
#
|
|
992
|
+
# Read off the log already in hand rather than by asking `origin` per id, which is the same
|
|
993
|
+
# answer at one git call per open line. A **promise** (RK431) is the one shape this reads as
|
|
994
|
+
# work: an id a sentence named before the line existed leaves the filing as the newest of
|
|
995
|
+
# two, which errs toward reporting — the safe direction for a report.
|
|
996
|
+
for named in naming.values():
|
|
997
|
+
named.pop()
|
|
998
|
+
|
|
999
|
+
return tuple(
|
|
1000
|
+
Pending(
|
|
1001
|
+
id=entry.task.id,
|
|
1002
|
+
marker=entry.task.status,
|
|
1003
|
+
block=entry.task.block,
|
|
1004
|
+
commits=tuple(naming.get(entry.task.id, ())),
|
|
1005
|
+
recorded=entry.task.id in recorded,
|
|
1006
|
+
)
|
|
1007
|
+
for entry in open_lines
|
|
1008
|
+
)
|
|
1009
|
+
|
|
1010
|
+
|
|
1011
|
+
#: What one `git log` line carries, separated by a NUL. A NUL cannot appear in a subject,
|
|
1012
|
+
#: which is what makes splitting safe where a subject may hold anything else — and it is
|
|
1013
|
+
#: spelled `%x00` because an argv may not carry one: Windows refuses the process outright.
|
|
1014
|
+
|
|
1015
|
+
|
|
1016
|
+
@dataclass(frozen=True, slots=True)
|
|
1017
|
+
class Unclosed:
|
|
1018
|
+
"""The sweep as one answer: which open lines the history already speaks for (RK1201).
|
|
1019
|
+
|
|
1020
|
+
**A report and never a refusal.** The honest reading of a line with commits is sometimes
|
|
1021
|
+
"the work is under way and these are partial", which is what a partial entry is for — so
|
|
1022
|
+
this states the fact and leaves the verdict where it belongs.
|
|
1023
|
+
"""
|
|
1024
|
+
|
|
1025
|
+
rows: tuple[Pending, ...] = ()
|
|
1026
|
+
#: True where git answered at all. `()` means two different things otherwise, and a
|
|
1027
|
+
#: checkout with no history reading as a clean backlog is the silence RK10 is about.
|
|
1028
|
+
searched: bool = True
|
|
1029
|
+
|
|
1030
|
+
@property
|
|
1031
|
+
def stale(self) -> tuple[Pending, ...]:
|
|
1032
|
+
return tuple(one for one in self.rows if one.stale)
|
|
1033
|
+
|
|
1034
|
+
def stated(self) -> str:
|
|
1035
|
+
if not self.searched:
|
|
1036
|
+
return "no history to read, so nothing here says whether a line was left open"
|
|
1037
|
+
found = self.stale
|
|
1038
|
+
rows = [
|
|
1039
|
+
f"{len(found)} of {len(self.rows)} open line(s) already have commits naming them"
|
|
1040
|
+
]
|
|
1041
|
+
for one in found:
|
|
1042
|
+
named = ", ".join(commit.short for commit in one.commits[:3])
|
|
1043
|
+
more = f" and {len(one.commits) - 3} more" if len(one.commits) > 3 else ""
|
|
1044
|
+
rows.append(
|
|
1045
|
+
f" {one.marker} {one.id:<8} Block {one.block:<3} {named}{more}"
|
|
1046
|
+
)
|
|
1047
|
+
if found:
|
|
1048
|
+
# The door, as every finding this tool prints carries one (RK420): what closes a
|
|
1049
|
+
# line is `ship`, and what closes it *honestly* where only half landed is `--part`.
|
|
1050
|
+
rows.append(
|
|
1051
|
+
" close `ship <id> --why …` records the outcome, or `--part` where only "
|
|
1052
|
+
"half of it landed"
|
|
1053
|
+
)
|
|
1054
|
+
return chr(10).join(rows)
|
|
1055
|
+
|
|
1056
|
+
def payload(self) -> dict[str, object]:
|
|
1057
|
+
return {
|
|
1058
|
+
"searched": self.searched,
|
|
1059
|
+
"open": len(self.rows),
|
|
1060
|
+
"unclosed": [
|
|
1061
|
+
{
|
|
1062
|
+
"id": one.id,
|
|
1063
|
+
"marker": one.marker,
|
|
1064
|
+
"block": one.block,
|
|
1065
|
+
"recorded": one.recorded,
|
|
1066
|
+
"commits": [
|
|
1067
|
+
{"sha": commit.sha, "short": commit.short, "subject": commit.subject}
|
|
1068
|
+
for commit in one.commits
|
|
1069
|
+
],
|
|
1070
|
+
}
|
|
1071
|
+
for one in self.stale
|
|
1072
|
+
],
|
|
1073
|
+
}
|
|
1074
|
+
|
|
1075
|
+
|
|
1076
|
+
@dataclass(frozen=True, slots=True)
|
|
1077
|
+
class Cited:
|
|
1078
|
+
"""An anchor somebody's prose still names, resolved against history (RK212)."""
|
|
1079
|
+
|
|
1080
|
+
anchor: str
|
|
1081
|
+
#: The prose role the address was searched in, and the commits at each end.
|
|
1082
|
+
role: str
|
|
1083
|
+
written_in: Commit | None
|
|
1084
|
+
removed_in: Commit | None
|
|
1085
|
+
#: Whether the log that came back empty was a log worth trusting — :class:`Gap`'s split.
|
|
1086
|
+
searched: bool = False
|
|
1087
|
+
|
|
1088
|
+
@property
|
|
1089
|
+
def live(self) -> bool:
|
|
1090
|
+
"""Written and never removed: the section is still there and this is a live cite."""
|
|
1091
|
+
return self.written_in is not None and self.removed_in is None
|
|
1092
|
+
|
|
1093
|
+
def stated(self, where: str, *, why: bool = False) -> str:
|
|
1094
|
+
"""Where the design behind this citation went, as the reader is told it (RK212).
|
|
1095
|
+
|
|
1096
|
+
Beside :meth:`payload` since RK1170: these two were a printer inside the handler and a
|
|
1097
|
+
builder in the same function, so one answer had two spellings and the file that holds the
|
|
1098
|
+
fact held neither. `where` is passed rather than stored — the role is the fact and how a
|
|
1099
|
+
project spells that file is the caller's (RK75).
|
|
1100
|
+
|
|
1101
|
+
The absences are three different answers and never one (RK95): a history nobody could
|
|
1102
|
+
search, a history searched to the root that never saw the address — which is what a typo
|
|
1103
|
+
looks like — and an address still in the file, where the citation simply resolves.
|
|
1104
|
+
"""
|
|
1105
|
+
if not self.searched:
|
|
1106
|
+
return f"§{self.anchor}: no history to resolve against"
|
|
1107
|
+
if self.written_in is None:
|
|
1108
|
+
return f"§{self.anchor}: searched {where} to the root and nothing ever wrote it"
|
|
1109
|
+
rows = [
|
|
1110
|
+
f"§{self.anchor} in {where}",
|
|
1111
|
+
f" written {self.written_in.short} {self.written_in.date[:10]} "
|
|
1112
|
+
f"{self.written_in.subject}",
|
|
1113
|
+
]
|
|
1114
|
+
if self.removed_in is None:
|
|
1115
|
+
rows.append(" removed — the section is still there, so the citation resolves")
|
|
1116
|
+
else:
|
|
1117
|
+
rows.append(
|
|
1118
|
+
f" removed {self.removed_in.short} {self.removed_in.date[:10]} "
|
|
1119
|
+
f"{self.removed_in.subject}"
|
|
1120
|
+
)
|
|
1121
|
+
if why:
|
|
1122
|
+
# The commit's own reasoning, only where it was asked for: it is the one field
|
|
1123
|
+
# here that is a paragraph, and a read that always printed it would be a read
|
|
1124
|
+
# nobody puts in a loop.
|
|
1125
|
+
rows += ["", self.removed_in.reasoning]
|
|
1126
|
+
return "\n".join(rows)
|
|
1127
|
+
|
|
1128
|
+
def payload(self, *, whole: bool = True) -> dict[str, object]:
|
|
1129
|
+
"""The same answer as data, with each end null where history answered nothing.
|
|
1130
|
+
|
|
1131
|
+
`whole` keeps the commit's message: a caller asking about an address is asking about
|
|
1132
|
+
those two commits, so the body is the answer here rather than a paragraph riding along.
|
|
1133
|
+
"""
|
|
1134
|
+
|
|
1135
|
+
def commit(one: Commit | None) -> dict[str, str] | None:
|
|
1136
|
+
if one is None:
|
|
1137
|
+
return None
|
|
1138
|
+
said = {
|
|
1139
|
+
"sha": one.sha,
|
|
1140
|
+
"short": one.short,
|
|
1141
|
+
"date": one.date,
|
|
1142
|
+
"subject": one.subject,
|
|
1143
|
+
}
|
|
1144
|
+
return {**said, "body": one.body} if whole else said
|
|
1145
|
+
|
|
1146
|
+
return {
|
|
1147
|
+
"anchor": self.anchor,
|
|
1148
|
+
"role": self.role,
|
|
1149
|
+
"searched": self.searched,
|
|
1150
|
+
"written": commit(self.written_in),
|
|
1151
|
+
"removed": commit(self.removed_in),
|
|
1152
|
+
}
|
|
1153
|
+
|
|
1154
|
+
|
|
1155
|
+
def cited_origin(config: Config, anchor: str) -> Cited:
|
|
1156
|
+
"""Where the design behind a dangling citation was written, and what took it away.
|
|
1157
|
+
|
|
1158
|
+
The half of RK206 a verb cannot reach. `ship` names the sections left citing what it
|
|
1159
|
+
deleted, at the moment it deletes it; a reader meeting `§XVIII.12` a year later has no
|
|
1160
|
+
such moment, and the files hold no answer — `as_ledger` keeps no pointer, so nothing
|
|
1161
|
+
records which anchor a shipped design had.
|
|
1162
|
+
|
|
1163
|
+
Measured before choosing this over a gate: 37 such references across this repository,
|
|
1164
|
+
claude-tray, Shio and Turing, and 36 of them are in `ref_scheme = "outline"` projects
|
|
1165
|
+
where the anchor carries no id at all. A finding would fail four files whose prose is
|
|
1166
|
+
correct; a *note* would be 28 of them in one Turing report, which is the output nobody
|
|
1167
|
+
reads that this project refuses elsewhere (RK16). So the answer is a question instead
|
|
1168
|
+
(L5) — it costs nothing until somebody meets the reference and asks.
|
|
1169
|
+
|
|
1170
|
+
Both ends, because they are different facts: the commit that *wrote* the section says
|
|
1171
|
+
what the design was, and the one that *removed* it says which task took it. `-G` finds
|
|
1172
|
+
both (:func:`commits_touching`), so a history that cannot be searched answers neither —
|
|
1173
|
+
reported as :attr:`searched` rather than as an anchor nobody ever wrote, which is
|
|
1174
|
+
:class:`Gap`'s split and made for the same reason.
|
|
1175
|
+
"""
|
|
1176
|
+
# The **heading**, not the citation. `§RK15` alone matches every commit that touched
|
|
1177
|
+
# somebody's prose about it, so the last one was RK206's ship — which deleted a
|
|
1178
|
+
# sentence citing §RK15 and never went near the section. `anchor_text` is the one
|
|
1179
|
+
# place a heading's spelling is decided (RK44), so the two schemes agree here for
|
|
1180
|
+
# free, and the trailing space keeps `§RK1` from answering for `§RK15`.
|
|
1181
|
+
# Grouped, not `§?`: git matches bytes, so an unparenthesised `?` would make the
|
|
1182
|
+
# *second* byte of the two-byte sigil optional and the pattern would match neither
|
|
1183
|
+
# spelling. Two live outline projects disagree about the sigil in a heading — Shio and
|
|
1184
|
+
# Turing write `### VIII.1`, claude-tray writes `### §I.1` and `### XVIII.12` in the
|
|
1185
|
+
# same file — so both are admitted, and the trailing space keeps `§I.1` from answering
|
|
1186
|
+
# for `§I.12`.
|
|
1187
|
+
needle = "# (§)?" + re.escape(anchor) + " "
|
|
1188
|
+
for role in ("improvements", "strategy"):
|
|
1189
|
+
if not config.has(role):
|
|
1190
|
+
continue
|
|
1191
|
+
try:
|
|
1192
|
+
found = _touching_role(config, needle, role, literal=False)
|
|
1193
|
+
except HistoryUnavailable:
|
|
1194
|
+
return Cited(anchor=anchor, role=role, written_in=None, removed_in=None)
|
|
1195
|
+
if not found:
|
|
1196
|
+
continue
|
|
1197
|
+
# Oldest first (`--reverse`), so the first wrote it. The last removed it only if
|
|
1198
|
+
# the address is gone now: a section still in the file has a last commit that
|
|
1199
|
+
# edited it, and calling that a removal would invent a deletion nobody made.
|
|
1200
|
+
gone = find(config.document(role), anchor) is None if config.path(role).is_file() else True
|
|
1201
|
+
return Cited(
|
|
1202
|
+
anchor=anchor,
|
|
1203
|
+
role=role,
|
|
1204
|
+
written_in=found[0],
|
|
1205
|
+
removed_in=found[-1] if gone else None,
|
|
1206
|
+
searched=True,
|
|
1207
|
+
)
|
|
1208
|
+
return Cited(anchor=anchor, role=PROSE_ROLES[0], written_in=None, removed_in=None, searched=True)
|
|
1209
|
+
|
|
1210
|
+
|
|
1211
|
+
@dataclass(frozen=True, slots=True)
|
|
1212
|
+
class Anchor:
|
|
1213
|
+
"""One outline address a prose file declares, or used to (RK247)."""
|
|
1214
|
+
|
|
1215
|
+
anchor: str
|
|
1216
|
+
role: str
|
|
1217
|
+
#: Whether a heading declares it *now*. False is retired: the section was deleted by a
|
|
1218
|
+
#: ship or a retirement, and every entry whose prose cited it still says `§<anchor>`.
|
|
1219
|
+
live: bool
|
|
1220
|
+
#: The first commit that wrote the heading, where history reaches it — a file older than
|
|
1221
|
+
#: the clone has live anchors nothing here can date, and that is not a state to hide.
|
|
1222
|
+
written_in: str = ""
|
|
1223
|
+
#: The task the **heading** names, or `""` where it names none (RK453). Under an outline
|
|
1224
|
+
#: that id is the ownership (RK262), and until this read it was visible only as `ship`'s
|
|
1225
|
+
#: `kept` field scrolling past. Empty on a retired anchor, which has no heading left.
|
|
1226
|
+
binds: str = ""
|
|
1227
|
+
#: Every **live line** pointing at this address, roadmap and deferred store, in the order
|
|
1228
|
+
#: those files hold them. Two facts and not one, because they come apart in both
|
|
1229
|
+
#: directions and each way is a different thing to do: a heading binding nobody that a
|
|
1230
|
+
#: line claims is RK452's write left undone on a corpus that predates it, and one binding
|
|
1231
|
+
#: a task no live line claims is prose whose task has shipped — what `ship` reports once
|
|
1232
|
+
#: and no reader has held since.
|
|
1233
|
+
claimed: tuple[str, ...] = ()
|
|
1234
|
+
|
|
1235
|
+
@property
|
|
1236
|
+
def memo(self) -> bool:
|
|
1237
|
+
"""A live heading that names no task and that no open line claims (RK461).
|
|
1238
|
+
|
|
1239
|
+
The third state, and the one that is never a thing to do. RK236 settled that a
|
|
1240
|
+
heading naming no task is prose belonging to none, which a standing memo genuinely
|
|
1241
|
+
is — Turing's GEO memo is the case it was decided for, and this repository's own `§0`
|
|
1242
|
+
to `§0.4` are five more. Nothing closes it, because nothing is open.
|
|
1243
|
+
|
|
1244
|
+
Named so the two states that *are* actionable can be told from it: reported beside
|
|
1245
|
+
them, it was five of the five rows this project's audit printed, and a list whose
|
|
1246
|
+
majority is noise is what teaches somebody to stop reading a report.
|
|
1247
|
+
"""
|
|
1248
|
+
return self.live and not self.binds and not self.claimed
|
|
1249
|
+
|
|
1250
|
+
@property
|
|
1251
|
+
def orphaned(self) -> bool:
|
|
1252
|
+
"""A live heading bound to a task no open line claims — prose whose task has left.
|
|
1253
|
+
|
|
1254
|
+
`binds` and not only the absence of a claimant (RK461): without it this was true of a
|
|
1255
|
+
memo too, which was never anybody's and so cannot have been left. Still not a
|
|
1256
|
+
violation, for RK236's reason; it is a fact this read states and the gate stays out of.
|
|
1257
|
+
"""
|
|
1258
|
+
return self.live and bool(self.binds) and not self.claimed
|
|
1259
|
+
|
|
1260
|
+
|
|
1261
|
+
def anchors(config: Config, role: str = "", family: str = "") -> tuple[Anchor, ...]:
|
|
1262
|
+
"""Every anchor this **project** declares or ever declared, in outline order (RK247).
|
|
1263
|
+
|
|
1264
|
+
The read `section add` could not make. Its refusals list the anchors that **exist**, so
|
|
1265
|
+
after a fully-shipped family that is none of them and the next free number looks like
|
|
1266
|
+
`.1` — while the ledger entries whose prose cited `.1` are still in the file, addressing
|
|
1267
|
+
a section that will now say something else. Observed on a project where §XXXVII.1 to
|
|
1268
|
+
§XXXVII.16 were all retired and all still cited, and the safe number was found by
|
|
1269
|
+
grepping the ledger by hand.
|
|
1270
|
+
|
|
1271
|
+
So the source is the diff and not the file: an anchor is *used* once a heading declared
|
|
1272
|
+
it, and `ship` deleting that heading does not give the address back — the same rule
|
|
1273
|
+
`add` applies to ids, where retired-never-reused is the roadmap's own property. One
|
|
1274
|
+
`git log -U0` over the file, on :func:`added_ids`' reasoning: one process, not one
|
|
1275
|
+
pickaxe per anchor.
|
|
1276
|
+
|
|
1277
|
+
Both sides of the diff are read. An anchor added before the clone's history and removed
|
|
1278
|
+
inside it appears only as a **removed** line, and that is exactly the retired address
|
|
1279
|
+
this exists to name; a live one the log cannot reach is still reported, off the file,
|
|
1280
|
+
with no commit to point at.
|
|
1281
|
+
|
|
1282
|
+
``family`` narrows to one subtree by segments — `XXXVII` gives `XXXVII.1` and
|
|
1283
|
+
`XXXVII.1.a` and never `XXXVIII.1`, the care :func:`~roadkeep.sections._extends` takes
|
|
1284
|
+
about where an anchor ends. Empty is the whole file.
|
|
1285
|
+
|
|
1286
|
+
**Every declared prose role, unless ``role`` names one** (RK297). An address is spent
|
|
1287
|
+
once a heading used it, and a project declaring two files has one outline across both:
|
|
1288
|
+
reading the first alone answered `IX.5` on a project whose sibling file had spent to
|
|
1289
|
+
`IX.12`, so the read made to avoid spending an address twice handed back one already
|
|
1290
|
+
taken — and writing it is the doubled anchor `ref.ambiguous` reports at both headings.
|
|
1291
|
+
The direction `_pointers` took at RK172, one read over. ``role`` stays as the narrower
|
|
1292
|
+
question, and it narrows the *listing*: :func:`next_child` and :func:`next_family` are
|
|
1293
|
+
taken over whatever they are handed, so a caller that means the free address hands them
|
|
1294
|
+
the project.
|
|
1295
|
+
"""
|
|
1296
|
+
roles = (role,) if role else PROSE_ROLES
|
|
1297
|
+
found = [
|
|
1298
|
+
one
|
|
1299
|
+
for name in roles
|
|
1300
|
+
if config.has(name)
|
|
1301
|
+
for one in _role_anchors(config, name)
|
|
1302
|
+
]
|
|
1303
|
+
found += _spent_by_departure(config, roles, found)
|
|
1304
|
+
# Whether this file numbers in Roman is a fact about the whole set (RK293), so it is
|
|
1305
|
+
# settled once here and handed to the key — a per-segment decision would read `C` as 100
|
|
1306
|
+
# in a file whose families are letters, and sort a listing by an arithmetic nobody meant.
|
|
1307
|
+
# The namespace is not part of the numbering (RK340): `S:IX` spells nine in Roman, and a
|
|
1308
|
+
# set read with the prefix on it would answer "no numerals here" and sort as text.
|
|
1309
|
+
numbered = bool(found) and all(numeral(_family_of(one.anchor)) for one in found)
|
|
1310
|
+
wanted = [_claimed(config, one) for one in found if _within(one.anchor, family)]
|
|
1311
|
+
# The role breaks the tie, so an address two files declare comes out as two adjacent
|
|
1312
|
+
# rows in `[files]` order — which is the doubling, reported rather than collapsed.
|
|
1313
|
+
return tuple(sorted(wanted, key=lambda one: (_ordinal(one, numbered), one.role)))
|
|
1314
|
+
|
|
1315
|
+
|
|
1316
|
+
def _claimed(config: Config, anchor: Anchor) -> Anchor:
|
|
1317
|
+
"""Fill in who binds this address and who points at it (RK453).
|
|
1318
|
+
|
|
1319
|
+
RK452 stops the unbound heading being created and does not reach the corpora already
|
|
1320
|
+
holding one — and no command listed them, so the fixture's §I.1 was found by reading
|
|
1321
|
+
`ship`'s `kept` field as it scrolled past, and Shio's the same way. `anchors` was the
|
|
1322
|
+
only verb that lists sections and its `live` answers a different question: RK247 built it
|
|
1323
|
+
about address *reuse*, so `live` means a heading declares the address now, and one
|
|
1324
|
+
written for a task that has since shipped is counted among the working ones.
|
|
1325
|
+
|
|
1326
|
+
Both files a line can be open in, for :func:`families_of_block`'s reason: a design whose
|
|
1327
|
+
task is paused is claimed, and answering "nobody" about it would name prose to delete.
|
|
1328
|
+
|
|
1329
|
+
Retired anchors are left alone. There is no heading to read an id off, and a claimant
|
|
1330
|
+
would be a live line pointing at an address nothing declares, which `lint` already
|
|
1331
|
+
refuses as `ref.unresolved` — a second reading of it here would be a second gate.
|
|
1332
|
+
"""
|
|
1333
|
+
if not anchor.live:
|
|
1334
|
+
return anchor
|
|
1335
|
+
section = None
|
|
1336
|
+
if config.has(anchor.role):
|
|
1337
|
+
section = find(config.document(anchor.role), anchor.anchor)
|
|
1338
|
+
binds = ""
|
|
1339
|
+
if section is not None:
|
|
1340
|
+
named = owners(section, config.schema.id_pattern())
|
|
1341
|
+
binds = named[0] if named else ""
|
|
1342
|
+
claimed = tuple(
|
|
1343
|
+
entry.task.id
|
|
1344
|
+
for role in ("roadmap", "deferred")
|
|
1345
|
+
if config.has(role)
|
|
1346
|
+
for entry in config.document(role).entries
|
|
1347
|
+
if entry.task.ref == anchor.anchor
|
|
1348
|
+
)
|
|
1349
|
+
return replace(anchor, binds=binds, claimed=claimed)
|
|
1350
|
+
|
|
1351
|
+
|
|
1352
|
+
def families_of_block(config: Config, block: str) -> tuple[str, ...]:
|
|
1353
|
+
"""Which outline families a block's prose already lives under (RK312).
|
|
1354
|
+
|
|
1355
|
+
The read that was derivable from no command at all. Under an outline a prose file
|
|
1356
|
+
declares no block headings — the address *is* the placement — so which numeral a block's
|
|
1357
|
+
designs sit in is written down nowhere, and the way to it was globbing pointers per block
|
|
1358
|
+
by hand: `list --block Q | grep -oE "§[IVXL]+"`, repeated once per block. It is a
|
|
1359
|
+
question, so it is a command (L5).
|
|
1360
|
+
|
|
1361
|
+
Read off the **pointers** and never off the prose file, for the reason
|
|
1362
|
+
:func:`~roadkeep.sections.pointers` gives: a heading nested under another is that other's
|
|
1363
|
+
prose until a line names it, and a task line is the only place that says which block an
|
|
1364
|
+
address belongs to. Both files a line can be open in, because a block whose every live
|
|
1365
|
+
line is paused still has a family and answering "none" would send the caller to open a
|
|
1366
|
+
second one.
|
|
1367
|
+
|
|
1368
|
+
More than one is a real answer and not a failure. A block that reopened under a fresh
|
|
1369
|
+
top-level has two, and returning both is what lets the caller see that before choosing —
|
|
1370
|
+
a single answer would pick one, which is the guess this exists to stop making.
|
|
1371
|
+
|
|
1372
|
+
Spelled **with the namespace** where `[refs]` declares one (RK340), because that is how
|
|
1373
|
+
:func:`_within` and :func:`next_child` read a family: `S:IX` and `IX` are two subtrees on
|
|
1374
|
+
a project whose two files each number their own outline, and a family stripped of the
|
|
1375
|
+
prefix here would be handed back an address the sibling file already spent.
|
|
1376
|
+
"""
|
|
1377
|
+
found: list[str] = []
|
|
1378
|
+
for role in ("roadmap", "deferred"):
|
|
1379
|
+
if not config.has(role) or not config.path(role).is_file():
|
|
1380
|
+
continue
|
|
1381
|
+
for entry in config.document(role).entries:
|
|
1382
|
+
if entry.task.block == block and entry.task.ref:
|
|
1383
|
+
family = entry.task.ref.split(".")[0]
|
|
1384
|
+
if family and family not in found:
|
|
1385
|
+
found.append(family)
|
|
1386
|
+
return tuple(found)
|
|
1387
|
+
|
|
1388
|
+
|
|
1389
|
+
def _spent_by_departure(
|
|
1390
|
+
config: Config, roles: Sequence[str], known: Sequence[Anchor]
|
|
1391
|
+
) -> list[Anchor]:
|
|
1392
|
+
"""Addresses no prose diff witnesses, read off the pointers that left with them (RK1178).
|
|
1393
|
+
|
|
1394
|
+
The blind spot :func:`_pointed_at` covers, joined here so one listing answers for both kinds
|
|
1395
|
+
of evidence: a heading any committed tree held, and an address whose heading no tree ever did
|
|
1396
|
+
because the `section add` that wrote it and the `ship` that dropped it were one commit.
|
|
1397
|
+
|
|
1398
|
+
**Outline only**, the rule :func:`~roadkeep.sections._refuse_reuse` keeps for the same reason:
|
|
1399
|
+
under `ref_scheme = "id"` the pointer *is* the id, retired-never-reused is the roadmap's own
|
|
1400
|
+
property (RK4), and every shipped task would arrive here as an address to refuse.
|
|
1401
|
+
|
|
1402
|
+
Attributed to the file the address belongs to, which its namespace answers where `[refs]`
|
|
1403
|
+
declares one (RK340). Where none does, both files number into one space and the row goes to
|
|
1404
|
+
the first declared role: the address is spent either way — that is the fact this reports — and
|
|
1405
|
+
which file would have held the heading is a question no history can settle.
|
|
1406
|
+
"""
|
|
1407
|
+
declared = [name for name in roles if config.has(name)]
|
|
1408
|
+
if not declared or config.schema_for(declared[0]).ref_scheme == "id":
|
|
1409
|
+
return []
|
|
1410
|
+
seen = {one.anchor for one in known}
|
|
1411
|
+
out: list[Anchor] = []
|
|
1412
|
+
for anchor, sha in _pointed_at(config).items():
|
|
1413
|
+
if anchor in seen:
|
|
1414
|
+
continue
|
|
1415
|
+
namespace, _ = split_ref(anchor)
|
|
1416
|
+
role = next(
|
|
1417
|
+
(name for name in declared if config.schema_for(name).ref_prefix == namespace),
|
|
1418
|
+
declared[0],
|
|
1419
|
+
)
|
|
1420
|
+
out.append(Anchor(anchor=anchor, role=role, live=False, written_in=sha))
|
|
1421
|
+
seen.add(anchor)
|
|
1422
|
+
return out
|
|
1423
|
+
|
|
1424
|
+
|
|
1425
|
+
def _pointed_at(config: Config) -> dict[str, str]:
|
|
1426
|
+
"""Every address a task line pointed at and **took with it**, by the commit that removed it.
|
|
1427
|
+
|
|
1428
|
+
The witness for an address declared and dropped inside one commit (RK1178). `_anchors_written`
|
|
1429
|
+
reads the prose file's own diffs, which is the whole history of an address in every case but
|
|
1430
|
+
one: a task whose `section add` and whose `ship` land in the same commit leaves a net-zero
|
|
1431
|
+
diff there — the heading was never in any committed tree, so no diff of that file mentions it.
|
|
1432
|
+
Nothing in the ledger does either, `as_ledger` keeping no pointer.
|
|
1433
|
+
|
|
1434
|
+
What does survive is the **roadmap**: that task's line was filed in an earlier commit carrying
|
|
1435
|
+
`→ §XIV.30`, and the ship removed the line. So the address is read off the pointer that left,
|
|
1436
|
+
which is a fact in the same history and about the same address.
|
|
1437
|
+
|
|
1438
|
+
Worth fixing rather than tolerating because of which workflow produces it: a task that files
|
|
1439
|
+
its own rationale and ships in one commit is what a one-task-one-commit rule *requires*, so
|
|
1440
|
+
this is the normal path and not unusual sequencing.
|
|
1441
|
+
|
|
1442
|
+
**Removed pointers only.** A pointer on a line still in the file is an address the two-command
|
|
1443
|
+
flow is halfway through spending — `add --ref I.3` then `section add I.3` — and counting it
|
|
1444
|
+
would make the second command refuse the address the first was told to take. A rewritten
|
|
1445
|
+
pointer (`amend --ref`) does register the one it abandoned: an address nothing wrote is still
|
|
1446
|
+
an address a reader saw cited, and they cost nothing.
|
|
1447
|
+
"""
|
|
1448
|
+
out: dict[str, str] = {}
|
|
1449
|
+
for role in ("roadmap", "deferred"):
|
|
1450
|
+
if not config.has(role):
|
|
1451
|
+
continue
|
|
1452
|
+
try:
|
|
1453
|
+
output = _run(
|
|
1454
|
+
config.root,
|
|
1455
|
+
"log",
|
|
1456
|
+
"--reverse",
|
|
1457
|
+
f"--format={_RECORD}%H",
|
|
1458
|
+
"--no-color",
|
|
1459
|
+
"-U0",
|
|
1460
|
+
"--",
|
|
1461
|
+
str(config.relative(config.path(role))),
|
|
1462
|
+
)
|
|
1463
|
+
except HistoryUnavailable:
|
|
1464
|
+
continue
|
|
1465
|
+
# Read as `anchor_of` reads a heading's: whatever follows the sigil up to the space
|
|
1466
|
+
# that ends the pointer, which is the last thing a rendered line carries. The address is
|
|
1467
|
+
# then validated by the same reader the prose file's own scan uses, so a bullet that
|
|
1468
|
+
# merely contains an arrow contributes nothing.
|
|
1469
|
+
pointer = re.compile(rf"{ARROW} §(\S+)\s*$")
|
|
1470
|
+
for head, rows in _records(output):
|
|
1471
|
+
for row in rows:
|
|
1472
|
+
if not row.startswith("-") or row.startswith("---"):
|
|
1473
|
+
continue
|
|
1474
|
+
found = pointer.search(row)
|
|
1475
|
+
if found:
|
|
1476
|
+
out.setdefault(found[1], head.strip())
|
|
1477
|
+
return out
|
|
1478
|
+
|
|
1479
|
+
|
|
1480
|
+
def _role_anchors(config: Config, role: str) -> list[Anchor]:
|
|
1481
|
+
"""One prose file's share of the answer, live rows first and retired ones behind them."""
|
|
1482
|
+
live = _declared(config, role) if config.path(role).is_file() else ()
|
|
1483
|
+
first = _anchors_written(config, role, config.schema_for(role))
|
|
1484
|
+
return [
|
|
1485
|
+
Anchor(anchor=anchor, role=role, live=True, written_in=first.get(anchor, ""))
|
|
1486
|
+
for anchor in live
|
|
1487
|
+
] + [
|
|
1488
|
+
Anchor(anchor=anchor, role=role, live=False, written_in=sha)
|
|
1489
|
+
for anchor, sha in first.items()
|
|
1490
|
+
if anchor not in live
|
|
1491
|
+
]
|
|
1492
|
+
|
|
1493
|
+
|
|
1494
|
+
def doubled(taken: Sequence[Anchor]) -> tuple[tuple[str, tuple[str, ...]], ...]:
|
|
1495
|
+
"""Every address more than one prose file **declares now**, with the files (RK297).
|
|
1496
|
+
|
|
1497
|
+
Reported here because this is the read that would otherwise hand one back as free: an
|
|
1498
|
+
author asking which address to take is the one who needs to know that two already answer
|
|
1499
|
+
to it. `lint` says the same thing as `ref.ambiguous`, and a gate is not a question — by
|
|
1500
|
+
the time it speaks, both headings exist and four verbs refuse to resolve between them.
|
|
1501
|
+
|
|
1502
|
+
Live only. A retired address in two files is two histories of one outline and nothing to
|
|
1503
|
+
act on; two *headings* are the state a pointer cannot resolve against.
|
|
1504
|
+
"""
|
|
1505
|
+
by_anchor: dict[str, list[str]] = {}
|
|
1506
|
+
for one in taken:
|
|
1507
|
+
if one.live:
|
|
1508
|
+
by_anchor.setdefault(one.anchor, []).append(one.role)
|
|
1509
|
+
return tuple(
|
|
1510
|
+
(anchor, tuple(roles)) for anchor, roles in by_anchor.items() if len(roles) > 1
|
|
1511
|
+
)
|
|
1512
|
+
|
|
1513
|
+
|
|
1514
|
+
def next_child(taken: Sequence[Anchor], family: str) -> str:
|
|
1515
|
+
"""The lowest numbered child of ``family`` no anchor above has ever used (RK247).
|
|
1516
|
+
|
|
1517
|
+
Derived one past the highest **ever** used and not one past the highest surviving, which
|
|
1518
|
+
is the whole difference: the surviving one is often none. Numeric children only — a
|
|
1519
|
+
lettered or roman segment is somebody's numbering and not this tool's to continue (L4) —
|
|
1520
|
+
and the answer is a suggestion a reader takes, never an anchor any verb writes.
|
|
1521
|
+
"""
|
|
1522
|
+
used = {
|
|
1523
|
+
int(child)
|
|
1524
|
+
for anchor in taken
|
|
1525
|
+
for child in (anchor.anchor[len(family) + 1 :].split(".")[:1] or [""])
|
|
1526
|
+
if anchor.anchor.startswith(f"{family}.") and child.isdigit()
|
|
1527
|
+
}
|
|
1528
|
+
return f"{family}.{max(used) + 1 if used else 1}"
|
|
1529
|
+
|
|
1530
|
+
|
|
1531
|
+
#: A well-formed Roman numeral, and only one: `IIII` and `IL` spell nothing here, because a
|
|
1532
|
+
#: reader that accepted them would order a file by a spelling nobody wrote.
|
|
1533
|
+
_ROMAN = re.compile(r"^M{0,3}(CM|CD|D?C{0,3})(XC|XL|L?X{0,3})(IX|IV|V?I{0,3})$")
|
|
1534
|
+
_DIGITS = (("M", 1000), ("CM", 900), ("D", 500), ("CD", 400), ("C", 100), ("XC", 90),
|
|
1535
|
+
("L", 50), ("XL", 40), ("X", 10), ("IX", 9), ("V", 5), ("IV", 4), ("I", 1))
|
|
1536
|
+
|
|
1537
|
+
|
|
1538
|
+
def numeral(text: str) -> tuple[str, int] | None:
|
|
1539
|
+
"""The number a segment spells and the system it spells it in, or None for neither.
|
|
1540
|
+
|
|
1541
|
+
Arithmetic and not prose (L4): `IX` is a number written a way this tool has to *read*
|
|
1542
|
+
to sort by, because a listing ordered by a numeral's spelling puts `IX` between `IV` and
|
|
1543
|
+
`V` and cannot be scanned for a gap (RK293). Reading it is also what lets the next free
|
|
1544
|
+
address be derived rather than guessed off the tail of the listing.
|
|
1545
|
+
|
|
1546
|
+
Strict, because a permissive reader is worse than none: a segment that is not a numeral
|
|
1547
|
+
must come back as one, so the caller can put it beside its siblings as text instead of
|
|
1548
|
+
among them as a number nobody meant.
|
|
1549
|
+
"""
|
|
1550
|
+
if text.isdigit():
|
|
1551
|
+
return "decimal", int(text)
|
|
1552
|
+
if text and _ROMAN.match(text):
|
|
1553
|
+
value, rest = 0, text
|
|
1554
|
+
for glyph, amount in _DIGITS:
|
|
1555
|
+
while rest.startswith(glyph):
|
|
1556
|
+
value, rest = value + amount, rest[len(glyph) :]
|
|
1557
|
+
return "roman", value
|
|
1558
|
+
return None
|
|
1559
|
+
|
|
1560
|
+
|
|
1561
|
+
def spell(value: int, system: str) -> str:
|
|
1562
|
+
"""``value`` written the way ``system`` writes it — the inverse of :func:`numeral`."""
|
|
1563
|
+
if system != "roman":
|
|
1564
|
+
return str(value)
|
|
1565
|
+
out, left = [], value
|
|
1566
|
+
for glyph, amount in sorted(_DIGITS, key=lambda pair: -pair[1]):
|
|
1567
|
+
while left >= amount:
|
|
1568
|
+
out.append(glyph)
|
|
1569
|
+
left -= amount
|
|
1570
|
+
return "".join(out)
|
|
1571
|
+
|
|
1572
|
+
|
|
1573
|
+
def namespaces(taken: Sequence[Anchor]) -> tuple[str, ...]:
|
|
1574
|
+
"""Every namespace these addresses live in, `""` for the unprefixed one (RK340).
|
|
1575
|
+
|
|
1576
|
+
Sorted with the unprefixed first, because it is the one a project has before it declares
|
|
1577
|
+
any and the one every listing had until this existed.
|
|
1578
|
+
"""
|
|
1579
|
+
return tuple(sorted({split_ref(one.anchor)[0] for one in taken}))
|
|
1580
|
+
|
|
1581
|
+
|
|
1582
|
+
def next_family(taken: Sequence[Anchor], namespace: str = "") -> str | None:
|
|
1583
|
+
"""The lowest top-level address no anchor has ever used, or None where none derives.
|
|
1584
|
+
|
|
1585
|
+
The question one line up from :func:`next_child`, and the normal case rather than an edge
|
|
1586
|
+
one (RK293): a block reused after its family shipped needs a *new* top-level, and until
|
|
1587
|
+
this the number was read off the tail of a listing sorted by spelling — where the last row
|
|
1588
|
+
is not the maximum. Derived from the same walk, so it costs nothing the command did not
|
|
1589
|
+
already pay.
|
|
1590
|
+
|
|
1591
|
+
None where the top-levels are not one numbering, which is the honest answer and not a
|
|
1592
|
+
fallback: a file whose families are `A`, `B` and `C` has a next nobody can derive, and a
|
|
1593
|
+
guess printed beside a total reads exactly like a fact. Spelled in the system of the
|
|
1594
|
+
family that holds the maximum, because that is the sequence being continued.
|
|
1595
|
+
|
|
1596
|
+
**Per namespace** (RK340), which is what a namespace is for: `[refs]` makes two files two
|
|
1597
|
+
outlines, each numbering itself from `I`, so a maximum taken across both would answer
|
|
1598
|
+
with the taller file's number for the shorter one — and reading the mixed set as one
|
|
1599
|
+
sequence answers None, which is the useful answer withheld from exactly the projects
|
|
1600
|
+
that declared their way out of the collision. The default is the unprefixed namespace,
|
|
1601
|
+
which is every project that declares no `[refs]` at all.
|
|
1602
|
+
|
|
1603
|
+
**One numbering means one system, and until RK1210 it meant one that reads as a number.**
|
|
1604
|
+
The guard below caught a segment that is no numeral at all and let `1` beside `I` through
|
|
1605
|
+
— they read as 1 and 1, so the key ties, and `max` returns whichever the iteration reached
|
|
1606
|
+
first. That order is a **set** comprehension's over strings, which is per-process hash
|
|
1607
|
+
randomisation: eight runs over one revision of one file answered `II`, `2`, `2`, `2`, `II`,
|
|
1608
|
+
`2`, `2`, `2`. The system the address is spelled in was the tie-break, so the address was
|
|
1609
|
+
too — and `ref.missing` carries it as `offered`, the string a retry substitutes, so a
|
|
1610
|
+
refusal and its own retry could name two different addresses. In one tree they did:
|
|
1611
|
+
`anchors` printed `next §2` where the refusal said `§II is its free top-level`.
|
|
1612
|
+
|
|
1613
|
+
The fix is this function's own rule applied and never a tie-break invented — sorting the
|
|
1614
|
+
set would make the answer stable and still make it a coin the file did not toss. Two
|
|
1615
|
+
systems is two numberings, so it is None, exactly as `A`, `B`, `C` is; every caller
|
|
1616
|
+
already has an answer for None, `_where_a_top_level_is` naming `anchors` in place of an
|
|
1617
|
+
address for the undecidables it already knew about.
|
|
1618
|
+
"""
|
|
1619
|
+
own = [one for one in taken if split_ref(one.anchor)[0] == namespace]
|
|
1620
|
+
read = {top: numeral(top) for top in {_family_of(one.anchor) for one in own}}
|
|
1621
|
+
if not read or any(value is None for value in read.values()):
|
|
1622
|
+
return None
|
|
1623
|
+
counted = [value for value in read.values() if value]
|
|
1624
|
+
if len({system for system, _ in counted}) > 1:
|
|
1625
|
+
# Roman in one family and decimal in another. Not a sequence to continue, and the one
|
|
1626
|
+
# shape where continuing it silently picked which of two conventions the project has.
|
|
1627
|
+
return None
|
|
1628
|
+
system, highest = max(counted, key=lambda one: one[1])
|
|
1629
|
+
top = spell(highest + 1, system)
|
|
1630
|
+
return f"{namespace}{REF_SEPARATOR}{top}" if namespace else top
|
|
1631
|
+
|
|
1632
|
+
|
|
1633
|
+
def left_the_repository(root: Path, token: str) -> bool:
|
|
1634
|
+
"""Whether this repository once held ``token`` and no longer does, as committed (RK1217).
|
|
1635
|
+
|
|
1636
|
+
The tree a shipped entry's paths are about is **not this afternoon's**. Turing's `T759`
|
|
1637
|
+
names `frontend/apps/site/scripts/emit-model-catalog.mjs`, a script that existed when the
|
|
1638
|
+
work shipped and was later extracted into its own repository with the model catalog it
|
|
1639
|
+
built. The entry is accurate, the file is gone, and the gate reported it every run and
|
|
1640
|
+
would have kept reporting it.
|
|
1641
|
+
|
|
1642
|
+
`Tree.anywhere` already forgives a path that moved **within** the repository, so what was
|
|
1643
|
+
left was the one that left it entirely — a correct statement about the past, read as drift.
|
|
1644
|
+
And the door made it worse than noise: the remedy rewrites the entry's sentence, which on
|
|
1645
|
+
that entry is about 1,500 characters of as-built record. The offered fix for a stale path
|
|
1646
|
+
was deleting the thing that made the entry worth keeping, so nobody took it and the finding
|
|
1647
|
+
sat forgiven by a baseline for ever.
|
|
1648
|
+
|
|
1649
|
+
**Two questions, and the first one is what keeps this narrow.** *Is it in `HEAD`* — because
|
|
1650
|
+
a file somebody deleted in their working tree and has not committed is still the
|
|
1651
|
+
repository's, and forgiving that would stop the gate reporting a deletion at exactly the
|
|
1652
|
+
moment it is worth reporting. Only then *did any commit ever hold it*, over all refs, which
|
|
1653
|
+
is the reading that answers `T759`.
|
|
1654
|
+
|
|
1655
|
+
Not `--follow`, which needs a single surviving path and answers about a rename chain rather
|
|
1656
|
+
than about existence.
|
|
1657
|
+
|
|
1658
|
+
**What this deliberately stops catching** is a rename the ledger did not follow, which was
|
|
1659
|
+
the one true finding this check produced on a live corpus: the old path was held once, so
|
|
1660
|
+
it is now forgiven. RK1217 takes that trade knowingly — the alternative is a correct
|
|
1661
|
+
statement about the past reported for ever, with a door whose only effect is to delete the
|
|
1662
|
+
as-built record that made the entry worth keeping. What is left is the reading the rule was
|
|
1663
|
+
always for: **a path this repository never had.**
|
|
1664
|
+
|
|
1665
|
+
Cheap because it is asked **last** (see :func:`~roadkeep.linting._paths`): the working tree
|
|
1666
|
+
answers first, so a healthy repository asks this nothing at all and a corpus with stale
|
|
1667
|
+
entries pays at most two calls per token that already failed every other reading.
|
|
1668
|
+
|
|
1669
|
+
False where git cannot be reached, which keeps the finding: this is a *forgiveness*, and an
|
|
1670
|
+
unavailable history is not evidence that a path was ever there.
|
|
1671
|
+
"""
|
|
1672
|
+
try:
|
|
1673
|
+
if _run(root, "ls-tree", "HEAD", "--", token).strip():
|
|
1674
|
+
return False
|
|
1675
|
+
found = _run(root, "log", "--all", "--max-count=1", "--format=%H", "--", token)
|
|
1676
|
+
except HistoryUnavailable:
|
|
1677
|
+
return False
|
|
1678
|
+
return bool(found.strip())
|
|
1679
|
+
|
|
1680
|
+
|
|
1681
|
+
def _declared(config: Config, role: str) -> tuple[str, ...]:
|
|
1682
|
+
from roadkeep.sections import anchored # noqa: PLC0415 - RK260
|
|
1683
|
+
|
|
1684
|
+
return tuple(section.anchor for section in anchored(config.document(role)))
|
|
1685
|
+
|
|
1686
|
+
|
|
1687
|
+
def _anchors_written(config: Config, role: str, schema: Schema) -> dict[str, str]:
|
|
1688
|
+
"""Anchor → the first sha whose diff on this file carries its heading, oldest first."""
|
|
1689
|
+
from roadkeep.sections import anchor_of, qualified # noqa: PLC0415 - RK260
|
|
1690
|
+
|
|
1691
|
+
try:
|
|
1692
|
+
relative = config.path(role).relative_to(config.root)
|
|
1693
|
+
except ValueError:
|
|
1694
|
+
relative = config.path(role)
|
|
1695
|
+
try:
|
|
1696
|
+
output = _run(
|
|
1697
|
+
config.root,
|
|
1698
|
+
"log",
|
|
1699
|
+
"--reverse",
|
|
1700
|
+
f"--format={_RECORD}%H",
|
|
1701
|
+
"--no-color",
|
|
1702
|
+
"-U0",
|
|
1703
|
+
"--",
|
|
1704
|
+
str(relative),
|
|
1705
|
+
)
|
|
1706
|
+
except HistoryUnavailable:
|
|
1707
|
+
return {}
|
|
1708
|
+
first: dict[str, str] = {}
|
|
1709
|
+
for head, rows in _records(output):
|
|
1710
|
+
for row in rows:
|
|
1711
|
+
if row[:1] not in ("+", "-") or row.startswith(("+++", "---")):
|
|
1712
|
+
continue
|
|
1713
|
+
# A heading and not any line that starts with the anchor's spelling: under an
|
|
1714
|
+
# outline the anchor is a bare number, so a table row or a bullet beginning
|
|
1715
|
+
# `XXXVII.4` would otherwise register an address nobody declared.
|
|
1716
|
+
text = row[1:].lstrip()
|
|
1717
|
+
if not text.startswith("#"):
|
|
1718
|
+
continue
|
|
1719
|
+
# Read the way a parsed heading is read — `Heading.text` is what follows the
|
|
1720
|
+
# hashes, and :func:`anchor_of` is written against that.
|
|
1721
|
+
anchor = anchor_of(text.lstrip("#").lstrip(), schema)
|
|
1722
|
+
if anchor is not None:
|
|
1723
|
+
# The project's address and not the heading's (RK340) — the same
|
|
1724
|
+
# qualification `anchored` makes of a live one, so the two halves of this
|
|
1725
|
+
# listing are addresses of one kind and a retired `S:I` is not a second `I`.
|
|
1726
|
+
first.setdefault(qualified(schema, anchor), head.strip())
|
|
1727
|
+
return first
|
|
1728
|
+
|
|
1729
|
+
|
|
1730
|
+
def _within(anchor: str, family: str) -> bool:
|
|
1731
|
+
"""Is this anchor the family or under it, segment by segment rather than by string."""
|
|
1732
|
+
if not family:
|
|
1733
|
+
return True
|
|
1734
|
+
segments, wanted = anchor.split("."), family.split(".")
|
|
1735
|
+
return segments[: len(wanted)] == wanted
|
|
1736
|
+
|
|
1737
|
+
|
|
1738
|
+
def _ordinal(anchor: Anchor, numbered: bool = False) -> tuple[object, ...]:
|
|
1739
|
+
"""File order is not sort order once retired addresses are back in the list, so the
|
|
1740
|
+
segments are compared as numbers where they are numbers and as text where they are not —
|
|
1741
|
+
`.2` before `.10`, and a lettered segment beside its siblings rather than among them.
|
|
1742
|
+
|
|
1743
|
+
``numbered`` reads a Roman segment as the number it spells (RK293), and is decided over
|
|
1744
|
+
the whole set rather than per segment: `C` and `D` are numerals on a file numbered in
|
|
1745
|
+
Roman and are letters on one whose families are `A` to `F`, and only the set says which.
|
|
1746
|
+
"""
|
|
1747
|
+
return tuple(
|
|
1748
|
+
(0, int(part), "")
|
|
1749
|
+
if part.isdigit()
|
|
1750
|
+
else ((0, read[1], "") if numbered and (read := numeral(part)) else (1, 0, part))
|
|
1751
|
+
# The first segment carries the namespace where a project declares one (RK340), and
|
|
1752
|
+
# it is read off for the same reason `numbered` is: the number is what orders a
|
|
1753
|
+
# listing, and a prefix in front of it is the file's name and not part of the number.
|
|
1754
|
+
for part in _unprefixed(anchor.anchor).split(".")
|
|
1755
|
+
)
|
|
1756
|
+
|
|
1757
|
+
|
|
1758
|
+
def _family_of(anchor: str) -> str:
|
|
1759
|
+
"""The top-level segment, with any namespace taken off — `S:IX.2` → `IX` (RK340)."""
|
|
1760
|
+
return _unprefixed(anchor).split(".")[0]
|
|
1761
|
+
|
|
1762
|
+
|
|
1763
|
+
def _unprefixed(anchor: str) -> str:
|
|
1764
|
+
"""The address without the namespace `[refs]` put in front of it (RK340)."""
|
|
1765
|
+
return split_ref(anchor)[1]
|
|
1766
|
+
|
|
1767
|
+
|
|
1768
|
+
@dataclass(frozen=True, slots=True)
|
|
1769
|
+
class Gap:
|
|
1770
|
+
"""An id that is in neither file, and the commit that took it out (RK32).
|
|
1771
|
+
|
|
1772
|
+
``removed_in`` is None for two unlike reasons, and RK95 is the record of them having
|
|
1773
|
+
read alike. A history that **cannot** be searched — no git, no repository, a shallow
|
|
1774
|
+
clone — answers nothing; a complete one that mentions the id nowhere answers that no
|
|
1775
|
+
line ever carried it, which is the shape of a number skipped when a batch was
|
|
1776
|
+
allocated. The first prints as *unresolvable* and the second as *never carried*, on
|
|
1777
|
+
RK28's reasoning: an absent answer and a negative one are different answers, and
|
|
1778
|
+
collapsing them here would invent a decision nobody recorded — or deny one that was.
|
|
1779
|
+
"""
|
|
1780
|
+
|
|
1781
|
+
id: str
|
|
1782
|
+
number: int
|
|
1783
|
+
removed_in: Commit | None
|
|
1784
|
+
#: Whether the log that came back empty was a log worth trusting.
|
|
1785
|
+
searched: bool = False
|
|
1786
|
+
|
|
1787
|
+
@property
|
|
1788
|
+
def resolved(self) -> bool:
|
|
1789
|
+
return self.removed_in is not None
|
|
1790
|
+
|
|
1791
|
+
@property
|
|
1792
|
+
def never_carried(self) -> bool:
|
|
1793
|
+
"""Searched to the root commit and found nowhere: skipped, not removed."""
|
|
1794
|
+
return self.removed_in is None and self.searched
|
|
1795
|
+
|
|
1796
|
+
|
|
1797
|
+
|
|
1798
|
+
def _ownership(one: Anchor) -> str:
|
|
1799
|
+
"""Who binds this address and who points at it, where either is worth saying (RK453).
|
|
1800
|
+
|
|
1801
|
+
Silent on the ordinary row — a heading bound to the one line that claims it is the state
|
|
1802
|
+
every write produces, and repeating it on every address would bury the two that are not.
|
|
1803
|
+
What it names is exactly the two ways they come apart, and each is a different act: an
|
|
1804
|
+
unbound heading a line claims is `section amend --title` away from bound, and a bound
|
|
1805
|
+
heading nothing claims is prose whose task has left, which is the reader's to keep or
|
|
1806
|
+
delete.
|
|
1807
|
+
|
|
1808
|
+
Three silences and not one (RK461). A retired address has no heading to have an opinion
|
|
1809
|
+
about; the bound-and-claimed row is what every write produces; and a **memo** — naming no
|
|
1810
|
+
task and claimed by none — is the state RK236 protects and nothing ever closes. Reported
|
|
1811
|
+
beside the two that are actionable, that third one was five of the five rows this
|
|
1812
|
+
project's audit printed, and a list whose majority is noise is what teaches somebody to
|
|
1813
|
+
stop reading a report.
|
|
1814
|
+
"""
|
|
1815
|
+
if not one.live or one.memo:
|
|
1816
|
+
return ""
|
|
1817
|
+
if one.binds and one.claimed == (one.binds,):
|
|
1818
|
+
return ""
|
|
1819
|
+
if not one.binds:
|
|
1820
|
+
return f" binds nobody, claimed by {', '.join(one.claimed)}"
|
|
1821
|
+
if not one.claimed:
|
|
1822
|
+
return f" binds {one.binds}, which no open line claims"
|
|
1823
|
+
return f" binds {one.binds}, claimed by {', '.join(one.claimed)}"
|
|
1824
|
+
|
|
1825
|
+
|
|
1826
|
+
def opens(family: str) -> str:
|
|
1827
|
+
"""The sentence a free top-level owes, and the command that makes it a section (RK1140)."""
|
|
1828
|
+
from roadkeep.provenance import invocation # noqa: PLC0415 - RK260
|
|
1829
|
+
|
|
1830
|
+
return (
|
|
1831
|
+
f"§{family} is free and not yet a section, so `{invocation()} add --ref {family}.1` "
|
|
1832
|
+
f"refuses until one exists — `{invocation()} section add {family} --title \"…\"` "
|
|
1833
|
+
f"opens it"
|
|
1834
|
+
)
|
|
1835
|
+
|
|
1836
|
+
|
|
1837
|
+
@dataclass(frozen=True, slots=True)
|
|
1838
|
+
class Addresses:
|
|
1839
|
+
"""Live and retired addresses across a project's prose, as one answer (RK247, RK297).
|
|
1840
|
+
|
|
1841
|
+
The result this read had none of (RK1170). The door narrowed the listing, derived the free
|
|
1842
|
+
address from a *wider* set than the one it listed, split the outline out of the ids, and
|
|
1843
|
+
then composed four readings from those four values — two payloads and two reports, each
|
|
1844
|
+
subtracting the same things again.
|
|
1845
|
+
|
|
1846
|
+
**The narrowing and the derivation are not the same set, and that is the whole of RK297.**
|
|
1847
|
+
`--role` narrows :attr:`found`; the free address is computed from :attr:`whole`, because
|
|
1848
|
+
where no `[refs]` declares a namespace both files number into one and a `next` taken from
|
|
1849
|
+
a single file is the answer this read exists to stop somebody acting on.
|
|
1850
|
+
"""
|
|
1851
|
+
|
|
1852
|
+
#: The role a caller narrowed to, or `""` for every declared prose file.
|
|
1853
|
+
role: str
|
|
1854
|
+
#: The roles actually read, which is what a listing names its files from.
|
|
1855
|
+
read: tuple[str, ...]
|
|
1856
|
+
#: The family a caller narrowed to, or `""`. Under `--block` it is resolved from the
|
|
1857
|
+
#: pointers rather than given (RK312).
|
|
1858
|
+
family: str
|
|
1859
|
+
#: The block asked about, and every family its open lines point into. Both, because one of
|
|
1860
|
+
#: them narrowed the listing and two did not, and a caller cannot tell those apart.
|
|
1861
|
+
block: str = ""
|
|
1862
|
+
spans: tuple[str, ...] = ()
|
|
1863
|
+
found: tuple[Anchor, ...] = ()
|
|
1864
|
+
#: The same read over the project, whatever the listing was narrowed to.
|
|
1865
|
+
whole: tuple[Anchor, ...] = ()
|
|
1866
|
+
#: :attr:`found` and :attr:`whole` with the task ids taken out. An address that is an id is
|
|
1867
|
+
#: a question already answered — `add` refuses to reuse one (RK4) and every shipped task
|
|
1868
|
+
#: leaves its section retired, so on this project they are 287 of 307 rows and none of them
|
|
1869
|
+
#: is a choice anybody makes.
|
|
1870
|
+
outline: tuple[Anchor, ...] = ()
|
|
1871
|
+
spread: tuple[Anchor, ...] = ()
|
|
1872
|
+
|
|
1873
|
+
@classmethod
|
|
1874
|
+
def of(
|
|
1875
|
+
cls,
|
|
1876
|
+
config: Config,
|
|
1877
|
+
role: str,
|
|
1878
|
+
family: str,
|
|
1879
|
+
read: Sequence[str],
|
|
1880
|
+
block: str = "",
|
|
1881
|
+
spans: Sequence[str] = (),
|
|
1882
|
+
) -> Addresses:
|
|
1883
|
+
found = anchors(config, role, family)
|
|
1884
|
+
whole = found if not role else anchors(config, "", family)
|
|
1885
|
+
ids = config.schema_for(role or read[0]).id_pattern()
|
|
1886
|
+
outside = lambda rows: tuple( # noqa: E731 - one predicate, read twice
|
|
1887
|
+
one for one in rows if not ids.match(one.anchor.split(".")[0])
|
|
1888
|
+
)
|
|
1889
|
+
return cls(
|
|
1890
|
+
role=role,
|
|
1891
|
+
read=tuple(read),
|
|
1892
|
+
family=family,
|
|
1893
|
+
block=block,
|
|
1894
|
+
spans=tuple(spans),
|
|
1895
|
+
found=tuple(found),
|
|
1896
|
+
whole=tuple(whole),
|
|
1897
|
+
outline=outside(found),
|
|
1898
|
+
spread=outside(whole),
|
|
1899
|
+
)
|
|
1900
|
+
|
|
1901
|
+
@property
|
|
1902
|
+
def retired(self) -> tuple[Anchor, ...]:
|
|
1903
|
+
return tuple(one for one in self.found if not one.live)
|
|
1904
|
+
|
|
1905
|
+
@property
|
|
1906
|
+
def spent(self) -> int:
|
|
1907
|
+
"""How many of the listed addresses are task ids rather than outline numerals."""
|
|
1908
|
+
return len(self.found) - len(self.outline)
|
|
1909
|
+
|
|
1910
|
+
def files(self, config: Config) -> str:
|
|
1911
|
+
return ", ".join(config.relative(config.path(one)) for one in self.read)
|
|
1912
|
+
|
|
1913
|
+
def families(self) -> list[dict[str, object]]:
|
|
1914
|
+
"""One row per top-level address, in numeral order (RK293), with the files it spans.
|
|
1915
|
+
|
|
1916
|
+
The counts are the project's and so is `next` (RK297): a family declared in two prose
|
|
1917
|
+
files is one family, and a per-file count would be the number this read exists to stop
|
|
1918
|
+
somebody taking. `files` is what a row says once it spans two — named rather than
|
|
1919
|
+
summed away, because which file spent an address is what a reader checks it against.
|
|
1920
|
+
"""
|
|
1921
|
+
out: dict[str, dict[str, object]] = {}
|
|
1922
|
+
for one in self.outline:
|
|
1923
|
+
top = one.anchor.split(".")[0]
|
|
1924
|
+
row = out.setdefault(top, {"family": top, "live": 0, "retired": 0, "files": []})
|
|
1925
|
+
key = "live" if one.live else "retired"
|
|
1926
|
+
row[key] = int(row[key]) + 1
|
|
1927
|
+
if one.role not in row["files"]: # type: ignore[operator]
|
|
1928
|
+
row["files"].append(one.role) # type: ignore[attr-defined]
|
|
1929
|
+
for top, row in out.items():
|
|
1930
|
+
row["next"] = next_child(self.outline, top)
|
|
1931
|
+
return list(out.values())
|
|
1932
|
+
|
|
1933
|
+
def doubled_rows(self) -> list[str]:
|
|
1934
|
+
"""The addresses two prose files both declare, named here and not only at the gate.
|
|
1935
|
+
|
|
1936
|
+
`lint` reports them as `ref.ambiguous`, and by then both headings exist and four verbs
|
|
1937
|
+
refuse to resolve between them (RK297). This is the read an author makes *before*
|
|
1938
|
+
choosing, so it is where the state is cheapest to hear about.
|
|
1939
|
+
"""
|
|
1940
|
+
return [
|
|
1941
|
+
f" doubled §{anchor} is declared by {' and '.join(roles)}"
|
|
1942
|
+
for anchor, roles in doubled(self.whole)
|
|
1943
|
+
]
|
|
1944
|
+
|
|
1945
|
+
def room_left(self, config: Config) -> str:
|
|
1946
|
+
"""What the parent of an offered child address has left, where it has too little.
|
|
1947
|
+
|
|
1948
|
+
An address `add` will refuse is an address this listing should not hand over silently
|
|
1949
|
+
(RK1024). Measured: `anchors --block AJ` offered `§L.1`, `§L` was 299 words of its own
|
|
1950
|
+
300, and every child of it — the empty one included — was over before a word was
|
|
1951
|
+
composed. Said and never refused, because `anchors` is a read (L5): the caller may be
|
|
1952
|
+
about to shorten the parent, which is a plan no count can see.
|
|
1953
|
+
"""
|
|
1954
|
+
from roadkeep.kernel.schema import body_aim # noqa: PLC0415 - RK260
|
|
1955
|
+
from roadkeep.sections import binding # noqa: PLC0415 - RK260
|
|
1956
|
+
|
|
1957
|
+
for role in self.read:
|
|
1958
|
+
answer = binding(config, role, self.family)
|
|
1959
|
+
if answer is None:
|
|
1960
|
+
continue
|
|
1961
|
+
taken, limit = answer
|
|
1962
|
+
if taken >= body_aim(limit):
|
|
1963
|
+
return (
|
|
1964
|
+
f", but §{self.family} already spends {taken} of its {limit} words, "
|
|
1965
|
+
f"so a child of it is charged over the limit before it is written"
|
|
1966
|
+
)
|
|
1967
|
+
return ""
|
|
1968
|
+
|
|
1969
|
+
# -- the free address alone (RK410) ------------------------------------
|
|
1970
|
+
|
|
1971
|
+
def freely(self) -> tuple[list[str], list[str]]:
|
|
1972
|
+
"""The next address and nothing else, as `(stdout, stderr)`.
|
|
1973
|
+
|
|
1974
|
+
`anchors` answers two questions at once: which addresses a family has spent, asked
|
|
1975
|
+
once before reopening a shipped subtree, and which one nothing ever used, asked by
|
|
1976
|
+
every `add --ref`. Under a 27-anchor family the second answer was the 28th row — and
|
|
1977
|
+
on a tool result the rows are what gets truncated first, which made the one line that
|
|
1978
|
+
mattered the one most likely to be cut.
|
|
1979
|
+
|
|
1980
|
+
Two streams, for `next-id`'s reason: stdout is the address, because this is captured
|
|
1981
|
+
in a shell. **No note where a family was named** and the difference is the whole of
|
|
1982
|
+
RK1140: a free *child* is placeable the moment it is answered, the family's heading
|
|
1983
|
+
already existing. It is the top-level below that is an address and not yet a section.
|
|
1984
|
+
"""
|
|
1985
|
+
if self.family:
|
|
1986
|
+
return [f"§{next_child(self.whole, self.family)}"], []
|
|
1987
|
+
out: list[str] = []
|
|
1988
|
+
notes: list[str] = []
|
|
1989
|
+
for space in namespaces(self.spread):
|
|
1990
|
+
fresh = next_family(self.spread, space)
|
|
1991
|
+
named = f" {space}" if space else ""
|
|
1992
|
+
# The same refusal the wide read gives, in one line: a namespace whose top-levels
|
|
1993
|
+
# are not one numbering derives nothing, and a blank row would read as an address.
|
|
1994
|
+
out.append(
|
|
1995
|
+
f"§{fresh}{named}" if fresh else f"—{named} not one numbering, so none derives"
|
|
1996
|
+
)
|
|
1997
|
+
if fresh:
|
|
1998
|
+
notes.append(f"roadkeep: {opens(fresh)}")
|
|
1999
|
+
return out, notes
|
|
2000
|
+
|
|
2001
|
+
def free_payload(self) -> dict[str, object]:
|
|
2002
|
+
"""The narrow read in the narrow shape (RK410).
|
|
2003
|
+
|
|
2004
|
+
`family` and `namespace` are kept because the answer is meaningless without saying
|
|
2005
|
+
which numbering it continues — everything else in the wide payload is the listing this
|
|
2006
|
+
flag exists to leave out.
|
|
2007
|
+
"""
|
|
2008
|
+
return {
|
|
2009
|
+
"family": self.family or None,
|
|
2010
|
+
"next": next_child(self.whole, self.family) if self.family else None,
|
|
2011
|
+
"next_families": []
|
|
2012
|
+
if self.family
|
|
2013
|
+
else [
|
|
2014
|
+
{
|
|
2015
|
+
"namespace": space or None,
|
|
2016
|
+
"next": next_family(self.spread, space),
|
|
2017
|
+
# The same sentence the reader gets, as the command it names (RK1140): a
|
|
2018
|
+
# client composing `add --ref <next>.1` walks into the refusal a person
|
|
2019
|
+
# now reads about, and two answers to one question is what a payload
|
|
2020
|
+
# beside a report must not be.
|
|
2021
|
+
"opens": None
|
|
2022
|
+
if not (fresh := next_family(self.spread, space))
|
|
2023
|
+
else f"section add {fresh} --title …",
|
|
2024
|
+
}
|
|
2025
|
+
for space in namespaces(self.spread)
|
|
2026
|
+
],
|
|
2027
|
+
}
|
|
2028
|
+
|
|
2029
|
+
# -- the wide read -----------------------------------------------------
|
|
2030
|
+
|
|
2031
|
+
def stated(self, config: Config, claims: bool) -> str:
|
|
2032
|
+
from roadkeep.provenance import invocation # noqa: PLC0415 - RK260
|
|
2033
|
+
|
|
2034
|
+
where = self.files(config)
|
|
2035
|
+
if claims:
|
|
2036
|
+
# Its own header and not a second one under the totals (RK459): this listing is
|
|
2037
|
+
# the exceptions, so the number a reader wants first is how many there are.
|
|
2038
|
+
rows = [one for one in self.found if _ownership(one)]
|
|
2039
|
+
# The memos are counted and not listed (RK461): "five of them and none needing
|
|
2040
|
+
# anything" is a different answer from silence, and it is the answer an adopting
|
|
2041
|
+
# corpus most often has.
|
|
2042
|
+
memos = sum(1 for one in self.found if one.memo)
|
|
2043
|
+
counted = f", {memos} standing memo(s)" if memos else ""
|
|
2044
|
+
said = [
|
|
2045
|
+
f"{len(rows)} of {len(self.found)} address(es) say something about "
|
|
2046
|
+
f"ownership{counted} ({where})"
|
|
2047
|
+
]
|
|
2048
|
+
said += [
|
|
2049
|
+
f" {one.anchor}"
|
|
2050
|
+
+ (f" in {one.role}" if len(self.read) > 1 else "")
|
|
2051
|
+
+ _ownership(one)
|
|
2052
|
+
for one in rows
|
|
2053
|
+
]
|
|
2054
|
+
return chr(10).join(said + self.doubled_rows())
|
|
2055
|
+
|
|
2056
|
+
said = [f"{len(self.found)} anchor(s), {len(self.retired)} retired ({where})"]
|
|
2057
|
+
if self.block:
|
|
2058
|
+
# Said whichever way it went (RK312): one family is the narrowing the rest of this
|
|
2059
|
+
# output is already about, and two is the answer itself — the caller picks, because
|
|
2060
|
+
# which subtree a new line belongs under is a judgement no file holds.
|
|
2061
|
+
named = ", ".join(f"§{one}" for one in self.spans)
|
|
2062
|
+
# The whole command and not the flag alone (RK1022): a caller arrives here from an
|
|
2063
|
+
# `add` refusal that named `--ref`, so a bare `--family` reads as a second flag of
|
|
2064
|
+
# the verb they were writing.
|
|
2065
|
+
picked = (
|
|
2066
|
+
""
|
|
2067
|
+
if len(self.spans) == 1
|
|
2068
|
+
else f" — pick one, e.g. `{invocation()} anchors --family {self.spans[0]}`"
|
|
2069
|
+
)
|
|
2070
|
+
said.append(f" block Block {self.block}'s prose is under {named}{picked}")
|
|
2071
|
+
if self.family:
|
|
2072
|
+
for one in self.found:
|
|
2073
|
+
written = f" written in {one.written_in[:7]}" if one.written_in else ""
|
|
2074
|
+
# The file, wherever the project has more than one: two rows spelling the same
|
|
2075
|
+
# address are the doubling, and unlabelled they read as one row printed twice.
|
|
2076
|
+
named = f" in {one.role}" if len(self.read) > 1 else ""
|
|
2077
|
+
said.append(
|
|
2078
|
+
f" {'live' if one.live else 'retired':<8} {one.anchor}{named}"
|
|
2079
|
+
f"{written}{_ownership(one)}"
|
|
2080
|
+
)
|
|
2081
|
+
said.append(
|
|
2082
|
+
f" next §{next_child(self.whole, self.family)} — nothing ever used it"
|
|
2083
|
+
f"{self.room_left(config)}"
|
|
2084
|
+
)
|
|
2085
|
+
return chr(10).join(said + self.doubled_rows())
|
|
2086
|
+
|
|
2087
|
+
# Beside the totals and above the rows, because it is the question a reused block asks
|
|
2088
|
+
# first and the listing cannot be read for it (RK293): the rows are per family, and the
|
|
2089
|
+
# last one is only the maximum once they are ordered by the number a numeral spells.
|
|
2090
|
+
for space in namespaces(self.spread) if self.spread else ():
|
|
2091
|
+
# One line per namespace (RK340). Where a project declares no `[refs]` this is the
|
|
2092
|
+
# one line it always printed; where it does, the two files each continue their own
|
|
2093
|
+
# numbering, and a single answer would give one file the other's next address.
|
|
2094
|
+
fresh = next_family(self.spread, space)
|
|
2095
|
+
named = f" in {space}" if space else ""
|
|
2096
|
+
said.append(
|
|
2097
|
+
f" next §{fresh} — no family{named} ever used it"
|
|
2098
|
+
if fresh
|
|
2099
|
+
else f" next — these families{named} are not one numbering, so none derives"
|
|
2100
|
+
)
|
|
2101
|
+
for family in self.families():
|
|
2102
|
+
# The files only where there is more than one to name (RK297): on the single-file
|
|
2103
|
+
# project that is every project until it declares a second, it would be noise.
|
|
2104
|
+
across = family["files"]
|
|
2105
|
+
spans = f" ({', '.join(across)})" if len(across) > 1 else "" # type: ignore[arg-type]
|
|
2106
|
+
said.append(
|
|
2107
|
+
f" {family['family']:<8} {family['live']} live, {family['retired']} retired"
|
|
2108
|
+
f" next §{family['next']}{spans}"
|
|
2109
|
+
)
|
|
2110
|
+
if self.spent:
|
|
2111
|
+
said.append(
|
|
2112
|
+
f" {self.spent} address(es) are task ids, which `add` already refuses to reuse"
|
|
2113
|
+
)
|
|
2114
|
+
said += self.doubled_rows()
|
|
2115
|
+
if self.outline:
|
|
2116
|
+
# Named because the listing above is per family and the addresses are what the
|
|
2117
|
+
# caller came for: one flag away, and never printed by the hundred unasked.
|
|
2118
|
+
said.append(
|
|
2119
|
+
f" `{invocation()} anchors --family <anchor>` lists the addresses under one"
|
|
2120
|
+
)
|
|
2121
|
+
return chr(10).join(said)
|
|
2122
|
+
|
|
2123
|
+
def payload(self, config: Config, claims: bool) -> dict[str, object]:
|
|
2124
|
+
return {
|
|
2125
|
+
"role": self.role or None,
|
|
2126
|
+
# Every file the answer was read from, and not one (RK297): a client comparing two
|
|
2127
|
+
# runs needs to know which outline it was handed.
|
|
2128
|
+
"files": [config.relative(config.path(one)) for one in self.read],
|
|
2129
|
+
"family": self.family or None,
|
|
2130
|
+
"block": self.block or None,
|
|
2131
|
+
"block_families": list(self.spans),
|
|
2132
|
+
"live": len(self.found) - len(self.retired),
|
|
2133
|
+
"retired": len(self.retired),
|
|
2134
|
+
# The rows are the answer where a family was named, and the families are the answer
|
|
2135
|
+
# where none was (RK264's rule): 287 retired addresses is not a listing anybody
|
|
2136
|
+
# reads. Under `--claims` the rows *are* the answer whatever the family (RK459).
|
|
2137
|
+
"anchors": [
|
|
2138
|
+
_anchor_row(one)
|
|
2139
|
+
for one in self.found
|
|
2140
|
+
if self.family or (claims and _ownership(one))
|
|
2141
|
+
],
|
|
2142
|
+
"families": [] if self.family else self.families(),
|
|
2143
|
+
"id_anchors": self.spent,
|
|
2144
|
+
# Both free addresses are the **project's** even where the listing was narrowed
|
|
2145
|
+
# (RK297): the field an author acts on may not be per file.
|
|
2146
|
+
"next": next_child(self.whole, self.family) if self.family else None,
|
|
2147
|
+
# The question one line up, asked **per namespace** and nowhere else (RK340,
|
|
2148
|
+
# RK346). One row where a project declares no `[refs]`, whose `namespace` is null,
|
|
2149
|
+
# and one per namespace where it does; `next` is null inside a row where those
|
|
2150
|
+
# top-levels are not one numbering, which is an answer and not an absence.
|
|
2151
|
+
#
|
|
2152
|
+
# Without `opens`, which the narrow payload carries and this one does not: there
|
|
2153
|
+
# the free address is the whole answer and the command that makes it a section is
|
|
2154
|
+
# what it owes (RK1140); here the listing already names every family, and a client
|
|
2155
|
+
# reading this one is not composing an `add --ref` off a single line.
|
|
2156
|
+
"next_families": []
|
|
2157
|
+
if self.family
|
|
2158
|
+
else [
|
|
2159
|
+
{"namespace": space or None, "next": next_family(self.spread, space)}
|
|
2160
|
+
for space in namespaces(self.spread)
|
|
2161
|
+
],
|
|
2162
|
+
# What no question asked and only the gate said (RK297): an address two headings
|
|
2163
|
+
# answer to is one no pointer resolves against.
|
|
2164
|
+
"doubled": [
|
|
2165
|
+
{"anchor": anchor, "files": list(roles)}
|
|
2166
|
+
for anchor, roles in doubled(self.whole)
|
|
2167
|
+
],
|
|
2168
|
+
}
|
|
2169
|
+
|
|
2170
|
+
|
|
2171
|
+
def _anchor_row(one: Anchor) -> dict[str, object]:
|
|
2172
|
+
return {
|
|
2173
|
+
"anchor": one.anchor,
|
|
2174
|
+
# Which file declared it, which is the whole of RK297 in one field: two rows with one
|
|
2175
|
+
# address are two headings, and unlabelled they read as a listing that repeated.
|
|
2176
|
+
"role": one.role,
|
|
2177
|
+
"live": one.live,
|
|
2178
|
+
"written_in": one.written_in or None,
|
|
2179
|
+
# The two facts RK453 adds, and they are two because they come apart in both
|
|
2180
|
+
# directions: a heading binding nobody that a line claims is RK452's write left undone
|
|
2181
|
+
# on an older corpus, and one binding a task no live line claims is prose whose task
|
|
2182
|
+
# has shipped. Null and `[]` on a retired address, which has no heading.
|
|
2183
|
+
"binds": one.binds or None,
|
|
2184
|
+
"claimed": list(one.claimed),
|
|
2185
|
+
"orphaned": one.orphaned,
|
|
2186
|
+
# The third state, told apart from the two that are (RK461): a memo is prose that was
|
|
2187
|
+
# never anybody's, so it is neither bound nor left behind, and a client filtering on
|
|
2188
|
+
# `orphaned` alone used to catch it.
|
|
2189
|
+
"memo": one.memo,
|
|
2190
|
+
}
|
|
2191
|
+
|
|
2192
|
+
|
|
2193
|
+
def gaps(config: Config) -> tuple[Gap, ...]:
|
|
2194
|
+
"""Every id below the highest that no line carries, oldest number first.
|
|
2195
|
+
|
|
2196
|
+
The gaps are computed from the *entries* of both files rather than from a text scan:
|
|
2197
|
+
an id mentioned in prose — `agents.md` cites plenty — is still a gap, because what is
|
|
2198
|
+
missing is the record of a decision and not the string.
|
|
2199
|
+
|
|
2200
|
+
Per family, and in declared order (RK74): each track counts on its own, so a `C##`
|
|
2201
|
+
that reached 40 says nothing about which `V##` are missing, and one range walked over
|
|
2202
|
+
the highest id anywhere would report every unreached number of every other track.
|
|
2203
|
+
"""
|
|
2204
|
+
searched = searchable(config)
|
|
2205
|
+
return tuple(
|
|
2206
|
+
gap
|
|
2207
|
+
for family in config.schema.prefixes
|
|
2208
|
+
for gap in _gaps_in(config, family, searched)
|
|
2209
|
+
)
|
|
2210
|
+
|
|
2211
|
+
|
|
2212
|
+
def searchable(config: Config) -> bool:
|
|
2213
|
+
"""Whether an empty `git log` here means *never* rather than *cannot tell* (RK95).
|
|
2214
|
+
|
|
2215
|
+
A missing git, a directory that is not a repository and a shallow clone all return
|
|
2216
|
+
nothing for an id some commit does carry. Only a history that reaches its root commit
|
|
2217
|
+
makes the absence of a hit a fact about the id instead of one about the clone.
|
|
2218
|
+
|
|
2219
|
+
Asked once per call and not per gap: it is a property of the checkout, and the answer
|
|
2220
|
+
is what separates the two ways :class:`Gap` has of holding no commit.
|
|
2221
|
+
"""
|
|
2222
|
+
try:
|
|
2223
|
+
answer = _run(config.root, "rev-parse", "--is-shallow-repository").strip()
|
|
2224
|
+
except HistoryUnavailable:
|
|
2225
|
+
return False
|
|
2226
|
+
return answer == "false"
|
|
2227
|
+
|
|
2228
|
+
|
|
2229
|
+
def _gaps_in(config: Config, family: str, searched: bool) -> tuple[Gap, ...]:
|
|
2230
|
+
from roadkeep.ids import highest # here, because ids.py reads this module's config
|
|
2231
|
+
|
|
2232
|
+
top = highest(config, family)
|
|
2233
|
+
if top is None:
|
|
2234
|
+
return ()
|
|
2235
|
+
recorded: set[int] = set()
|
|
2236
|
+
for role in ("roadmap", "changelog"):
|
|
2237
|
+
if not config.has(role) or not config.path(role).is_file():
|
|
2238
|
+
continue
|
|
2239
|
+
for task_id in config.document(role).by_id():
|
|
2240
|
+
number = _number(task_id, family)
|
|
2241
|
+
if number is not None:
|
|
2242
|
+
recorded.add(number)
|
|
2243
|
+
return tuple(
|
|
2244
|
+
Gap(
|
|
2245
|
+
id=f"{family}{number}",
|
|
2246
|
+
number=number,
|
|
2247
|
+
removed_in=_last_touching(config, f"**{family}{number}**"),
|
|
2248
|
+
searched=searched,
|
|
2249
|
+
)
|
|
2250
|
+
for number in range(1, top.number + 1)
|
|
2251
|
+
if number not in recorded
|
|
2252
|
+
)
|
|
2253
|
+
|
|
2254
|
+
|
|
2255
|
+
def _number(task_id: str, prefix: str) -> int | None:
|
|
2256
|
+
tail = task_id[len(prefix) :] if task_id.startswith(prefix) else ""
|
|
2257
|
+
return int(tail) if tail.isdigit() else None
|
|
2258
|
+
|
|
2259
|
+
|
|
2260
|
+
def _last_touching(config: Config, needle: str) -> Commit | None:
|
|
2261
|
+
"""The last commit whose roadmap diff mentions the id — where the line left.
|
|
2262
|
+
|
|
2263
|
+
The last and not the first: the first added it. A removal is not distinguished from a
|
|
2264
|
+
rewording here, because a line that was reworded and is now absent still left in that
|
|
2265
|
+
commit, and the commit message is what the reader is being sent to read.
|
|
2266
|
+
"""
|
|
2267
|
+
try:
|
|
2268
|
+
found = _touching_role(config, needle, "roadmap")
|
|
2269
|
+
except HistoryUnavailable:
|
|
2270
|
+
return None
|
|
2271
|
+
return found[-1] if found else None
|
|
2272
|
+
|
|
2273
|
+
|
|
2274
|
+
def _first_touching(config: Config, needle: str, role: str) -> Commit | None:
|
|
2275
|
+
found = _touching_role(config, needle, role)
|
|
2276
|
+
return found[0] if found else None
|
|
2277
|
+
|
|
2278
|
+
|
|
2279
|
+
def _touching_role(
|
|
2280
|
+
config: Config, needle: str, role: str, *, literal: bool = True
|
|
2281
|
+
) -> tuple[Commit, ...]:
|
|
2282
|
+
if not config.has(role):
|
|
2283
|
+
return ()
|
|
2284
|
+
try:
|
|
2285
|
+
relative = config.path(role).relative_to(config.root)
|
|
2286
|
+
except ValueError:
|
|
2287
|
+
relative = config.path(role)
|
|
2288
|
+
return commits_touching(config.root, needle, relative, literal=literal)
|
|
2289
|
+
|
|
2290
|
+
|
|
2291
|
+
@dataclass(frozen=True, slots=True)
|
|
2292
|
+
class Gapped:
|
|
2293
|
+
"""Every id below the highest that no file carries, as one result (RK1170).
|
|
2294
|
+
|
|
2295
|
+
The second verb moved to the shape RK1170 asks for, and `weight`'s reasons hold unchanged:
|
|
2296
|
+
both registers are derived here, beside the numbers, so the payload carries what the printed
|
|
2297
|
+
answer showed by construction. What the handler keeps is the door — run it, and say which
|
|
2298
|
+
register was asked for.
|
|
2299
|
+
|
|
2300
|
+
The two registers differ on purpose, and here that difference is the whole of RK1165: the
|
|
2301
|
+
printed one collapses a **contiguous run** of never-carried ids into a single row, because 499
|
|
2302
|
+
of this repository's own 503 lines were a numbering jump saying one sentence with a different
|
|
2303
|
+
number. The payload keeps every id, a key costing a client nothing to skip where a line costs
|
|
2304
|
+
every reader the same attention.
|
|
2305
|
+
"""
|
|
2306
|
+
|
|
2307
|
+
gaps: tuple[Gap, ...]
|
|
2308
|
+
|
|
2309
|
+
def __str__(self) -> str:
|
|
2310
|
+
if not self.gaps:
|
|
2311
|
+
return "no gaps: every id below the highest is in one of the files"
|
|
2312
|
+
rows: list[tuple[str, str]] = []
|
|
2313
|
+
at = 0
|
|
2314
|
+
for gap, run in _runs(self.gaps):
|
|
2315
|
+
where = gap.id if run == 1 else f"{gap.id}–{self.gaps[at + run - 1].id}"
|
|
2316
|
+
at += run
|
|
2317
|
+
if gap.never_carried:
|
|
2318
|
+
# **Every** run and not a long one (RK1165): a threshold would be a number nobody
|
|
2319
|
+
# can re-read, and two consecutive ids in one row is the same information rather
|
|
2320
|
+
# than less. What decides the row is contiguity, which is a fact and not a
|
|
2321
|
+
# judgement about why the numbering skipped.
|
|
2322
|
+
counted = "" if run == 1 else f" ({run} ids)"
|
|
2323
|
+
rows.append(
|
|
2324
|
+
(where, f"never carried the whole history mentions it nowhere{counted}")
|
|
2325
|
+
)
|
|
2326
|
+
elif gap.removed_in is None:
|
|
2327
|
+
rows.append((where, "unresolvable no history here to search"))
|
|
2328
|
+
else:
|
|
2329
|
+
commit = gap.removed_in
|
|
2330
|
+
rows.append((where, f"{commit.short} {commit.date[:10]} {commit.subject}"))
|
|
2331
|
+
# Padded to the widest label, which a range is: a column sized for one id puts the
|
|
2332
|
+
# sentence of a collapsed row in a different place from every other one.
|
|
2333
|
+
width = max(len(label) for label, _ in rows)
|
|
2334
|
+
resolved = sum(1 for gap in self.gaps if gap.resolved)
|
|
2335
|
+
skipped = sum(1 for gap in self.gaps if gap.never_carried)
|
|
2336
|
+
tail = f", {skipped} never carried" if skipped else ""
|
|
2337
|
+
return "\n".join(
|
|
2338
|
+
[
|
|
2339
|
+
*(f" {label:<{width}} {said}" for label, said in rows),
|
|
2340
|
+
f"{len(self.gaps)} gap(s), {resolved} resolved against history{tail}",
|
|
2341
|
+
]
|
|
2342
|
+
)
|
|
2343
|
+
|
|
2344
|
+
def payload(self) -> list[dict[str, object]]:
|
|
2345
|
+
"""Every gap, one row each — the runs the printed answer collapses are the reader's cost.
|
|
2346
|
+
|
|
2347
|
+
The commit is the four fields a caller reaches an id's departure by, and `None` where
|
|
2348
|
+
history was searched and answered nothing: *unresolvable* and *never carried* are two
|
|
2349
|
+
different absences (RK95), which the two flags beside it tell apart.
|
|
2350
|
+
"""
|
|
2351
|
+
return [
|
|
2352
|
+
{
|
|
2353
|
+
"id": gap.id,
|
|
2354
|
+
"resolved": gap.resolved,
|
|
2355
|
+
"never_carried": gap.never_carried,
|
|
2356
|
+
"removed_in": None
|
|
2357
|
+
if gap.removed_in is None
|
|
2358
|
+
else {
|
|
2359
|
+
"sha": gap.removed_in.sha,
|
|
2360
|
+
"short": gap.removed_in.short,
|
|
2361
|
+
"date": gap.removed_in.date,
|
|
2362
|
+
"subject": gap.removed_in.subject,
|
|
2363
|
+
},
|
|
2364
|
+
}
|
|
2365
|
+
for gap in self.gaps
|
|
2366
|
+
]
|
|
2367
|
+
|
|
2368
|
+
|
|
2369
|
+
def _runs(found: Sequence[Gap]) -> list[tuple[Gap, int]]:
|
|
2370
|
+
"""Each gap with how many **contiguous never-carried** ids start there (RK1165).
|
|
2371
|
+
|
|
2372
|
+
Only that kind runs together: a gap resolved against history carries a commit of its own and
|
|
2373
|
+
two of them are two answers, however adjacent their numbers. What a run of never-carried ids
|
|
2374
|
+
carries is one sentence repeated, and this is what lets the row say it once.
|
|
2375
|
+
|
|
2376
|
+
Contiguity is read off the numbers the ids spell, which `next_id` already treats as a
|
|
2377
|
+
sequence — a prefix change ends a run for free, two families being two sequences.
|
|
2378
|
+
"""
|
|
2379
|
+
out: list[tuple[Gap, int]] = []
|
|
2380
|
+
index = 0
|
|
2381
|
+
while index < len(found):
|
|
2382
|
+
gap = found[index]
|
|
2383
|
+
run = 1
|
|
2384
|
+
if gap.never_carried:
|
|
2385
|
+
while index + run < len(found) and _follows(found[index + run - 1], found[index + run]):
|
|
2386
|
+
run += 1
|
|
2387
|
+
out.append((gap, run))
|
|
2388
|
+
index += run
|
|
2389
|
+
return out
|
|
2390
|
+
|
|
2391
|
+
|
|
2392
|
+
def _follows(earlier: Gap, later: Gap) -> bool:
|
|
2393
|
+
"""Whether one never-carried id is the next number after another, in the same family."""
|
|
2394
|
+
if not later.never_carried:
|
|
2395
|
+
return False
|
|
2396
|
+
one, two = _numbered(earlier.id), _numbered(later.id)
|
|
2397
|
+
return one is not None and two is not None and one[0] == two[0] and two[1] == one[1] + 1
|
|
2398
|
+
|
|
2399
|
+
|
|
2400
|
+
def _numbered(task_id: str) -> tuple[str, int] | None:
|
|
2401
|
+
"""An id as its family and its number, or None where it spells neither."""
|
|
2402
|
+
found = re.match(r"^([A-Za-z]+)(\d+)$", task_id)
|
|
2403
|
+
return (found[1], int(found[2])) if found else None
|