rungate 0.7.0 → 0.8.0

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 (63) hide show
  1. package/hooks/ActionVerificationGate.hook.ts +96 -0
  2. package/hooks/AgentBriefGuard.hook.ts +38 -0
  3. package/hooks/AgentVerdictCapture.hook.ts +87 -0
  4. package/hooks/AutoVerifyGate.hook.ts +79 -0
  5. package/hooks/BashToolGuard.hook.ts +65 -0
  6. package/hooks/BashWriteGuard.hook.ts +60 -0
  7. package/hooks/CommitEnforcement.hook.ts +130 -0
  8. package/hooks/DocHygiene.hook.ts +148 -0
  9. package/hooks/GateEnforcement.hook.ts +58 -0
  10. package/hooks/GateResultProtection.hook.ts +69 -0
  11. package/hooks/HarnessAFKGate.hook.ts +85 -0
  12. package/hooks/HookCurrency.hook.ts +99 -0
  13. package/hooks/IssueCloseGuard.hook.ts +149 -0
  14. package/hooks/MergeGuard.hook.ts +58 -0
  15. package/hooks/PostCompact.hook.ts +60 -0
  16. package/hooks/ProjectStateSync.hook.ts +103 -0
  17. package/hooks/SkillGuard.hook.ts +69 -0
  18. package/hooks/SpecConformityTrigger.hook.ts +43 -0
  19. package/hooks/SpecSCGuard.hook.ts +123 -0
  20. package/hooks/StaleTTLCleanup.hook.ts +141 -0
  21. package/hooks/TaskCompleted.hook.ts +51 -0
  22. package/hooks/TeamInit.hook.ts +85 -0
  23. package/hooks/TestSuiteGuard.hook.ts +70 -0
  24. package/hooks/TestSuiteRelease.hook.ts +85 -0
  25. package/hooks/TopLevelCdGuard.hook.ts +108 -0
  26. package/hooks/VerifyPhaseLock.hook.ts +84 -0
  27. package/hooks/WorkflowStateGuard.hook.ts +40 -0
  28. package/hooks/lib/agent-config.json +9 -0
  29. package/hooks/lib/agentDetection.ts +201 -0
  30. package/hooks/lib/comment-template.ts +86 -0
  31. package/hooks/lib/findWorkflow.ts +101 -0
  32. package/hooks/lib/parseStdin.ts +37 -0
  33. package/hooks/lib/paths.ts +111 -0
  34. package/hooks/lib/utils.ts +338 -0
  35. package/lib/affected-tests.ts +29 -0
  36. package/lib/bash-write-guard.ts +373 -0
  37. package/lib/branch-cleanup.ts +279 -7
  38. package/lib/config-trackable.ts +9 -0
  39. package/lib/distribution-currency.ts +55 -5
  40. package/lib/failure-intake.ts +7 -1
  41. package/lib/gate-enforcement.ts +222 -28
  42. package/lib/gate-names.ts +72 -0
  43. package/lib/gate-result-protection.ts +427 -0
  44. package/lib/intake-sources.ts +380 -0
  45. package/lib/late-env-spawn.ts +331 -0
  46. package/lib/launch-base.ts +128 -5
  47. package/lib/paths.ts +96 -3
  48. package/lib/phase2-decomposition.ts +1 -1
  49. package/lib/published-artifact.ts +162 -18
  50. package/lib/sc-id-cross-tree.ts +84 -8
  51. package/lib/scaffold/ai-review-findings.ts +7 -1
  52. package/lib/scaffold/ai-review-step.ts +861 -116
  53. package/lib/scaffold/defaults.ts +82 -1
  54. package/lib/scaffold/steps.ts +436 -44
  55. package/lib/security-verdict.ts +1 -1
  56. package/lib/shell-path-interpolation.ts +594 -0
  57. package/lib/text-dependents.ts +875 -0
  58. package/lib/workflow-security.ts +29 -0
  59. package/lib/workflow-taint.ts +732 -0
  60. package/lib/worktree-cleanup.ts +65 -38
  61. package/lib/worktree-repo.ts +32 -2
  62. package/package.json +3 -1
  63. package/scripts/check-installed-hook-currency.ts +825 -0
