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/ranking.py ADDED
@@ -0,0 +1,139 @@
1
+ """Order a block's delivered claims by a sentence about to be proposed (RK442).
2
+
3
+ `delivered` is one of the two reads before an `add`, and it was the last query answering by
4
+ printing the file: `delivered B` is 103 lines and 9,773 bytes spent to decide one question,
5
+ which is L5 unapplied to its own verb. What the author actually asks is *does this collide
6
+ with something already shipped*, and the entries that could answer it are a handful.
7
+
8
+ So the entries are ranked against the proposed sentence and the nearest few are printed.
9
+ Measured on the `superseded by` pairs this ledger records — the only cases where the right
10
+ answer is known — the true partner lands at #2, #2, #1 and #1 inside its own block, against 31,
11
+ 102, 65 and 71 entries. Five lines instead of a hundred, same recall.
12
+
13
+ **Four of five, and the fifth is not a miss** (RK1183). A retirement may name the task that
14
+ delivered the larger half of a claim rather than the one whose symptom matches: RK1182 names
15
+ RK1152, and this read places RK348 first — whose sentence is nearly RK1182's own, and which
16
+ delivered the other half. The reach is over pairs whose *sentences* are the pair, which is what
17
+ a proposal about to be written has, so `tests/test_ranking.py` holds the count as a floor and
18
+ publishes what is out of reach rather than exempting it by name.
19
+
20
+ Three constraints are the whole design, and each is a thing this deliberately does not do:
21
+
22
+ * **It never refuses and never warns.** RK441 measured that the absolute score separates
23
+ nothing — two of those four true pairs score below the 13th percentile of the top-1 score
24
+ a proposal with *no* duplicate produces, so a threshold catching all four flags 419 of
25
+ 426. The absence of a gate is a known result and not caution, and it is why :func:`nearest`
26
+ returns an *order* and no number: publishing a score invites the threshold the measurement
27
+ rules out. Relative order inside one query carries signal; the score does not travel
28
+ between queries.
29
+ * **It stores no index.** BM25 rebuilt per call costs 0.23 ms over these 426 entries and
30
+ 0.73 ms over Turing's 892 — a second store would buy nothing and cost L2.
31
+ * **It takes no dependency.** The ranking below is stdlib. Lucene is a JVM and every Python
32
+ index is a wheel, in a tool whose whole promise is `argparse` + `tomllib`.
33
+
34
+ The no-model non-goal is not reached. Nothing here writes prose or judges meaning; it orders
35
+ lines that already exist by word overlap, and the answer is unchanged in kind — the author
36
+ still reads it and still decides.
37
+ """
38
+
39
+ from __future__ import annotations
40
+
41
+ import math
42
+ import re
43
+ from collections import Counter
44
+ from collections.abc import Sequence
45
+
46
+ #: Runs of letters and digits, lowercased. Not a stemmer and not a stopword list: both are
47
+ #: judgements about a language, and the corpora this reads are four projects' English plus
48
+ #: whatever identifiers their symptoms carry. BM25's own idf already discounts a word that
49
+ #: is in every entry, which is the whole of what a stopword list would have bought here.
50
+ _WORD = re.compile(r"[0-9a-z]+")
51
+
52
+ #: How many entries `delivered --near` prints. Five, because the worst of the four cases
53
+ #: where the right answer is known lands at #2 — so five is the recall of a hundred with
54
+ #: three ranks of headroom, and the figure moves only if a pair is ever found further down.
55
+ #: Not configuration (L6): a project declares its limits, and this is a property of how far
56
+ #: down the true answer has ever been, which a project cannot know about its own ledger.
57
+ NEAREST = 5
58
+
59
+ #: How many an `add` volunteers beside the line it just wrote (RK1370). Three and not
60
+ #: :data:`NEAREST`, because the two answer different callers: that one is asked for and sized
61
+ #: for recall, and this one arrives unrequested on every `add`, so it is sized to be read. The
62
+ #: worst of the four cases where the right answer is known lands at #2, so three keeps every
63
+ #: pair this ledger knows about with a rank of headroom. Not configuration (L6), for the reason
64
+ #: the number above is not.
65
+ #:
66
+ #: **Unfiltered, like the read it volunteers.** A first cut dropped entries sharing no word
67
+ #: with the symptom, so an `add` nobody had a neighbour for would say nothing. Measured against
68
+ #: this ledger it did not work and could not: a query about a leaking kitchen floor keeps three
69
+ #: of Block C's entries on `the`, `is` and `an`, and the one term that discriminates — `floor`,
70
+ #: in one entry of 137 — is indistinguishable at that door from `filed` or `delivered`. Which
71
+ #: is RK441's own finding arriving from the other side: no threshold separates a duplicate from
72
+ #: a neighbour, so a filter here would be the impossible gate rebuilt as a silence. The rows are
73
+ #: the same rows `--near` prints, and the sentence above them says what the order is not.
74
+ VOLUNTEERED = 3
75
+
76
+ #: Saturation and length normalisation, at the figures BM25 is published with. Not
77
+ #: configuration (L6): a project declares how long its lines may be, and these are
78
+ #: properties of the ranking rather than of the backlog it is run over.
79
+ _K1 = 1.5
80
+ _B = 0.75
81
+
82
+
83
+ def words(text: str) -> list[str]:
84
+ """The tokens a sentence contributes, in order of appearance."""
85
+ return _WORD.findall(text.lower())
86
+
87
+
88
+ def nearest(query: str, corpus: Sequence[str], count: int) -> tuple[int, ...]:
89
+ """The indices of the ``count`` entries of ``corpus`` closest to ``query``, nearest first.
90
+
91
+ Indices and not scores, and not the strings either: the caller holds the entries and
92
+ everything about them the answer has to print, and what this knows is only the order.
93
+ That is also the shape RK441 argues for — a caller handed a score is one turn from a
94
+ threshold the measurement says cannot exist.
95
+
96
+ Ties keep the corpus's own order, which is the ledger's, so two entries a query cannot
97
+ separate are printed in the order they shipped rather than in whatever order a sort
98
+ happened to leave them. An entry sharing no word with the query scores zero and is
99
+ still returned where the count is not filled: "these are the nearest" is true of a
100
+ block whose every entry is far, and dropping them would make an empty answer mean two
101
+ things again — nothing near, and nothing at all.
102
+ """
103
+ if count <= 0 or not corpus:
104
+ return ()
105
+ documents = [words(text) for text in corpus]
106
+ scored = _scores(words(query), documents)
107
+ order = sorted(range(len(corpus)), key=lambda index: (-scored[index], index))
108
+ return tuple(order[:count])
109
+
110
+
111
+ def _scores(query: Sequence[str], documents: Sequence[Sequence[str]]) -> list[float]:
112
+ """BM25 for one query over a corpus built for it and thrown away.
113
+
114
+ Okapi BM25, which is fifty lines here because the corpus is small enough to hold in a
115
+ list: the inverse document frequency of each query term, weighted by how often the term
116
+ occurs in the entry and damped by how long that entry is against the average. A term the
117
+ query repeats counts once — a symptom is one sentence, and a word said twice in it is
118
+ emphasis rather than evidence.
119
+ """
120
+ total = len(documents)
121
+ lengths = [len(document) for document in documents]
122
+ average = sum(lengths) / total if total else 0.0
123
+ counted = [Counter(document) for document in documents]
124
+ scores = [0.0] * total
125
+ for term in dict.fromkeys(query):
126
+ holding = sum(1 for count in counted if term in count)
127
+ if not holding:
128
+ continue
129
+ # The +0.5 terms are the published smoothing, and the outer 1 + … is what keeps a
130
+ # term present in every entry at zero rather than negative: a word the whole block
131
+ # shares is no evidence, and evidence *against* is not a thing word overlap knows.
132
+ idf = math.log(1 + (total - holding + 0.5) / (holding + 0.5))
133
+ for index, count in enumerate(counted):
134
+ frequency = count.get(term, 0)
135
+ if not frequency:
136
+ continue
137
+ damping = _K1 * (1 - _B + _B * lengths[index] / average) if average else _K1
138
+ scores[index] += idf * frequency * (_K1 + 1) / (frequency + damping)
139
+ return scores
roadkeep/referring.py ADDED
@@ -0,0 +1,231 @@
1
+ """Reference as a field type — the relations this backlog has, declared (RK1066).
2
+
3
+ A field whose type is a *reference* carries its own integrity, and this gate asks that
4
+ question in three vocabularies: a dep names an id, a pointer names a heading, a queue entry
5
+ names an id or a block. Sixteen of the thirty-eight codes those four families emit are
6
+ reference questions, and the argument for declaring them is that a **fourth** relation
7
+ should be a line here rather than a fourth implementation somewhere.
8
+
9
+ **What measuring found, and it is not what §RK1066 assumed.** That section reads *deps
10
+ resolve in backlog.py, pointers and orphan sections in linting.py and the queue's tokens in a
11
+ third place*. There is no third place: `_queued` calls `Backlog.resolve_dep` and turns one
12
+ :class:`~roadkeep.backlog.Resolution` into the `priority.*` codes, so the queue and the deps
13
+ have shared one machine since RK326. Two vocabularies, one resolver. What was missing was
14
+ never the resolver — it was the **index**: nothing said which relations exist, which machine
15
+ each uses, or which codes each is the source of, so the answer to "where does a fourth one
16
+ go" was a reading of three modules.
17
+
18
+ So this is that index, and its one hard property is that it is **total**. Every reference
19
+ code the gate can emit is named by exactly one relation, and every rule that stays code is
20
+ named in :data:`ELSEWHERE` with the reason it cannot be a constraint over a record. A
21
+ declaration listing only the half that fit is the second source of truth this tool exists to
22
+ remove, and it would be one carrying the tool's own authority — so `tests/test_referring.py`
23
+ holds the closure rather than this paragraph.
24
+
25
+ The line this draws is the one that decides whether a declaration is worth anything: a
26
+ vocabulary of *scalar* types — string, max, enum — buys none of this, and a **relational**
27
+ one buys all of it. A `maxLength` with better branding is not the thing.
28
+ """
29
+
30
+ from __future__ import annotations
31
+
32
+ from collections.abc import Mapping
33
+ from dataclasses import dataclass
34
+
35
+
36
+ @dataclass(frozen=True, slots=True)
37
+ class Relation:
38
+ """One kind of reference a record's field can carry, and what answers about it.
39
+
40
+ `resolver` is the code that says what the target *is*, named rather than imported: this
41
+ module is an index and importing the three would make it a layer. `answers` is every
42
+ gate code this relation is the source of, which is what makes the index checkable —
43
+ a code belonging to no relation and to no :data:`ELSEWHERE` entry is a rule nothing here
44
+ accounts for, and that is the state this file exists to make impossible.
45
+ """
46
+
47
+ #: What the field means, in the words the format uses for it.
48
+ name: str
49
+ #: The field that carries it, as the record spells it.
50
+ field: str
51
+ #: What a value points at: an id, a heading anchor, or either an id or a block label.
52
+ targets: str
53
+ #: The value meaning *no reference*, which is not an unresolved one — a line with no
54
+ #: deps is complete, and a resolver that could not tell the two apart would report
55
+ #: every such line. `""` where the field is simply absent.
56
+ empty: str
57
+ #: Where the target's state is decided, by qualified name.
58
+ resolver: str
59
+ #: Every code this relation is the source of.
60
+ answers: tuple[str, ...]
61
+
62
+
63
+ #: The four relations this backlog has. Two share a resolver and two do not, which is a
64
+ #: fact about the target space rather than an omission: an id lives in a set of records and a
65
+ #: heading lives in a tree of prose, and a resolver that pretended otherwise would answer
66
+ #: `ref.ambiguous` — two files declaring one anchor — with a lookup that has no such case.
67
+ #:
68
+ #: The fourth arrived the way this index was written to make possible (RK1106): a citation
69
+ #: was always a reference and nothing resolved it, so `ship` deleted designs other designs
70
+ #: argued from and the gate reported clean over 11 of them in claude-tray and 25 in Turing.
71
+ #: What it cost to add was a row here, a scan `citing` already had, and the pointer's own
72
+ #: resolver — which is the argument §RK1066 made and could not yet demonstrate.
73
+ RELATIONS: tuple[Relation, ...] = (
74
+ Relation(
75
+ name="dep",
76
+ field="deps",
77
+ targets="id",
78
+ # The em dash a rendered line carries where a task waits on nothing (`NO_DEPS`).
79
+ empty="—",
80
+ resolver="roadkeep.backlog.Backlog.resolve_dep",
81
+ answers=("deps.unknown", "deps.retired", "deps.cycle", "deps.block"),
82
+ ),
83
+ Relation(
84
+ name="pointer",
85
+ field="ref",
86
+ targets="heading",
87
+ empty="",
88
+ resolver="roadkeep.sections.anchored",
89
+ answers=(
90
+ "ref.unresolved",
91
+ "ref.ambiguous",
92
+ "section.orphan",
93
+ "section.unreachable",
94
+ # The same ambiguity from the target's side (RK239): two prose files declaring
95
+ # one anchor is a defect at both headings whether or not a line reached it.
96
+ # §RK1066 counted four here and there are five, which the closure test found on
97
+ # its first run — the argument for a total index, made by the index.
98
+ "section.ambiguous",
99
+ ),
100
+ ),
101
+ Relation(
102
+ name="citation",
103
+ # Not a field of a task line at all — the first relation whose carrier is prose, which
104
+ # is why it took a scan to find and not a lookup: `body` is the whole paragraph, and
105
+ # which of its tokens is a reference is `sections.references`' reading to make.
106
+ field="body",
107
+ targets="heading",
108
+ empty="",
109
+ # The pointer's resolver, deliberately: a citation of `§S:I.2` resolves in the same
110
+ # index a `→ §S:I.2` does, and two answers about one address would be the disagreement
111
+ # this file exists to prevent — one of them across the namespaces and one inside a file.
112
+ resolver="roadkeep.sections.anchored",
113
+ # Two, since RK1168: an address neither file declares is `ref.dangling`, and one that
114
+ # resolves into the *other* prose file while the citing file declares the same address
115
+ # is `ref.crossed` — the state a namespace leaves behind, which reads as correct.
116
+ answers=("ref.dangling", "ref.crossed"),
117
+ ),
118
+ Relation(
119
+ name="queued",
120
+ field="priority",
121
+ targets="id-or-block",
122
+ empty="",
123
+ # The same machine the deps use, which is the half of RK1066 that was already
124
+ # done: `_queued` reads one `Resolution` and spells it in this family's codes.
125
+ resolver="roadkeep.backlog.Backlog.resolve_dep",
126
+ answers=(
127
+ "priority.unknown",
128
+ "priority.shipped",
129
+ "priority.retired",
130
+ "priority.deferred",
131
+ "priority.block",
132
+ "priority.block-empty",
133
+ "priority.block-paused",
134
+ "priority.block-unstarted",
135
+ ),
136
+ ),
137
+ )
138
+
139
+
140
+ @dataclass(frozen=True, slots=True)
141
+ class Carried:
142
+ """One pair of governed files that may not both hold a line for the same id (RK1082).
143
+
144
+ The fourth relation, and the same kind as the other three: a target, a sentinel meaning
145
+ *no reference*, and a policy for a target that turned out to be somewhere else. What
146
+ differs is the direction — a dep points at an id and this one points at a **file**, so
147
+ the pairs are a cross product over :data:`~roadkeep.ids.CARRIERS` rather than a rule
148
+ somebody writes per pair.
149
+
150
+ Written per pair and not folded into one message, which is the line RK1081 drew and this
151
+ keeps: open-and-gone, open-and-paused and gone-and-paused are three sentences with three
152
+ doors. The declaration holds *which pairs exist*; the wording and the remedy stay with
153
+ the code. A pair with no code yet is a pair nobody has walked into, and it says so here
154
+ rather than by being absent — which is the whole difference from the arrangement RK1077
155
+ was filed about, where a gap was found by the project that reached it.
156
+ """
157
+
158
+ #: The role a finding about this pair is filed against, and whose line number it carries.
159
+ first: str
160
+ #: The other file holding a line for the same id.
161
+ second: str
162
+ #: The gate code, or `""` where no rule reads this pair yet — and then :attr:`because`
163
+ #: says what is missing rather than leaving a silence.
164
+ code: str = ""
165
+ #: What the two files each claim, as the finding's own sentence spells it.
166
+ says: str = ""
167
+ #: Why there is no rule, on a pair whose `code` is empty.
168
+ because: str = ""
169
+
170
+
171
+ #: Every pair of governed files that can hold a line for one id (RK1082). Three, because
172
+ #: `CARRIERS` is three, and all three are read since RK1084 — which measured first and found
173
+ #: that **neither adopting corpus declares a store at all**, so the pair nobody had walked
174
+ #: into is one nobody *can* walk into yet. The rule is written anyway: a contradiction the
175
+ #: format can express should not be silent, and the cost of the third row is one entry here.
176
+ PAIRS: tuple[Carried, ...] = (
177
+ Carried(
178
+ first="roadmap",
179
+ second="changelog",
180
+ code="id.two-files",
181
+ says="open and recorded as gone are not both true",
182
+ ),
183
+ Carried(
184
+ first="roadmap",
185
+ second="deferred",
186
+ code="id.paused-and-open",
187
+ says="open and paused are not both true",
188
+ ),
189
+ Carried(
190
+ first="changelog",
191
+ second="deferred",
192
+ code="id.paused-and-gone",
193
+ says="recorded as gone and still paused are not both true",
194
+ ),
195
+ )
196
+
197
+
198
+ #: The rules in these four families that are **not** reference questions, each with why. Here
199
+ #: rather than left out, because the index has to name every rule including the ones it does
200
+ #: not implement: a reader asking "is this relation declared" must not have to know which
201
+ #: half of the file to look in. Three kinds — the shape of a value before anything is
202
+ #: resolved, a traversal that reads more than one record, and a procedure over history.
203
+ ELSEWHERE: Mapping[str, str] = {
204
+ # -- the shape of the value, which is a scalar question and stays one -------------
205
+ "deps.format": "the token's own shape, refused before any target is looked for",
206
+ "deps.range": "a range whose ends are the wrong way round: a shape, not a target",
207
+ "deps.compound": "two relations written into one token, which is a spelling",
208
+ "deps.self": "a line naming itself, decidable from the record alone",
209
+ "deps.duplicate": "one target named twice in one field, decidable from the field",
210
+ "deps.marker": "the cached annotation, which is derived and re-derived (RK8)",
211
+ "deps.stale": "the same annotation gone out of date, which `--fix` rewrites",
212
+ "deps.unexpected": "a field the role's grammar drops carrying a value (RK1064)",
213
+ # RK1229. About the *slot*, not about the target: a dep carrying `)` or the pointer arrow
214
+ # stops the rendered line parsing, which is decidable from the value and the grammar with
215
+ # nothing resolved — and is why it is refused before any target is looked for.
216
+ "deps.unrenderable": "text the deps group cannot carry back, decidable before resolving",
217
+ "deps.collective": "a note about what `Block X` names, not a defect about a target",
218
+ "ref.format": "the anchor's shape under `ref_scheme`, before it is resolved",
219
+ "ref.sigil": "the `§` itself, a character question",
220
+ "ref.missing": "a line that carries no pointer where the role requires one",
221
+ "ref.mismatch": "a pointer that is not the one the id derives (RK1063)",
222
+ "priority.shape": "a queue token that is neither an id nor a block label",
223
+ "priority.duplicate": "one token queued twice, decidable from the queue alone",
224
+ # -- traversals and procedures, which are not constraints over a record ----------
225
+ "section.too-long": "a word budget over a subtree, which is a traversal (RK9)",
226
+ "section.duplicate": "two headings at one address, a property of the prose file",
227
+ "section.stale": "a section whose task left, decided against the other files",
228
+ "section.unpaired": "a design with no line since a revision, which reads git",
229
+ "priority.config": "where the queue is declared, a fact about `roadkeep.toml`",
230
+ "priority.unmigrated": "a queue in the old home, a migration and not a target",
231
+ }