roadkeep 0.2.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (67) hide show
  1. roadkeep/__init__.py +79 -0
  2. roadkeep/adopting.py +2347 -0
  3. roadkeep/attesting.py +293 -0
  4. roadkeep/authoring.py +2117 -0
  5. roadkeep/backlog.py +767 -0
  6. roadkeep/blocking.py +1622 -0
  7. roadkeep/briefing.py +970 -0
  8. roadkeep/budgeting.py +2056 -0
  9. roadkeep/capturing.py +1699 -0
  10. roadkeep/claiming.py +1019 -0
  11. roadkeep/cli.py +638 -0
  12. roadkeep/commanding.py +487 -0
  13. roadkeep/config.py +1832 -0
  14. roadkeep/counting.py +376 -0
  15. roadkeep/criteria.py +933 -0
  16. roadkeep/deferring.py +708 -0
  17. roadkeep/describing.py +568 -0
  18. roadkeep/exporting.py +808 -0
  19. roadkeep/fixing.py +629 -0
  20. roadkeep/governing.py +934 -0
  21. roadkeep/graph.py +395 -0
  22. roadkeep/guarding.py +1028 -0
  23. roadkeep/history.py +2403 -0
  24. roadkeep/ids.py +301 -0
  25. roadkeep/installing.py +2145 -0
  26. roadkeep/kernel/__init__.py +24 -0
  27. roadkeep/kernel/document.py +1719 -0
  28. roadkeep/kernel/schema.py +2308 -0
  29. roadkeep/linting.py +4420 -0
  30. roadkeep/locking.py +209 -0
  31. roadkeep/markers.py +172 -0
  32. roadkeep/merging.py +1159 -0
  33. roadkeep/picking.py +772 -0
  34. roadkeep/provenance.py +789 -0
  35. roadkeep/queueing.py +752 -0
  36. roadkeep/ranking.py +139 -0
  37. roadkeep/referring.py +231 -0
  38. roadkeep/remaining.py +336 -0
  39. roadkeep/remedying.py +1989 -0
  40. roadkeep/rendering.py +1601 -0
  41. roadkeep/renumbering.py +503 -0
  42. roadkeep/repairing.py +295 -0
  43. roadkeep/reverting.py +144 -0
  44. roadkeep/scoping.py +708 -0
  45. roadkeep/screening.py +196 -0
  46. roadkeep/sections.py +4121 -0
  47. roadkeep/serving.py +2909 -0
  48. roadkeep/shipping.py +3993 -0
  49. roadkeep/showing.py +613 -0
  50. roadkeep/storing.py +224 -0
  51. roadkeep/verbs/__init__.py +26 -0
  52. roadkeep/verbs/adopting.py +974 -0
  53. roadkeep/verbs/authoring.py +566 -0
  54. roadkeep/verbs/declaring.py +335 -0
  55. roadkeep/verbs/linting.py +645 -0
  56. roadkeep/verbs/querying.py +2138 -0
  57. roadkeep/verbs/reading.py +307 -0
  58. roadkeep/verbs/refusing.py +146 -0
  59. roadkeep/verbs/sections.py +1433 -0
  60. roadkeep/verbs/shipping.py +819 -0
  61. roadkeep/weighing.py +380 -0
  62. roadkeep-0.2.0.dist-info/METADATA +453 -0
  63. roadkeep-0.2.0.dist-info/RECORD +67 -0
  64. roadkeep-0.2.0.dist-info/WHEEL +5 -0
  65. roadkeep-0.2.0.dist-info/entry_points.txt +2 -0
  66. roadkeep-0.2.0.dist-info/licenses/LICENSE +202 -0
  67. roadkeep-0.2.0.dist-info/top_level.txt +1 -0
roadkeep/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