@@ -0,0 +1,875 @@
1
+ /**
2
+ * Which files read a changed source file AS TEXT, and which region of it (#1054).
3
+ *
4
+ * The third relationship, beside the two this repository already routes by.
5
+ * `lib/affected-tests.ts` routes by what a change IMPORTS;
6
+ * `scripts/census-routing.ts` routes by what a change DID. Neither answers
7
+ * the question an author actually asks before pushing: *of the thousands of
8
+ * lines in the file I just edited, which other files lift the part I touched,
9
+ * and by what name?*
10
+ *
11
+ * ## The measurement this module is built on, and the premise it corrected
12
+ *
13
+ * #1054 reports that the import graph "cannot see" a test that parses a
14
+ * source file it does not import, and names PR #1034 as the instance: a
15
+ * change to `workflows/ship.js` reddened five files, every one of which lifts
16
+ * a region of `ship.js` out of its text, and the fixing agent's own report
17
+ * says *"none has 'container' in its name, so my local grep missed them."*
18
+ *
19
+ * Re-measured against the tree at that commit before any of this was written,
20
+ * the premise is **wrong in its stated form and right in its consequence**.
21
+ * `affectedTests` with `workflows/ship.js` in the change set selects all five
22
+ * — it has a basename-literal rule, and each of the five writes
23
+ * `join(REPO_ROOT, "workflows", "ship.js")`. What it selects is **226 of 538
24
+ * test files**. Three answers were available that night and not one of them
25
+ * was usable:
26
+ *
27
+ * | the question asked | answer | the five |
28
+ * |---|---|---|
29
+ * | filenames matching `container` | 1 file | **1 of 5** |
30
+ * | `grep -rl container test/` | 46 files | 5 of 5 |
31
+ * | `affectedTests(ship.js)` | 226 files| 5 of 5 |
32
+ *
33
+ * The narrow answer missed; the answers that caught were 46 and 226 files
34
+ * wide, and the selector that produced the 226 runs only inside a ship run.
35
+ * So the gap is not that nothing could reach those files. It is that nothing
36
+ * could **name** them: no command said *these are the files that lift the
37
+ * block you edited, and here is the anchor each one lifts it by.* An agent
38
+ * holding a 226-file list and no attribution greps, which is what happened.
39
+ *
40
+ * ## What an anchor is
41
+ *
42
+ * A file that lifts a region of another file has to name where the region
43
+ * starts. In this tree that name is a string literal or a regex literal whose
44
+ * text occurs verbatim in the subject:
45
+ *
46
+ * markerRegion(shipSource, "RECORDER-COMMAND") // string
47
+ * region(/^let quinnContainerResult = null$/m, ...) // regex
48
+ *
49
+ * Both are **anchors**: literal text, written in the reader, present in the
50
+ * subject. That is a dependency as real as an import, expressed in a syntax
51
+ * no resolver reads — #484's shape, where a guard knew one spelling of a
52
+ * property that had two.
53
+ *
54
+ * Anchors are read from a COMMENT-STRIPPED view of the reader, for the reason
55
+ * `lib/affected-tests.ts` states about the same question: this repository
56
+ * quotes its own source constantly in prose, and a docstring that mentions a
57
+ * marker is a citation, not a read.
58
+ *
59
+ * ## Two readings, and only one of them is allowed to narrow the run
60
+ *
61
+ * An anchor gives a span in the subject — the marker pair's first and last
62
+ * occurrence, or the balanced block enclosing a lone anchor. Comparing that
63
+ * span against the changed line numbers says whether the edit landed INSIDE
64
+ * the lifted region, which is the attribution a human wants.
65
+ *
66
+ * **It is not allowed to remove anything from the selection.** The brace scan
67
+ * is a raw text scan with the limits `lib/source-slice.ts` states, the diff's
68
+ * line numbers are the new side only, and a span computed slightly wrong
69
+ * narrows a run — which is the one direction a test selector may never be
70
+ * wrong in. So an anchor match is an edge, full stop, and the span only sets
71
+ * `direct`. A narrow answer that is sometimes wrong is worse than a wide one
72
+ * that is never wrong; the narrowing here is in the REPORT.
73
+ *
74
+ * ## UNMEASURED fails, it does not empty
75
+ *
76
+ * `0`, `{}` and an empty selection are indistinguishable from success, which
77
+ * is the whole of `.claude/rules/config-access.md` and of #492. A changed
78
+ * file this module could not read is not a file with no dependents, so:
79
+ *
80
+ * - nothing changed, nothing scanned, or no test file found -> UNMEASURED
81
+ * - a changed path that is not on disk -> UNMEASURED, named. Its anchors
82
+ * cannot be computed at all, and a deletion is exactly when a lifter
83
+ * breaks.
84
+ * - a changed path that is on disk and unreadable -> UNMEASURED, named
85
+ * - a changed path that is binary -> recorded in `notText` and NOT
86
+ * unmeasured. A text-anchor router is definitionally not about bytes,
87
+ * and saying which files it declined by name is the difference between
88
+ * a skip and a silence.
89
+ *
90
+ * and the caller is told `filesRead` of `filesSeen` either way, because
91
+ * `36/426` and `426/426` are the same PASS when only the verdict is printed.
92
+ */
93
+ import { readdirSync, readFileSync, realpathSync, statSync } from "fs";
94
+ import { dirname, join } from "path";
95
+
96
+ import { relativeImports } from "./package-closure";
97
+ import { commentMask, stripJsComments } from "./strip-js-comments";
98
+
99
+ /**
100
+ * The shortest literal that may be an anchor.
101
+ *
102
+ * Not a tuning knob so much as a statement about what a name is. Below this,
103
+ * literals stop being names of places and start being fragments every file
104
+ * shares — `"utf-8"`, `"const "`, `" null"` — and an anchor that matches
105
+ * everywhere anchors nothing. Measured on this tree, dropping it to 6
106
+ * roughly triples the edge count without adding a reader that any of the
107
+ * three corpus changes needed.
108
+ */
109
+ export const ANCHOR_MIN_LENGTH = 12;
110
+
111
+ /**
112
+ * Occurrences above which a literal stops being an anchor.
113
+ *
114
+ * `lib/source-slice.ts` refuses a duplicated anchor by name
115
+ * (`AmbiguousAnchorError`) because a cut taken around whichever occurrence
116
+ * the search reached is a confident answer about the wrong region. The same
117
+ * judgement, one notch looser: a marker pair is two occurrences and legal, a
118
+ * literal appearing nine times in the subject is a coincidence. Declined
119
+ * literals are REPORTED (`ambiguous`), never silently dropped.
120
+ */
121
+ export const ANCHOR_AMBIGUITY_MAX = 8;
122
+
123
+ /**
124
+ * What makes a literal a NAME rather than a word.
125
+ *
126
+ * Measured before this pair existed, on the #1034 diff: length alone admitted
127
+ * `"implementation"`, `"do not touch"` and `"verification"`, which occur in
128
+ * every long document in the tree, and the reading came back with 510 of 538
129
+ * test files and 4,155 edges. A router that names 95% of the suite has
130
+ * answered the question nobody asked; the author still has to grep.
131
+ *
132
+ * The two families that are real anchors here, and nothing else:
133
+ *
134
+ * MARKER `CONTAINER-PROBE`, `RECORDER-COMMAND` — a screaming-case label
135
+ * that exists to be found
136
+ * CODE `let quinnContainerResult = null`, `async function
137
+ * runContainerVerify() {` — a line of source, which is recognisable
138
+ * because source has punctuation and prose does not
139
+ *
140
+ * This is the filter that can be wrong in the dangerous direction, so it is
141
+ * the one to suspect first when a lifter is missed: a reader that anchors on
142
+ * a bare lowercase phrase is invisible here. That is a deliberate trade
143
+ * against a result nobody reads, it is stated rather than implied, and the
144
+ * edge count makes it checkable.
145
+ */
146
+ const MARKER_ANCHOR = /[A-Z][A-Z0-9_-]{5,}/;
147
+ const CODE_ANCHOR = /[=(){}[\];<>]/;
148
+
149
+ /**
150
+ * How much of an anchor has to be letters and digits.
151
+ *
152
+ * Length alone counts punctuation and newlines, so a fixture holding
153
+ * `");\n } return"` cleared a twelve-character bar on syntax, and syntax
154
+ * occurs in every file. Measured on this branch's own diff before the rule
155
+ * existed: six of the first twenty edges were punctuation runs, each naming
156
+ * a reader with no relationship to the change at all.
157
+ */
158
+ const ANCHOR_MIN_ALNUM = 10;
159
+
160
+ /**
161
+ * Extensions a target may have.
162
+ *
163
+ * Declared scope, not an oversight: this router answers *which files read
164
+ * this SOURCE file as text*. A markdown target shares vocabulary with every
165
+ * other document in the tree, so the same filter that makes code anchors
166
+ * precise makes prose anchors meaningless — and prose coupling is already
167
+ * `scripts/census-routing.ts`'s question, routed by what the diff DID.
168
+ * Declined targets are listed in `notAnchorable` by name.
169
+ */
170
+ const ANCHORABLE_TARGET = /\.(ts|tsx|js|jsx|mjs|cjs|mts|cts)$/;
171
+
172
+ /** Directories walked for readers. The same population `affectedTests` walks. */
173
+ export const SCAN_DIRS = ["test", "lib", "scripts", "gates", "bin", "hooks", "workflows"];
174
+
175
+ const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build", "coverage"]);
176
+
177
+ /** A reader this module can extract anchors from. */
178
+ const SCANNABLE = /\.(ts|tsx|js|jsx|mts|cts)$/;
179
+
180
+ /** A test file, by the convention this repo uses everywhere. */
181
+ export const TEST_FILE = /\.test\.(ts|tsx)$/;
182
+
183
+ /** One changed region of a changed file, on the NEW side, 1-based. */
184
+ export interface Hunk {
185
+ start: number;
186
+ lines: number;
187
+ }
188
+
189
+ /** What this module needs to know about a changed file. */
190
+ export interface ChangedFile {
191
+ path: string;
192
+ /**
193
+ * New-side hunks. `undefined` means the caller could not say, which is not
194
+ * the same as "no lines changed": every edge is then reported `direct:
195
+ * false` rather than being dropped.
196
+ */
197
+ hunks?: Hunk[];
198
+ }
199
+
200
+ /** Why a span is the shape it is — attribution only, never selection. */
201
+ export type AnchorScope =
202
+ /** Two sibling anchors of one reader: the span is the text between them. */
203
+ | "marker-pair"
204
+ /** The balanced `{}` block the anchor sits in, or opens. */
205
+ | "block"
206
+ /**
207
+ * The anchor's own lines.
208
+ *
209
+ * What a module-scope anchor gets. Its enclosing block is the whole
210
+ * document, which delimits nothing — counting that as a region made 124
211
+ * of the #1034 diff's readers direct hits — so the honest span is the
212
+ * text the reader actually named, and a sibling anchor is what widens it.
213
+ */
214
+ | "line";
215
+
216
+ /** One reader, one subject, one anchor. */
217
+ export interface TextEdge {
218
+ /** Repo-relative path of the file doing the reading. */
219
+ reader: string;
220
+ /** Repo-relative path of the changed file being read. */
221
+ target: string;
222
+ /** The literal, as written in the reader. */
223
+ anchor: string;
224
+ scope: AnchorScope;
225
+ /** 1-based, inclusive, in the target. */
226
+ from: number;
227
+ to: number;
228
+ /**
229
+ * The change landed inside the span. Attribution, not selection — a
230
+ * `false` edge is still in `tests`.
231
+ */
232
+ direct: boolean;
233
+ }
234
+
235
+ export interface TextDependentsReading {
236
+ /** `UNMEASURED` means this router could not look. It never means "none". */
237
+ reading: "MEASURED" | "UNMEASURED";
238
+ /** Why it could not look. Empty when MEASURED. */
239
+ unmeasuredReasons: string[];
240
+ /** Every anchor match, direct first then by reader. Empty under UNMEASURED. */
241
+ edges: TextEdge[];
242
+ /** Runnable test files: readers that are tests, plus tests importing a reader. */
243
+ tests: string[];
244
+ /** Readers that are not themselves test files — a helper is a real dependent. */
245
+ helpers: string[];
246
+ /** Changed paths declined as binary, by name. */
247
+ notText: string[];
248
+ /** Changed paths outside this router's declared scope, by name. */
249
+ notAnchorable: string[];
250
+ /** Literals present in a target too often to anchor anything, by name. */
251
+ ambiguous: { target: string; anchor: string; occurrences: number }[];
252
+ /** Coverage (#492): how many of the files it could see it actually read. */
253
+ filesSeen: number;
254
+ filesRead: number;
255
+ unreadable: string[];
256
+ }
257
+
258
+ /** Repo-relative, forward slashes, no leading `./`. */
259
+ function norm(p: string): string {
260
+ return p.split("\\").join("/").replace(/^\.\//, "");
261
+ }
262
+
263
+ /**
264
+ * Every scannable file under `SCAN_DIRS`.
265
+ *
266
+ * Symlinked directories are followed and visited once by real path, for the
267
+ * reasons `lib/affected-tests.ts` records (#500): a linked package is a real
268
+ * layout, and following links without a visited set recurses forever.
269
+ */
270
+ function readerFiles(root: string): string[] {
271
+ const out: string[] = [];
272
+ const seen = new Set<string>();
273
+ let rootReal: string;
274
+ try {
275
+ rootReal = realpathSync(root);
276
+ } catch {
277
+ rootReal = root;
278
+ }
279
+
280
+ const walk = (rel: string): void => {
281
+ const abs = join(root, rel);
282
+ let real: string;
283
+ try {
284
+ real = realpathSync(abs);
285
+ } catch {
286
+ return;
287
+ }
288
+ if (real !== rootReal && !real.startsWith(`${rootReal}/`)) return;
289
+ if (seen.has(real)) return;
290
+ seen.add(real);
291
+
292
+ let entries;
293
+ try {
294
+ entries = readdirSync(abs, { withFileTypes: true });
295
+ } catch {
296
+ return;
297
+ }
298
+ for (const e of entries) {
299
+ if (SKIP_DIRS.has(e.name)) continue;
300
+ const child = norm(join(rel, e.name));
301
+ let isDir = e.isDirectory();
302
+ if (e.isSymbolicLink()) {
303
+ try {
304
+ isDir = statSync(join(root, child)).isDirectory();
305
+ } catch {
306
+ continue;
307
+ }
308
+ }
309
+ if (isDir) walk(child);
310
+ else if (SCANNABLE.test(e.name)) out.push(child);
311
+ }
312
+ };
313
+ for (const d of SCAN_DIRS) walk(d);
314
+ return out.sort();
315
+ }
316
+
317
+ /**
318
+ * Quoted string literals in `code`, templates included when they interpolate
319
+ * nothing.
320
+ *
321
+ * An interpolating template is excluded deliberately: its text is assembled
322
+ * at runtime, so no part of it is a name the subject can be searched for, and
323
+ * taking the literal chunks around a `${}` would produce fragments that match
324
+ * by accident.
325
+ */
326
+ export function stringLiterals(code: string): string[] {
327
+ const out: string[] = [];
328
+ const re = /"((?:[^"\\\n]|\\.)*)"|'((?:[^'\\\n]|\\.)*)'|`((?:[^`\\$]|\\.|\$(?!\{))*)`/g;
329
+ for (const m of code.matchAll(re)) {
330
+ const raw = m[1] ?? m[2] ?? m[3];
331
+ if (raw === undefined) continue;
332
+ out.push(unescapeJs(raw));
333
+ }
334
+ return out;
335
+ }
336
+
337
+ /** `\n` to a newline, `\"` to a quote; anything else keeps its payload. */
338
+ function unescapeJs(s: string): string {
339
+ return s.replace(/\\(.)/g, (_, c: string) =>
340
+ c === "n" ? "\n" : c === "t" ? "\t" : c === "r" ? "\r" : c,
341
+ );
342
+ }
343
+
344
+ /**
345
+ * The literal runs inside regex literals in `code`.
346
+ *
347
+ * `region(/^let quinnContainerResult = null$/m, ...)` names a line of
348
+ * `ship.js` exactly, and a module that reads only string literals is blind to
349
+ * every lifter written this way — which is most of them here.
350
+ *
351
+ * The regex-literal scan declines a `/` that follows a value, because
352
+ * division and a regex open identically and a misread one swallows the rest
353
+ * of the line. A missed regex costs an anchor and is reported in the
354
+ * coverage line; a misread one would invent a span.
355
+ */
356
+ export function regexAnchors(code: string): string[] {
357
+ const out: string[] = [];
358
+ const re = /\/((?:[^/\\\n[]|\\.|\[(?:[^\]\\]|\\.)*\])+)\/[gimsuyvd]*/g;
359
+ for (const m of code.matchAll(re)) {
360
+ // Walk back over whitespace: a `/` whose last meaningful neighbour is a
361
+ // value is division. `total / count / 2` would otherwise be read as a
362
+ // regex `/ count /` and contribute ` count ` as an anchor.
363
+ let k = (m.index as number) - 1;
364
+ while (k >= 0 && /\s/.test(code[k])) k--;
365
+ if (k >= 0 && /[\w)\]"'`.]/.test(code[k])) continue;
366
+ for (const run of literalRuns(m[1])) out.push(run);
367
+ }
368
+ return out;
369
+ }
370
+
371
+ /**
372
+ * The maximal runs of literal text in a regex body.
373
+ *
374
+ * Split on every unescaped metacharacter, unescape the rest. `^const
375
+ * containerConfig = projectConfig\.container \|\| null$` yields `const
376
+ * containerConfig = projectConfig`, which occurs once in `ship.js` and is a
377
+ * better anchor than the whole pattern would be.
378
+ */
379
+ export function literalRuns(body: string): string[] {
380
+ const runs: string[] = [];
381
+ let cur = "";
382
+ for (let i = 0; i < body.length; i++) {
383
+ const c = body[i];
384
+ if (c === "\\") {
385
+ const next = body[i + 1];
386
+ i++;
387
+ if (next === undefined) break;
388
+ // A class escape (\d, \s, \w, \b, \n...) is not literal text.
389
+ if (/[dDsSwWbBnrtfv0-9uxkpP]/.test(next)) {
390
+ if (cur) runs.push(cur);
391
+ cur = "";
392
+ } else {
393
+ cur += next;
394
+ }
395
+ continue;
396
+ }
397
+ if ("^$.*+?()[]{}|".includes(c)) {
398
+ if (cur) runs.push(cur);
399
+ cur = "";
400
+ continue;
401
+ }
402
+ cur += c;
403
+ }
404
+ if (cur) runs.push(cur);
405
+ return runs;
406
+ }
407
+
408
+ /** 1-based line number of a byte offset. */
409
+ function lineAt(starts: number[], index: number): number {
410
+ let lo = 0;
411
+ let hi = starts.length - 1;
412
+ while (lo < hi) {
413
+ const mid = (lo + hi + 1) >> 1;
414
+ if (starts[mid] <= index) lo = mid;
415
+ else hi = mid - 1;
416
+ }
417
+ return lo + 1;
418
+ }
419
+
420
+ function lineStarts(source: string): number[] {
421
+ const starts = [0];
422
+ for (let i = 0; i < source.length; i++) if (source[i] === "\n") starts.push(i + 1);
423
+ return starts;
424
+ }
425
+
426
+ /**
427
+ * The balanced `{}` block enclosing `index`, as a half-open byte range.
428
+ *
429
+ * A raw brace scan, with the scope `lib/source-slice.ts` states for the same
430
+ * technique: it does not know strings, comments or regex literals. At depth
431
+ * zero it returns the whole document rather than guessing, and the caller
432
+ * labels that `file` so a reader of the report can see that the span is not a
433
+ * claim about a region. The result never removes an edge.
434
+ */
435
+ export function enclosingBlock(source: string, index: number): { start: number; end: number } {
436
+ const opens: number[] = [];
437
+ for (let i = 0; i < index; i++) {
438
+ if (source[i] === "{") opens.push(i);
439
+ else if (source[i] === "}") opens.pop();
440
+ }
441
+ const open = opens.pop();
442
+ if (open === undefined) return { start: 0, end: source.length };
443
+
444
+ let depth = 0;
445
+ for (let i = open; i < source.length; i++) {
446
+ if (source[i] === "{") depth++;
447
+ else if (source[i] === "}") {
448
+ depth--;
449
+ if (depth === 0) return { start: open, end: i + 1 };
450
+ }
451
+ }
452
+ return { start: open, end: source.length };
453
+ }
454
+
455
+ /**
456
+ * The candidate regions site `i` could be delimiting, tightest first.
457
+ *
458
+ * Two, and the second is the one that makes marker pairs work:
459
+ *
460
+ * 1. the balanced block enclosing the site. This is the right answer for a
461
+ * code anchor — `async function runContainerVerify() {` delimits its own
462
+ * function — and it degenerates to the whole document at brace depth
463
+ * zero, which is labelled `file` and never counted as a direct hit.
464
+ *
465
+ * 2. the text from this site to the reader's NEXT anchor site in the same
466
+ * target. `sliceBlock("// ──── SECURITY-DECISION-START ────", "// ──── …
467
+ * -END ────")` names two DIFFERENT literals, so no rule about repeated
468
+ * occurrences of one literal can see that region; what makes it a region
469
+ * is that one anchor of this reader is followed by another.
470
+ *
471
+ * The second rule is self-limiting in the way that matters: the more anchors
472
+ * a reader has in a file, the tighter every span between them becomes, and a
473
+ * reader with two anchors nine thousand lines apart genuinely cannot say
474
+ * anything narrower than that. It is also why the pairing is per READER —
475
+ * pairing across readers would join two files' unrelated anchors into a
476
+ * region neither of them lifts.
477
+ */
478
+ function spansFor(
479
+ source: string,
480
+ starts: number[],
481
+ sites: { anchor: string; start: number; end: number }[],
482
+ i: number,
483
+ ): { from: number; to: number; scope: AnchorScope }[] {
484
+ const site = sites[i];
485
+ const out: { from: number; to: number; scope: AnchorScope }[] = [];
486
+
487
+ // Both ends of the anchor are asked, because an anchor that OPENS a block
488
+ // — `if (discovery.tier !== 'LIGHT' && probeTarget) {` — sits at the
489
+ // depth outside it, and asking only where it starts returns the block it
490
+ // is written in rather than the one it names.
491
+ for (const at of new Set([site.start, site.end])) {
492
+ const block = enclosingBlock(source, at);
493
+ if (block.start === 0 && block.end === source.length) continue;
494
+ out.push({
495
+ from: lineAt(starts, block.start),
496
+ to: lineAt(starts, Math.max(block.start, block.end - 1)),
497
+ scope: "block",
498
+ });
499
+ }
500
+ out.push({
501
+ from: lineAt(starts, site.start),
502
+ to: lineAt(starts, Math.max(site.start, site.end - 1)),
503
+ scope: "line",
504
+ });
505
+
506
+ const next = pairedWith(sites, i);
507
+ if (next) {
508
+ out.push({
509
+ from: lineAt(starts, site.start),
510
+ to: lineAt(starts, next.end - 1),
511
+ scope: "marker-pair",
512
+ });
513
+ }
514
+ return out;
515
+ }
516
+
517
+ /**
518
+ * The site that closes the region site `i` opens, under a START/END reading.
519
+ *
520
+ * Sites are paired greedily and WITHOUT OVERLAP in file order: 0 with 1, 2
521
+ * with 3, and so on. A site that closes a pair does not open the next one.
522
+ *
523
+ * That one clause is what makes the pairing a region rule rather than a
524
+ * sliding window, and it was measured into existence. Pairing every site
525
+ * with its successor gave `test/blocking-grades.test.ts` a span of
526
+ * `ship.js` 2413–8776 — the END marker of the region it lifts, joined to
527
+ * the next unrelated anchor nine thousand lines later — and 55 direct
528
+ * readers on a one-file diff. A reader that quotes a START and an END
529
+ * quotes them in that order, so the even sites are the openers.
530
+ */
531
+ function pairedWith(
532
+ sites: { anchor: string; start: number; end: number }[],
533
+ i: number,
534
+ ): { start: number; end: number } | undefined {
535
+ let open = 0;
536
+ for (let k = 0; k < i; k++) if (open === k && pairs(sites[k], sites[k + 1])) open = k + 2;
537
+ if (open !== i) return undefined;
538
+ return pairs(sites[i], sites[i + 1]) ? sites[i + 1] : undefined;
539
+ }
540
+
541
+ /**
542
+ * Whether two adjacent sites are the two ends of one region.
543
+ *
544
+ * Disjoint, and SIBLING NAMES — the two anchors agree on at least half of
545
+ * the shorter one. `// ──── SECURITY-DECISION-START ────` and
546
+ * `// ──── SECURITY-DECISION-END ────` agree on thirty characters; `function
547
+ * shellQuote(` and whatever a reader quotes six thousand lines later agree
548
+ * on nothing, and joining them produced a `ship.js` 497–7000 "region" and
549
+ * 39 direct readers on a one-file diff.
550
+ *
551
+ * Prefix agreement rather than a `-START`/`-END` literal, because the
552
+ * convention is not universal — BEGIN/END, OPEN/CLOSE and a bare repeated
553
+ * marker all share the prefix, and a rule naming one spelling of a
554
+ * convention is the narrow-detector shape `#484` is the worked example of.
555
+ */
556
+ function pairs(
557
+ a: { anchor: string; start: number; end: number } | undefined,
558
+ b: { anchor: string; start: number; end: number } | undefined,
559
+ ): boolean {
560
+ if (!a || !b || b.start < a.end) return false;
561
+ let shared = 0;
562
+ const limit = Math.min(a.anchor.length, b.anchor.length);
563
+ while (shared < limit && a.anchor[shared] === b.anchor[shared]) shared++;
564
+ return shared * 2 >= limit;
565
+ }
566
+
567
+ /** Every occurrence of `needle` in `hay`, as byte offsets. */
568
+ function occurrences(hay: string, needle: string): number[] {
569
+ const out: number[] = [];
570
+ let at = hay.indexOf(needle);
571
+ while (at !== -1) {
572
+ out.push(at);
573
+ at = hay.indexOf(needle, at + needle.length);
574
+ }
575
+ return out;
576
+ }
577
+
578
+ /** A NUL in the first page is the cheapest reliable "this is not text". */
579
+ function looksBinary(s: string): boolean {
580
+ return s.slice(0, 8192).includes("\u0000");
581
+ }
582
+
583
+ /**
584
+ * Which files read any of `changed` as text, and where.
585
+ *
586
+ * `changed` is repo-relative, with new-side hunks where the caller has them.
587
+ */
588
+ export function textDependents(root: string, changed: ChangedFile[]): TextDependentsReading {
589
+ const unmeasuredReasons: string[] = [];
590
+ const notText: string[] = [];
591
+ const notAnchorable: string[] = [];
592
+ const unreadable: string[] = [];
593
+
594
+ const empty = (reasons: string[], filesSeen = 0, filesRead = 0): TextDependentsReading => ({
595
+ reading: "UNMEASURED",
596
+ unmeasuredReasons: reasons,
597
+ edges: [],
598
+ tests: [],
599
+ helpers: [],
600
+ notText,
601
+ notAnchorable,
602
+ ambiguous: [],
603
+ filesSeen,
604
+ filesRead,
605
+ unreadable,
606
+ });
607
+
608
+ if (changed.length === 0) {
609
+ return empty([
610
+ "no changed files were supplied, so nothing constrains the reading — and an " +
611
+ "unconstrained reading is every file, not none",
612
+ ]);
613
+ }
614
+
615
+ // --- the subjects -------------------------------------------------------
616
+ interface Target {
617
+ path: string;
618
+ source: string;
619
+ starts: number[];
620
+ /** Per character: is this inside a comment in the target? */
621
+ inComment: boolean[];
622
+ touched: number[];
623
+ knowsLines: boolean;
624
+ }
625
+ const targets: Target[] = [];
626
+ for (const c of changed) {
627
+ if (!ANCHORABLE_TARGET.test(c.path)) {
628
+ notAnchorable.push(c.path);
629
+ continue;
630
+ }
631
+ const abs = join(root, c.path);
632
+ let source: string;
633
+ try {
634
+ source = readFileSync(abs, "utf-8");
635
+ } catch (e) {
636
+ const missing = (e as NodeJS.ErrnoException).code === "ENOENT";
637
+ unmeasuredReasons.push(
638
+ missing
639
+ ? `${c.path} is not on disk, so its anchors cannot be computed — and a file that ` +
640
+ "was deleted or renamed is precisely when the files that lift it break"
641
+ : `${c.path} could not be read (${(e as Error).message.split("\n")[0]}), so an empty ` +
642
+ "dependent list would be an artefact of not looking",
643
+ );
644
+ continue;
645
+ }
646
+ if (looksBinary(source)) {
647
+ notText.push(c.path);
648
+ continue;
649
+ }
650
+ const starts = lineStarts(source);
651
+ const touched: number[] = [];
652
+ for (const h of c.hunks ?? []) {
653
+ // A pure deletion is `+N,0`: nothing on the new side, but the join
654
+ // between N and N+1 is where the lines went, and a lifter of either
655
+ // side is affected. Both are marked.
656
+ const span = Math.max(1, h.lines);
657
+ for (let i = 0; i < span; i++) touched.push(h.start + i);
658
+ if (h.lines === 0) touched.push(h.start + 1);
659
+ }
660
+ targets.push({
661
+ path: c.path,
662
+ source,
663
+ starts,
664
+ inComment: commentMask(source),
665
+ touched,
666
+ knowsLines: c.hunks !== undefined,
667
+ });
668
+ }
669
+
670
+ // --- the readers --------------------------------------------------------
671
+ const files = readerFiles(root);
672
+ const filesSeen = files.length;
673
+ if (filesSeen === 0) {
674
+ unmeasuredReasons.push(
675
+ `the walk over ${SCAN_DIRS.join(", ")} found no readable source file, which is not the ` +
676
+ "same as finding no dependent",
677
+ );
678
+ }
679
+
680
+ const edges: TextEdge[] = [];
681
+ const ambiguous: TextDependentsReading["ambiguous"] = [];
682
+ const ambiguousSeen = new Set<string>();
683
+ const importsOf = new Map<string, string[]>();
684
+ let filesRead = 0;
685
+
686
+ for (const f of files) {
687
+ let source: string;
688
+ try {
689
+ source = readFileSync(join(root, f), "utf-8");
690
+ } catch {
691
+ unreadable.push(f);
692
+ continue;
693
+ }
694
+ filesRead++;
695
+ importsOf.set(f, relativeImports(source));
696
+
697
+ if (targets.length === 0) continue;
698
+ const code = stripJsComments(source);
699
+ const anchors = new Set<string>();
700
+ for (const l of [...stringLiterals(code), ...regexAnchors(code)]) {
701
+ if (l.length < ANCHOR_MIN_LENGTH) continue;
702
+ if ((l.match(/[A-Za-z0-9]/g) ?? []).length < ANCHOR_MIN_ALNUM) continue;
703
+ if (!MARKER_ANCHOR.test(l) && !CODE_ANCHOR.test(l)) continue;
704
+ anchors.add(l);
705
+ }
706
+ if (anchors.size === 0) continue;
707
+
708
+ for (const t of targets) {
709
+ if (t.path === f) continue; // a file is not its own dependent
710
+
711
+ // Every place any of this reader's anchors lands in this target, in
712
+ // file order. Collected per reader/target rather than per anchor,
713
+ // because the span a reader lifts is bounded by its OWN other anchors
714
+ // and by nothing else — see `spanFor`.
715
+ const sites: { anchor: string; start: number; end: number }[] = [];
716
+ for (const anchor of anchors) {
717
+ const hits = occurrences(t.source, anchor);
718
+ if (hits.length === 0) continue;
719
+ if (hits.length > ANCHOR_AMBIGUITY_MAX) {
720
+ const key = `${t.path}\u0000${anchor}`;
721
+ if (!ambiguousSeen.has(key)) {
722
+ ambiguousSeen.add(key);
723
+ ambiguous.push({ target: t.path, anchor, occurrences: hits.length });
724
+ }
725
+ continue;
726
+ }
727
+ // A CODE anchor found inside the target's COMMENTS is a citation,
728
+ // not a read — the mirror of the rule `lib/affected-tests.ts`
729
+ // already applies on the reader's side, where matching raw source
730
+ // made one rule file select 322 of 388 files. A MARKER is the
731
+ // opposite: `// ──── X-START ────` IS a comment, and that is the
732
+ // whole mechanism, so markers are matched raw. Measured on this
733
+ // branch's own diff, where the new module's docblock quotes other
734
+ // files' anchors: 7 of 12 readers were citing, not reading.
735
+ const citation = !MARKER_ANCHOR.test(anchor);
736
+ for (const hit of hits) {
737
+ if (citation && t.inComment[hit]) continue;
738
+ sites.push({ anchor, start: hit, end: hit + anchor.length });
739
+ }
740
+ }
741
+ if (sites.length === 0) continue;
742
+ sites.sort((a, b) => a.start - b.start);
743
+
744
+ const byAnchor = new Map<string, { from: number; to: number; scope: AnchorScope }[]>();
745
+ for (let i = 0; i < sites.length; i++) {
746
+ const spans = spansFor(t.source, t.starts, sites, i);
747
+ const prev = byAnchor.get(sites[i].anchor);
748
+ if (prev) prev.push(...spans);
749
+ else byAnchor.set(sites[i].anchor, spans);
750
+ }
751
+
752
+ for (const [anchor, spans] of byAnchor) {
753
+ // One edge per reader/target/anchor: a reader does not become two
754
+ // dependents by naming the same thing twice.
755
+ //
756
+ // When the caller could not give line numbers there is nothing to
757
+ // narrow WITH, so nothing is narrowed and every anchor into that
758
+ // target is direct. "I could not tell" resolving to the empty set is
759
+ // the `0`-reads-as-success shape, and this is the position where it
760
+ // costs a red `main`.
761
+ //
762
+ // No span is the whole document: `spansFor` declines a depth-zero
763
+ // enclosing block and gives the anchor's own lines instead. A
764
+ // whole-file span delimits nothing, and counting one as a region
765
+ // made 124 of the #1034 diff's readers direct hits.
766
+ const hit = (s: { from: number; to: number }) =>
767
+ t.touched.some(n => n >= s.from && n <= s.to);
768
+ const chosen = t.knowsLines
769
+ ? spans.filter(hit).sort((a, b) => a.to - a.from - (b.to - b.from))[0]
770
+ : undefined;
771
+ edges.push({
772
+ reader: f,
773
+ target: t.path,
774
+ anchor,
775
+ ...(chosen ?? spans[0]),
776
+ direct: !t.knowsLines || chosen !== undefined,
777
+ });
778
+ }
779
+ }
780
+ }
781
+
782
+ if (filesRead === 0 && filesSeen > 0) {
783
+ unmeasuredReasons.push(
784
+ `all ${filesSeen} candidate readers were unreadable, so the empty result describes this ` +
785
+ "process's permissions and not the tree",
786
+ );
787
+ }
788
+ if (unmeasuredReasons.length > 0) return empty(unmeasuredReasons, filesSeen, filesRead);
789
+
790
+ // --- make the readers runnable -----------------------------------------
791
+ //
792
+ // A helper that lifts a region is a real dependent and is not a test file,
793
+ // so handing it to `bun test` runs nothing. The tests that import it,
794
+ // transitively, are what the author has to run. Walking importers outward
795
+ // from the helpers is linear and cannot loop on an import cycle, which
796
+ // walking forward from each test with a memo can (`lib/affected-tests.ts`
797
+ // records paying for that).
798
+ const importers = new Map<string, Set<string>>();
799
+ for (const [f, specs] of importsOf) {
800
+ for (const spec of specs) {
801
+ const target = resolveSpec(f, spec, new Set(files));
802
+ if (!target) continue;
803
+ let s = importers.get(target);
804
+ if (!s) importers.set(target, (s = new Set()));
805
+ s.add(f);
806
+ }
807
+ }
808
+
809
+ //
810
+ // Only DIRECT readers become a run.
811
+ //
812
+ // This router is ADDITIVE — its caller unions it into a selection the
813
+ // import graph already made — so a narrow contribution can only add files,
814
+ // never take one away, and the safety argument that forces `affectedTests`
815
+ // to over-select does not transfer here. Measured on the #1034 diff: every
816
+ // anchor edge is 345 of 538 test files, which is wider than the graph's own
817
+ // 226 and attributes nothing; the direct edges are 10 readers, each with
818
+ // the anchor and the line span that put it there. The second is the answer
819
+ // an author can act on, and the first is another number to grep past.
820
+ const readers = [...new Set(edges.filter(e => e.direct).map(e => e.reader))];
821
+ const reached = new Set<string>();
822
+ const queue = [...readers];
823
+ while (queue.length > 0) {
824
+ const cur = queue.pop() as string;
825
+ if (reached.has(cur)) continue;
826
+ reached.add(cur);
827
+ for (const up of importers.get(cur) ?? []) if (!reached.has(up)) queue.push(up);
828
+ }
829
+
830
+ edges.sort(
831
+ (a, b) =>
832
+ Number(b.direct) - Number(a.direct) ||
833
+ a.reader.localeCompare(b.reader) ||
834
+ a.target.localeCompare(b.target) ||
835
+ a.anchor.localeCompare(b.anchor),
836
+ );
837
+
838
+ return {
839
+ reading: "MEASURED",
840
+ unmeasuredReasons: [],
841
+ edges,
842
+ tests: [...reached].filter(f => TEST_FILE.test(f)).sort(),
843
+ helpers: readers.filter(f => !TEST_FILE.test(f)).sort(),
844
+ notText,
845
+ notAnchorable,
846
+ ambiguous: ambiguous.sort((a, b) => b.occurrences - a.occurrences),
847
+ filesSeen,
848
+ filesRead,
849
+ unreadable,
850
+ };
851
+ }
852
+
853
+ /**
854
+ * Resolve a relative specifier written in `from` against `known`.
855
+ *
856
+ * The `.js` -> `.ts` candidates matter for the same reason they do in
857
+ * `lib/affected-tests.ts`: ESM-targeting TypeScript writes `./x.js` for a
858
+ * file on disk called `x.ts`, and a resolver that does not know that drops
859
+ * the edge in silence.
860
+ */
861
+ function resolveSpec(from: string, spec: string, known: Set<string>): string | null {
862
+ const base = norm(join(dirname(from), spec));
863
+ const candidates = [
864
+ base,
865
+ `${base}.ts`,
866
+ `${base}.tsx`,
867
+ `${base}.js`,
868
+ base.replace(/\.js$/, ".ts"),
869
+ base.replace(/\.js$/, ".tsx"),
870
+ norm(join(base, "index.ts")),
871
+ norm(join(base, "index.tsx")),
872
+ ];
873
+ for (const c of candidates) if (known.has(c)) return c;
874
+ return null;
875
+ }