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/weighing.py ADDED
@@ -0,0 +1,380 @@
1
+ """What a comparable task cost, so granularity is a query and not a feel (RK71).
2
+
3
+ Sixty-nine shipped tasks here cost between 40 and 1384 lines in the commit that wrote their
4
+ ledger entry: median 376, p75 574, p90 826. Nine are above 800 and they are the
5
+ architectural ones. The spread is real, nothing in the backlog says it, and a line being
6
+ written cannot consult it — so whether a task should be two tasks is decided by feel.
7
+
8
+ **That reading was taken at 69 entries and is not maintained here** (RK364). `roadkeep
9
+ weight` is the current answer, which is the whole argument for deriving it (L5), and a
10
+ number restated in prose is one that goes stale while reading as current. What has held
11
+ across 359 entries is the *shape* rather than the figures: the tail is the architectural
12
+ work, the middle is an ordinary task, and the two are more than an order of magnitude
13
+ apart. The middle has more than halved on the way — the tasks got smaller, monotonically,
14
+ under one task one commit — and none of the three sentences this module is here to support
15
+ depended on where it was.
16
+
17
+ **Derived, never stored.** The commit that added an entry is findable by pickaxe over the
18
+ ledger (RK31), so this is a query over git and not a number anybody maintains: it cannot
19
+ rot, it costs nothing on the turns nobody asks (L5), and a reader who doubts it can check
20
+ it against `git log`. That is also why there is no field on a line — §RK72 carries that
21
+ argument, and the non-goal it produced is binding.
22
+
23
+ **Two axes, because the corpus disagrees about which one is paid.** What carries that is
24
+ the comparison and not either range, so it is stated scale-free (RK367): median to p90,
25
+ lines vary 2.7× and files — which is what an agent holds in context — 1.4×, the axis paid
26
+ being the flatter one by half. Reporting one would be choosing the author's axis for them,
27
+ so both are here and neither is combined into a score.
28
+
29
+ What this is for: **granularity, at the moment the line is written.** A block whose last
30
+ comparables shipped at 800+ lines is a block where the next line is probably two lines.
31
+ What it is explicitly not for: **ranking work.** Every tier of `pick` is a fact, and a
32
+ cheapness tier would defer exactly the nine tasks above — the ones with the most leverage.
33
+
34
+ **A commit that wrote N entries is not N costs** (RK94). One task, one commit is the rule
35
+ the whole derivation rests on, and history is full of files where it was not kept: a
36
+ squashed adoption import writes the entire backlog at once, and this repository itself has
37
+ three entries in one commit. Charging that commit's size to each of them put its value in
38
+ every percentile at once, and the median offered for judging granularity then described
39
+ the batch instead of a task. So a co-shipped entry is **named and left out of the
40
+ distributions**, never divided across them: 20963 lines over 47 entries is 446 apiece, a
41
+ number no commit contains and `git show` cannot refute, which is the one property a
42
+ derived answer has. The entry stays in :attr:`Weights.weighed` carrying its real commit —
43
+ that list was the only usable part when the percentiles collapsed, and it is what a reader
44
+ checks the exclusion against.
45
+ """
46
+
47
+ from __future__ import annotations
48
+
49
+ import statistics
50
+ from collections import Counter
51
+ from collections.abc import Mapping
52
+ from dataclasses import dataclass
53
+
54
+ from roadkeep.config import Config
55
+ from roadkeep.kernel.document import Entry
56
+ from roadkeep.history import Cost, added_ids, costs_of
57
+
58
+ #: How many recent comparables a scoped answer names. Three, because the question it serves
59
+ #: is "is the next line in this block one task or two", and the fourth is already a trend.
60
+ COMPARABLES = 3
61
+
62
+
63
+ @dataclass(frozen=True, slots=True)
64
+ class Weight:
65
+ """One shipped task, what it cost, and the commit that says so."""
66
+
67
+ task_id: str
68
+ block: str
69
+ lines: int
70
+ files: int
71
+ #: The abbreviated sha, so the number is checkable by hand — the whole claim of a
72
+ #: derived answer is that it can be refuted with `git show`.
73
+ commit: str
74
+ #: How many ledger entries this commit wrote (RK94). 1 is the rule kept, and then
75
+ #: `lines` and `files` are this task's own cost; above 1 they are the batch's, shared
76
+ #: by every entry in it and belonging to none of them.
77
+ shared: int = 1
78
+
79
+ @property
80
+ def alone(self) -> bool:
81
+ """Whether the commit's size is this task's cost, which is what a spread is over."""
82
+ return self.shared == 1
83
+
84
+
85
+ @dataclass(frozen=True, slots=True)
86
+ class Spread:
87
+ """A distribution over one axis. Empty is a real answer: nothing shipped yet.
88
+
89
+ Percentiles rather than a mean: the corpus spans two orders of magnitude and the
90
+ architectural tasks at the top would pull an average into a number no task ever cost.
91
+ """
92
+
93
+ count: int = 0
94
+ low: int = 0
95
+ high: int = 0
96
+ p25: int = 0
97
+ median: int = 0
98
+ p75: int = 0
99
+ p90: int = 0
100
+
101
+ @classmethod
102
+ def of(cls, values: tuple[int, ...]) -> Spread:
103
+ if not values:
104
+ return cls()
105
+ ordered = sorted(values)
106
+ return cls(
107
+ count=len(ordered),
108
+ low=ordered[0],
109
+ high=ordered[-1],
110
+ p25=_percentile(ordered, 25),
111
+ median=round(statistics.median(ordered)),
112
+ p75=_percentile(ordered, 75),
113
+ p90=_percentile(ordered, 90),
114
+ )
115
+
116
+ def __str__(self) -> str:
117
+ if not self.count:
118
+ return "nothing shipped"
119
+ return (
120
+ f"{self.low}–{self.high} p25 {self.p25} median {self.median} "
121
+ f"p75 {self.p75} p90 {self.p90}"
122
+ )
123
+
124
+
125
+ @dataclass(frozen=True, slots=True)
126
+ class Weights:
127
+ """Every shipped task's cost, and the two distributions it belongs to.
128
+
129
+ ``block`` is set when the question was scoped, and then ``lines``/``files`` describe that
130
+ block while ``everywhere`` still describes the ledger: a block median means nothing
131
+ without the one it is being compared against.
132
+ """
133
+
134
+ weighed: tuple[Weight, ...] = ()
135
+ lines: Spread = Spread()
136
+ files: Spread = Spread()
137
+ everywhere: Spread = Spread()
138
+ block: str | None = None
139
+ #: Shipped ids whose commit history cannot answer — a squash, a shallow clone, an entry
140
+ #: that never reached a commit. Counted and never guessed at, on RK28's reasoning: an
141
+ #: absent answer is not a cheap task.
142
+ unresolved: tuple[str, ...] = ()
143
+ #: Ids whose commit wrote more than one entry (RK94), in scope and left out of every
144
+ #: distribution above. Named for `unresolved`'s reason: an exclusion the answer does not
145
+ #: state is a count that reads as the whole ledger.
146
+ co_shipped: tuple[str, ...] = ()
147
+
148
+ @property
149
+ def recent(self) -> tuple[Weight, ...]:
150
+ """The last comparables, newest first — what the shipped order already implies.
151
+
152
+ Only entries whose commit is their own: "the last three comparables" is a question
153
+ about what a task costs, and a batch is not comparable to the line being written.
154
+ """
155
+ return tuple(reversed([w for w in self.weighed if w.alone][-COMPARABLES:]))
156
+
157
+ def by_block(self) -> dict[str, Spread]:
158
+ """The line spread per block, in the order the ledger states them.
159
+
160
+ Lines only: the per-block answer is the one a `--block` question refines, and a table
161
+ carrying both axes for every block is the file back rather than an answer (RK29).
162
+ """
163
+ grouped: dict[str, list[int]] = {}
164
+ for weight in self.weighed:
165
+ # The block keeps its row even when every entry in it was co-shipped: an empty
166
+ # spread reads as "nothing comparable here", and a missing row reads as no block.
167
+ values = grouped.setdefault(weight.block, [])
168
+ if weight.alone:
169
+ values.append(weight.lines)
170
+ return {label: Spread.of(tuple(values)) for label, values in grouped.items()}
171
+
172
+
173
+ def _percentile(ordered: list[int], at: int) -> int:
174
+ """The value at a percentile, by nearest rank. No interpolation, because every value
175
+ here is a commit somebody can open, and an interpolated 811.4 is nobody's commit."""
176
+ index = max(0, min(len(ordered) - 1, round(at / 100 * (len(ordered) - 1))))
177
+ return ordered[index]
178
+
179
+
180
+ def weigh(config: Config, block: str | None = None) -> Weights:
181
+ """What the ledger's tasks cost, in ledger order, scoped to one block on request.
182
+
183
+ Two git calls whatever the size of the ledger: which commit added each id, then how big
184
+ those commits were. Raises :class:`~roadkeep.history.HistoryUnavailable` when git cannot
185
+ answer at all, which the caller reports as an absent answer rather than a zero.
186
+ """
187
+ ledger = config.document("changelog")
188
+ shipped = added_ids(config, "changelog")
189
+ costs = costs_of(config, tuple(dict.fromkeys(shipped.values())))
190
+ # Counted over the whole ledger and never over the scope (RK94): how many entries a
191
+ # commit wrote is a fact about that commit, and a `--block` question that only saw its
192
+ # own two of the forty-seven would call a batch a task.
193
+ entries_per_commit = Counter(shipped.values())
194
+
195
+ every = tuple(
196
+ (entry, _weight(entry, shipped, costs, entries_per_commit))
197
+ for entry in ledger.entries
198
+ )
199
+ scoped = tuple(
200
+ pair for pair in every if block is None or pair[0].task.block == block
201
+ )
202
+ # In the order they *shipped*, which is what "the last three comparables" means: where a
203
+ # ledger writes its newest entry is a rendering convention, and this repository's own
204
+ # order agreeing with history is exactly why reading position would look correct here.
205
+ order = {task_id: n for n, task_id in enumerate(shipped)}
206
+ weighed = tuple(
207
+ sorted(
208
+ (weight for _, weight in scoped if weight is not None),
209
+ key=lambda weight: order.get(weight.task_id, 0),
210
+ )
211
+ )
212
+ alone = tuple(w for w in weighed if w.alone)
213
+ return Weights(
214
+ weighed=weighed,
215
+ lines=Spread.of(tuple(w.lines for w in alone)),
216
+ files=Spread.of(tuple(w.files for w in alone)),
217
+ # Always the whole ledger, scoped or not: a block's median says nothing without the
218
+ # number it is being compared against.
219
+ everywhere=Spread.of(
220
+ tuple(w.lines for _, w in every if w is not None and w.alone)
221
+ ),
222
+ block=block,
223
+ unresolved=tuple(entry.task.id for entry, weight in scoped if weight is None),
224
+ co_shipped=tuple(w.task_id for w in weighed if not w.alone),
225
+ )
226
+
227
+
228
+ def _weight(
229
+ entry: Entry,
230
+ shipped: dict[str, str],
231
+ costs: dict[str, Cost],
232
+ entries_per_commit: Mapping[str, int],
233
+ ) -> Weight | None:
234
+ """One entry as a weight, or None when no commit accounts for it."""
235
+ sha = shipped.get(entry.task.id, "")
236
+ cost = costs.get(sha)
237
+ if cost is None:
238
+ return None
239
+ return Weight(
240
+ task_id=entry.task.id,
241
+ block=entry.task.block,
242
+ lines=cost.lines,
243
+ files=cost.files,
244
+ commit=cost.short,
245
+ shared=entries_per_commit.get(sha, 1),
246
+ )
247
+
248
+
249
+ @dataclass(frozen=True, slots=True)
250
+ class Weighed:
251
+ """What `weight` answers, as one result both registers are derived from (RK1170).
252
+
253
+ `rendering.py` was cut out of a `cli.py` that had reached 8,489 lines, and the printers went
254
+ first because theirs is the cut with no import cycle. That fixed a file's size and not where a
255
+ verb's answer lives: counted for RK1170, `verbs/` makes 386 `print` calls of its own against
256
+ 102 delegations, and this verb was the shape of it — the plain answer spelled inside the
257
+ handler and `_weight_json` in the other file, one verb's two registers two files apart.
258
+
259
+ **The two registers are meant to differ.** Plain stdout is the value a shell composes with;
260
+ `--json` carries the provenance that makes an answer auditable. So this is not one output: it
261
+ is one result, and both readings are derived from it here, where the numbers were computed.
262
+ What the payload carries is then what the plain answer showed by construction, which is
263
+ today's `test_weighing` assertion turned into a property of the code.
264
+
265
+ Here and not in `verbs/querying.py`: the record is the *answer*, and the verb is the door.
266
+ A handler that owned the type would be the layer this task is unwinding, one file over.
267
+ """
268
+
269
+ #: The ledger this weighed, as the project spells it.
270
+ where: str
271
+ weights: Weights
272
+ #: Whether the caller asked for the sample behind the percentiles (RK264).
273
+ records: bool
274
+
275
+ def __str__(self) -> str:
276
+ """The plain register: the value a shell composes with, one fact per line."""
277
+ scope = f" Block {self.weights.block}" if self.weights.block else ""
278
+ rows = [
279
+ f"{self.where}{scope} {self.weights.lines.count} weighed",
280
+ f" lines {self.weights.lines}",
281
+ f" files {self.weights.files}",
282
+ ]
283
+ if self.weights.block:
284
+ # The number the block is being compared against, without a second command.
285
+ rows.append(f" ledger {self.weights.everywhere}")
286
+ rows += [
287
+ f" last {one.task_id:<6} {one.lines:>5} lines "
288
+ f"{one.files:>3} files {one.commit}"
289
+ for one in self.weights.recent
290
+ ]
291
+ else:
292
+ rows += [
293
+ f" block {label:<3} {spread}"
294
+ for label, spread in self.weights.by_block().items()
295
+ ]
296
+ if self.weights.co_shipped:
297
+ # Named for the reason `missing` is (RK94): the numbers above are over fewer entries
298
+ # than the ledger holds, and a spread that does not say so reads as all of it.
299
+ rows.append(
300
+ f" batched {len(self.weights.co_shipped)} entr(ies) left out, whose commit "
301
+ f"wrote more than one: {', '.join(self.weights.co_shipped)}"
302
+ )
303
+ if self.weights.unresolved:
304
+ # An absent answer is not a cheap task (RK28): a squash or a shallow clone leaves an
305
+ # entry no commit accounts for, and a count that hid them would read as complete.
306
+ rows.append(
307
+ f" missing {len(self.weights.unresolved)} entr(ies) no commit accounts for: "
308
+ f"{', '.join(self.weights.unresolved)}"
309
+ )
310
+ if self.records:
311
+ rows += [
312
+ f" record {one.task_id:<6} {one.lines:>5} lines {one.files:>3} files "
313
+ f"{one.commit}"
314
+ + (f" shared with {one.shared - 1} more" if one.shared > 1 else "")
315
+ for one in self.weights.weighed
316
+ ]
317
+ elif self.weights.weighed:
318
+ # Named and never silent (RK10): a listing that looked complete is the whole symptom
319
+ # one command over, and an elision the answer does not state is the same defect here.
320
+ rows.append(
321
+ f" records {len(self.weights.weighed)} not shown — `--records` prints them"
322
+ )
323
+ return "\n".join(rows)
324
+
325
+ def payload(self) -> dict[str, object]:
326
+ """The distribution, the counts, and the sample only where it was asked for (RK264).
327
+
328
+ The percentiles **are** the answer — 22.7k of 23.7k characters here were the sample they
329
+ summarise, and scoping to a block only moved that to 89%, so the read priced to save
330
+ context was the one that spent it. What replaces the array is a count and never a cap: a
331
+ top-N would make the p90 a statement about a sample nobody chose, and the figure is the
332
+ one thing this command may not get wrong.
333
+
334
+ `unresolved` and `co_shipped` stay unconditionally. They are ids and not records, and they
335
+ are what says the distribution is over fewer entries than the ledger holds — the half of
336
+ this that must never be behind a flag.
337
+ """
338
+ return {
339
+ "file": self.where,
340
+ "block": self.weights.block,
341
+ "lines": _spread_json(self.weights.lines),
342
+ "files": _spread_json(self.weights.files),
343
+ "ledger": _spread_json(self.weights.everywhere),
344
+ "blocks": {
345
+ label: _spread_json(one) for label, one in self.weights.by_block().items()
346
+ },
347
+ "weighed": [
348
+ {
349
+ "id": one.task_id,
350
+ "block": one.block,
351
+ "lines": one.lines,
352
+ "files": one.files,
353
+ "commit": one.commit,
354
+ # The entry keeps its real numbers and says what they are the size of, so
355
+ # the list stays checkable against `git show` (RK94).
356
+ "shared": one.shared,
357
+ }
358
+ for one in self.weights.weighed
359
+ ]
360
+ if self.records
361
+ else [],
362
+ # `brief`'s `non_goals_elided`, one command over: the caller knows the list it read
363
+ # was cut, and 0 is the honest answer where nothing was.
364
+ "weighed_elided": 0 if self.records else len(self.weights.weighed),
365
+ "unresolved": list(self.weights.unresolved),
366
+ "co_shipped": list(self.weights.co_shipped),
367
+ }
368
+
369
+
370
+ def _spread_json(one: Spread) -> dict[str, int]:
371
+ """One distribution as the fields both registers name it by."""
372
+ return {
373
+ "count": one.count,
374
+ "low": one.low,
375
+ "high": one.high,
376
+ "p25": one.p25,
377
+ "median": one.median,
378
+ "p75": one.p75,
379
+ "p90": one.p90,
380
+ }