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
@@ -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