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/governing.py
ADDED
|
@@ -0,0 +1,934 @@
|
|
|
1
|
+
"""A number that is a judgement, declared where the reading that decides it is taken (RK1272).
|
|
2
|
+
|
|
3
|
+
`declare` retrofits a role into `[files]` and `priority migrate` moves the queue out of the
|
|
4
|
+
config. Every other table is edited by hand — and in an agent session that is not a hand edit,
|
|
5
|
+
it is no edit at all: the write path is the served surface, and nothing on it wrote this file.
|
|
6
|
+
|
|
7
|
+
The tables worth a verb are the ones whose value is a **judgement about a number**: `[limits]`,
|
|
8
|
+
`[budgets]`, `[tools]` and `[claims]`. Each already has the read that decides it — `budget
|
|
9
|
+
--file` prices an every-turn file, `cost --tools` ranks the served descriptions, and the P90
|
|
10
|
+
of the lines that already read well is what put `symptom` at 120. What they do not have is a
|
|
11
|
+
place where the reading and the number meet, so the reading happens once and the number is
|
|
12
|
+
defended in a comment afterwards: this project's own `[tools]` entry is four paragraphs of
|
|
13
|
+
exactly that, re-argued three times in one session.
|
|
14
|
+
|
|
15
|
+
So this prints the reading and takes the number in the same call, and **refuses one the corpus
|
|
16
|
+
already violates** rather than writing a limit whose first act is a finding. Which is L1 at the
|
|
17
|
+
one address it had never reached: the schema is enforced where the text is created everywhere
|
|
18
|
+
except the file the schema is written in.
|
|
19
|
+
|
|
20
|
+
Three things it deliberately is not:
|
|
21
|
+
|
|
22
|
+
* **Not a serialiser.** The key is inserted and every other byte stays, which is `declare`'s
|
|
23
|
+
rule and `bump_version`'s before it: a `tomllib` round-trip drops the comments a scaffolded
|
|
24
|
+
config is mostly made of.
|
|
25
|
+
* **Not the argument.** Why 120 and not 130 is prose, and the tool does not write prose (L4).
|
|
26
|
+
What it writes is the declaration; the reading is printed for the author to argue from.
|
|
27
|
+
* **Not a second statement of the shape.** Which addresses exist, what type each takes and
|
|
28
|
+
what this build defaults to are :mod:`roadkeep.describing`'s, read and never repeated.
|
|
29
|
+
"""
|
|
30
|
+
|
|
31
|
+
from __future__ import annotations
|
|
32
|
+
|
|
33
|
+
import re
|
|
34
|
+
from collections.abc import Sequence
|
|
35
|
+
from dataclasses import dataclass, replace
|
|
36
|
+
from pathlib import Path
|
|
37
|
+
|
|
38
|
+
from roadkeep.config import Config
|
|
39
|
+
from roadkeep.kernel.schema import width
|
|
40
|
+
from roadkeep.provenance import invocation
|
|
41
|
+
|
|
42
|
+
__all__ = ["Declared", "Measured", "NoSuchKey", "Violated", "govern", "reading"]
|
|
43
|
+
|
|
44
|
+
#: The four tables this verb writes, and the whole of what it claims. Every other table in
|
|
45
|
+
#: `describing.TABLES` holds a name, a path or a flag — a decision with no reading behind it,
|
|
46
|
+
#: which is a `declare` or a hand edit and never a measurement.
|
|
47
|
+
GOVERNED = ("limits", "budgets.<path>", "tools", "claims", "reads")
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
class NoSuchKey(KeyError):
|
|
51
|
+
"""An address this build has no key for, or one no reading decides (RK1272).
|
|
52
|
+
|
|
53
|
+
Two absences and one message, because the caller is choosing an address either way: a
|
|
54
|
+
typo, and a key that exists and is not a number. The second is the interesting one — a
|
|
55
|
+
`[files]` role or a `[markers]` glyph is a decision with nothing to measure it against, so
|
|
56
|
+
a verb that took one would be printing an empty reading beside a write `declare` makes.
|
|
57
|
+
"""
|
|
58
|
+
|
|
59
|
+
def __init__(self, address: str, known: Sequence[str]) -> None:
|
|
60
|
+
self.address = address
|
|
61
|
+
spelled = ", ".join(known)
|
|
62
|
+
super().__init__(
|
|
63
|
+
f"no governed number at {address!r}: this verb writes the tables a reading "
|
|
64
|
+
f"decides — {spelled} — and `{invocation()} config` lists every key there is, "
|
|
65
|
+
f"including the ones that are a name rather than a measurement"
|
|
66
|
+
)
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
class Violated(ValueError):
|
|
70
|
+
"""A number the corpus already breaks, refused before it is written (RK1272).
|
|
71
|
+
|
|
72
|
+
The whole of what makes this a verb rather than an editor. A limit whose first act is a
|
|
73
|
+
finding is one somebody lowers, reads the report, and raises again — three commits and a
|
|
74
|
+
red gate for a decision that was measurable before the first of them.
|
|
75
|
+
|
|
76
|
+
The **widest** site is named and not all of them: what an author needs to choose a number
|
|
77
|
+
is the one that would refuse, and a listing of every line over it is the gate's answer to
|
|
78
|
+
a question this call exists to stop them asking.
|
|
79
|
+
"""
|
|
80
|
+
|
|
81
|
+
def __init__(self, address: str, at: int, worst: int, where: str, over: int) -> None:
|
|
82
|
+
self.address = address
|
|
83
|
+
self.at = at
|
|
84
|
+
self.worst = worst
|
|
85
|
+
super().__init__(
|
|
86
|
+
f"{address} = {at} is a limit this project already breaks: {where} measures "
|
|
87
|
+
f"{worst}, and {over} of them would be over — declare it at {worst} or above, or "
|
|
88
|
+
f"bring the corpus under it first and then declare it, which is the order that "
|
|
89
|
+
f"leaves no commit with a red gate in it"
|
|
90
|
+
)
|
|
91
|
+
|
|
92
|
+
|
|
93
|
+
@dataclass(frozen=True, slots=True)
|
|
94
|
+
class Measured:
|
|
95
|
+
"""What the corpus says about one governed number, now.
|
|
96
|
+
|
|
97
|
+
Printed before the write and answerable on its own, which is the half a comment in the
|
|
98
|
+
config was standing in for: the number is a judgement, and a judgement wants the figure it
|
|
99
|
+
was made against written down where it can be taken again.
|
|
100
|
+
"""
|
|
101
|
+
|
|
102
|
+
address: str
|
|
103
|
+
#: What the key is measured in, as the read that owns it names it.
|
|
104
|
+
unit: str
|
|
105
|
+
#: The widest thing this limit governs today, and where it is.
|
|
106
|
+
worst: int = 0
|
|
107
|
+
where: str = ""
|
|
108
|
+
#: How many sites the reading looked at, so a `0` is told from an empty corpus.
|
|
109
|
+
sites: int = 0
|
|
110
|
+
#: What this project declares now, or `None` where it declares nothing.
|
|
111
|
+
declared: int | None = None
|
|
112
|
+
#: What holds the key when the project declares nothing — the number this build falls back
|
|
113
|
+
#: to, or `None` where there is no fallback at all (RK1343). Three governable keys are in
|
|
114
|
+
#: the second state by design: `reads.brief`, `tools.session` and `tools.characters` are
|
|
115
|
+
#: unpriced until somebody looks, and `budget.session` refuses a surface only where the
|
|
116
|
+
#: ceiling *is* declared, so an undeclared one is not a lenient gate but no gate. Reported
|
|
117
|
+
#: because the reader running this verb is asking exactly whether anything holds them, and
|
|
118
|
+
#: :meth:`Schema.source_of` already refuses to guess for the same reason one surface over:
|
|
119
|
+
#: a citation invented for an undeclared limit answers that question in the reassuring
|
|
120
|
+
#: direction.
|
|
121
|
+
default: int | None = None
|
|
122
|
+
#: Absent where nothing measures this key — `[claims] held` is a judgement about how long
|
|
123
|
+
#: work takes, which no file here holds evidence about (said, never invented).
|
|
124
|
+
unmeasured: str = ""
|
|
125
|
+
#: The argument standing above the key, one string per comment line and the `#` stripped
|
|
126
|
+
#: (RK1296). Kept in the file by `--because` and handed back here, because a reason the
|
|
127
|
+
#: read does not return is one the caller opens the config for — the read L5 exists to
|
|
128
|
+
#: replace, on the one file every other rule is read out of. Verbatim: what the comment
|
|
129
|
+
#: *means* is not this tool's to say (L4).
|
|
130
|
+
because: tuple[str, ...] = ()
|
|
131
|
+
|
|
132
|
+
def over(self, at: int) -> bool:
|
|
133
|
+
return bool(self.sites) and self.worst > at
|
|
134
|
+
|
|
135
|
+
def stated(self, standing: bool = True) -> str:
|
|
136
|
+
"""The reading, and what the project declares — the second omitted by a write.
|
|
137
|
+
|
|
138
|
+
`standing` is False at a `govern` that just wrote one: the header there already says
|
|
139
|
+
the new number and the old, so a `declared` row beside it would state the value this
|
|
140
|
+
call has replaced as if it were current.
|
|
141
|
+
"""
|
|
142
|
+
rows = [f"{self.address} {self.unit}"]
|
|
143
|
+
if self.unmeasured:
|
|
144
|
+
rows.append(f" reading none — {self.unmeasured}")
|
|
145
|
+
else:
|
|
146
|
+
rows.append(
|
|
147
|
+
f" reading {self.sites} site(s), widest {self.worst}"
|
|
148
|
+
+ (f" at {self.where}" if self.where else "")
|
|
149
|
+
)
|
|
150
|
+
if standing:
|
|
151
|
+
if self.declared is not None:
|
|
152
|
+
rows.append(f" declared {self.declared}")
|
|
153
|
+
elif self.default is not None:
|
|
154
|
+
# The number, not the fact that one exists (RK1343): *a default applies* is
|
|
155
|
+
# the half a reader cannot act on, and the whole question they came with is
|
|
156
|
+
# which figure they are held to.
|
|
157
|
+
rows.append(f" declared none — this tool's default of {self.default} holds")
|
|
158
|
+
else:
|
|
159
|
+
# And the honest other half. Three keys reach here — `reads.brief`,
|
|
160
|
+
# `tools.session`, `tools.characters` — and their gates read `if … is not
|
|
161
|
+
# None`, so undeclared is not lenient but absent. Saying *a default applies*
|
|
162
|
+
# answered the reader's real question in the reassuring direction, which is
|
|
163
|
+
# what `Schema.source_of` refuses to do about a limit for the same reason.
|
|
164
|
+
# The gate clause only where there is a gate: `prose` and `claims.held` say
|
|
165
|
+
# in the row above that nothing measures or refuses them, and a sentence
|
|
166
|
+
# announcing a gate switched off would argue with the line it follows.
|
|
167
|
+
gate = (
|
|
168
|
+
""
|
|
169
|
+
if self.unmeasured
|
|
170
|
+
else ", so the gate reading it is off until a number is written here"
|
|
171
|
+
)
|
|
172
|
+
rows.append(
|
|
173
|
+
f" declared none — and nothing holds it: this key has no default{gate}"
|
|
174
|
+
)
|
|
175
|
+
# Under the number and not beside it, because it is prose and wraps: the first
|
|
176
|
+
# line is labelled and the rest are indented to it, which is how every wrapped
|
|
177
|
+
# answer here is read (RK1296).
|
|
178
|
+
rows.extend(
|
|
179
|
+
f" {'because' if index == 0 else ' '} {line}"
|
|
180
|
+
for index, line in enumerate(self.because)
|
|
181
|
+
)
|
|
182
|
+
return "\n".join(rows)
|
|
183
|
+
|
|
184
|
+
|
|
185
|
+
@dataclass(frozen=True, slots=True)
|
|
186
|
+
class Declared:
|
|
187
|
+
"""One key written into `roadkeep.toml`, with the reading it was written against."""
|
|
188
|
+
|
|
189
|
+
address: str
|
|
190
|
+
at: int
|
|
191
|
+
measured: Measured
|
|
192
|
+
#: The line the key landed on, 1-based — what a reviewer reads the diff against.
|
|
193
|
+
lineno: int
|
|
194
|
+
#: What it said before, or `None` where the key is new.
|
|
195
|
+
before: int | None = None
|
|
196
|
+
#: Whether an argument stands above the key after this call (RK1293). A field because the
|
|
197
|
+
#: answer says which of the two happened: the reason is theirs either way, and where none
|
|
198
|
+
#: arrived the line saying so is the one thing that keeps the number from being a figure
|
|
199
|
+
#: nobody can date. Read off the **lines** and never off the flag (RK1295) — a `--because`
|
|
200
|
+
#: that wrapped to nothing placed nothing, and the caller cannot see the file to tell.
|
|
201
|
+
argued: bool = False
|
|
202
|
+
#: Whether that argument was **already** the one above the key, so this call wrote none
|
|
203
|
+
#: (RK1294). The number is idempotent and the reason beside it is too: a retried call, a
|
|
204
|
+
#: replayed capture or an agent unsure its command took would otherwise leave the same
|
|
205
|
+
#: sentence twice, which reads as two decisions and is one.
|
|
206
|
+
standing: bool = False
|
|
207
|
+
#: The comment lines `--instead` took out, verbatim and `#` included (RK1367). Empty on
|
|
208
|
+
#: every `--because`, which stacks. Handed back rather than counted, because withdrawing an
|
|
209
|
+
#: argument in silence is history removed — the caller reads what was displaced in the
|
|
210
|
+
#: answer, puts back anything the run swept up that it should not have, and the commit
|
|
211
|
+
#: carries the rest. What those lines *meant* is not this tool's to weigh (L4): the whole
|
|
212
|
+
#: contiguous run above the key is what argues the number, so the whole run is what a
|
|
213
|
+
#: replacement replaces, and saying which lines those were is the check on that reach.
|
|
214
|
+
displaced: tuple[str, ...] = ()
|
|
215
|
+
|
|
216
|
+
def stated(self, config: Config) -> str:
|
|
217
|
+
where = config.relative(config.source) if config.source else "roadkeep.toml"
|
|
218
|
+
was = "" if self.before is None else f" (was {self.before})"
|
|
219
|
+
# The reading indented under this write's header (RK1372, RK1376): that record prints
|
|
220
|
+
# its own column-0 header, which is right when `govern <key>` is the whole answer and
|
|
221
|
+
# is a second subject line in the middle of one when it is not — the address is already
|
|
222
|
+
# in the line above, so what the row adds is the unit and the sites.
|
|
223
|
+
reading = "\n".join(f" {row}" for row in self.measured.stated(standing=False).splitlines())
|
|
224
|
+
return "\n".join(
|
|
225
|
+
[
|
|
226
|
+
f"{where}:{self.lineno} {self.address} = {self.at}{was}",
|
|
227
|
+
reading,
|
|
228
|
+
# The prose is the author's and the placing is this verb's (RK1293). Said
|
|
229
|
+
# either way, because a number with no argument beside it is one nobody can
|
|
230
|
+
# date — and the rule that sent it to the commit was unkeepable here, the
|
|
231
|
+
# commit body being composed by a tool this project does not own.
|
|
232
|
+
self._reason(),
|
|
233
|
+
# And the file, which is the half a reviewer would otherwise miss (RK298,
|
|
234
|
+
# RK1130): a number moved in `roadkeep.toml` changes what every write is held
|
|
235
|
+
# to, and it is the one file a commit about a limit is really about.
|
|
236
|
+
f" stage git add -- {where}",
|
|
237
|
+
]
|
|
238
|
+
)
|
|
239
|
+
|
|
240
|
+
def _reason(self) -> str:
|
|
241
|
+
"""Which of the three happened to the argument, said in the answer (RK1293, RK1294).
|
|
242
|
+
|
|
243
|
+
Three and not two, because "already there" is neither a write nor an absence: a caller
|
|
244
|
+
told nothing was written would write it again, and a caller told it was would believe
|
|
245
|
+
a second decision had been recorded.
|
|
246
|
+
"""
|
|
247
|
+
if self.standing:
|
|
248
|
+
return (
|
|
249
|
+
" reason already above the key — the same sentence, so it was not "
|
|
250
|
+
"written a second time"
|
|
251
|
+
)
|
|
252
|
+
if self.displaced:
|
|
253
|
+
# A fourth, and the only one that reports a **deletion** (RK1367): the count and
|
|
254
|
+
# the lines, because an argument withdrawn without saying so is the accreting
|
|
255
|
+
# rationale read backwards, and the reach of the run is what a caller checks.
|
|
256
|
+
return "\n".join(
|
|
257
|
+
[
|
|
258
|
+
f" reason written above the key, in your words, instead of the "
|
|
259
|
+
f"{len(self.displaced)} line(s) that argued it before",
|
|
260
|
+
*(
|
|
261
|
+
f" {'withdrew' if index == 0 else ' '} {line.rstrip()}"
|
|
262
|
+
for index, line in enumerate(self.displaced)
|
|
263
|
+
),
|
|
264
|
+
]
|
|
265
|
+
)
|
|
266
|
+
if self.argued:
|
|
267
|
+
return " reason written above the key, in your words"
|
|
268
|
+
return (
|
|
269
|
+
' reason none — `--because "…"` writes yours above the key, and a number '
|
|
270
|
+
"with none is one nobody can date"
|
|
271
|
+
)
|
|
272
|
+
|
|
273
|
+
def payload(self, config: Config) -> dict[str, object]:
|
|
274
|
+
return {
|
|
275
|
+
"address": self.address,
|
|
276
|
+
"at": self.at,
|
|
277
|
+
"was": self.before,
|
|
278
|
+
"file": config.relative(config.source) if config.source else None,
|
|
279
|
+
"line": self.lineno,
|
|
280
|
+
"argued": self.argued,
|
|
281
|
+
"standing": self.standing,
|
|
282
|
+
# What `--instead` took out (RK1367). Always published and never omitted when
|
|
283
|
+
# empty, for the reason `over` is: a key that appears only when it is set is one a
|
|
284
|
+
# reader learns to stop looking for, and this one is a deletion.
|
|
285
|
+
"displaced": [line.rstrip("\n") for line in self.displaced],
|
|
286
|
+
"reading": {
|
|
287
|
+
"unit": self.measured.unit,
|
|
288
|
+
"sites": self.measured.sites,
|
|
289
|
+
"worst": self.measured.worst,
|
|
290
|
+
"where": self.measured.where,
|
|
291
|
+
"unmeasured": self.measured.unmeasured or None,
|
|
292
|
+
},
|
|
293
|
+
}
|
|
294
|
+
|
|
295
|
+
|
|
296
|
+
def _addressed(config: Config, address: str) -> tuple[str, str]:
|
|
297
|
+
"""The `(table, key)` an address names, refused where no reading decides it."""
|
|
298
|
+
from roadkeep.describing import TABLES # noqa: PLC0415 - RK260
|
|
299
|
+
|
|
300
|
+
table, _, key = address.rpartition(".")
|
|
301
|
+
for name in GOVERNED:
|
|
302
|
+
stem = name.split(".")[0]
|
|
303
|
+
if table in (name, stem) and key in TABLES[name]:
|
|
304
|
+
return name, key
|
|
305
|
+
raise NoSuchKey(address, GOVERNED)
|
|
306
|
+
|
|
307
|
+
|
|
308
|
+
def reading(config: Config, address: str, *, file: str = "", role: str = "") -> Measured:
|
|
309
|
+
"""What this project's own files say about one governed number, now (RK1272).
|
|
310
|
+
|
|
311
|
+
Every branch here calls a read that already exists and owns the question — the whole
|
|
312
|
+
argument for the verb is that those readings live somewhere other than the declaration,
|
|
313
|
+
not that they are missing.
|
|
314
|
+
"""
|
|
315
|
+
from roadkeep.describing import shape # noqa: PLC0415 - RK260
|
|
316
|
+
|
|
317
|
+
table, key = _addressed(config, address)
|
|
318
|
+
# Whether the project declared it is the shape's answer and the *value* is the live
|
|
319
|
+
# config's: one read says which of the two facts this is, and the other says the number.
|
|
320
|
+
written = any(one.name == key and one.declared for one in shape(config, table).keys)
|
|
321
|
+
declared = _current(config, table, key, file=file, role=role) if written else None
|
|
322
|
+
if table == "limits":
|
|
323
|
+
found = _limits(config, address, key, declared, role=role)
|
|
324
|
+
elif table == "budgets.<path>":
|
|
325
|
+
found = _budgets(config, address, key, declared, file=file)
|
|
326
|
+
elif table == "tools":
|
|
327
|
+
found = _tools(config, address, key, declared)
|
|
328
|
+
elif table == "reads":
|
|
329
|
+
found = _reads(config, address, declared)
|
|
330
|
+
else:
|
|
331
|
+
found = Measured(
|
|
332
|
+
address=address,
|
|
333
|
+
unit="minutes",
|
|
334
|
+
declared=declared,
|
|
335
|
+
unmeasured=(
|
|
336
|
+
"how long a claim reads as held is a judgement about how long work takes, "
|
|
337
|
+
"and no file here holds evidence about that"
|
|
338
|
+
),
|
|
339
|
+
)
|
|
340
|
+
# And the argument, joined here rather than inside six branches: what argues a number is
|
|
341
|
+
# the same question wherever the number is measured, and the answer is in one file (RK1296).
|
|
342
|
+
# The fallback joins it for the same reason and from the same place (RK1343): which number
|
|
343
|
+
# holds an undeclared key is one question, and only `limits` has an answer — a bare
|
|
344
|
+
# `Schema` *is* this build's defaults, so reading them off one is reading them off the
|
|
345
|
+
# thing that enforces them rather than off a second list that would drift.
|
|
346
|
+
return replace(
|
|
347
|
+
found,
|
|
348
|
+
because=_because(config, table, key, file=file, role=role),
|
|
349
|
+
default=_fallback(table, key),
|
|
350
|
+
)
|
|
351
|
+
|
|
352
|
+
|
|
353
|
+
def _fallback(table: str, key: str) -> int | None:
|
|
354
|
+
"""The number this build holds an undeclared key to, where it holds one at all (RK1343).
|
|
355
|
+
|
|
356
|
+
Only `limits`, and that is the finding rather than an omission here: `[tools]`, `[reads]`
|
|
357
|
+
and `[budgets]` are `None` on `Config` until a project writes them, and the gates that
|
|
358
|
+
read them are written `if … is not None` — so an undeclared ceiling there is no ceiling.
|
|
359
|
+
Measured: with no `[limits]`, a 192-character symptom is refused at `120 (this tool's
|
|
360
|
+
default)`; with no `[tools]`, `lint` reports nothing at all about the served surface.
|
|
361
|
+
|
|
362
|
+
`prose` is absent from the schema and stays `None`, which is right and is the same fact
|
|
363
|
+
its own row already states: it is a width this tool fills to and no gate refuses.
|
|
364
|
+
"""
|
|
365
|
+
if table != "limits":
|
|
366
|
+
return None
|
|
367
|
+
from roadkeep.kernel.schema import Schema # noqa: PLC0415 - RK1065's edge, deferred
|
|
368
|
+
|
|
369
|
+
return getattr(Schema(), f"{key}_max", None)
|
|
370
|
+
|
|
371
|
+
|
|
372
|
+
def _current(config: Config, table: str, key: str, *, file: str, role: str) -> int | None:
|
|
373
|
+
"""What this project declares for a key today, read off the live config and not the file."""
|
|
374
|
+
from roadkeep.config import _LIMIT_KEYS # noqa: PLC0415 - RK260
|
|
375
|
+
|
|
376
|
+
if table == "limits":
|
|
377
|
+
return getattr(config.schema_for(role or "roadmap"), _LIMIT_KEYS[key])
|
|
378
|
+
if table == "tools":
|
|
379
|
+
return config.tool_characters if key == "characters" else config.tool_session
|
|
380
|
+
if table == "reads":
|
|
381
|
+
return config.brief_read
|
|
382
|
+
if table == "claims":
|
|
383
|
+
return config.held
|
|
384
|
+
for budget in config.budgets:
|
|
385
|
+
if config.relative(budget.path) == file or budget.path.as_posix().endswith(file):
|
|
386
|
+
return getattr(budget, key)
|
|
387
|
+
return None
|
|
388
|
+
|
|
389
|
+
|
|
390
|
+
def _limits(
|
|
391
|
+
config: Config, address: str, key: str, declared: int | None, *, role: str
|
|
392
|
+
) -> Measured:
|
|
393
|
+
"""The widest field this limit governs, over the files the project declares.
|
|
394
|
+
|
|
395
|
+
Measured in the unit the limit is in — code units for a field, words for a section, and
|
|
396
|
+
the rendered line for `line` — because a number compared against the wrong unit is the one
|
|
397
|
+
kind of reading that looks right.
|
|
398
|
+
"""
|
|
399
|
+
from roadkeep.config import LINE_ROLES # noqa: PLC0415 - RK260
|
|
400
|
+
|
|
401
|
+
if key == "prose":
|
|
402
|
+
# A width and not a ceiling, which is the one key in this table nothing refuses: it
|
|
403
|
+
# says how wide a section this tool *writes* is filled, so the widest line on disk is
|
|
404
|
+
# a fact about imported prose and never a violation. Measured by nobody, said here.
|
|
405
|
+
return Measured(
|
|
406
|
+
address=address,
|
|
407
|
+
unit="utf-16 code units",
|
|
408
|
+
declared=declared,
|
|
409
|
+
unmeasured=(
|
|
410
|
+
"the width a written section is filled to, which no gate refuses — an "
|
|
411
|
+
"adopted file's own lines are wider and are not wrong"
|
|
412
|
+
),
|
|
413
|
+
)
|
|
414
|
+
if key == "section":
|
|
415
|
+
return _sections(config, address, key, declared, role=role)
|
|
416
|
+
# Declared and read from one place (RK1279, RK1361). It was derived here — a line file is
|
|
417
|
+
# a declared role that is not a prose one — which held until `decisions` became both, and
|
|
418
|
+
# then failed the way the derivation was written to fail loudly and did not: a widest
|
|
419
|
+
# measured over three files where four hold lines, and a limit the fourth already breaks
|
|
420
|
+
# accepted. So the set is stated in `config` beside the one it stopped being the
|
|
421
|
+
# complement of, and the seventh role is added there once rather than reasoned about here.
|
|
422
|
+
roles = (role,) if role else LINE_ROLES
|
|
423
|
+
worst, where, sites = 0, "", 0
|
|
424
|
+
for one in roles:
|
|
425
|
+
if not config.has(one):
|
|
426
|
+
continue
|
|
427
|
+
document = config.document(one)
|
|
428
|
+
for entry in document.entries:
|
|
429
|
+
measured = _field(document, entry, key)
|
|
430
|
+
if measured is None:
|
|
431
|
+
continue
|
|
432
|
+
sites += 1
|
|
433
|
+
if measured > worst:
|
|
434
|
+
worst = measured
|
|
435
|
+
where = f"{config.relative(config.path(one))}:{entry.lineno}"
|
|
436
|
+
# And what a write would **carry into** this file (RK1284), which for one role is not the
|
|
437
|
+
# same population as what it holds. `ship --decides` composes the decision from the open
|
|
438
|
+
# line's own claim, so a decisions file with nothing in it measured zero sites and
|
|
439
|
+
# accepted any number — after which every ship carrying a claim wider than it was refused
|
|
440
|
+
# over a field no flag on that call writes. RK1279's hole at a different set: there the
|
|
441
|
+
# reading missed a file, and here it reads the right one and misses what is coming.
|
|
442
|
+
for entry, carried in _carried(config, key, role):
|
|
443
|
+
sites += 1
|
|
444
|
+
if carried > worst:
|
|
445
|
+
worst = carried
|
|
446
|
+
where = f"{config.relative(config.path('roadmap'))}:{entry.lineno} (inherited)"
|
|
447
|
+
return Measured(
|
|
448
|
+
address=address,
|
|
449
|
+
unit="utf-16 code units",
|
|
450
|
+
worst=worst,
|
|
451
|
+
where=where,
|
|
452
|
+
sites=sites,
|
|
453
|
+
declared=declared,
|
|
454
|
+
)
|
|
455
|
+
|
|
456
|
+
|
|
457
|
+
def _carried(config: Config, key: str, role: str) -> tuple[tuple[object, int], ...]:
|
|
458
|
+
"""Every open claim a `ship --decides` would carry into the decisions file (RK1284).
|
|
459
|
+
|
|
460
|
+
One role and one field, and both are declared in code rather than guessed:
|
|
461
|
+
:func:`~roadkeep.shipping._decided` composes the record with `as_recorded`, which keeps
|
|
462
|
+
the task's **symptom** and replaces the `why`. So the symptom is inherited whole and
|
|
463
|
+
nothing else is, which is what makes this derivable — a reading of what *might* be
|
|
464
|
+
written anywhere would be a guess, and this is the one inheritance the code states.
|
|
465
|
+
|
|
466
|
+
Empty for every other role and every other key, and — the case that matters — for a call
|
|
467
|
+
with **no** role at all: the shared `[limits]` already walks every line file including the
|
|
468
|
+
roadmap, so adding the carried claims there would be one population reported twice.
|
|
469
|
+
"""
|
|
470
|
+
if role != "decisions" or key != "symptom" or not config.has("roadmap"):
|
|
471
|
+
return ()
|
|
472
|
+
return tuple(
|
|
473
|
+
(entry, width(entry.task.symptom))
|
|
474
|
+
for entry in config.document("roadmap").entries
|
|
475
|
+
if entry.task.symptom
|
|
476
|
+
)
|
|
477
|
+
|
|
478
|
+
|
|
479
|
+
def _field(document: object, entry: object, key: str) -> int | None:
|
|
480
|
+
"""One line's measurement for one limit, or `None` where the line has no such field."""
|
|
481
|
+
task = entry.task # type: ignore[attr-defined]
|
|
482
|
+
if key == "line":
|
|
483
|
+
return width(entry.raw.rstrip("\r\n")) # type: ignore[attr-defined]
|
|
484
|
+
if key == "part":
|
|
485
|
+
return width(task.part) if task.part else None
|
|
486
|
+
value = getattr(task, key, None)
|
|
487
|
+
return None if not value else width(value)
|
|
488
|
+
|
|
489
|
+
|
|
490
|
+
def _sections(
|
|
491
|
+
config: Config, address: str, key: str, declared: int | None, *, role: str = ""
|
|
492
|
+
) -> Measured:
|
|
493
|
+
"""The longest rationale section, charged as the budget charges one (RK136).
|
|
494
|
+
|
|
495
|
+
``role`` narrows it to one prose file, and it had to the moment a third one arrived with a
|
|
496
|
+
budget of its own (RK1361): `[limits.decisions] section` governs that file alone, and a
|
|
497
|
+
reading over every prose file would refuse a decisions limit the improvements file breaks
|
|
498
|
+
— a number rejected on evidence from a file it does not govern.
|
|
499
|
+
"""
|
|
500
|
+
from roadkeep.config import PROSE_ROLES # noqa: PLC0415 - RK260
|
|
501
|
+
from roadkeep.sections import anchored # noqa: PLC0415 - RK260
|
|
502
|
+
|
|
503
|
+
worst, where, sites = 0, "", 0
|
|
504
|
+
for role in (role,) if role else PROSE_ROLES:
|
|
505
|
+
if not config.has(role):
|
|
506
|
+
continue
|
|
507
|
+
document = config.document(role)
|
|
508
|
+
for found in anchored(document):
|
|
509
|
+
sites += 1
|
|
510
|
+
# The section's own charge and the prose width, each read the way the limit that
|
|
511
|
+
# governs it is: `words` is what the budget charges (RK136) and a `prose` width is
|
|
512
|
+
# about the longest line somebody filled, not about the paragraph.
|
|
513
|
+
measured = found.words
|
|
514
|
+
if measured > worst:
|
|
515
|
+
worst = measured
|
|
516
|
+
where = f"{config.relative(config.path(role))}:{found.first}"
|
|
517
|
+
return Measured(
|
|
518
|
+
address=address,
|
|
519
|
+
unit="words",
|
|
520
|
+
worst=worst,
|
|
521
|
+
where=where,
|
|
522
|
+
sites=sites,
|
|
523
|
+
declared=declared,
|
|
524
|
+
)
|
|
525
|
+
|
|
526
|
+
|
|
527
|
+
def _budgets(
|
|
528
|
+
config: Config, address: str, key: str, declared: int | None, *, file: str
|
|
529
|
+
) -> Measured:
|
|
530
|
+
"""What an every-turn file costs now — `budget --file`'s own reading, taken here.
|
|
531
|
+
|
|
532
|
+
That read **refuses** a project with no `[budgets]` at all, correctly: a budget for a file
|
|
533
|
+
nobody declared is a limit invented there. Here it is the ordinary case — the caller is
|
|
534
|
+
declaring the first one — so the refusal is caught and reported as the absence it is.
|
|
535
|
+
"""
|
|
536
|
+
from roadkeep.budgeting import file_budget # noqa: PLC0415 - RK260
|
|
537
|
+
|
|
538
|
+
try:
|
|
539
|
+
loads = file_budget(config)
|
|
540
|
+
except (KeyError, OSError):
|
|
541
|
+
loads = ()
|
|
542
|
+
for one in loads:
|
|
543
|
+
if file and one.path != file:
|
|
544
|
+
continue
|
|
545
|
+
cost = next((each for each in one.costs if each.unit == key), None)
|
|
546
|
+
if cost is None:
|
|
547
|
+
continue
|
|
548
|
+
return Measured(
|
|
549
|
+
address=address,
|
|
550
|
+
unit=key,
|
|
551
|
+
worst=cost.taken,
|
|
552
|
+
where=one.path,
|
|
553
|
+
sites=1,
|
|
554
|
+
declared=declared,
|
|
555
|
+
)
|
|
556
|
+
# The file itself, for a budget nothing declares yet: what it costs is what decides the
|
|
557
|
+
# number, and `spent` is the one counter both this and the gate go through.
|
|
558
|
+
if file:
|
|
559
|
+
from roadkeep.config import spent # noqa: PLC0415 - RK260
|
|
560
|
+
|
|
561
|
+
target = config.root / file
|
|
562
|
+
if target.is_file():
|
|
563
|
+
counted = spent(target.read_bytes())
|
|
564
|
+
return Measured(
|
|
565
|
+
address=address,
|
|
566
|
+
unit=key,
|
|
567
|
+
worst=counted[key],
|
|
568
|
+
where=file,
|
|
569
|
+
sites=1,
|
|
570
|
+
declared=declared,
|
|
571
|
+
)
|
|
572
|
+
return Measured(
|
|
573
|
+
address=address,
|
|
574
|
+
unit=key,
|
|
575
|
+
declared=declared,
|
|
576
|
+
unmeasured=(
|
|
577
|
+
f"{file or 'no file'} is not on disk, so there is nothing to measure — a budget "
|
|
578
|
+
f"is about what a loader pays, and a file that is not there pays nothing"
|
|
579
|
+
),
|
|
580
|
+
)
|
|
581
|
+
|
|
582
|
+
|
|
583
|
+
def _tools(config: Config, address: str, key: str, declared: int | None) -> Measured:
|
|
584
|
+
"""What the served surface costs now — `cost --tools`' own reading, taken here."""
|
|
585
|
+
from roadkeep.serving import surface # noqa: PLC0415 - RK260
|
|
586
|
+
|
|
587
|
+
sent = surface(config)
|
|
588
|
+
if key == "characters":
|
|
589
|
+
largest = max(sent.tools, key=lambda one: one[1], default=("", 0))
|
|
590
|
+
return Measured(
|
|
591
|
+
address=address,
|
|
592
|
+
unit="utf-16 code units, per tool",
|
|
593
|
+
worst=largest[1],
|
|
594
|
+
where=largest[0],
|
|
595
|
+
sites=len(sent.tools),
|
|
596
|
+
declared=declared,
|
|
597
|
+
)
|
|
598
|
+
return Measured(
|
|
599
|
+
address=address,
|
|
600
|
+
unit="utf-16 code units, the whole surface",
|
|
601
|
+
worst=sent.characters,
|
|
602
|
+
where=f"{len(sent.tools)} tool(s) and the handshake",
|
|
603
|
+
sites=1,
|
|
604
|
+
declared=declared,
|
|
605
|
+
)
|
|
606
|
+
|
|
607
|
+
|
|
608
|
+
def _reads(config: Config, address: str, declared: int | None) -> Measured:
|
|
609
|
+
"""What the widest brief costs now — `cost --brief`'s own reading, taken here (RK1286).
|
|
610
|
+
|
|
611
|
+
The read this project recommends over reading the file, priced the way every other number
|
|
612
|
+
in this table is: by the reader that owns the question. The **widest** and not the median
|
|
613
|
+
is the reading, for that verb's reason — a brief that fits on the average task and not on
|
|
614
|
+
the hardest one is a brief a session replaces exactly when the file is longest.
|
|
615
|
+
"""
|
|
616
|
+
from roadkeep.budgeting import brief_budget # noqa: PLC0415 - RK260
|
|
617
|
+
|
|
618
|
+
found = brief_budget(config)
|
|
619
|
+
if found.widest is None:
|
|
620
|
+
return Measured(
|
|
621
|
+
address=address,
|
|
622
|
+
unit="utf-16 code units, per brief",
|
|
623
|
+
declared=declared,
|
|
624
|
+
unmeasured=(
|
|
625
|
+
"no open line to brief, so there is nothing to price — a ceiling declared "
|
|
626
|
+
"now is one the first task filed measures itself against"
|
|
627
|
+
),
|
|
628
|
+
)
|
|
629
|
+
return Measured(
|
|
630
|
+
address=address,
|
|
631
|
+
unit="utf-16 code units, per brief",
|
|
632
|
+
worst=found.widest.characters,
|
|
633
|
+
where=found.widest.id,
|
|
634
|
+
sites=len(found.briefs),
|
|
635
|
+
declared=declared,
|
|
636
|
+
)
|
|
637
|
+
|
|
638
|
+
|
|
639
|
+
def govern(
|
|
640
|
+
config: Config,
|
|
641
|
+
address: str,
|
|
642
|
+
at: int,
|
|
643
|
+
*,
|
|
644
|
+
file: str = "",
|
|
645
|
+
role: str = "",
|
|
646
|
+
because: str = "",
|
|
647
|
+
instead: str = "",
|
|
648
|
+
) -> Declared:
|
|
649
|
+
"""Declare one governed number, against the reading that decides it (RK1272).
|
|
650
|
+
|
|
651
|
+
Validated whole before anything is written, which is every other write here: a number the
|
|
652
|
+
corpus breaks, an address this build has no key for, or a config with no table to put it in
|
|
653
|
+
each cost a refusal and an untouched file.
|
|
654
|
+
|
|
655
|
+
``instead`` is the same sentence placed the other way (RK1367): `because` **stacks** on
|
|
656
|
+
whatever argued the number before it, which is right while each paragraph argues about the
|
|
657
|
+
same question, and this one **replaces** the run — the case where the question was settled
|
|
658
|
+
differently and the argument above the key is now for a reading nothing takes. Naming both
|
|
659
|
+
is refused, the two being two acts, and what came out is on :attr:`Declared.displaced`.
|
|
660
|
+
|
|
661
|
+
Neither writes prose (L4). The verb wraps a sentence and places it, and — here — says
|
|
662
|
+
which lines it took to do so.
|
|
663
|
+
"""
|
|
664
|
+
if because and instead:
|
|
665
|
+
raise ValueError(
|
|
666
|
+
"`--because` stacks an argument onto the one above the key and `--instead` "
|
|
667
|
+
"replaces it, so naming both is asking for two placements of one sentence: pass "
|
|
668
|
+
"`--because` where this number is a decision about the last one, and `--instead` "
|
|
669
|
+
"where the reading that decided it has moved"
|
|
670
|
+
)
|
|
671
|
+
if config.source is None:
|
|
672
|
+
raise ValueError(
|
|
673
|
+
"this project declares no roadkeep.toml, so there is no table to write a number "
|
|
674
|
+
f"into: `{invocation()} init` scaffolds one, and every limit is declared there"
|
|
675
|
+
)
|
|
676
|
+
measured = reading(config, address, file=file, role=role)
|
|
677
|
+
if measured.over(at):
|
|
678
|
+
raise Violated(address, at, measured.worst, measured.where, 1)
|
|
679
|
+
if address.startswith("budgets.") and not measured.sites:
|
|
680
|
+
# The same argument as `Violated` for the other absence: a budget for a file that is
|
|
681
|
+
# not there is `budget.absent` to the gate, so writing one is declaring a finding.
|
|
682
|
+
raise ValueError(
|
|
683
|
+
f"{file or 'no file'} is not in this repository, so a budget on it would be a "
|
|
684
|
+
f"limit nothing pays: `budget --file` lists what this project holds, and a file "
|
|
685
|
+
f"that exists is the one thing a budget is about"
|
|
686
|
+
)
|
|
687
|
+
table, key = _addressed(config, address)
|
|
688
|
+
written = _spelled(table, key, file=file, role=role)
|
|
689
|
+
# The lines, not the flag: an argument that wrapped to nothing placed nothing, and an
|
|
690
|
+
# answer reporting a write that did not happen is the one thing no read here may do
|
|
691
|
+
# (RK1295) — the caller this transport is reached from cannot see the file to tell.
|
|
692
|
+
argument = _argued(config, because or instead)
|
|
693
|
+
text, lineno, before, stands, displaced = _inserted(
|
|
694
|
+
config.source, written, at, argument, withdrawing=bool(instead)
|
|
695
|
+
)
|
|
696
|
+
config.source.write_text(text, encoding="utf-8", newline="")
|
|
697
|
+
return Declared(
|
|
698
|
+
address=address,
|
|
699
|
+
at=at,
|
|
700
|
+
measured=measured,
|
|
701
|
+
lineno=lineno,
|
|
702
|
+
before=before,
|
|
703
|
+
argued=bool(argument),
|
|
704
|
+
standing=stands,
|
|
705
|
+
displaced=displaced,
|
|
706
|
+
)
|
|
707
|
+
|
|
708
|
+
|
|
709
|
+
def _spelled(table: str, key: str, *, file: str, role: str) -> tuple[str, str, str]:
|
|
710
|
+
"""The `(heading, key, unit)` this write addresses, as the file spells them.
|
|
711
|
+
|
|
712
|
+
A `<role>` or a `<path>` in the published name is a table declared once per something the
|
|
713
|
+
project names, so the heading is composed from what the caller passed rather than from the
|
|
714
|
+
placeholder — and a path is quoted, that being how TOML spells a key with a stop in it.
|
|
715
|
+
|
|
716
|
+
``unit`` is non-empty only for `[budgets]`, whose value is an **inline table**: the address
|
|
717
|
+
there is the file and the two numbers live inside it, so the key and the thing being set
|
|
718
|
+
are two names rather than one. Every other table's value is a scalar and says so with `""`.
|
|
719
|
+
"""
|
|
720
|
+
if table == "budgets.<path>":
|
|
721
|
+
return "[budgets]", f'"{file}"', key
|
|
722
|
+
if table == "limits" and role:
|
|
723
|
+
return f"[limits.{role}]", key, ""
|
|
724
|
+
return f"[{table}]", key, ""
|
|
725
|
+
|
|
726
|
+
|
|
727
|
+
def _because(
|
|
728
|
+
config: Config, table: str, key: str, *, file: str, role: str
|
|
729
|
+
) -> tuple[str, ...]:
|
|
730
|
+
"""The argument standing above one key in `roadkeep.toml`, verbatim (RK1296).
|
|
731
|
+
|
|
732
|
+
The contiguous comment run directly above the row, with the `#` and one space taken off
|
|
733
|
+
and nothing else touched. Whether those lines were placed by `--because` or written by
|
|
734
|
+
hand years ago is not a question this can answer and not one worth asking: what argues
|
|
735
|
+
the number is what is above it.
|
|
736
|
+
|
|
737
|
+
A project with no config, a table nobody declared or a key nobody wrote each answer with
|
|
738
|
+
nothing, which is the same answer a key with no comment above it gives — and correct in
|
|
739
|
+
all four, an argument being absent either way.
|
|
740
|
+
"""
|
|
741
|
+
if config.source is None or not config.source.exists():
|
|
742
|
+
return ()
|
|
743
|
+
heading, spelled, _ = _spelled(table, key, file=file, role=role)
|
|
744
|
+
lines = config.source.read_text(encoding="utf-8").splitlines()
|
|
745
|
+
inside = False
|
|
746
|
+
for index, line in enumerate(lines):
|
|
747
|
+
stripped = line.strip()
|
|
748
|
+
if stripped.startswith("["):
|
|
749
|
+
if inside:
|
|
750
|
+
return ()
|
|
751
|
+
inside = stripped == heading
|
|
752
|
+
elif inside and "=" in stripped and _named(stripped) == spelled.strip('"'):
|
|
753
|
+
start = _run(lines, index)
|
|
754
|
+
return tuple(line.lstrip()[1:].strip() for line in lines[start:index])
|
|
755
|
+
return ()
|
|
756
|
+
|
|
757
|
+
|
|
758
|
+
def _above(lines: list[str], index: int, because: tuple[str, ...]) -> bool:
|
|
759
|
+
"""Whether `because` is already the last thing standing above `index` (RK1294).
|
|
760
|
+
|
|
761
|
+
The **tail** of the comment run and not the whole of it: a key under a table's own
|
|
762
|
+
scaffolded explanation has that text above it for good, and the argument stacked onto it
|
|
763
|
+
last session is above it too. What a re-run would duplicate is the bottom of that stack.
|
|
764
|
+
"""
|
|
765
|
+
return bool(because) and tuple(lines[max(index - len(because), 0) : index]) == because
|
|
766
|
+
|
|
767
|
+
|
|
768
|
+
def _inserted(
|
|
769
|
+
source: Path,
|
|
770
|
+
written: tuple[str, str, str],
|
|
771
|
+
at: int,
|
|
772
|
+
because: tuple[str, ...] = (),
|
|
773
|
+
*,
|
|
774
|
+
withdrawing: bool = False,
|
|
775
|
+
) -> tuple[str, int, int | None, bool, tuple[str, ...]]:
|
|
776
|
+
"""The config with one key set, byte for byte otherwise (`adopting._with_role`'s rule).
|
|
777
|
+
|
|
778
|
+
A targeted edit and never a serialiser: a `tomllib` round-trip drops the comments a
|
|
779
|
+
config is mostly made of, and this file's comments are the arguments for its numbers —
|
|
780
|
+
which is the one thing this verb exists to keep beside them.
|
|
781
|
+
|
|
782
|
+
A key already there is **rewritten in place**, not appended: a second declaration of one
|
|
783
|
+
number is a file `tomllib` reads one way and a reader reads the other. Where the value is
|
|
784
|
+
an inline table the *other* unit inside it is carried across, for the same reason — a
|
|
785
|
+
`bytes` declared last year is not something a `lines` call decided to drop.
|
|
786
|
+
|
|
787
|
+
The author's argument lands **above** the row wherever the row lands, and **stacks** on
|
|
788
|
+
whatever argued the number before it (RK1293): a raise is a decision about the previous
|
|
789
|
+
decision, and this project's own `[tools]` entry is five of them written that way by hand.
|
|
790
|
+
|
|
791
|
+
**Except where it is that same argument**, byte for byte, in which case nothing is written
|
|
792
|
+
and the fourth return says so (RK1294). The number is idempotent already; the sentence
|
|
793
|
+
beside it is a second decision only when it is a second sentence, and a retried call, a
|
|
794
|
+
replayed capture or an unsure re-run is not one. Byte-for-byte and no wider: whether two
|
|
795
|
+
sentences mean the same thing is a judgement, and this tool has no model (L4).
|
|
796
|
+
|
|
797
|
+
``withdrawing`` is `--instead` (RK1367), and it is the one path that **deletes**: the
|
|
798
|
+
contiguous comment run above the row — the same span :func:`_because` reads back and
|
|
799
|
+
`govern <key>` prints, so the caller replacing it has been shown it — comes out, and the
|
|
800
|
+
argument lands in its place. Only where the key is already there, an argument being
|
|
801
|
+
withdrawn from somewhere; a key this file does not carry has nothing above it, and the
|
|
802
|
+
write is the stacking one with an empty stack. What came out is the fifth return, because
|
|
803
|
+
a deletion nobody is told about is history removed.
|
|
804
|
+
"""
|
|
805
|
+
heading, key, unit = written
|
|
806
|
+
text = source.read_text(encoding="utf-8")
|
|
807
|
+
lines = text.splitlines(keepends=True)
|
|
808
|
+
table, last = None, None
|
|
809
|
+
for index, line in enumerate(lines):
|
|
810
|
+
stripped = line.strip()
|
|
811
|
+
if stripped.startswith("["):
|
|
812
|
+
if stripped == heading:
|
|
813
|
+
table = index
|
|
814
|
+
elif table is not None and index > table:
|
|
815
|
+
break
|
|
816
|
+
elif table is not None and index > table and "=" in stripped:
|
|
817
|
+
last = index
|
|
818
|
+
if _named(stripped) == key.strip('"'):
|
|
819
|
+
before = _number(stripped, unit)
|
|
820
|
+
lines[index] = _row(key, at, unit, standing=stripped)
|
|
821
|
+
stands = _above(lines, index, because)
|
|
822
|
+
# The run comes out first, so `index` is re-taken against the shortened file
|
|
823
|
+
# rather than adjusted by a count computed before the splice.
|
|
824
|
+
# And only where there is a sentence to put in its place (RK1295): an argument
|
|
825
|
+
# that wrapped to nothing placed nothing, so it withdraws nothing either —
|
|
826
|
+
# otherwise `--instead " "` is the silent deletion this flag is built not
|
|
827
|
+
# to be, and the answer would report a reason where the file has none.
|
|
828
|
+
displaced: tuple[str, ...] = ()
|
|
829
|
+
if withdrawing and because and not stands:
|
|
830
|
+
start = _run(lines, index)
|
|
831
|
+
displaced = tuple(lines[start:index])
|
|
832
|
+
del lines[start:index]
|
|
833
|
+
index = start
|
|
834
|
+
placed = () if stands else because
|
|
835
|
+
lines[index:index] = placed
|
|
836
|
+
return "".join(lines), index + len(placed) + 1, before, stands, displaced
|
|
837
|
+
row = _row(key, at, unit)
|
|
838
|
+
if table is None:
|
|
839
|
+
# The table is opened where the key is written, which is `criterion add`'s rule about a
|
|
840
|
+
# heading: a project that never declared one has no place for the first number, and a
|
|
841
|
+
# verb that refused would send the author to the hand edit this exists to end.
|
|
842
|
+
opened = _opened(lines, heading, row, because)
|
|
843
|
+
return "".join(opened), len(opened), None, False, ()
|
|
844
|
+
into = (last if last is not None else table) + 1
|
|
845
|
+
return (
|
|
846
|
+
"".join([*lines[:into], *because, row, *lines[into:]]),
|
|
847
|
+
into + len(because) + 1,
|
|
848
|
+
None,
|
|
849
|
+
False,
|
|
850
|
+
(),
|
|
851
|
+
)
|
|
852
|
+
|
|
853
|
+
|
|
854
|
+
def _run(lines: list[str], index: int) -> int:
|
|
855
|
+
"""Where the contiguous comment run above `index` starts (RK1367).
|
|
856
|
+
|
|
857
|
+
:func:`_because`'s own scan, over lines in hand rather than over the file, so the span a
|
|
858
|
+
read hands back and the span a `--instead` replaces cannot come apart.
|
|
859
|
+
"""
|
|
860
|
+
start = index
|
|
861
|
+
while start > 0 and lines[start - 1].lstrip().startswith("#"):
|
|
862
|
+
start -= 1
|
|
863
|
+
return start
|
|
864
|
+
|
|
865
|
+
|
|
866
|
+
def _row(key: str, at: int, unit: str = "", standing: str = "") -> str:
|
|
867
|
+
"""One declaration line: a scalar, or an inline table with the other unit carried over."""
|
|
868
|
+
if not unit:
|
|
869
|
+
return f"{key} = {at}\n"
|
|
870
|
+
inside = dict(_pairs(standing))
|
|
871
|
+
inside[unit] = at
|
|
872
|
+
spelled = ", ".join(f"{name} = {value}" for name, value in inside.items())
|
|
873
|
+
return f"{key} = {{ {spelled} }}\n"
|
|
874
|
+
|
|
875
|
+
|
|
876
|
+
def _pairs(line: str) -> tuple[tuple[str, int], ...]:
|
|
877
|
+
"""The `name = <number>` pairs inside an inline table, in the order the file wrote them."""
|
|
878
|
+
if "{" not in line:
|
|
879
|
+
return ()
|
|
880
|
+
body = line[line.index("{") + 1 : line.rindex("}")] if "}" in line else ""
|
|
881
|
+
return tuple(
|
|
882
|
+
(found.group(1), int(found.group(2)))
|
|
883
|
+
for found in re.finditer(r"(\w+)\s*=\s*(-?\d+)", body)
|
|
884
|
+
)
|
|
885
|
+
|
|
886
|
+
|
|
887
|
+
def _named(line: str) -> str:
|
|
888
|
+
return line.split("=", 1)[0].strip().strip('"')
|
|
889
|
+
|
|
890
|
+
|
|
891
|
+
def _number(line: str, unit: str = "") -> int | None:
|
|
892
|
+
"""What the line declares now — the scalar, or the one unit inside an inline table."""
|
|
893
|
+
if unit:
|
|
894
|
+
return dict(_pairs(line)).get(unit)
|
|
895
|
+
found = re.search(r"-?\d+", line.split("=", 1)[1])
|
|
896
|
+
return int(found.group()) if found else None
|
|
897
|
+
|
|
898
|
+
|
|
899
|
+
def _opened(
|
|
900
|
+
lines: list[str], heading: str, row: str, because: tuple[str, ...] = ()
|
|
901
|
+
) -> list[str]:
|
|
902
|
+
"""The file with a new table appended, separated by one blank line and no more."""
|
|
903
|
+
end = len(lines)
|
|
904
|
+
while end > 0 and not lines[end - 1].strip():
|
|
905
|
+
end -= 1
|
|
906
|
+
return [*lines[:end], "\n", f"{heading}\n", *because, row]
|
|
907
|
+
|
|
908
|
+
|
|
909
|
+
def _argued(config: Config, because: str) -> tuple[str, ...]:
|
|
910
|
+
"""The author's argument as comment lines, filled to this project's own width (RK1293).
|
|
911
|
+
|
|
912
|
+
Filled and never one long line, because the file it lands in is read by a person and every
|
|
913
|
+
comment already in it wraps. The width is the project's `[limits] prose` — the one number
|
|
914
|
+
here about how wide written prose is — so a config whose author chose 72 gets 72 rather
|
|
915
|
+
than a column this module picked.
|
|
916
|
+
|
|
917
|
+
The prose is the author's verbatim (L4). What this composes is the `#` and the wrapping,
|
|
918
|
+
which is the same split every field of every write here already takes.
|
|
919
|
+
"""
|
|
920
|
+
if not because:
|
|
921
|
+
return ()
|
|
922
|
+
import textwrap # noqa: PLC0415 - RK260
|
|
923
|
+
|
|
924
|
+
return tuple(
|
|
925
|
+
f"{line}\n"
|
|
926
|
+
for line in textwrap.wrap(
|
|
927
|
+
" ".join(because.split()),
|
|
928
|
+
width=config.schema.prose_width,
|
|
929
|
+
initial_indent="# ",
|
|
930
|
+
subsequent_indent="# ",
|
|
931
|
+
break_long_words=False,
|
|
932
|
+
break_on_hyphens=False,
|
|
933
|
+
)
|
|
934
|
+
)
|