rungate 0.8.7 → 0.8.8

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.
@@ -0,0 +1,414 @@
1
+ /**
2
+ * DOC-DIST: a document may not state, in prose, how many lines away one of
3
+ * its OWN parts is.
4
+ *
5
+ * ## What this refuses, and what it deliberately does not
6
+ *
7
+ * "the comment recording #174 sits four lines above it" is about a source
8
+ * file this document is describing. That distance is a fact about another
9
+ * artefact, it is as checkable as any other quoted fact, and nothing here
10
+ * touches it.
11
+ *
12
+ * The deciding measurement, 2026-10-27, over `specs/`, `.claude/rules/`,
13
+ * `docs/` and `reference/`: **19** distance claims, **17** of that kind.
14
+ * After three rounds of #1624 review moved the pattern and the scanned set,
15
+ * the population is **41** distance claims across **205** tracked
16
+ * non-fixture markdown files, and the ratio did not move in the direction
17
+ * that would matter — **none** of the 41 is self-referential.
18
+ *
19
+ * The figure is the count under the CURRENT rule, and it has moved every
20
+ * round, which is why it is restated rather than inherited: 40 at round 1,
21
+ * **38** at round 2 (teens added, `on` removed), **41** at rounds 3 and 4.
22
+ *
23
+ * **Round 3 explained that last move wrongly and the correction matters.**
24
+ * It said the wrap-crossing window "found three claims no line-by-line scan
25
+ * could see" — read off the delta 38 → 41, with two changes in the commit.
26
+ * Counted directly: **5** of the 41 span a newline, and every one of them
27
+ * spans it inside the distance phrase itself (`"twenty\nlines above"`),
28
+ * where the separator is `\s+` and always was. Removing `a`/`an` took two
29
+ * away; whole-text matching added five; the net was three and the three were
30
+ * never a population.
31
+ *
32
+ * Which leaves a fact worth stating plainly rather than leaving implied:
33
+ * **no claim in this tree exercises the GAP's newline at all.** The wrap
34
+ * case is real — it is why round 3 exists — but against the live corpus the
35
+ * crossing is UNMEASURED, and its only evidence is the planted rows in
36
+ * `DOC-DIST-3d` and `DOC-DIST-3e`.
37
+ *
38
+ * The two that were not are a different animal: *"roughly two hundred lines
39
+ * above this bullet"*. The referent is the document itself, so the claim is
40
+ * about a number that every insertion above it changes, in a file whose whole
41
+ * job is to be edited. Nobody recomputes it, nothing can, and it is wrong
42
+ * quietly.
43
+ *
44
+ * So the signal is the **deictic referent** — `this line`, `this bullet`,
45
+ * `this spec` — not the distance. That is what separates the 2 from the 17,
46
+ * and it is why a blanket ban on "N lines above" is the wrong check: it would
47
+ * have refused seventeen true sentences to catch two false ones.
48
+ *
49
+ * ## Why a ban rather than a comparison
50
+ *
51
+ * The obvious check is to recompute the distance and compare. It cannot be
52
+ * written: "167 lines below this line" names no target, so there is nothing
53
+ * to measure TO. Resolving the referent is a reading-comprehension problem,
54
+ * and a checker that guessed would be a detector narrower than what it
55
+ * detects.
56
+ *
57
+ * A self-referential distance is therefore unverifiable **by construction**,
58
+ * and the honest response to an unverifiable claim is not to check it but to
59
+ * stop writing it. The replacement is always available and never rots: name
60
+ * the section. A heading reference breaks loudly, because the heading has to
61
+ * change for it to break.
62
+ *
63
+ * ## Both instances in the tree were TRUE when this was written
64
+ *
65
+ * In `INSTRUCTION-COMPLIANCE-SPEC.md` the *Layer 3 — Behavioral Compliance*
66
+ * section said "167 lines below this line" and SC-453 said "167 lines below
67
+ * this spec's own". At `f0a9d973` they sat at lines 88 and 255, and
68
+ * 255 − 88 is 167 — the commit is named because a bare line number in a
69
+ * sentence is the thing this module exists to object to.
70
+ *
71
+ * That both were TRUE is the point rather than a mitigation: this check is
72
+ * not green because the numbers were wrong, it exists because nothing would
73
+ * have gone red on the day they stopped being right.
74
+ *
75
+ * ## There is no allowlist, by design
76
+ *
77
+ * Every instance has a mechanical fix that is strictly better, so an
78
+ * exemption would only ever record that somebody did not want to apply it.
79
+ *
80
+ * ## What this does NOT catch, measured rather than assumed
81
+ *
82
+ * The deictic is required, so the **bare** form goes free: *"the two rows
83
+ * above are that one being mutated"*, *"the three sections below were moved
84
+ * out of the rule"*. Measured 2026-10-27 the tree holds **4** of those, and
85
+ * they are the same defect — a count that no insertion updates.
86
+ *
87
+ * They are not caught because the signal that would catch them also catches a
88
+ * true sentence. *"The function's own docstring states the property it was
89
+ * breaking, two paragraphs above the code that breaks it"*
90
+ * (`specs/HARNESS-STANDARD.md`) is a bare structural distance about a SOURCE
91
+ * FILE, so "a structural unit with no deictic" is not the separator it looks
92
+ * like, and a rule built on it would be the blanket ban again at smaller
93
+ * scale. `UNCAUGHT` in the test file holds all four and asserts this returns
94
+ * nothing for them, so the limit is a row that goes red when somebody widens
95
+ * the rule rather than a paragraph that quietly stops being true.
96
+ *
97
+ * ## The vocabulary is a closed list over an open language
98
+ *
99
+ * Three rounds of the #1624 review each found the same shape — a word missing
100
+ * from, or wrongly admitted to, a hand-enumerated list. Round 2: the teens
101
+ * were missing and `on` was wrongly in `DIRECTION`. Round 3: bare `a`/`an`
102
+ * were wrongly in `QUANTITY`. Each was fixed as a one-off, and round 6 made
103
+ * the right objection: **the class is what keeps producing findings, not the
104
+ * words**, so fixing a word at a time predicts another round rather than a
105
+ * last one.
106
+ *
107
+ * Measured, so the shape is a reading rather than a worry — four ways in, each
108
+ * one word away from a sentence this DOES refuse:
109
+ *
110
+ * | uncaught | what stopped it |
111
+ * |---|---|
112
+ * | "couple lines above this section" | not in `QUANTITY` |
113
+ * | "two lines removed from this section" | not in `DIRECTION` |
114
+ * | "two short lines above this section" | `QUANTITY`→`UNIT` must be adjacent |
115
+ * | "two lines further above this section" | `UNIT`→`DIRECTION` must be adjacent |
116
+ *
117
+ * The reviewer offered the alternative of widening `GAP` so the three parts
118
+ * need not be contiguous, "closing a shape rather than a word". That is the
119
+ * right diagnosis and the wrong moment: it is a third widening of the same
120
+ * window, and this pull request's own history is that the first reintroduced
121
+ * the seventeen-false-positive class (round 3) and the second cost a round to
122
+ * undo (round 4). A widening whose false-positive cost nobody has measured is
123
+ * how both of those shipped.
124
+ *
125
+ * So the other half of the reviewer's own suggestion is taken instead: this is
126
+ * a **standing, named limitation**, with `UNCAUGHT_VOCABULARY` asserting each
127
+ * row above beside the control that differs from it by one word. Every row is
128
+ * therefore falsifiable in both directions — the uncaught sentence must stay
129
+ * uncaught, and the control must stay caught, or the limit is misattributed
130
+ * and the table above is wrong rather than merely incomplete.
131
+ *
132
+ * ## `a` and `an`: no setting of that switch is right
133
+ *
134
+ * Round 3 removed the articles from `QUANTITY` because
135
+ * *"Add a line above this heading explaining the exception"* is an instruction
136
+ * and was being refused. Round 6 pointed out the cost was never written down:
137
+ * *"A note sits a line above this heading, restating the same count"* is a
138
+ * genuine self-referential claim, with a real deictic, and it is now missed.
139
+ *
140
+ * Both are right, and the measurement says why the gap cannot be closed by
141
+ * choosing better. Re-admitting `a|an` to `QUANTITY` moves the count of real
142
+ * claims across all **205** tracked non-fixture markdown files by **zero**.
143
+ *
144
+ * It now matches twice, and both are this argument quoting itself: #1626
145
+ * landed a session entry reproducing the two worked examples below, so the
146
+ * tree contains the phrase as a MENTION. `DOC-DIST-3h` therefore asserts over
147
+ * the distinct phrases rather than a count — the quotations are named and
148
+ * skipped, anything else is red. The row went red on that merge, which is the
149
+ * check behaving correctly about a corpus that had genuinely changed. So round
150
+ * 3's removal was decided by a sentence somebody constructed in a review
151
+ * comment and not by anything in this repository — and the two sentences are
152
+ * the same bytes to this detector, `a line above this heading` in both. What
153
+ * separates them is grammatical mood, which is the reading-comprehension
154
+ * problem this module refuses to pretend to solve.
155
+ *
156
+ * The articles stay out, because a false positive on an instruction is a
157
+ * sentence somebody must rewrite to satisfy a checker, and a false negative is
158
+ * a claim that goes unrefused — the direction this check is allowed to be
159
+ * wrong in. That is a choice, not an oversight, and `UNCAUGHT_VOCABULARY`
160
+ * holds the sentence it gives up.
161
+ */
162
+
163
+ /** A refused claim, with enough to find it without opening the file. */
164
+ export interface ProseSelfDistance {
165
+ readonly file: string;
166
+ readonly line: number;
167
+ readonly text: string;
168
+ }
169
+
170
+ /**
171
+ * The deictic referents that make a distance self-referential. `this spec`
172
+ * and `this document` are here because a distance measured from the document
173
+ * as a whole decays the same way one measured from a line does.
174
+ *
175
+ * **`rule` and `check` were added at round 9 of the #1624 review**, and the
176
+ * finding behind them is the one about process rather than about words:
177
+ * `QUANTITY`, `UNIT` and `DIRECTION` were each revisited across several
178
+ * rounds and **this list never was**, so it kept whatever the first draft
179
+ * guessed. *"ticked, 46 lines above this check"* and *"two lines above this
180
+ * rule"* are the shape the module exists to refuse, in the vocabulary
181
+ * `.claude/rules/*.md` actually uses, and both went free.
182
+ *
183
+ * Free, measured: admitting them moves the count across all 205 tracked
184
+ * non-fixture markdown files by **zero**, so this is the same category as
185
+ * `before`/`after` and the structural units — a gap closed at no cost, not a
186
+ * widening traded against false positives.
187
+ *
188
+ * **A wider set was measured and deliberately not taken.** `criterion`,
189
+ * `entry`, `item` and `step` also cost zero today. They are not here, because
190
+ * "costs zero today" is exactly the argument behind both widenings this pull
191
+ * request had to undo (rounds 3 and 4): every word is future false-positive
192
+ * surface, and the two that are here are the two a reviewer produced a real
193
+ * sentence for. A third should arrive the same way.
194
+ *
195
+ * **Round 10 made that paragraph into rows, which is this module's own
196
+ * standard applied back to it.** Describing a limit in a docblock is what
197
+ * `UNCAUGHT` exists not to do. REFERENTS was the fourth closed vocabulary and
198
+ * the only one with no declared limit, so the next reviewer to notice a
199
+ * missing word was set up to repeat the rounds 2–3 patch cycle on it. The
200
+ * four words above, and a bare `this one`, are now `UNCAUGHT_VOCABULARY`
201
+ * rows: each paired with a control that must stay caught, and admitting one
202
+ * means deleting its row rather than quietly outgrowing a sentence.
203
+ *
204
+ * `this one` is the row that is NOT a candidate. A bare pronoun names
205
+ * whatever the previous clause named, so admitting it would not widen the
206
+ * deictic requirement, it would dissolve it.
207
+ */
208
+ const REFERENTS =
209
+ "line|bullet|paragraph|section|sentence|spec|document|file|row|table|heading|list|comment|note|rule|check";
210
+
211
+ /**
212
+ * Spelled-out numbers as well as digits: *"two hundred lines away"* carries
213
+ * no digit and so is invisible to `.claude/line-citation-ratchet.json`, which
214
+ * counts `path:NNN` citations. That gap is why this is a separate check and
215
+ * not a widening of that one.
216
+ *
217
+ * **`a` and `an` are NOT counts, and were removed in round 3 of the #1624
218
+ * review.** *"Add a line above this heading explaining the exception"* is an
219
+ * instruction, not a claim, and the first two drafts refused it — the same
220
+ * false positive as `on` in `DIRECTION`, which I had already found and fixed
221
+ * without applying the lesson one constant over. An article is a determiner;
222
+ * every member left is a number or a word that means one.
223
+ */
224
+ const QUANTITY =
225
+ "(?:one|two|three|four|five|six|seven|eight|nine|ten|eleven|twelve" +
226
+ "|thirteen|fourteen|fifteen|sixteen|seventeen|eighteen|nineteen" +
227
+ "|twenty|thirty|forty|fifty|sixty|seventy|eighty|ninety" +
228
+ "|hundred|dozen|several|many|[0-9][0-9,]*)" +
229
+ "(?:[ -](?:hundred|thousand))?";
230
+
231
+ /**
232
+ * `before` and `after` are here because a position is as natural a way to
233
+ * spell a self-referential distance as a direction — *"three lines before
234
+ * this section"* — and the first draft of this module omitted both, which the
235
+ * review of #1624 caught. Measured over all 205 tracked non-fixture markdown
236
+ * files on 2026-10-27, admitting them adds **zero** violations, so this is a
237
+ * gap closed at no cost rather than a widening traded against false
238
+ * positives. The same measurement admitted `sixty`…`ninety`, `dozen` and a
239
+ * standalone `hundred` to `QUANTITY`: three lines in the tree spell a
240
+ * distance that way, none carries a deictic.
241
+ *
242
+ * `on` was here in the first two drafts and is **removed**: it is not a
243
+ * direction, it is the commonest preposition in English, and the review of
244
+ * #1624 produced the sentence that breaks it — *"This file lists two pages
245
+ * on this document that still need review"* is not a distance claim at all
246
+ * and was refused. Nothing in the tree needed it; every direction left is a
247
+ * word that can only mean displacement.
248
+ */
249
+ const DIRECTION =
250
+ "above|below|away|apart|earlier|later|up|down|back|before|after";
251
+
252
+ /**
253
+ * The unit the distance is counted in. `lines` is where both live instances
254
+ * were; the structural units are here because they are what a writer reaches
255
+ * for next and the widening is free — measured 2026-10-27, a structural unit
256
+ * followed by a deictic referent occurs **zero** times in the tree, so no
257
+ * true sentence is refused by admitting them.
258
+ */
259
+ const UNIT = "lines?|rows?|sections?|paragraphs?|bullets?|columns?|pages?";
260
+
261
+ /**
262
+ * The deictic half of the pattern, as its own exported substring.
263
+ *
264
+ * This exists so the mutation can be PERFORMED on the real pattern rather
265
+ * than approximated. The first version of `DOC-DIST-6` hand-wrote a widened
266
+ * regex beside the real one and called it the mutant; the review of #1624
267
+ * pointed out it had already drifted — it was missing `eleven`, `twenty`,
268
+ * `many`, `back` and more — so the row was comparing two independent
269
+ * vocabularies and reporting it as the deictic requirement being removed.
270
+ * Two deciders that agree, in the test written to demonstrate they must not
271
+ * be.
272
+ *
273
+ * `PROSE_SELF_DISTANCE_PATTERN` contains this string **exactly once**, which
274
+ * the test asserts before it mutates, so deleting it is the whole and only
275
+ * difference between the real rule and the banned one.
276
+ *
277
+ * The distance and the referent are allowed up to 60 characters apart so that
278
+ * "167 lines below this spec's own …" matches, and no more, because the wider
279
+ * the window the more likely two unrelated clauses are joined into a claim
280
+ * nobody made.
281
+ *
282
+ * ## The window crosses a line break, and that is the whole point
283
+ *
284
+ * The first two drafts matched each physical line on its own. This repo
285
+ * hard-wraps prose at around 76 characters, so a claim whose distance and
286
+ * deictic land on opposite sides of a wrap was invisible:
287
+ *
288
+ * that criterion was ticked some 46 lines above
289
+ * this document's own listing of criteria.
290
+ *
291
+ * — exactly the shape the module exists to refuse. The review of #1624 found
292
+ * it, and the measurement this module reported did not: both live instances
293
+ * sat on single very long unwrapped lines, so **"0 violations" was a property
294
+ * of how today's tree happens to wrap**, not of the rule. A detector narrower
295
+ * than what it detects, in the one place that is least excusable.
296
+ *
297
+ * So the gap admits a newline and the scan runs over the whole file rather
298
+ * than line by line.
299
+ *
300
+ * ## But a newline is not only a wrap, and a blank line is not the only stop
301
+ *
302
+ * The first attempt at the above crossed ANY non-blank newline, which let the
303
+ * window walk out of one block and into the next. Round 4 of the #1624 review
304
+ * produced the input:
305
+ *
306
+ * - the offset drifts three lines down
307
+ * - this paragraph is unrelated
308
+ *
309
+ * Two unrelated bullets. The first ends with no terminal stop, so the gap
310
+ * crossed `\n- ` — three characters of its sixty — and read them as one
311
+ * claim. That is the seventeen-false-positives shape the whole module was
312
+ * narrowed to avoid, reintroduced by the fix for the wrap. The reviewer's
313
+ * sharper point is the one worth keeping: **`DOC-DIST-4` passing proved only
314
+ * that today's tree does not contain the input**, and no row covered it, so
315
+ * the mechanism had no evidence either way.
316
+ *
317
+ * A newline may therefore be crossed only into a **continuation** — a line
318
+ * that starts no new block. A blank line stops it, and so does a list
319
+ * marker, a table row, a heading, a blockquote and a fence, because each of
320
+ * those opens something the previous line was not part of. `DOC-DIST-3e`
321
+ * plants one of each.
322
+ *
323
+ * ### The markers require their space, because CommonMark does
324
+ *
325
+ * The first spelling of this was a bare character class, and round 5 of the
326
+ * review found it stopping on lines that start no block at all: `#1624` is
327
+ * an issue number this repository writes constantly and not an ATX heading,
328
+ * `3.14` is a decimal and not an ordered-list marker, and `*italic*` is
329
+ * emphasis. Each of those made the window refuse to cross a line it should
330
+ * have crossed.
331
+ *
332
+ * The direction is the opposite of round 4's — these are false NEGATIVES, a
333
+ * claim going unrefused rather than a true sentence being refused — which
334
+ * makes them quieter and no less wrong. CommonMark requires a space after
335
+ * `-`, `*`, `+`, `#` and an ordered marker, so the pattern requires one too;
336
+ * `>` and `|` do not take one and so do not ask for one.
337
+ */
338
+ const BLOCK_START = "[-*+][ \\t]|#{1,6}[ \\t]|[0-9]+[.)][ \\t]|[>|]|```|~~~";
339
+
340
+ const GAP = `(?:[^.!?\\n]|\\n(?![ \\t]*(?:\\n|${BLOCK_START})))`;
341
+
342
+ /**
343
+ * The glue inside the distance phrase itself — `twenty` `lines` `above`.
344
+ *
345
+ * It was a plain `\s+` until round 11 of the #1624 review, and `\s` includes
346
+ * `\n`, so it crossed a blank line freely:
347
+ *
348
+ * we raised it to twenty
349
+ *
350
+ * lines above this heading, which is unrelated
351
+ *
352
+ * — two paragraphs read as one claim. That is the round-4 false positive
353
+ * exactly, on the half of the pattern round 4 never looked at: all the
354
+ * block-boundary work went into `GAP`, between the direction word and the
355
+ * deictic, and the three words before it kept the separator the first draft
356
+ * used.
357
+ *
358
+ * **The reachable case is narrower than it first looks, and the reason is
359
+ * worth keeping.** A list marker, a heading, a blockquote or a fence cannot
360
+ * be crossed here whatever this is, because they are NON-WHITESPACE and a
361
+ * whitespace-only separator stops at them for free. `BLOCK_START` is not
362
+ * needed and is not used. Only the pure blank line was reachable, because a
363
+ * blank line is the one block boundary made entirely of whitespace —
364
+ * verified as one case rather than assumed to be five, and `DOC-DIST-3i`
365
+ * holds both halves so the free ones cannot quietly stop being free.
366
+ *
367
+ * So: ordinary horizontal space, or exactly one newline that is not the start
368
+ * of a blank line. A hard-wrapped claim still matches, which is round 3's
369
+ * whole point and is the control in the same row.
370
+ */
371
+ const SEP = "(?:[ \\t]+|[ \\t]*\\n(?![ \\t]*\\n)[ \\t]*)";
372
+
373
+ export const PROSE_SELF_DISTANCE_DEICTIC = `${GAP}{0,60}?\\bthis\\s+(?:${REFERENTS})\\b`;
374
+
375
+ /**
376
+ * ONE binding, so there is one site for a mutation to remove. A second
377
+ * predicate deciding the same question would leave this one dead with the
378
+ * suite still green — `.claude/rules/checks-must-be-able-to-fail.md`, *two
379
+ * deciders that agree*.
380
+ */
381
+ export const PROSE_SELF_DISTANCE_PATTERN =
382
+ `\\b${QUANTITY}${SEP}(?:${UNIT})${SEP}(?:${DIRECTION})\\b` + PROSE_SELF_DISTANCE_DEICTIC;
383
+
384
+ /**
385
+ * Every claim in every file, each with the line its distance phrase STARTS on.
386
+ *
387
+ * `g`, not a single `exec`: the earlier version reported the first match per
388
+ * line and stopped, so a line carrying two claims answered for one — the
389
+ * reviewer's lower-severity half of the same finding. The scan is over the
390
+ * whole text because the window crosses wraps (see
391
+ * `PROSE_SELF_DISTANCE_DEICTIC`), so the line number is counted from the
392
+ * match offset rather than handed over by a loop index, and the quoted text
393
+ * has its newlines flattened so a failure message stays one line per claim.
394
+ */
395
+ export function proseSelfDistanceViolations(
396
+ files: ReadonlyArray<{ readonly path: string; readonly text: string }>,
397
+ ): ProseSelfDistance[] {
398
+ const out: ProseSelfDistance[] = [];
399
+ for (const { path, text } of files) {
400
+ const pattern = new RegExp(PROSE_SELF_DISTANCE_PATTERN, "gi");
401
+ for (const hit of text.matchAll(pattern)) {
402
+ const line = text.slice(0, hit.index).split("\n").length;
403
+ out.push({ file: path, line, text: hit[0].replace(/\s*\n\s*/g, " ") });
404
+ }
405
+ }
406
+ return out;
407
+ }
408
+
409
+ /** What to do about one, in the failure message rather than in a rule nobody opens. */
410
+ export const PROSE_SELF_DISTANCE_FIX =
411
+ "name the section instead of counting lines to it — a heading reference cannot " +
412
+ "drift without the heading changing, and a line count drifts on every insertion " +
413
+ "above it with nothing going red. There is no allowlist: the replacement is " +
414
+ "always available.";