rungate 0.5.0 → 0.7.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 (142) hide show
  1. package/lib/affected-tests.ts +398 -0
  2. package/lib/agent-audit.ts +2 -3
  3. package/lib/agent-worktree.ts +287 -0
  4. package/lib/agents-md-sections.ts +209 -0
  5. package/lib/behavioral-cache.ts +150 -2
  6. package/lib/branch-diff.ts +139 -0
  7. package/lib/branch-protection.ts +790 -0
  8. package/lib/brief-ac-alignment.ts +104 -0
  9. package/lib/brief-references.ts +205 -0
  10. package/lib/bun-version.ts +347 -0
  11. package/lib/check-remedy.ts +140 -0
  12. package/lib/ci-checkout.ts +18 -1
  13. package/lib/ci-history-depth.ts +159 -0
  14. package/lib/ci-setup-step.ts +96 -0
  15. package/lib/claude-code-action.ts +85 -0
  16. package/lib/claude-tool-vocabulary.ts +188 -0
  17. package/lib/cli-commands.ts +15 -0
  18. package/lib/commit-sha.ts +42 -0
  19. package/lib/commit-subject.ts +90 -0
  20. package/lib/compliance-report.ts +377 -45
  21. package/lib/compliance.ts +196 -20
  22. package/lib/config-loader.ts +51 -1
  23. package/lib/config-trackable.ts +391 -0
  24. package/lib/conformity.ts +1272 -189
  25. package/lib/containment.ts +238 -0
  26. package/lib/content-hash.ts +24 -0
  27. package/lib/context-docs.ts +143 -28
  28. package/lib/create-brief.ts +2 -1
  29. package/lib/create-sc.ts +323 -4
  30. package/lib/dev-liveness.ts +180 -0
  31. package/lib/discovery-branch-points.ts +432 -0
  32. package/lib/discovery-stability.ts +481 -0
  33. package/lib/distribution-currency.ts +186 -0
  34. package/lib/doc-routing.ts +157 -0
  35. package/lib/doc-scan-targets.ts +9 -0
  36. package/lib/evidence-command-transport.ts +160 -0
  37. package/lib/evidence-prevalidator.ts +246 -2
  38. package/lib/evidence-satisfiability.ts +534 -12
  39. package/lib/failure-intake.ts +317 -0
  40. package/lib/fallow-availability.ts +286 -0
  41. package/lib/fs-write-capabilities.ts +232 -0
  42. package/lib/gate-refusal-currency.ts +112 -0
  43. package/lib/gate-run-split.ts +147 -0
  44. package/lib/gate-timeouts.ts +82 -0
  45. package/lib/generators/agent-briefs.ts +4 -1
  46. package/lib/generators/agents-md.ts +204 -48
  47. package/lib/generators/code-map.ts +2 -1
  48. package/lib/generators/types.ts +8 -0
  49. package/lib/git-dates.ts +55 -0
  50. package/lib/git-isolation.ts +140 -0
  51. package/lib/github.ts +15 -0
  52. package/lib/google-auth-action.ts +93 -0
  53. package/lib/harness-project.ts +48 -0
  54. package/lib/harness-provenance.ts +255 -0
  55. package/lib/hook-evidence.ts +235 -0
  56. package/lib/hook-scopes.ts +386 -0
  57. package/lib/hook-target-tree.ts +398 -0
  58. package/lib/hook-trees.ts +447 -0
  59. package/lib/js-top-level-code.ts +78 -10
  60. package/lib/junit-checks.ts +536 -0
  61. package/lib/launch-base.ts +253 -0
  62. package/lib/line-citation.ts +372 -0
  63. package/lib/local-calendar-day.ts +78 -0
  64. package/lib/orphan-reaper.ts +468 -0
  65. package/lib/parity-binding.ts +205 -0
  66. package/lib/per-test-timeouts.ts +219 -0
  67. package/lib/plan-coverage.ts +151 -0
  68. package/lib/prior-branch.ts +201 -8
  69. package/lib/process-table.ts +146 -0
  70. package/lib/project-state-derivation.ts +219 -0
  71. package/lib/project-state-root.ts +258 -0
  72. package/lib/project-state-shape.ts +59 -0
  73. package/lib/promote-outputs.ts +6 -2
  74. package/lib/published-artifact.ts +525 -0
  75. package/lib/readdir-sorted.ts +45 -0
  76. package/lib/report-provenance.ts +156 -0
  77. package/lib/review-execution-reading.ts +206 -0
  78. package/lib/review-tool-agreement.ts +433 -0
  79. package/lib/rule-promotion.ts +234 -0
  80. package/lib/rule-retirement.ts +525 -0
  81. package/lib/run-branch.ts +612 -0
  82. package/lib/rungate-schema.ts +19 -0
  83. package/lib/runner-home.ts +274 -0
  84. package/lib/sc-claim-forms.ts +75 -0
  85. package/lib/sc-id-cross-tree.ts +323 -0
  86. package/lib/sc-ids.ts +121 -13
  87. package/lib/sc-reservations.ts +289 -0
  88. package/lib/scaffold/ai-review-findings.ts +403 -0
  89. package/lib/scaffold/ai-review-step.ts +4777 -0
  90. package/lib/scaffold/managed-workflow.ts +587 -192
  91. package/lib/scaffold/owned-files.ts +186 -39
  92. package/lib/scaffold/pre-push-hook.ts +49 -5
  93. package/lib/scaffold/rehearsal.ts +205 -71
  94. package/lib/scaffold/steps.ts +1517 -293
  95. package/lib/scaffold/workflow-census.ts +217 -0
  96. package/lib/scaffold/workflow-drift.ts +217 -0
  97. package/lib/scaffold/write-steps.ts +10 -4
  98. package/lib/scan-budget.ts +247 -0
  99. package/lib/scanner.ts +80 -62
  100. package/lib/scratch-roots.ts +50 -5
  101. package/lib/screenshot-discovery.ts +121 -0
  102. package/lib/screenshot-upload.ts +41 -1
  103. package/lib/secret-patterns.ts +511 -8
  104. package/lib/ship-mode.ts +219 -0
  105. package/lib/source-slice.ts +294 -0
  106. package/lib/spec-listing.ts +148 -0
  107. package/lib/spec-requirements.ts +209 -0
  108. package/lib/stale-cleanup.ts +37 -3
  109. package/lib/suite-flake.ts +278 -0
  110. package/lib/suite-measurement.ts +23 -4
  111. package/lib/suite-run-reading.ts +411 -1
  112. package/lib/suite-timeout-margin.ts +193 -0
  113. package/lib/test-case-bodies.ts +883 -0
  114. package/lib/test-case-deletion.ts +653 -0
  115. package/lib/test-census.ts +97 -29
  116. package/lib/test-command-positions.ts +274 -0
  117. package/lib/test-command.ts +133 -0
  118. package/lib/test-suite-lock.ts +325 -26
  119. package/lib/tool-probe.ts +142 -0
  120. package/lib/top-level-cd.ts +393 -0
  121. package/lib/tracked-vs-ignored.ts +234 -0
  122. package/lib/tree-entries.ts +89 -0
  123. package/lib/ts-ast.ts +200 -0
  124. package/lib/validators/spec-validators.ts +3 -2
  125. package/lib/walk-test-files.ts +97 -0
  126. package/lib/workflow-actions.ts +263 -0
  127. package/lib/worktree-collect.ts +177 -5
  128. package/lib/worktree-repo.ts +36 -1
  129. package/package.json +2 -1
  130. package/scripts/ai-review-findings.ts +45 -0
  131. package/scripts/audit-specs.ts +247 -12
  132. package/scripts/audit-transcript.ts +2 -1
  133. package/scripts/convert-spec.ts +2 -1
  134. package/scripts/create-sc.ts +37 -7
  135. package/scripts/create-spec.ts +2 -1
  136. package/scripts/create-success.ts +2 -1
  137. package/scripts/extract-constraints.ts +197 -26
  138. package/scripts/generate-code-map.ts +62 -28
  139. package/scripts/scaffold-project.ts +12 -2
  140. package/scripts/split-spec.ts +2 -1
  141. package/scripts/sync-sc-status.ts +127 -14
  142. package/scripts/sync-spec-tests.ts +2 -1
