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/remaining.py
ADDED
|
@@ -0,0 +1,336 @@
|
|
|
1
|
+
"""What a task has left, derived from the repository rather than written down (RK492).
|
|
2
|
+
|
|
3
|
+
§RK72's non-goal refuses a **stored** size: nothing can verify a letter, so the field rots
|
|
4
|
+
from the first commit that makes it wrong. :mod:`roadkeep.weighing` is what replaced it —
|
|
5
|
+
the same question, derived from the commits that shipped comparable work, landing on no line
|
|
6
|
+
and rotting never. This is that question's mirror and it takes the same answer.
|
|
7
|
+
|
|
8
|
+
RK488, RK489, RK490 and RK491 were each one invariant with **sites**: emitters spelling a
|
|
9
|
+
command themselves, subparsers validating their own flags, rows repeating what their finding
|
|
10
|
+
already carries, rules no property reaches. Every one of them was enumerable by a query the
|
|
11
|
+
task could have declared — a grep over the package, a set difference against a table — and
|
|
12
|
+
none of them had a way to ask how many were left. So a migration read in every governed file
|
|
13
|
+
exactly like a run of unrelated defects, which is how the last fifty commits read here, and
|
|
14
|
+
the reading was wrong.
|
|
15
|
+
|
|
16
|
+
**Where the declaration lives is the whole of the decision.** Three places were possible and
|
|
17
|
+
two are wrong. A field on the line is what §RK72 refuses and what `[limits]` would then have
|
|
18
|
+
to price. `roadkeep.toml` outlives the task and is per project, so a query about one
|
|
19
|
+
migration would sit in it after the migration shipped, with nothing to delete it. What is
|
|
20
|
+
left is the **rationale section**, and it is not a fallback: the query is a statement about
|
|
21
|
+
the design, it is in the repository (L2), a `ship` deletes it with the section that made the
|
|
22
|
+
claim, and a reader who greps for the pattern finds the paragraph that says what it is for.
|
|
23
|
+
|
|
24
|
+
So a section may carry one fenced block tagged :data:`FENCE`, and each line in it is a
|
|
25
|
+
**pathspec and a pattern**. Nothing here interprets either: the glob is the author's and the
|
|
26
|
+
regex is the author's, which is L4 one level down — this counts what somebody else declared
|
|
27
|
+
and composes no part of the claim. The count is computed on demand, so it cannot go stale, it
|
|
28
|
+
costs nothing on the turns nobody asks (L5), and it is checkable by running the query printed
|
|
29
|
+
beside it.
|
|
30
|
+
|
|
31
|
+
What this is **not** is a progress bar. A query that answers `0` says the pattern no longer
|
|
32
|
+
matches, not that the work is done: the author chose the pattern, and a migration whose last
|
|
33
|
+
site is spelled differently is one this reports clean. That is stated rather than defended
|
|
34
|
+
against, for the reason the size field was refused — the alternative is a number the tool
|
|
35
|
+
asserts and nobody can check.
|
|
36
|
+
|
|
37
|
+
**And a zero that means neither of those is named** (RK1216). The sentence above has one more
|
|
38
|
+
reading it cannot carry: a pathspec that reached **no file at all**, where the pattern was
|
|
39
|
+
never run over anything. Measured in pportal declaring its first two queries — `lib/src ::
|
|
40
|
+
<regex>` on both, a directory that `Path.glob` matches as one entry that is not a file — and
|
|
41
|
+
both answered `0 site(s) left in 0 file(s)` over trees holding 14 and 420 sites. The count
|
|
42
|
+
this verb exists to be trusted with had a failure mode indistinguishable from success, and
|
|
43
|
+
the tell was a second number beside it. So :attr:`Remaining.unmatched` says it in words, on
|
|
44
|
+
the headline and per clause. Refusing was the other candidate and is not this module's to
|
|
45
|
+
make: a query is a claim in a file, and a claim nothing answers is the gate's kind of finding.
|
|
46
|
+
"""
|
|
47
|
+
|
|
48
|
+
from __future__ import annotations
|
|
49
|
+
|
|
50
|
+
import re
|
|
51
|
+
from collections.abc import Iterator, Sequence
|
|
52
|
+
from dataclasses import dataclass, field
|
|
53
|
+
from pathlib import Path
|
|
54
|
+
|
|
55
|
+
#: The info string a fenced block carries to be read as a query. Hyphenated rather than
|
|
56
|
+
#: `roadkeep:remaining`, because a colon in an info string is how several renderers spell a
|
|
57
|
+
#: language attribute and this has to survive being viewed on a forge.
|
|
58
|
+
FENCE = "roadkeep-remaining"
|
|
59
|
+
|
|
60
|
+
#: The other fence, and the same grammar (RK1184). A design says what is *left* and what would
|
|
61
|
+
#: *prove it done*, and the two are one read with the sign flipped — sites that must exist
|
|
62
|
+
#: rather than sites still there. A second tag and never a second parser: the clause, the
|
|
63
|
+
#: separator, the refusal and the count are all shared, so a query that is legal in one block
|
|
64
|
+
#: is legal in the other by construction.
|
|
65
|
+
EVIDENCE = "roadkeep-evidence"
|
|
66
|
+
|
|
67
|
+
#: What separates a pathspec from the pattern that marks a site. Two colons and not one: a
|
|
68
|
+
#: glob carries no `::` and a regex that wants one spells it `:{2}`, so the split is
|
|
69
|
+
#: unambiguous without anything here parsing either half.
|
|
70
|
+
SEPARATOR = "::"
|
|
71
|
+
|
|
72
|
+
#: How many addresses a report prints before it says how many more there are. The count is
|
|
73
|
+
#: the answer; the addresses are what makes it checkable, and a list nobody scrolls is a
|
|
74
|
+
#: list that costs context (RK146).
|
|
75
|
+
SHOWN = 10
|
|
76
|
+
|
|
77
|
+
|
|
78
|
+
class QueryError(ValueError):
|
|
79
|
+
"""A fence this grammar cannot read, naming the line inside it that failed."""
|
|
80
|
+
|
|
81
|
+
def __init__(self, line: int, said: str) -> None:
|
|
82
|
+
self.line = line
|
|
83
|
+
super().__init__(f"line {line} of the {FENCE} block: {said}")
|
|
84
|
+
|
|
85
|
+
|
|
86
|
+
@dataclass(frozen=True, slots=True)
|
|
87
|
+
class Clause:
|
|
88
|
+
"""One pathspec and the pattern that marks a site inside it."""
|
|
89
|
+
|
|
90
|
+
#: A glob relative to the project root, as `Path.glob` reads one.
|
|
91
|
+
pathspec: str
|
|
92
|
+
#: The pattern, as the author wrote it — kept as text beside the compiled form so the
|
|
93
|
+
#: report can print the query it ran rather than a repr of a compiled object.
|
|
94
|
+
pattern: str
|
|
95
|
+
matcher: re.Pattern[str]
|
|
96
|
+
|
|
97
|
+
def __str__(self) -> str:
|
|
98
|
+
return f"{self.pathspec} {SEPARATOR} {self.pattern}"
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
@dataclass(frozen=True, slots=True)
|
|
102
|
+
class Site:
|
|
103
|
+
"""One place the query still matches."""
|
|
104
|
+
|
|
105
|
+
file: str
|
|
106
|
+
lineno: int
|
|
107
|
+
text: str
|
|
108
|
+
|
|
109
|
+
def __str__(self) -> str:
|
|
110
|
+
return f"{self.file}:{self.lineno} {self.text.strip()}"
|
|
111
|
+
|
|
112
|
+
|
|
113
|
+
@dataclass(frozen=True, slots=True)
|
|
114
|
+
class Remaining:
|
|
115
|
+
"""What one task's declared query answers right now."""
|
|
116
|
+
|
|
117
|
+
task_id: str
|
|
118
|
+
clauses: tuple[Clause, ...]
|
|
119
|
+
sites: tuple[Site, ...]
|
|
120
|
+
#: Which fence this counted (RK1184). The numbers are identical and the sentences are
|
|
121
|
+
#: opposites: `3 site(s) left` is work outstanding, and `3 site(s) of evidence` is what
|
|
122
|
+
#: the author said would prove the task done. A field and not two classes, because every
|
|
123
|
+
#: other property of the read — the scan, the refusal, the truncation — is one thing.
|
|
124
|
+
kind: str = FENCE
|
|
125
|
+
#: How many files each clause actually read, so a query whose glob names nothing is
|
|
126
|
+
#: distinguishable from one whose pattern no longer matches. Two very different answers
|
|
127
|
+
#: that both count zero, and the second is done while the first is a typo.
|
|
128
|
+
scanned: tuple[int, ...] = ()
|
|
129
|
+
#: Files a clause matched and this could not read as text, by path. Named and never
|
|
130
|
+
#: skipped in silence: a count over a set that quietly lost a member is the defect this
|
|
131
|
+
#: whole module is against.
|
|
132
|
+
unread: tuple[str, ...] = ()
|
|
133
|
+
|
|
134
|
+
@property
|
|
135
|
+
def total(self) -> int:
|
|
136
|
+
return len(self.sites)
|
|
137
|
+
|
|
138
|
+
@property
|
|
139
|
+
def files(self) -> int:
|
|
140
|
+
return sum(self.scanned)
|
|
141
|
+
|
|
142
|
+
@property
|
|
143
|
+
def unmatched(self) -> tuple[str, ...]:
|
|
144
|
+
"""The pathspecs that reached no file at all, in declaration order (RK1216).
|
|
145
|
+
|
|
146
|
+
The distinction :attr:`scanned` was added to make and nothing then said out loud.
|
|
147
|
+
Measured on pportal declaring its first two queries: both were given `lib/src ::
|
|
148
|
+
<regex>`, which reads as a directory and which `Path.glob` matches as one entry that
|
|
149
|
+
is not a file, so both answered `0 site(s) left in 0 file(s)`. The regexes were right
|
|
150
|
+
— counted by hand the same trees hold 14 and 420, and corrected to `lib/src/**/*.c`
|
|
151
|
+
this tool agrees exactly. Nothing was wrong but the glob.
|
|
152
|
+
|
|
153
|
+
Which way the failure points is the whole finding. `0` is documented here to mean
|
|
154
|
+
*the pattern stopped matching*, so the reading an author gets is **the migration is
|
|
155
|
+
done**, and the truth was the opposite: the query never ran over anything. A failure
|
|
156
|
+
mode indistinguishable from success, on the one question the verb exists to answer.
|
|
157
|
+
|
|
158
|
+
The tell was already printed — `in 0 file(s)` sits beside the count — so this is
|
|
159
|
+
about which of the two the eye lands on. Named rather than left to that arithmetic,
|
|
160
|
+
and named per pathspec, because a query of three clauses where one reached nothing is
|
|
161
|
+
short by an unknown amount while still looking like a total.
|
|
162
|
+
"""
|
|
163
|
+
return tuple(
|
|
164
|
+
clause.pathspec
|
|
165
|
+
for clause, read in zip(self.clauses, self.scanned, strict=False)
|
|
166
|
+
if not read
|
|
167
|
+
)
|
|
168
|
+
|
|
169
|
+
@property
|
|
170
|
+
def counting(self) -> str:
|
|
171
|
+
"""`left` or `of evidence` — never a verdict either way (RK1184).
|
|
172
|
+
|
|
173
|
+
The pattern is the author's claim and the count is the answer, so `0` says the
|
|
174
|
+
evidence is not there yet and whether that is the work being done is the caller's
|
|
175
|
+
judgement. This tool has no model of one (L4).
|
|
176
|
+
"""
|
|
177
|
+
return "left" if self.kind == FENCE else "of evidence"
|
|
178
|
+
|
|
179
|
+
def __str__(self) -> str:
|
|
180
|
+
# On the **headline**, because the headline is the number being misread (RK1216): a
|
|
181
|
+
# note under the clauses is the `in 0 file(s)` problem again one line down.
|
|
182
|
+
never = ""
|
|
183
|
+
if self.unmatched:
|
|
184
|
+
never = (
|
|
185
|
+
f" — {len(self.unmatched)} pathspec(s) matched no file, so this count is "
|
|
186
|
+
f"a query that did not run and not work that is done"
|
|
187
|
+
)
|
|
188
|
+
lines = [
|
|
189
|
+
f"{self.task_id} {self.total} site(s) {self.counting} in {self.files} "
|
|
190
|
+
f"file(s){never}"
|
|
191
|
+
]
|
|
192
|
+
for clause, read in zip(self.clauses, self.scanned, strict=False):
|
|
193
|
+
# Marked per clause too, so a three-clause query says *which* one reached nothing
|
|
194
|
+
# rather than leaving the reader to find the zero among the counts.
|
|
195
|
+
missed = " ← matched no file" if not read else ""
|
|
196
|
+
lines.append(f" query {clause} ({read} file(s)){missed}")
|
|
197
|
+
for site in self.sites[:SHOWN]:
|
|
198
|
+
lines.append(f" site {site}")
|
|
199
|
+
if self.total > SHOWN:
|
|
200
|
+
lines.append(f" … and {self.total - SHOWN} more")
|
|
201
|
+
if self.unread:
|
|
202
|
+
lines.append(f" unread {', '.join(self.unread)}: not text this could search")
|
|
203
|
+
return "\n".join(lines)
|
|
204
|
+
|
|
205
|
+
def payload(self) -> dict[str, object]:
|
|
206
|
+
return {
|
|
207
|
+
"id": self.task_id,
|
|
208
|
+
# Which question was asked, because the two payloads are otherwise identical and
|
|
209
|
+
# a consumer acting on `total` means opposite things by it (RK1184).
|
|
210
|
+
"kind": self.kind,
|
|
211
|
+
"total": self.total,
|
|
212
|
+
"files": self.files,
|
|
213
|
+
"query": [
|
|
214
|
+
{"pathspec": one.pathspec, "pattern": one.pattern, "files": read}
|
|
215
|
+
for one, read in zip(self.clauses, self.scanned, strict=False)
|
|
216
|
+
],
|
|
217
|
+
# Every site and not the printed ten: a consumer acting per address needs them
|
|
218
|
+
# all, and the truncation above is about a terminal (RK146).
|
|
219
|
+
"sites": [{"file": s.file, "line": s.lineno, "text": s.text} for s in self.sites],
|
|
220
|
+
"unread": list(self.unread),
|
|
221
|
+
# The pathspecs that reached no file (RK1216). Its own key beside the per-clause
|
|
222
|
+
# `files`, because a consumer deciding whether a migration is finished is reading
|
|
223
|
+
# `total` — and the one state where `total` means nothing at all has to be
|
|
224
|
+
# answerable without summing a list to find a zero in it.
|
|
225
|
+
"unmatched": list(self.unmatched),
|
|
226
|
+
}
|
|
227
|
+
|
|
228
|
+
|
|
229
|
+
def declared(body: str, tag: str = FENCE) -> tuple[Clause, ...]:
|
|
230
|
+
"""The query a section's prose declares under ``tag``, or `()` where it declares none.
|
|
231
|
+
|
|
232
|
+
One fence per section **per tag** (RK1184). A second of the same kind is refused rather
|
|
233
|
+
than merged: two blocks are two claims about what is left, and the sum of them is a number
|
|
234
|
+
neither paragraph states. The two *kinds* are a different matter — a design may say both
|
|
235
|
+
what remains and what would prove it done, and neither is the other's total.
|
|
236
|
+
"""
|
|
237
|
+
found: list[Clause] = []
|
|
238
|
+
fences = list(_fenced(body, tag))
|
|
239
|
+
if len(fences) > 1:
|
|
240
|
+
raise QueryError(
|
|
241
|
+
fences[1][0] + 1, "a section declares one query, and this is the second"
|
|
242
|
+
)
|
|
243
|
+
for offset, block in fences:
|
|
244
|
+
# 1-based lines of the section body, so the number the refusal prints is one a
|
|
245
|
+
# reader counts down the paragraph — the fence itself is `offset + 1`.
|
|
246
|
+
for index, line in enumerate(block, start=offset + 2):
|
|
247
|
+
stripped = line.strip()
|
|
248
|
+
if not stripped or stripped.startswith("#"):
|
|
249
|
+
continue
|
|
250
|
+
found.append(_clause(index, stripped))
|
|
251
|
+
return tuple(found)
|
|
252
|
+
|
|
253
|
+
|
|
254
|
+
def _fenced(body: str, tag: str = FENCE) -> Iterator[tuple[int, list[str]]]:
|
|
255
|
+
"""Each ``` block carrying ``tag``, as its 0-based start line and its lines."""
|
|
256
|
+
lines = body.splitlines()
|
|
257
|
+
index = 0
|
|
258
|
+
while index < len(lines):
|
|
259
|
+
opening = lines[index].strip()
|
|
260
|
+
if opening.startswith("```") and opening[3:].strip() == tag:
|
|
261
|
+
end = index + 1
|
|
262
|
+
while end < len(lines) and not lines[end].strip().startswith("```"):
|
|
263
|
+
end += 1
|
|
264
|
+
yield index, lines[index + 1 : end]
|
|
265
|
+
index = end + 1
|
|
266
|
+
continue
|
|
267
|
+
index += 1
|
|
268
|
+
|
|
269
|
+
|
|
270
|
+
def _clause(lineno: int, line: str) -> Clause:
|
|
271
|
+
pathspec, separator, pattern = line.partition(SEPARATOR)
|
|
272
|
+
if not separator:
|
|
273
|
+
raise QueryError(lineno, f"no {SEPARATOR!r}: a clause is `<pathspec> {SEPARATOR} <regex>`")
|
|
274
|
+
pathspec, pattern = pathspec.strip(), pattern.strip()
|
|
275
|
+
if not pathspec or not pattern:
|
|
276
|
+
raise QueryError(lineno, "both halves are required: a pathspec, and the pattern")
|
|
277
|
+
try:
|
|
278
|
+
matcher = re.compile(pattern)
|
|
279
|
+
except re.error as error:
|
|
280
|
+
raise QueryError(lineno, f"the pattern is not a regex this can compile: {error}") from None
|
|
281
|
+
return Clause(pathspec=pathspec, pattern=pattern, matcher=matcher)
|
|
282
|
+
|
|
283
|
+
|
|
284
|
+
@dataclass(slots=True)
|
|
285
|
+
class _Read:
|
|
286
|
+
"""One clause's answer, before the clauses are joined."""
|
|
287
|
+
|
|
288
|
+
sites: list[Site] = field(default_factory=list)
|
|
289
|
+
scanned: int = 0
|
|
290
|
+
unread: list[str] = field(default_factory=list)
|
|
291
|
+
|
|
292
|
+
|
|
293
|
+
def count(
|
|
294
|
+
root: Path, task_id: str, clauses: Sequence[Clause], kind: str = FENCE
|
|
295
|
+
) -> Remaining:
|
|
296
|
+
"""Run a declared query against this tree, now.
|
|
297
|
+
|
|
298
|
+
Nothing is cached and nothing is written. The whole value of the read is that it is
|
|
299
|
+
taken at the moment somebody asks, which is what a stored count could never be.
|
|
300
|
+
"""
|
|
301
|
+
sites: list[Site] = []
|
|
302
|
+
scanned: list[int] = []
|
|
303
|
+
unread: list[str] = []
|
|
304
|
+
for clause in clauses:
|
|
305
|
+
read = _run(root, clause)
|
|
306
|
+
sites += read.sites
|
|
307
|
+
scanned.append(read.scanned)
|
|
308
|
+
unread += read.unread
|
|
309
|
+
return Remaining(
|
|
310
|
+
task_id=task_id,
|
|
311
|
+
kind=kind,
|
|
312
|
+
clauses=tuple(clauses),
|
|
313
|
+
sites=tuple(sites),
|
|
314
|
+
scanned=tuple(scanned),
|
|
315
|
+
unread=tuple(dict.fromkeys(unread)),
|
|
316
|
+
)
|
|
317
|
+
|
|
318
|
+
|
|
319
|
+
def _run(root: Path, clause: Clause) -> _Read:
|
|
320
|
+
read = _Read()
|
|
321
|
+
for path in sorted(root.glob(clause.pathspec)):
|
|
322
|
+
if not path.is_file():
|
|
323
|
+
continue
|
|
324
|
+
where = path.relative_to(root).as_posix()
|
|
325
|
+
try:
|
|
326
|
+
text = path.read_text(encoding="utf-8")
|
|
327
|
+
except (OSError, UnicodeDecodeError):
|
|
328
|
+
# Not an error and not silence: a clause whose glob reached a binary has read
|
|
329
|
+
# fewer files than it looks like, and the count is only honest if it says so.
|
|
330
|
+
read.unread.append(where)
|
|
331
|
+
continue
|
|
332
|
+
read.scanned += 1
|
|
333
|
+
for lineno, line in enumerate(text.splitlines(), start=1):
|
|
334
|
+
if clause.matcher.search(line):
|
|
335
|
+
read.sites.append(Site(file=where, lineno=lineno, text=line))
|
|
336
|
+
return read
|