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
|
@@ -0,0 +1,307 @@
|
|
|
1
|
+
"""Prose on the way in: a pipe, a path, and the encoding both are read under (RK494).
|
|
2
|
+
|
|
3
|
+
Three things a verb needs before it has anything to validate, and one module because they
|
|
4
|
+
are one act: a paragraph arrives on stdin (RK9) or by path (RK381), and either way it is
|
|
5
|
+
read under an encoding this process had to force — the default Windows console encoding is
|
|
6
|
+
cp1252, and a substituted character round-trips out of the file it lands in (L3).
|
|
7
|
+
|
|
8
|
+
:func:`harden` is where the `global` lives now. `main` used to set that flag in `cli`'s own
|
|
9
|
+
namespace and every reader of it sat alongside; with the readers here the write belongs here
|
|
10
|
+
too — one process, one answer, and the module that answers is the module that decides.
|
|
11
|
+
"""
|
|
12
|
+
|
|
13
|
+
from __future__ import annotations
|
|
14
|
+
|
|
15
|
+
import codecs
|
|
16
|
+
import io
|
|
17
|
+
import re
|
|
18
|
+
import sys
|
|
19
|
+
from collections.abc import Callable
|
|
20
|
+
from pathlib import Path
|
|
21
|
+
|
|
22
|
+
from roadkeep.authoring import Rereadable
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
def _verbatim(path: Path) -> str:
|
|
26
|
+
"""One of git's three versions, read the way `Document.load` reads a governed file."""
|
|
27
|
+
with path.open("r", encoding="utf-8", newline="") as handle:
|
|
28
|
+
return handle.read()
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
#: The spelling every prose argument here reads as "take it off the pipe". One string, for
|
|
32
|
+
#: :attr:`~roadkeep.serving.Prose.sentinel`'s reason: a second would be a second thing to know.
|
|
33
|
+
STDIN = "-"
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
#: The line terminators a pipe adds and nobody typed (RK329). All of them, so a file
|
|
37
|
+
#: ending in a blank line reads as the sentence it holds — and nothing else, so a trailing
|
|
38
|
+
#: space stays the author's and stays refused.
|
|
39
|
+
_TRAILING_NEWLINES = re.compile(r"[\r\n]+\Z")
|
|
40
|
+
|
|
41
|
+
#: The byte order mark an encoder writes ahead of the stream, which nobody typed (RK1023).
|
|
42
|
+
_BOM = ""
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def _unmarked(text: str) -> str:
|
|
46
|
+
"""A stream's first character, less the mark its encoder opened with (RK1023).
|
|
47
|
+
|
|
48
|
+
Windows PowerShell 5.1 pipes to a native command through `$OutputEncoding`, whose UTF-8
|
|
49
|
+
encoder emits a preamble — so the first character this tool reads is U+FEFF, and
|
|
50
|
+
`char.invisible` refuses the field. The refusal is correct about the codepoint and wrong
|
|
51
|
+
about who wrote it, and it then names *stdin* as the remedy for a byte stdin added:
|
|
52
|
+
the author is told to take the route they already took, and nothing in their command
|
|
53
|
+
names the encoding that put it there. `$OutputEncoding = UTF8Encoding.new($false)` does
|
|
54
|
+
not help either, which is what makes this the reader's to fix.
|
|
55
|
+
|
|
56
|
+
**One, and only at position 1.** A mark there is a byte order mark doing its job; the
|
|
57
|
+
same codepoint anywhere else in the sentence is prose that no keyboard produces, and the
|
|
58
|
+
scan that refuses it is untouched. `str.removeprefix` is that distinction exactly, and
|
|
59
|
+
the reason this is not `utf-8-sig`: a codec would eat one wherever a read began, and the
|
|
60
|
+
governed files are read by `Document`, where a stripped byte is a file that stopped
|
|
61
|
+
round-tripping (L3).
|
|
62
|
+
"""
|
|
63
|
+
return text.removeprefix(_BOM)
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
def _piped(value: str | None) -> str | None:
|
|
67
|
+
"""A prose argument, read off stdin where it spells `-` (RK329).
|
|
68
|
+
|
|
69
|
+
The asymmetry this closes was backwards. `--section-body` documented the pipe because a
|
|
70
|
+
paragraph is long; `--why` is the field that reliably carries an apostrophe, a backtick, an
|
|
71
|
+
em dash and a `§` — its sentence names types, files and prior ids — and every one of those
|
|
72
|
+
is read by a shell before this program sees it. Measured twice in one session against an
|
|
73
|
+
adopting repo: a `ship --why` lost to a PowerShell parse, another to a bash single-quoted
|
|
74
|
+
string containing `T293's`, both recovered by writing the prose to a variable first, which
|
|
75
|
+
is what stdin exists to avoid.
|
|
76
|
+
|
|
77
|
+
**The failure is silent in the bad direction**, which is why it is worth a door: a shell
|
|
78
|
+
that eats a backtick does not refuse, it hands over prose subtly unlike what was written
|
|
79
|
+
and the line lands. A quote terminating early is the loud case, and the lucky one.
|
|
80
|
+
|
|
81
|
+
No validation changes. The sentence is still refused for a missing terminator or a length
|
|
82
|
+
it cannot have — what changes is how it arrives.
|
|
83
|
+
|
|
84
|
+
**The line terminator is the pipe's and not the author's**, so it comes off. `echo`,
|
|
85
|
+
`printf` and every heredoc end with one, and `why.whitespace` firing on it would make the
|
|
86
|
+
affordance unusable by the tools that reach for it — the refusal correct about the bytes
|
|
87
|
+
and wrong about who wrote them. Only the terminators: a trailing *space* is the author's
|
|
88
|
+
and is still refused, and an interior newline is still `why.newline`, because prose that
|
|
89
|
+
arrived in two lines is a second sentence however it got here.
|
|
90
|
+
"""
|
|
91
|
+
if value != STDIN:
|
|
92
|
+
return value
|
|
93
|
+
_refuse_unhardened()
|
|
94
|
+
# Both ends of the stream belong to the encoder and not to the author (RK1023): the
|
|
95
|
+
# terminator it closed with, and the mark it opened with.
|
|
96
|
+
return _TRAILING_NEWLINES.sub("", _unmarked(sys.stdin.read()))
|
|
97
|
+
|
|
98
|
+
|
|
99
|
+
def _body_reader(literal: str | None, path: str | None) -> Callable[[], str]:
|
|
100
|
+
"""Where a paragraph comes from, as a reader nobody calls until it is needed (RK381).
|
|
101
|
+
|
|
102
|
+
Three sources and one function, because the caller that has to know which of them a given
|
|
103
|
+
argv chose is the caller that gets it wrong: a path, a string, and the pipe that both an
|
|
104
|
+
omitted argument and the documented `-` reach. Returned rather than read, so the ordering
|
|
105
|
+
:func:`~roadkeep.authoring.add` now guarantees is available to every door — a body fetched
|
|
106
|
+
at the call site is a body spent before the field that refuses has been looked at.
|
|
107
|
+
|
|
108
|
+
A file is read whole, in UTF-8, and its bytes are the author's: the trailing newline every
|
|
109
|
+
editor writes is `_normalize`'s to take off, exactly as it is for the pipe, and nothing
|
|
110
|
+
here reflows or strips. A path that is not there raises `OSError`, which is in
|
|
111
|
+
:data:`REFUSALS` and exits 2 like every other bad input.
|
|
112
|
+
"""
|
|
113
|
+
# Two of the three are **re-readable**, and saying so is what lets `add` refuse both
|
|
114
|
+
# fields at once (RK426): a path costs a file read to fetch twice and a literal costs
|
|
115
|
+
# nothing, while the pipe is the one source spent by looking at it. RK381's deferral is
|
|
116
|
+
# unchanged for that one — it is the only case its argument was ever about.
|
|
117
|
+
if path is not None:
|
|
118
|
+
# The same mark, by the shorter route (RK1028): every mainstream Windows editor
|
|
119
|
+
# writes one, and a path is the source a caller reaches for when the prose is long.
|
|
120
|
+
return Rereadable(lambda: _unmarked(Path(path).read_text(encoding="utf-8")))
|
|
121
|
+
if literal is not None and literal != STDIN:
|
|
122
|
+
return Rereadable(lambda: literal)
|
|
123
|
+
_refuse_unhardened()
|
|
124
|
+
# The same preamble reaches a body, and by a shorter route: a paragraph is the field a
|
|
125
|
+
# caller pipes first, so the escape hatch fails here before it fails on a `why` (RK1023).
|
|
126
|
+
return lambda: _unmarked(sys.stdin.read())
|
|
127
|
+
|
|
128
|
+
|
|
129
|
+
def _refuse_unhardened() -> None:
|
|
130
|
+
"""Stop a prose read this process cannot make strictly (RK455).
|
|
131
|
+
|
|
132
|
+
A `ValueError`, so it lands in :data:`REFUSALS` and exits 2 with every other bad input —
|
|
133
|
+
the caller passed an argv this process cannot honour, which is exactly what a usage
|
|
134
|
+
refusal is. Raised at the point of *reading* and never at startup: the overwhelming
|
|
135
|
+
majority of calls never touch stdin, and refusing them would be the crash this replaced
|
|
136
|
+
with an exit code stapled on.
|
|
137
|
+
"""
|
|
138
|
+
said = _unhardened()
|
|
139
|
+
if said is not None:
|
|
140
|
+
raise ValueError(said.removeprefix("roadkeep: "))
|
|
141
|
+
|
|
142
|
+
|
|
143
|
+
def _one_body(named: str, literal: str | None, path: str | None) -> str | None:
|
|
144
|
+
"""Why an argv naming a paragraph twice is refused, or None (RK381).
|
|
145
|
+
|
|
146
|
+
:func:`_one_pipe`'s rule for the other pair. A string and a path are two answers to one
|
|
147
|
+
question, and honouring either silently is how a caller comes to believe the file is what
|
|
148
|
+
landed — which is worse than the refusal, because the wrong prose is in the file and the
|
|
149
|
+
command said it worked.
|
|
150
|
+
|
|
151
|
+
And the dash, which is the other way to name a source twice (RK406). Measured filing a
|
|
152
|
+
task in this repository: `--section-body-file -` opened a file called `-` and answered
|
|
153
|
+
`[Errno 2] No such file or directory: '-'`, from a door whose body **already** comes from
|
|
154
|
+
stdin unless a path is given. The refusal is by name and not a second reading of it: `-`
|
|
155
|
+
is already this CLI's spelling on the *literal* flag, and taking it here too would be two
|
|
156
|
+
spellings of one thing on one pair of arguments — which is what this function exists to
|
|
157
|
+
refuse. So the sentence says where the body comes from, which is the fact the caller
|
|
158
|
+
typing it did not have.
|
|
159
|
+
"""
|
|
160
|
+
if path == STDIN:
|
|
161
|
+
return (
|
|
162
|
+
f"{named}-file takes a path and {STDIN!r} is not one: the body already comes "
|
|
163
|
+
f"from stdin unless a path is given, so pass no source at all — or {named} "
|
|
164
|
+
f"{STDIN} where a flag is wanted"
|
|
165
|
+
)
|
|
166
|
+
if literal in (None, STDIN) or path is None:
|
|
167
|
+
return None
|
|
168
|
+
return (
|
|
169
|
+
f"{named} and {named}-file are two answers to one question: pass the prose or "
|
|
170
|
+
f"the path it is in, not both"
|
|
171
|
+
)
|
|
172
|
+
|
|
173
|
+
|
|
174
|
+
def _one_pipe(*asked: tuple[str, bool]) -> str | None:
|
|
175
|
+
"""Why an argv that sent two arguments to one pipe is refused, or None (RK329).
|
|
176
|
+
|
|
177
|
+
There is one stdin and it is read to EOF, so a call whose `why` and whose section body
|
|
178
|
+
both want it has asked for a split no rule here can make. Refused rather than given to the
|
|
179
|
+
first: a body that silently absorbed the sentence meant for the line would be the quiet
|
|
180
|
+
corruption this whole task is about, one layer further in.
|
|
181
|
+
"""
|
|
182
|
+
named = [name for name, reached in asked if reached]
|
|
183
|
+
if len(named) < 2:
|
|
184
|
+
return None
|
|
185
|
+
return (
|
|
186
|
+
f"{' and '.join(named)} both read stdin, and there is one: pass one of them as a "
|
|
187
|
+
f"string. A pipe is read to EOF, so splitting it between two fields is a guess"
|
|
188
|
+
)
|
|
189
|
+
|
|
190
|
+
|
|
191
|
+
def _force_utf8(stream: object, errors: str = "backslashreplace") -> bool:
|
|
192
|
+
"""Harden one stream, and say whether it took (RK455).
|
|
193
|
+
|
|
194
|
+
A text stream that has **already been read** refuses `reconfigure`, and the refusal is a
|
|
195
|
+
raise — so `main` died out of this line with the verb never reached, on a stream this
|
|
196
|
+
tool did not open and cannot assume it may re-encode. Measured with `pytest -n 8`, where
|
|
197
|
+
an xdist worker is bootstrapped over its own stdin so fd 0 arrives read: nine to sixteen
|
|
198
|
+
tests failed here, none of them about what they assert. The same shape reaches any host
|
|
199
|
+
that embeds this CLI and hands over a used stdin.
|
|
200
|
+
|
|
201
|
+
**Not a bare `pass`.** `errors="strict"` on the way in is what keeps input that is not
|
|
202
|
+
UTF-8 refused rather than repaired, because a substituted character round-trips into a
|
|
203
|
+
governed file and stays (L3) — a stdin that silently keeps cp1252 is that defect with no
|
|
204
|
+
report. So the failure is returned rather than swallowed, and :func:`_unhardened` is
|
|
205
|
+
where a verb that actually reads the stream says what it could not apply.
|
|
206
|
+
"""
|
|
207
|
+
reconfigure = getattr(stream, "reconfigure", None)
|
|
208
|
+
if reconfigure is not None:
|
|
209
|
+
try:
|
|
210
|
+
reconfigure(encoding="utf-8", errors=errors)
|
|
211
|
+
except (io.UnsupportedOperation, ValueError, OSError):
|
|
212
|
+
# Every way a stream says no: already read, or detached.
|
|
213
|
+
return _already_utf8(stream)
|
|
214
|
+
return True
|
|
215
|
+
return _already_utf8(stream)
|
|
216
|
+
|
|
217
|
+
|
|
218
|
+
def _already_utf8(stream: object) -> bool:
|
|
219
|
+
"""Whether this stream needs no hardening, having no decoding to get wrong (RK455).
|
|
220
|
+
|
|
221
|
+
The narrowing that keeps the refusal about the defect. What `errors="strict"` buys is
|
|
222
|
+
that bytes which are not UTF-8 are **refused rather than substituted**, and a stream with
|
|
223
|
+
no `encoding` is decoding nothing — a `StringIO` a caller handed over is already `str`,
|
|
224
|
+
so there is no codec that could be silently keeping cp1252. One that names UTF-8 is the
|
|
225
|
+
same answer arriving the other way.
|
|
226
|
+
|
|
227
|
+
Read after the reconfigure rather than instead of it: hardening also sets `errors`, which
|
|
228
|
+
a stream already in UTF-8 may still have as `replace`. That is a residual this states
|
|
229
|
+
rather than hides — the substitution it would make is of *undecodable* bytes, which by
|
|
230
|
+
then are not a codec question, and refusing every such caller would take the pipe away
|
|
231
|
+
from the hosts this exists to keep working.
|
|
232
|
+
"""
|
|
233
|
+
named = getattr(stream, "encoding", None)
|
|
234
|
+
if named is None:
|
|
235
|
+
return True
|
|
236
|
+
return codecs.lookup(str(named)).name == "utf-8"
|
|
237
|
+
|
|
238
|
+
|
|
239
|
+
#: Whether stdin arrived as a stream this process could make strict UTF-8 (RK455). Module
|
|
240
|
+
#: state because `main` decides it once per process and the reader that needs it is four
|
|
241
|
+
#: frames down a handler — and because it is a fact about the *process*, not about a call.
|
|
242
|
+
_STDIN_HARDENED = True
|
|
243
|
+
|
|
244
|
+
|
|
245
|
+
def harden() -> None:
|
|
246
|
+
"""Force the three standard streams to UTF-8, and record what stdin allowed (RK494).
|
|
247
|
+
|
|
248
|
+
`main` did this inline while the flag and every reader of it were in one file. The readers
|
|
249
|
+
are here now, so the write is too: a `global` reaches one module's namespace, and a caller
|
|
250
|
+
rebinding its own imported copy would leave :func:`_unhardened` answering about a stream
|
|
251
|
+
nobody hardened.
|
|
252
|
+
|
|
253
|
+
stdin is strict on the way in — input that is not UTF-8 is refused, never repaired, because
|
|
254
|
+
a substituted character round-trips out of the file it lands in (L3). stdout and stderr are
|
|
255
|
+
not: the markers are emoji and the default Windows console encoding is cp1252, which raises
|
|
256
|
+
mid-write and leaves a half-printed report. What these three were before is
|
|
257
|
+
`provenance.STARTUP_CODECS`, recorded at import because after this the fact is gone (RK341)
|
|
258
|
+
— and recorded rather than assumed (RK455), a stream this tool did not open being one it
|
|
259
|
+
cannot insist on re-encoding, with the verb running either way.
|
|
260
|
+
"""
|
|
261
|
+
global _STDIN_HARDENED # noqa: PLW0603 - one process, one answer, decided here
|
|
262
|
+
_STDIN_HARDENED = _force_utf8(sys.stdin, errors="strict")
|
|
263
|
+
_force_utf8(sys.stdout)
|
|
264
|
+
_force_utf8(sys.stderr)
|
|
265
|
+
|
|
266
|
+
|
|
267
|
+
def unread_prose(*, named: str = "--body") -> str:
|
|
268
|
+
"""The clause an answer adds where it left the prose alone (RK1109).
|
|
269
|
+
|
|
270
|
+
A title-only `section amend` does not read the pipe, by design and correctly — `None` stays
|
|
271
|
+
`None` so a call with nothing to read never blocks on a stream nobody opened. What that cost
|
|
272
|
+
was silence: a caller who piped the replacement prose *and* passed `--title` got the title
|
|
273
|
+
compared alone, and where it already read that way the answer was `unchanged: it already
|
|
274
|
+
reads that way` at exit 0, over a paragraph that was never read.
|
|
275
|
+
|
|
276
|
+
**Said rather than detected**, which is the whole reading. "Is a body waiting on stdin" has
|
|
277
|
+
no portable answer, and the one that looks right — stdin is not a tty — is wrong exactly
|
|
278
|
+
where this tool is used most: the MCP server owns stdin for the protocol, so every served
|
|
279
|
+
`section_amend` would be refused for a pipe that is the transport. A sentence naming what
|
|
280
|
+
the call did not do is true unconditionally, costs no test, and cannot false-positive.
|
|
281
|
+
|
|
282
|
+
The flag it names is the one that would work here: over a stream this process could not make
|
|
283
|
+
strict UTF-8 the pipe is not available at all, and `--body-file` is the door (RK455).
|
|
284
|
+
"""
|
|
285
|
+
if _STDIN_HARDENED:
|
|
286
|
+
return f"the prose was not read; pass {named} - to replace it"
|
|
287
|
+
return (
|
|
288
|
+
f"the prose was not read, and this process cannot read a pipe; "
|
|
289
|
+
f"{named}-file <path> is the door"
|
|
290
|
+
)
|
|
291
|
+
|
|
292
|
+
|
|
293
|
+
def _unhardened() -> str | None:
|
|
294
|
+
"""Why this process may not read prose off stdin, or None where it may (RK455).
|
|
295
|
+
|
|
296
|
+
The refusal a verb makes instead of assuming a strictness it failed to apply. Only the
|
|
297
|
+
commands that actually read the stream are refused: a `lint` in a worker whose stdin was
|
|
298
|
+
consumed has nothing to lose by it, and refusing there would be the crash this replaced
|
|
299
|
+
wearing an exit code.
|
|
300
|
+
"""
|
|
301
|
+
if _STDIN_HARDENED:
|
|
302
|
+
return None
|
|
303
|
+
return (
|
|
304
|
+
"roadkeep: stdin was already read by this process's host, so it could not be made "
|
|
305
|
+
"strict UTF-8 — and prose decoded by whatever codec it kept would round-trip into a "
|
|
306
|
+
"governed file (L3). Pass the text as an argument, or `--body-file <path>`."
|
|
307
|
+
)
|
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
"""The three exit codes, and the one place a raised error becomes one (RK494).
|
|
2
|
+
|
|
3
|
+
What every handler ends with, so it is what they may not each spell: 0 success, 1 the gate
|
|
4
|
+
says no, 2 usage or configuration — the contract :mod:`roadkeep.cli`'s own rules state, held
|
|
5
|
+
in the module a verb can import without importing the command surface.
|
|
6
|
+
|
|
7
|
+
:data:`REFUSALS` is listed once for the same reason it always was: fourteen writing commands
|
|
8
|
+
catch the same set, so adding a class to it is one edit rather than fourteen and thirteen of
|
|
9
|
+
them enough.
|
|
10
|
+
"""
|
|
11
|
+
|
|
12
|
+
from __future__ import annotations
|
|
13
|
+
|
|
14
|
+
import sys
|
|
15
|
+
|
|
16
|
+
from roadkeep import provenance
|
|
17
|
+
from roadkeep.kernel.document import RoundTripError, StaleFile
|
|
18
|
+
from roadkeep.kernel.schema import SchemaError
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
EXIT_OK = 0
|
|
22
|
+
EXIT_GATE = 1
|
|
23
|
+
EXIT_USAGE = 2
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
#: What a write may fail with, listed once because every writing command catches the same
|
|
27
|
+
#: set and :func:`_refused` decides the code. Written out at fourteen call sites, adding
|
|
28
|
+
#: :class:`StaleFile` (RK116) to the tuple would have been fourteen edits and thirteen of
|
|
29
|
+
#: them enough — a command that missed it would print a traceback instead of a refusal.
|
|
30
|
+
REFUSALS = (RoundTripError, StaleFile, KeyError, ValueError, OSError)
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
#: Where a refusal that computed an address keeps it. Two names and not one field: the first is
|
|
34
|
+
#: a channel the kernel declares for the layer above it (`SchemaError.offered`), the second is a
|
|
35
|
+
#: refusal class's own answer that its callers and its tests already read (`SectionExists.free`).
|
|
36
|
+
#: Both are addresses this tool derived while explaining why it refused, which is the whole
|
|
37
|
+
#: population RK1149 is about — and a third one is a row here rather than a second function.
|
|
38
|
+
_OFFERS = ("offered", "free")
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
def _retrying(error: Exception) -> str | None:
|
|
42
|
+
"""The caller's own call with the address it was refused for, or ``None`` (RK1149).
|
|
43
|
+
|
|
44
|
+
`lint` findings have carried a door since RK15 — the command, pre-filled — and a write
|
|
45
|
+
refusal carried prose alone. Two of them had already *done the work*: the free anchor is
|
|
46
|
+
computed to explain the rule and then handed over as a sentence to read, extract and retype
|
|
47
|
+
into an otherwise identical call. Measured on a project on the outline scheme: seven tasks
|
|
48
|
+
filed, five refused first for exactly this, five retries carrying no new information.
|
|
49
|
+
|
|
50
|
+
Two conditions, and both are absences rather than judgements. No offered address — which is
|
|
51
|
+
every refusal about anything else, and the two anchor cases that decline to guess (RK360) — is
|
|
52
|
+
nothing to substitute. And **no recorded argv is a caller that made none**: the MCP server
|
|
53
|
+
dispatches a parsed namespace (RK24), so there is no call of theirs to hand back, and the
|
|
54
|
+
served `add` withholds `--ref` anyway — under an id scheme it is derived — which is why the
|
|
55
|
+
sentence there names `anchors`, a read that surface does serve (RK444, RK463). That the slot
|
|
56
|
+
is *empty* rather than stale is `serving`'s to guarantee, and it clears it where a call begins.
|
|
57
|
+
|
|
58
|
+
**The address the caller typed is replaced wherever it sits**, which is one rule for two
|
|
59
|
+
shapes: `--ref XXIII.7` on a task line and the bare positional `section add XXIII.7`. The
|
|
60
|
+
second refusal is the one RK1149 measured as worse than the first — the address is burnt, the
|
|
61
|
+
author had no way to know, and the retry is the same call one token different. Where nothing
|
|
62
|
+
matches, nothing was typed, and the flag is appended.
|
|
63
|
+
|
|
64
|
+
A `Door`, so the spelling is the one every other command's remedy uses (RK254) — this engine
|
|
65
|
+
as this machine can reach it, and never a console script no `pip install` put on PATH. Quoted,
|
|
66
|
+
this being the first door whose argv carries the caller's own prose: a symptom and a why with
|
|
67
|
+
spaces and apostrophes in them, and an unquoted line is one that runs as eight arguments.
|
|
68
|
+
"""
|
|
69
|
+
from roadkeep.provenance import invocation_argv # noqa: PLC0415 - RK260
|
|
70
|
+
from roadkeep.remedying import Door # noqa: PLC0415 - RK260
|
|
71
|
+
|
|
72
|
+
offered = next((getattr(error, one, "") for one in _OFFERS if getattr(error, one, "")), "")
|
|
73
|
+
if not offered:
|
|
74
|
+
return None
|
|
75
|
+
argv = list(invocation_argv())
|
|
76
|
+
if not argv:
|
|
77
|
+
return None
|
|
78
|
+
# **Which token the address replaces is the error's to say** (RK1378). Every refusal here
|
|
79
|
+
# until now offered an address for the one the caller *spent* — `anchor` — so substituting
|
|
80
|
+
# it was one rule. `NotASibling` offers one for the **destination**: the source is where the
|
|
81
|
+
# heading is and the free child is where it may go, so replacing the anchor composes a call
|
|
82
|
+
# that moves a different section to the address just refused. Read off `to` first, and only
|
|
83
|
+
# where the error carries one, which no other refusal in `_OFFERS` does.
|
|
84
|
+
destination = getattr(error, "to", "")
|
|
85
|
+
burnt = getattr(error, "anchor", "")
|
|
86
|
+
if destination and destination in argv:
|
|
87
|
+
argv[argv.index(destination)] = offered
|
|
88
|
+
elif burnt and burnt in argv:
|
|
89
|
+
argv[argv.index(burnt)] = offered
|
|
90
|
+
elif "--ref" in argv:
|
|
91
|
+
at = argv.index("--ref")
|
|
92
|
+
argv[at + 1 : at + 2] = [offered]
|
|
93
|
+
else:
|
|
94
|
+
argv += ["--ref", offered]
|
|
95
|
+
return Door(
|
|
96
|
+
argv=tuple(argv), what="the same call, with the address it was refused for"
|
|
97
|
+
).quoted
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
def _refused(error: Exception) -> int:
|
|
101
|
+
"""One error path for every command that writes. The exit code is the contract.
|
|
102
|
+
|
|
103
|
+
And the one place the exception still exists, so it is where the modules that decided it are
|
|
104
|
+
recorded (RK267): below here there is a printed line and an exit code, and a surface reading
|
|
105
|
+
those cannot tell a `why.too-long` from `schema.py` apart from a `ref.missing` from
|
|
106
|
+
`sections.py`. Free on this path — a refusal is already the slow branch — and read by nothing
|
|
107
|
+
a terminal reaches.
|
|
108
|
+
"""
|
|
109
|
+
provenance.witness(error)
|
|
110
|
+
if isinstance(error, SchemaError):
|
|
111
|
+
# Every violation at once, each naming its limit: a refusal that reports one
|
|
112
|
+
# problem per run turns a single fix into a conversation.
|
|
113
|
+
print("roadkeep: refused, nothing written:", file=sys.stderr)
|
|
114
|
+
if error.beside:
|
|
115
|
+
# First, and above the fields (RK1256): it is the half a caller cannot fix by
|
|
116
|
+
# editing prose, so a reader who stops at the first line has stopped at the one
|
|
117
|
+
# that decides whether the rest is worth rewriting.
|
|
118
|
+
print(f" {error.beside}", file=sys.stderr)
|
|
119
|
+
if error.about:
|
|
120
|
+
# Above the fields for the same reason and a narrower one (RK1262): it says which
|
|
121
|
+
# argument the rows below are about, and a reader who reads them first has already
|
|
122
|
+
# started editing the wrong one.
|
|
123
|
+
print(f" {error.about}", file=sys.stderr)
|
|
124
|
+
for violation in error.violations:
|
|
125
|
+
print(f" {violation}", file=sys.stderr)
|
|
126
|
+
retry = _retrying(error)
|
|
127
|
+
if retry is not None:
|
|
128
|
+
print(f" retry {retry}", file=sys.stderr)
|
|
129
|
+
return EXIT_USAGE
|
|
130
|
+
if isinstance(error, (RoundTripError, StaleFile)):
|
|
131
|
+
# The file drifted before this command ran, so the gate says no: normalizing a
|
|
132
|
+
# line the parser may have misread is the corruption L3 forbids — and a file that
|
|
133
|
+
# moved between the read and the write is the same refusal one layer down (RK116),
|
|
134
|
+
# where what would be lost is somebody else's line rather than this one's shape.
|
|
135
|
+
print(f"roadkeep: {error}", file=sys.stderr)
|
|
136
|
+
return EXIT_GATE
|
|
137
|
+
# KeyError renders its message in quotes, which reads as a stray token in a report.
|
|
138
|
+
message = error.args[0] if isinstance(error, KeyError) else error
|
|
139
|
+
print(f"roadkeep: {message}", file=sys.stderr)
|
|
140
|
+
# The other refusal that computed an address (RK1149): a `section add` onto one a shipped
|
|
141
|
+
# entry's prose still cites, whose remedy sentence names the free child. Here and not only in
|
|
142
|
+
# the SchemaError branch, because that is where `SectionExists` arrives — a ValueError.
|
|
143
|
+
retry = _retrying(error)
|
|
144
|
+
if retry is not None:
|
|
145
|
+
print(f" retry {retry}", file=sys.stderr)
|
|
146
|
+
return EXIT_USAGE
|