@@ -0,0 +1,317 @@
1
+ /**
2
+ * Observed failures, mined from the one source that is always in the tree:
3
+ * `fix:` and `Revert` commit subjects (#545).
4
+ *
5
+ * ## Why this source, and not the three others #545 names
6
+ *
7
+ * #545 lists four intake sources — correction language in transcripts, revert
8
+ * and fix-up commits, CI failures on merged PRs, and gate refusals in
9
+ * `workflow-state.json`. Three of them are unreachable from a check running in
10
+ * the configuration CI runs it in:
11
+ *
12
+ * | Source | Needs | Present under an empty `HOME`, no credentials |
13
+ * |---|---|---|
14
+ * | `git log` fix/revert | the repository | **yes** |
15
+ * | CI failures on merged PRs | an authenticated API client | no |
16
+ * | Gate refusals | a populated `~/.rungate` run store | no |
17
+ * | Transcripts | a session store, and a confidentiality decision | no |
18
+ *
19
+ * A miner whose input is absent on a runner has no failing input there and
20
+ * passes vacuously, which is the defect class this repository pays for most
21
+ * often. `git log` is the only one of the four that is offline, in-tree, dated
22
+ * and citable by construction.
23
+ *
24
+ * ## Why a commit subject is a rule candidate at all
25
+ *
26
+ * The thing #544 has to rank on is *a specific observed failure*, not a
27
+ * general principle — "a two-run window cannot falsify a three-arrival model"
28
+ * rather than "verify before asserting". Signal-phrase extraction over prose
29
+ * produces the second kind, 1,010 times on one consumer, with no dates.
30
+ *
31
+ * This repository's commit convention already produces the first kind. Four
32
+ * subjects from `main`, unaltered, beside the hand-written rule each one
33
+ * corresponds to:
34
+ *
35
+ * | Subject | The rule somebody later wrote by hand |
36
+ * |---|---|
37
+ * | `fix(#960): the drift reading stops consulting a config the reviewer can write` | *a control whose input the measured thing can write is not a control* |
38
+ * | `fix(#921): take the containment reading off $HOME` | *run the guard in the configuration CI runs it in* |
39
+ * | `fix(#926, #962): give the bookkeeping list a reachability witness` | *never source a fixture from the list it tests* |
40
+ * | `fix(#506): CONFIG-1 reads the source it could not reach, instead of refusing over it` | *an unreadable position refuses; it does not read as clean* |
41
+ *
42
+ * Each arrives carrying a sha, an ISO date and the issue numbers it cites.
43
+ * Evidence is a property of this source rather than something a scorer infers
44
+ * from text shape, and that is the whole reason #544's promotion criterion can
45
+ * be mechanical.
46
+ *
47
+ * ## WHAT THIS DOES NOT COVER
48
+ *
49
+ * This is a classifier, so the honest question is what it misclassifies. Each
50
+ * escape below is asserted as a case in `test/failure-intake-promotion.test.ts`
51
+ * rather than described here and left unmeasured — a documented escape nobody
52
+ * ran is a sentence, not a boundary.
53
+ *
54
+ * - **A trivial `fix:` is mined as though it were an incident.** `fix(#1): the
55
+ * typo in the README heading (#2)` carries a sha, a date and two issue
56
+ * numbers, so it outranks every doc-prose candidate. Nothing here reads the
57
+ * diff, and "was this failure worth a rule" is not a question a subject line
58
+ * can answer. Narrowing by diff size or by touched path is the obvious next
59
+ * move and is deliberately not taken here, because a narrowing measured
60
+ * against nothing is the other half of this defect class.
61
+ * - **A defect fixed under `feat:` is invisible.** `feat(#892): the collect
62
+ * refusal says whether the copies it refuses are the same bytes` is on `main`
63
+ * and is rule-shaped; it is not mined, because widening to every
64
+ * conventional type would admit `chore` and `docs` with it.
65
+ * - **A revert of a revert reads as a failure.** `Revert "Revert "fix(#7): …""`
66
+ * is a re-land — the original change was right after all — and is classified
67
+ * as a revert anyway.
68
+ * - **A subject with no description is dropped, not reported.** `fix(#5):` with
69
+ * nothing after it falls under the ten-character floor and leaves no trace in
70
+ * the reading. It is counted in `commitsScanned` and nowhere else.
71
+ *
72
+ * The first two are the ones that matter: they are a false positive and a false
73
+ * negative of the SAME classifier, and closing either without measuring the
74
+ * other is how a detector ends up refusing every commit or seeing none.
75
+ */
76
+ import { spawnSync } from "child_process";
77
+ import { existsSync } from "fs";
78
+ import { join } from "path";
79
+ import { contentHash } from "./content-hash";
80
+
81
+ /** Where a candidate's evidence came from. */
82
+ export type EvidenceKind = "fix-commit" | "revert-commit";
83
+
84
+ export interface CandidateEvidence {
85
+ kind: EvidenceKind;
86
+ /** The commit's ISO 8601 committer date. A candidate without one is not evidence-backed. */
87
+ date: string;
88
+ /** The commit sha. The citation a reader can check. */
89
+ citation: string;
90
+ /** Every `#N` the subject names, in order of appearance, deduplicated. */
91
+ issues: number[];
92
+ }
93
+
94
+ export interface EvidenceCandidate {
95
+ /** The failure, in the committer's own words. Never re-derived. */
96
+ rule: string;
97
+ /** `git:<short sha>`, so a candidate says where to look without a line number that rots. */
98
+ source: string;
99
+ /** The whole subject, kept so the reading never has to be re-parsed to be read. */
100
+ context: string;
101
+ hash: string;
102
+ evidence: CandidateEvidence;
103
+ }
104
+
105
+ /**
106
+ * Why a reading is not a reading. Exported because a caller that wants to
107
+ * distinguish the cases must compare against the producer's own spelling
108
+ * rather than a second copy of it.
109
+ */
110
+ export const NOT_A_GIT_REPOSITORY = "NOT_A_GIT_REPOSITORY";
111
+ export const SHALLOW_HISTORY = "SHALLOW_HISTORY";
112
+ export const GIT_LOG_FAILED = "GIT_LOG_FAILED";
113
+
114
+ /**
115
+ * How far back to read. Bounded on purpose: HYGIENE-6 is a caller, and #508
116
+ * records that check timing out at 5001ms because a scan it owned had become
117
+ * load-sensitive. One `git log` is one subprocess, and this cap keeps its
118
+ * output bounded as well.
119
+ */
120
+ export const MAX_COMMITS_SCANNED = 500;
121
+
122
+ export interface FailureIntakeReading {
123
+ /**
124
+ * The single discriminator. `unmeasuredReasons` and this field are two
125
+ * projections of one computation, so they cannot disagree.
126
+ */
127
+ reading: "MEASURED" | "UNMEASURED";
128
+ unmeasuredReasons: string[];
129
+ /**
130
+ * Commits the log actually returned. A reading that produced no candidates
131
+ * over 500 commits and one that produced none over 1 are the same empty
132
+ * list, and only this number tells them apart.
133
+ */
134
+ commitsScanned: number;
135
+ candidates: EvidenceCandidate[];
136
+ }
137
+
138
+ const CONVENTIONAL_FIX = /^fix(?:\(([^)]*)\))?!?:\s*(.+)$/;
139
+ const REVERT = /^Revert\s+"(.+)"\s*$/;
140
+ const TRAILING_PR = /\s*\(#\d+\)\s*$/;
141
+ const ISSUE_REF = /#(\d+)/g;
142
+
143
+ /**
144
+ * The floor a candidate's text has to clear, matching the one
145
+ * `extractSignalPhrases` applies to doc prose so the two producers do not
146
+ * disagree about what counts as a sentence.
147
+ */
148
+ const MIN_RULE_LENGTH = 10;
149
+
150
+ export interface ClassifiedSubject {
151
+ kind: EvidenceKind;
152
+ rule: string;
153
+ issues: number[];
154
+ }
155
+
156
+ /**
157
+ * THE detector. One binding, so there is one thing to mutate — a second place
158
+ * deciding "is this commit a reported failure" would survive any mutation of
159
+ * this one and the guard would go green for the wrong reason.
160
+ *
161
+ * Returns `null` for a subject that reports no failure.
162
+ */
163
+ export function classifyCommitSubject(subject: string): ClassifiedSubject | null {
164
+ const trimmed = subject.trim();
165
+
166
+ const reverted = REVERT.exec(trimmed);
167
+ if (reverted) {
168
+ const inner = reverted[1];
169
+ const innerFix = CONVENTIONAL_FIX.exec(inner);
170
+ const description = describe(innerFix ? innerFix[2] : inner);
171
+ if (!description) return null;
172
+ return { kind: "revert-commit", rule: description, issues: issueRefs(trimmed) };
173
+ }
174
+
175
+ const fixed = CONVENTIONAL_FIX.exec(trimmed);
176
+ if (fixed) {
177
+ const description = describe(fixed[2]);
178
+ if (!description) return null;
179
+ return { kind: "fix-commit", rule: description, issues: issueRefs(trimmed) };
180
+ }
181
+
182
+ return null;
183
+ }
184
+
185
+ /**
186
+ * The sentence, with the trailing `(#PR)` the squash merge appended removed.
187
+ * The PR number is not discarded — `issueRefs` reads it off the whole subject
188
+ * — it is removed from the TEXT, because a rule that ends in a bare number
189
+ * reads as a citation rather than a statement.
190
+ */
191
+ function describe(raw: string): string | null {
192
+ const text = raw.replace(TRAILING_PR, "").trim().replace(/[.;]$/, "");
193
+ return text.length >= MIN_RULE_LENGTH ? text : null;
194
+ }
195
+
196
+ function issueRefs(subject: string): number[] {
197
+ const seen: number[] = [];
198
+ for (const m of subject.matchAll(ISSUE_REF)) {
199
+ const n = Number(m[1]);
200
+ if (!seen.includes(n)) seen.push(n);
201
+ }
202
+ return seen;
203
+ }
204
+
205
+ function gitStdout(root: string, args: string[]): { status: number; out: string; err: string } {
206
+ const r = spawnSync("git", ["-C", root, ...args], {
207
+ timeout: 60_000,
208
+ maxBuffer: 16 * 1024 * 1024,
209
+ encoding: "utf-8",
210
+ });
211
+ if (r.error) return { status: -1, out: "", err: r.error.message };
212
+ return { status: r.status ?? -1, out: r.stdout ?? "", err: (r.stderr ?? "").trim() };
213
+ }
214
+
215
+ /**
216
+ * Mine `fix:` and `Revert` commits into evidence-bearing candidates.
217
+ *
218
+ * Three states are refusals rather than empty readings, and the third is the
219
+ * one this module exists to be honest about:
220
+ *
221
+ * - **no repository** — nothing to read. A scaffolded project with no `.git`
222
+ * hits this and it is not a failure of the project.
223
+ * - **`git log` could not run** — including a repository with no commits at
224
+ * all, which exits 128. An empty history is not a history with no fixes.
225
+ * - **a shallow clone** — the reading is of a truncated history, so zero
226
+ * candidates means nothing. `actions/checkout@v4` with no `fetch-depth`
227
+ * clones to depth 1, so this is the state a CI runner is in by default and
228
+ * the reading there is UNMEASURED on every run, not a silent pass.
229
+ *
230
+ * In every case the candidates found so far are still returned. Withholding
231
+ * them would make a refusal and an empty tree look alike from the outside,
232
+ * which is the shape being avoided.
233
+ */
234
+ export function mineFixCommits(
235
+ root: string,
236
+ options?: { maxCommits?: number },
237
+ ): FailureIntakeReading {
238
+ const unmeasuredReasons: string[] = [];
239
+ const empty = (): FailureIntakeReading => ({
240
+ reading: "UNMEASURED",
241
+ unmeasuredReasons,
242
+ commitsScanned: 0,
243
+ candidates: [],
244
+ });
245
+
246
+ if (!existsSync(join(root, ".git"))) {
247
+ unmeasuredReasons.push(NOT_A_GIT_REPOSITORY);
248
+ return empty();
249
+ }
250
+
251
+ const shallow = gitStdout(root, ["rev-parse", "--is-shallow-repository"]);
252
+ if (shallow.status === 0 && shallow.out.trim() === "true") {
253
+ unmeasuredReasons.push(SHALLOW_HISTORY);
254
+ }
255
+
256
+ const max = options?.maxCommits ?? MAX_COMMITS_SCANNED;
257
+ // %x1f is the ASCII unit separator: it cannot occur in a subject, so the
258
+ // split cannot be defeated by a commit message containing the delimiter.
259
+ const log = gitStdout(root, [
260
+ "log",
261
+ "--no-merges",
262
+ `-n${max}`,
263
+ "--format=%H%x1f%cI%x1f%s",
264
+ ]);
265
+ if (log.status !== 0) {
266
+ unmeasuredReasons.push(`${GIT_LOG_FAILED}: ${log.err || "(no stderr)"}`);
267
+ return empty();
268
+ }
269
+
270
+ const lines = log.out.split("\n").filter((l) => l.length > 0);
271
+ const candidates: EvidenceCandidate[] = [];
272
+ const seen = new Set<string>();
273
+
274
+ for (const line of lines) {
275
+ const [sha, date, subject] = line.split("\u001f");
276
+ if (!sha || !date || subject === undefined) continue;
277
+ const classified = classifyCommitSubject(subject);
278
+ if (!classified) continue;
279
+ const hash = contentHash(classified.rule);
280
+ // The dedup key carries the KIND; the hash does not.
281
+ //
282
+ // Those are two different questions and the first draft asked only one.
283
+ // `Revert "fix(#921): take the containment reading off $HOME"` describes
284
+ // the same sentence as the commit it reverts and means the opposite
285
+ // thing, so a key of the sentence alone drops one of the two — measured,
286
+ // as the first red this module's battery produced.
287
+ //
288
+ // The HASH stays the sentence, because the hash is what
289
+ // `reference/rejected-constraints.md` matches on, and a
290
+ // veto is a judgement about a sentence. So vetoing one vetoes both, which
291
+ // is the intended reading and is asserted rather than assumed.
292
+ const key = `${classified.kind}:${hash}`;
293
+ // Newest first, so the first occurrence of a repeated sentence is the one
294
+ // kept — a re-land cites the most recent observation, not the oldest.
295
+ if (seen.has(key)) continue;
296
+ seen.add(key);
297
+ candidates.push({
298
+ rule: classified.rule,
299
+ source: `git:${sha.slice(0, 8)}`,
300
+ context: subject,
301
+ hash,
302
+ evidence: {
303
+ kind: classified.kind,
304
+ date,
305
+ citation: sha,
306
+ issues: classified.issues,
307
+ },
308
+ });
309
+ }
310
+
311
+ return {
312
+ reading: unmeasuredReasons.length > 0 ? "UNMEASURED" : "MEASURED",
313
+ unmeasuredReasons,
314
+ commitsScanned: lines.length,
315
+ candidates,
316
+ };
317
+ }
@@ -0,0 +1,286 @@
1
+ /**
2
+ * Whether `fallow` can be run without reaching the network (#581).
3
+ *
4
+ * `fallow` is an optional external tool and is NOT a declared dependency —
5
+ * not in `package.json`, not in `node_modules/.bin`, not on `PATH`, on this
6
+ * machine or on CI. So every bare `npx fallow` is a registry fetch.
7
+ *
8
+ * `lib/conformity.ts` learned that in its own words:
9
+ *
10
+ * > When it is absent, `npx fallow` does a registry fetch on every
11
+ * > invocation — four tests x one fetch each, each outliving bun's
12
+ * > per-test timeout. … Resolve it locally instead, with no network path.
13
+ *
14
+ * and then kept the fix to itself. `scripts/generate-code-map.ts` — the
15
+ * caller on the **scaffold** path, which runs once per consumer forever
16
+ * rather than four times in a suite — still spawned `npx fallow`
17
+ * unconditionally. So the fix landed in the cheap caller and not in the
18
+ * expensive one, and the cost of that is not a slow test: a consumer
19
+ * scaffolding behind a proxy, in an air-gapped CI, or on a bad connection
20
+ * gets a 30-second stall and then a silently degraded CODE-MAP, with nothing
21
+ * in the output saying a network call was attempted.
22
+ *
23
+ * It also made the suite non-deterministic. PR #580 — three state files, no
24
+ * code — went red on `SC-1665`, which asserts that `.fallow/cache.bin` was
25
+ * produced by both of two scaffold runs; when the fetch fails it is produced
26
+ * by neither. Reproduced with no repo change at all:
27
+ *
28
+ * npm_config_registry=http://127.0.0.1:1/ bun test test/scaffold-relative-root.test.ts
29
+ * error: .fallow/cache.bin is excluded but was not produced by both runs
30
+ *
31
+ * ## One binding
32
+ *
33
+ * This module exists rather than an export from `lib/conformity.ts` because
34
+ * conformity imports `bun:test` at module scope and so cannot be imported by
35
+ * a CLI. Same arrangement as `lib/git-dates.ts` (#508) and
36
+ * `lib/harness-identity.ts` (#380): one implementation, re-exported, because
37
+ * two answers to one question are behaviourally one and no test can tell
38
+ * them apart.
39
+ */
40
+
41
+ import { existsSync } from "fs";
42
+ import { join } from "path";
43
+
44
+ /**
45
+ * Memoised PER ROOT.
46
+ *
47
+ * `runFallowCheck` is exported and consumer projects call it with their own
48
+ * root, so a single process can ask about several. A root-independent cache
49
+ * would answer for the wrong directory.
50
+ */
51
+ const FALLOW_AVAILABLE = new Map<string, boolean>();
52
+
53
+ export function fallowAvailable(root: string): boolean {
54
+ const cached = FALLOW_AVAILABLE.get(root);
55
+ if (cached !== undefined) return cached;
56
+ const available = existsSync(join(root, "node_modules", ".bin", "fallow")) || Bun.which("fallow") !== null;
57
+ FALLOW_AVAILABLE.set(root, available);
58
+ return available;
59
+ }
60
+
61
+ /** Test seam: drop the memo so a case can change the answer. */
62
+ export function resetFallowAvailability(): void {
63
+ FALLOW_AVAILABLE.clear();
64
+ }
65
+
66
+ /**
67
+ * Why a fallow-derived reading is missing, or null when it is not missing.
68
+ *
69
+ * Three outcomes, not two. `null` from the old `runFallow()` meant "not
70
+ * installed", "the spawn failed", "the output did not parse" and "it ran and
71
+ * found nothing" all at once, and a CODE-MAP written from it was
72
+ * byte-identical in every case — which is
73
+ * `.claude/rules/config-access.md`'s *Silent Default Substitution* with a
74
+ * document as the victim.
75
+ */
76
+ export type FallowUnavailable =
77
+ | { kind: "not-installed"; reason: string }
78
+ | { kind: "timed-out"; reason: string }
79
+ | { kind: "run-failed"; reason: string };
80
+
81
+ export function fallowNotInstalled(): FallowUnavailable {
82
+ return {
83
+ kind: "not-installed",
84
+ reason:
85
+ "fallow is not installed (it is an optional tool, not a declared dependency) — " +
86
+ "no static analysis was run, and no registry fetch was attempted",
87
+ };
88
+ }
89
+
90
+ /**
91
+ * A tool's output, made safe to put in a document an agent reads.
92
+ *
93
+ * The `run-failed` reason quotes what fallow printed, and that string ends
94
+ * up inside CODE-MAP.md — which `.claude/rules/key-files.md` tells every
95
+ * agent to read to understand the codebase. So it is untrusted text on its
96
+ * way into a trusted document, and fallow's error text can quote the repo's
97
+ * own file names and contents.
98
+ *
99
+ * One line, an allowlist, and a cap. Not an escape routine: a denylist of
100
+ * markdown syntax is a detector narrower than what it detects, and the
101
+ * useful content of a tool error survives an allowlist intact.
102
+ */
103
+ export function safeToolDetail(raw: string): string {
104
+ const firstLine = raw.split("\n")[0] ?? "";
105
+ // A RUN of disallowed characters collapses to one `?`, rather than one
106
+ // `?` each. Both are safe; the difference is whether a detail that was
107
+ // entirely unprintable comes back as `????????` — which carries no
108
+ // information and is indistinguishable from a tool that said something.
109
+ const cleaned = firstLine.replace(/[^A-Za-z0-9 .,:;()/'"=+-]+/g, "?").slice(0, 120).trim();
110
+ return /^[?\s]*$/.test(cleaned) ? "(no printable detail)" : cleaned;
111
+ }
112
+
113
+ export function fallowRunFailed(detail: string): FallowUnavailable {
114
+ return {
115
+ kind: "run-failed",
116
+ reason: `fallow is installed but the run did not produce a reading: ${safeToolDetail(detail)}`,
117
+ };
118
+ }
119
+
120
+ /**
121
+ * The budget, and there is exactly one of it (#935).
122
+ *
123
+ * It is BOTH the spawn's `timeout` and the per-test timeout every FALLOW
124
+ * registration is given, because the defect this constant exists to prevent
125
+ * is the two disagreeing. `lib/conformity.ts` spawned with `timeout: 30_000`
126
+ * inside a `test()` that passed no timeout at all — so bun killed the body at
127
+ * its 5000ms default and the 30s was unreachable, a budget nothing could
128
+ * spend. Measured on `hornjason/agentgrit` PR #310: FALLOW-1 died at 5010ms
129
+ * on a commit that changed two markdown files, four times in one day.
130
+ *
131
+ * A second literal anywhere is the whole bug returning, so
132
+ * `test/fallow-budget-reading.test.ts` holds the population of other budget
133
+ * spellings at zero rather than trusting this comment.
134
+ */
135
+ export const FALLOW_BUDGET_MS = 30_000;
136
+
137
+ /**
138
+ * A run the clock killed.
139
+ *
140
+ * Its own kind, and NOT a flavour of `run-failed`, because the two send an
141
+ * operator to different places: one says go and look at the tool, this one
142
+ * says the tool was still working when we stopped it. It carries the budget
143
+ * because that is the number the reader would change, and the elapsed time
144
+ * because a run killed at the budget and a run killed by something else at
145
+ * 200ms are different facts.
146
+ */
147
+ export function fallowTimedOut(budgetMs: number, elapsedMs: number): FallowUnavailable {
148
+ return {
149
+ kind: "timed-out",
150
+ reason:
151
+ `fallow is installed and was still running when the ${budgetMs}ms budget expired ` +
152
+ `(killed after ${elapsedMs}ms) — no static analysis reading was produced. This is ` +
153
+ `UNMEASURED, not a clean result: raise the budget, or warm the index before the run`,
154
+ };
155
+ }
156
+
157
+ /** Only the fields the classifier is allowed to read, so a test can plant one. */
158
+ export interface FallowSpawnResult {
159
+ stdout: { toString(): string };
160
+ stderr?: { toString(): string };
161
+ exitCode: number | null;
162
+ exitedDueToTimeout?: boolean;
163
+ }
164
+
165
+ export type FallowReading<T> = { data: T } | { unavailable: FallowUnavailable };
166
+
167
+ /**
168
+ * The ONE place in the tree that spawns fallow (#935, #621).
169
+ *
170
+ * There were two — `lib/conformity.ts` and `scripts/generate-code-map.ts` —
171
+ * each with its own `timeout: 30_000` literal and only one of them
172
+ * classifying anything. Two positions answering one question with nothing
173
+ * comparing them: mutate either and the other carries on spawning, which is
174
+ * `.claude/rules/checks-must-be-able-to-fail.md`'s fourth shape.
175
+ *
176
+ * **The classification ORDER is the fix, not the `timed-out` arm.** A killed
177
+ * process writes nothing, so a run that exceeded the budget satisfies the
178
+ * empty-stdout branch too — and whichever is tested first decides what the
179
+ * operator is told. Reading `exitedDueToTimeout` second is how a 30-second
180
+ * hang got reported as `fallow is not installed (not a declared dependency)`
181
+ * on a tree where fallow is exactly pinned. An operator acting on that goes
182
+ * and declares a dependency that is already there.
183
+ *
184
+ * `available` and `spawn` are injected rather than reached for, so a case can
185
+ * force a timeout without waiting for one and can prove the absent-tool arm
186
+ * never spawns at all. Both default to the real thing.
187
+ */
188
+ export function runFallowJson<T>(
189
+ root: string,
190
+ args: string[],
191
+ opts?: {
192
+ budgetMs?: number;
193
+ available?: (root: string) => boolean;
194
+ spawn?: (argv: string[], options: Record<string, unknown>) => FallowSpawnResult;
195
+ },
196
+ ): FallowReading<T> {
197
+ const budgetMs = opts?.budgetMs ?? FALLOW_BUDGET_MS;
198
+ const isAvailable = opts?.available ?? fallowAvailable;
199
+ if (!isAvailable(root)) return { unavailable: fallowNotInstalled() };
200
+
201
+ const spawn =
202
+ opts?.spawn ??
203
+ ((argv: string[], options: Record<string, unknown>) =>
204
+ Bun.spawnSync(argv, options as Parameters<typeof Bun.spawnSync>[1]) as FallowSpawnResult);
205
+
206
+ const startedAt = Date.now();
207
+ const result = spawn(["npx", "fallow", ...args, "--format", "json", "--quiet"], {
208
+ cwd: root,
209
+ env: { ...process.env, NODE_NO_WARNINGS: "1" },
210
+ timeout: budgetMs,
211
+ });
212
+ const elapsedMs = Date.now() - startedAt;
213
+
214
+ // FIRST, and the order is the whole point — see the docstring above.
215
+ if (result.exitedDueToTimeout) return { unavailable: fallowTimedOut(budgetMs, elapsedMs) };
216
+
217
+ const stdout = result.stdout.toString().trim();
218
+ if (!stdout) {
219
+ const stderr = result.stderr?.toString().trim() ?? "";
220
+ return {
221
+ unavailable: fallowRunFailed(stderr || `exit ${result.exitCode}, no output`),
222
+ };
223
+ }
224
+ // fallow's own error envelope. It is well-formed JSON, so it would parse
225
+ // and be returned as a reading of zero issues.
226
+ if (stdout.startsWith('{"error"')) return { unavailable: fallowRunFailed(stdout) };
227
+ try {
228
+ return { data: JSON.parse(stdout) as T };
229
+ } catch (e) {
230
+ return {
231
+ unavailable: fallowRunFailed(`output did not parse as JSON (${(e as Error).name})`),
232
+ };
233
+ }
234
+ }
235
+
236
+ /**
237
+ * Pay the cold index build once, before anyone is being timed for it.
238
+ *
239
+ * fallow builds an index on first use: ~1.5s cold against ~455ms warm,
240
+ * measured. Four checks run in sequence and the FIRST one pays it, which is
241
+ * why FALLOW-1 looked slow and the three after it looked fast. It was never
242
+ * FALLOW-1 — it is whichever check runs first, and moving the checks around
243
+ * would move the symptom without touching the cause.
244
+ *
245
+ * Failures are deliberately swallowed: this is a warm-up, and every caller
246
+ * takes its own reading immediately afterwards and reports its own outcome.
247
+ * A warm-up that could fail a suite would be a second decider for whether
248
+ * fallow works.
249
+ *
250
+ * It takes the same seam `runFallowJson` does, and that is not symmetry for
251
+ * its own sake. Without it the only assertable property is WHERE the call
252
+ * sits in the source, and a warm-up short-circuited to `return` is invisible
253
+ * to a position check — measured, as row M7 of this change's battery, which
254
+ * came back 0 of 14. Worse, fallow is not installed on this machine or on
255
+ * CI, so `fallowAvailable` is false and the real function returns without
256
+ * spawning too: there was no input anywhere in this repository on which the
257
+ * no-op and the original behaved differently. That is not a check that is
258
+ * blind, it is a row that could not be run
259
+ * (`.claude/rules/checks-must-be-able-to-fail.md`, *before you believe a 0*).
260
+ */
261
+ export function warmFallow(
262
+ root: string,
263
+ opts?: Parameters<typeof runFallowJson>[2],
264
+ ): void {
265
+ // No availability check of its own, deliberately. It had one, and
266
+ // `runFallowJson` opens with the same question — two deciders answering it
267
+ // about the same root, which is behaviourally one and which no test can
268
+ // tell apart. The battery said so before any of this was argued: deleting
269
+ // the guard here was 0 of 15, because the one below it still refused
270
+ // (`.claude/rules/checks-must-be-able-to-fail.md`, fourth shape). There is
271
+ // no input only this copy could reach, so the honest fix is to collapse
272
+ // rather than to invent a case for it.
273
+ runFallowJson(root, ["dead-code"], opts);
274
+ }
275
+
276
+ /**
277
+ * The line a generated document carries in place of a section it could not
278
+ * produce.
279
+ *
280
+ * UNMEASURED by name. An omitted section and a section reporting nothing
281
+ * wrong are the same absence to a reader, and the reader of a CODE-MAP is an
282
+ * agent deciding whether this project has dead code.
283
+ */
284
+ export function fallowUnmeasuredNotice(u: FallowUnavailable): string {
285
+ return `## Code Health (fallow)\n\n**UNMEASURED** — ${u.reason}.`;
286
+ }