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,393 @@
1
+ /**
2
+ * top-level-cd.ts — the decision behind TopLevelCdGuard (#992)
3
+ *
4
+ * One question: does this Bash command move the SESSION's working directory?
5
+ *
6
+ * `topLevelCdRefusal` is the only exported binding and the only decider, so
7
+ * there is one thing to mutate and one thing for a later caller to reuse —
8
+ * the grader, a conformity check, a transcript audit. A second copy of this
9
+ * parse anywhere would survive any mutation of this one and both would read
10
+ * as covered (`.claude/rules/checks-must-be-able-to-fail.md`, fourth shape).
11
+ *
12
+ * ## Why the question is "top level" and not "anywhere"
13
+ *
14
+ * A Bash tool call runs in a shell whose cwd PERSISTS between calls, and the
15
+ * agent runtime resolves `isolation: 'worktree'` against that directory. So a
16
+ * `cd` at the top level of one call can kill a peer agent's worktree creation
17
+ * hours later, and the failure names the session's directory rather than the
18
+ * command that moved it. A `cd` inside a subshell, a command substitution or
19
+ * a child interpreter cannot do that: the child exits and the parent's cwd is
20
+ * untouched.
21
+ *
22
+ * ## The direction this is allowed to be wrong in
23
+ *
24
+ * Toward REFUSAL. A false refusal costs one retyped command and teaches the
25
+ * habit; a false allow costs another agent half a day. Three forms are
26
+ * refused that bash would in fact fork — a pipeline element, a backgrounded
27
+ * command, and `exec cd` — because distinguishing them needs the shell's own
28
+ * semantics and the saving is one retype.
29
+ *
30
+ * An input this cannot READ is refused for the same reason and said out loud:
31
+ * a command that is absent, or not a string, has not been examined and found
32
+ * clean. See `unreadableMessage`, and the `|| ''` it replaced.
33
+ *
34
+ * ## KNOWN FALSE REFUSALS — the direction this is allowed to be wrong in
35
+ *
36
+ * A `#` comment is not parsed. `ls # cd /tmp` is allowed because `ls` is the
37
+ * segment's first token, but a comment carrying a separator —
38
+ * `make # fails; cd /x is not the fix` — splits and the tail reads as a
39
+ * top-level `cd`. Both forms are asserted in `test/top-level-cd.test.ts`.
40
+ *
41
+ * Stripping comments would fix it and was deliberately not done: a `#` inside
42
+ * `$(…)` on one line comments out the closing paren, so a stripper unbalances
43
+ * the depth counter and a later top-level `cd` falls INSIDE the unclosed
44
+ * subshell and is allowed. That trades a rare false refusal for a new
45
+ * false-allow path, which is the wrong direction.
46
+ *
47
+ * ## WHAT THIS DOES NOT COVER
48
+ *
49
+ * Every form below moves the session and is NOT refused. They are asserted as
50
+ * cases in `test/top-level-cd.test.ts` under AC-10, not merely listed here, so
51
+ * a later widening that closes one goes red rather than silently changing the
52
+ * behaviour of every session on the machine.
53
+ *
54
+ * - `eval "cd /x"` — the command is a string until the shell expands it.
55
+ * - `CMD=cd; $CMD /x` — a command built from a variable. The hook has no
56
+ * access to shell state and cannot know what `$CMD` holds.
57
+ * - A heredoc body sourced into the current shell (`source /dev/stdin <<EOF`).
58
+ * Heredoc bodies are stripped before the scan because they are data in
59
+ * every other case, and `cat <<EOF` carrying the word `cd` was a real false
60
+ * positive in the sibling guard (`lib/bash-file-read.ts`).
61
+ * - A function defined and called in one command: `goto() { cd "$1"; }; goto /x`.
62
+ * - A zsh function or alias from the user's rc — the token is not `cd` and
63
+ * nothing in the command says what it expands to.
64
+ * - A sourced script that cds: `. ./setup.sh`, `source ./setup.sh`.
65
+ * - A `trap 'cd /x' EXIT` body, which is quoted now and run later.
66
+ *
67
+ * Closing any of these needs a real shell parser plus the shell's runtime
68
+ * state. This is a habit-former, not a sandbox.
69
+ *
70
+ * Issue: #992
71
+ */
72
+
73
+ export interface CdRefusal {
74
+ /** The top-level segment that moves the shell, trimmed. */
75
+ segment: string;
76
+ /** What the caller is told, naming the alternatives. */
77
+ message: string;
78
+ }
79
+
80
+ /**
81
+ * THE refusal exit, declared once.
82
+ *
83
+ * `hooks/TopLevelCdGuard.hook.ts` emits this as its `decision` and has no
84
+ * literal of its own, so there is exactly one site to mutate and a case that
85
+ * observes a refusal can be proved to have observed THIS one
86
+ * (`.claude/rules/checks-must-be-able-to-fail.md`, *For a script whose job is
87
+ * to exit non-zero*). A second inlined `'block'` anywhere in the hook would
88
+ * survive the mutation and the case would go green having witnessed nothing —
89
+ * `test/top-level-cd.test.ts` asserts the literal appears exactly once.
90
+ */
91
+ export const CD_GUARD_DECISION = 'block';
92
+
93
+ /** Builtins that move the shell's own working directory. */
94
+ const SHELL_MOVERS = new Set(['cd', 'pushd', 'popd']);
95
+
96
+ /**
97
+ * Wrappers that delegate to the real command. `command cd /x` and
98
+ * `builtin cd /x` both run the builtin. `exec`, `time` and `nohup` are here
99
+ * for the refusal direction: they would not in fact move the parent, and
100
+ * refusing them costs one retype.
101
+ */
102
+ const PREFIXES = new Set(['command', 'builtin', 'exec', 'time', 'nohup']);
103
+
104
+ /**
105
+ * Shell keywords that can be immediately followed by a command which runs in
106
+ * the CURRENT shell. `{ … }` is a group, not a subshell — it is in this list
107
+ * deliberately, and `(` is deliberately not.
108
+ */
109
+ const LEADING_KEYWORDS = new Set([
110
+ 'if', 'then', 'elif', 'else', 'fi',
111
+ 'while', 'until', 'do', 'done',
112
+ '{', '}', '!',
113
+ ]);
114
+
115
+ /** An inline `VAR=value` assignment preceding the command. */
116
+ const ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
117
+
118
+ /**
119
+ * Remove heredoc bodies before scanning. A heredoc body is data, and the hook
120
+ * sees the raw command string, so `cat <<EOF > f … cd /x … EOF` would
121
+ * otherwise read as a top-level `cd` on its own line.
122
+ *
123
+ * Unlike `lib/bash-file-read.ts` this drops the body even when the feeding
124
+ * command is a shell interpreter, because `bash <<EOF` runs the body in a
125
+ * CHILD and cannot move the session. The one form that can — `source
126
+ * /dev/stdin <<EOF` — is a declared gap above.
127
+ */
128
+ function stripHeredocBodies(command: string): string {
129
+ if (!command.includes('<<')) return command;
130
+
131
+ const out: string[] = [];
132
+ let delim: string | null = null;
133
+ let allowIndent = false;
134
+
135
+ for (const line of command.split('\n')) {
136
+ if (delim !== null) {
137
+ if ((allowIndent ? line.trimStart() : line) === delim) delim = null;
138
+ continue; // drop body and terminator
139
+ }
140
+
141
+ const m = line.match(/<<(-?)\s*(['"]?)([A-Za-z_][A-Za-z0-9_]*)\2/);
142
+ if (m) {
143
+ allowIndent = m[1] === '-';
144
+ delim = m[3];
145
+ out.push(line.slice(0, m.index) + line.slice(m.index! + m[0].length));
146
+ continue;
147
+ }
148
+
149
+ out.push(line);
150
+ }
151
+
152
+ return out.join('\n');
153
+ }
154
+
155
+ /**
156
+ * Split a command into the segments that run in the CURRENT shell.
157
+ *
158
+ * Quote-, paren- and backtick-aware by necessity. A naive split tears quoted
159
+ * strings apart (`git commit -m "cd into /x"` would yield a bogus `cd into
160
+ * /x"` segment) and, worse, cannot tell `(cd /x && make)` from `cd /x &&
161
+ * make` — which is the whole distinction this module exists for.
162
+ *
163
+ * Text inside `(` … `)`, `$(` … `)` and backticks is a child process, so no
164
+ * split happens there and the enclosing segment keeps its own first token:
165
+ * `(cd /x && make)` is one segment beginning `(cd`, which is not `cd`.
166
+ *
167
+ * This is deliberately NOT `splitSegments` from `lib/bash-file-read.ts`.
168
+ * That one answers a question where depth is irrelevant — a `cat` reading a
169
+ * file reads it in a subshell too — so it tracks quotes and nothing else.
170
+ */
171
+ function topLevelSegments(command: string): string[] {
172
+ const segments: string[] = [];
173
+ let current = '';
174
+ let quote: "'" | '"' | null = null;
175
+ let depth = 0;
176
+ let backtick = false;
177
+
178
+ for (let i = 0; i < command.length; i++) {
179
+ const ch = command[i];
180
+
181
+ if (quote) {
182
+ current += ch;
183
+ if (ch === '\\' && quote === '"' && i + 1 < command.length) current += command[++i];
184
+ else if (ch === quote) quote = null;
185
+ continue;
186
+ }
187
+
188
+ if (ch === "'" || ch === '"') {
189
+ quote = ch;
190
+ current += ch;
191
+ continue;
192
+ }
193
+
194
+ if (ch === '\\' && i + 1 < command.length) {
195
+ current += ch + command[++i];
196
+ continue;
197
+ }
198
+
199
+ if (ch === '`') {
200
+ backtick = !backtick;
201
+ current += ch;
202
+ continue;
203
+ }
204
+
205
+ if (ch === '(') depth++;
206
+ else if (ch === ')') depth = Math.max(0, depth - 1);
207
+
208
+ if (depth === 0 && !backtick && (ch === '|' || ch === '&' || ch === ';' || ch === '\n')) {
209
+ if ((ch === '|' || ch === '&') && command[i + 1] === ch) i++; // consume || and &&
210
+ segments.push(current);
211
+ current = '';
212
+ continue;
213
+ }
214
+
215
+ current += ch;
216
+ }
217
+
218
+ segments.push(current);
219
+ return segments;
220
+ }
221
+
222
+ /**
223
+ * Resolve a token to the command name it invokes: quotes off, escapes off,
224
+ * directory off. `'cd'`, `\cd` and `/usr/bin/cd` all resolve to `cd`.
225
+ */
226
+ function commandName(token: string): string {
227
+ let t = token;
228
+ if (t.length > 1 && (t[0] === "'" || t[0] === '"') && t[t.length - 1] === t[0]) {
229
+ t = t.slice(1, -1);
230
+ }
231
+ t = t.replace(/\\/g, '');
232
+ return t.split('/').pop() || t;
233
+ }
234
+
235
+ /** Drop leading keywords, wrapper prefixes and inline assignments. */
236
+ function firstCommandName(segment: string): string | null {
237
+ const tokens = segment.trim().split(/\s+/).filter(Boolean);
238
+ for (const raw of tokens) {
239
+ if (ASSIGNMENT.test(raw)) continue;
240
+ const name = commandName(raw);
241
+ if (LEADING_KEYWORDS.has(name) || PREFIXES.has(name)) continue;
242
+ return name;
243
+ }
244
+ return null;
245
+ }
246
+
247
+ /**
248
+ * The refusal text. It names `git -C <path>` and the subshell form, because a
249
+ * refusal that does not say what to do instead gets worked around rather than
250
+ * obeyed — which is how this started as prose and ended as a hook.
251
+ */
252
+ function refusalMessage(segment: string): string {
253
+ return [
254
+ '#992: refusing a top-level `cd`.',
255
+ '',
256
+ `Offending segment: ${segment}`,
257
+ '',
258
+ 'A top-level `cd` moves the SESSION\'s working directory, not just this',
259
+ 'command\'s. Worktree isolation resolves against that directory, so a peer',
260
+ 'agent\'s worktree creation dies hours later with no error naming the cause.',
261
+ '',
262
+ 'Use one of these instead:',
263
+ ' git -C <path> <subcommand> — for anything git, always',
264
+ ' (cd <path> && <command>) — a subshell; the session does not move',
265
+ ' bun --cwd <path> <args> — bun',
266
+ ' make -C <path> / npm --prefix <path>',
267
+ '',
268
+ 'If the session really must move, that is a deliberate decision — say so',
269
+ 'out loud rather than reaching for `cd` by reflex.',
270
+ ].join('\n');
271
+ }
272
+
273
+ /**
274
+ * What the caller is told when the command could not be read at all.
275
+ *
276
+ * A Bash tool call always carries a command string. If one arrives without
277
+ * one, the guard has not examined a command and found it clean — it has
278
+ * examined nothing, and `0`, `{}`, `null` and silence are indistinguishable
279
+ * from success (`.claude/rules/config-access.md`). The previous shape here
280
+ * was `payload.tool_input?.command || ''`, which is that defect exactly: an
281
+ * absent command became an empty one and the guard passed over it.
282
+ */
283
+ function unreadableMessage(command: unknown): string {
284
+ return [
285
+ '#992: refusing a Bash command this guard could not read.',
286
+ '',
287
+ `Received: ${typeof command} ${JSON.stringify(command) ?? String(command)}`,
288
+ '',
289
+ 'This is UNMEASURED, not clean. The guard refuses a top-level `cd`, and it',
290
+ 'cannot tell whether this command carries one, so it refuses rather than',
291
+ 'reporting a pass it did not earn.',
292
+ '',
293
+ 'Re-send the call with a command string. If a Bash call legitimately has',
294
+ 'no command, that is a bug in the caller, not in this guard.',
295
+ ].join('\n');
296
+ }
297
+
298
+ /**
299
+ * Does this command move the session's working directory at the top level?
300
+ *
301
+ * Returns the refusal, or null when the command is clean. THE one decider:
302
+ * every caller — the hook, any future grader — asks this and nothing else.
303
+ *
304
+ * Takes `unknown` deliberately. The hook's input is JSON off a pipe, so the
305
+ * command's type is an assumption until it is checked, and the check belongs
306
+ * with the decision rather than at the call site where a `|| ''` is one
307
+ * keystroke away.
308
+ */
309
+ export function topLevelCdRefusal(command: unknown): CdRefusal | null {
310
+ if (typeof command !== 'string' || command.trim() === '') {
311
+ return { segment: '<unreadable>', message: unreadableMessage(command) };
312
+ }
313
+
314
+ for (const segment of topLevelSegments(stripHeredocBodies(command))) {
315
+ const name = firstCommandName(segment);
316
+ if (name === null) continue;
317
+ if (!SHELL_MOVERS.has(name)) continue;
318
+ const trimmed = segment.trim();
319
+ return { segment: trimmed, message: refusalMessage(trimmed) };
320
+ }
321
+ return null;
322
+ }
323
+
324
+ /**
325
+ * How loudly the guard speaks: the WARN→data→FAIL ladder
326
+ * `specs/harness-automation-matrix.md` prescribes (#992).
327
+ *
328
+ * ## Why a mode exists at all, with the number that decided it
329
+ *
330
+ * The parser is sound: **32.7% of 31,577 unique Bash commands** from this
331
+ * machine's transcript store since 2026-10-14 would be refused, with **zero
332
+ * false positives** — all three deliberate over-refusal classes clean, a
333
+ * 20-command spread hand-read and all 20 genuine, and the 245 `cd`-carrying
334
+ * commands it allows are subshells and heredoc bodies.
335
+ *
336
+ * The issue's original cost model was *"a false refusal costs one retyped
337
+ * command"*. At that rate it costs **10,332 retyped commands**, and a hook
338
+ * refusing a third of all Bash calls is the gets-disabled failure the issue
339
+ * itself warns about two paragraphs below its own recommendation. The
340
+ * premise was corrected on the issue; this is the code catching up to the
341
+ * correction.
342
+ *
343
+ * So `cd` is not an occasional lapse, it is the dominant navigation idiom,
344
+ * and most instances are harmless — a top-level `cd` costs something only in
345
+ * a session with concurrent agents holding worktrees.
346
+ *
347
+ * ## The default is `block`, and that is a decision, not a reading
348
+ *
349
+ * The paragraphs above are the argument for `warn` and they are left intact
350
+ * because they are the honest case against what this now does. **Jason took
351
+ * `block`** (#992), with the 32.7% in hand: the scoping to harnessed
352
+ * projects is the answer to "mis-scoped rather than mis-tuned", and a rung
353
+ * that costs a retype is preferred to one that costs a peer's half-day. The
354
+ * first rung of the ladder exists and was skipped deliberately.
355
+ *
356
+ * `RUNGATE_CD_GUARD=warn` and `=off` are both still reachable, so reversing
357
+ * this needs no code change — which is the property #1040 built the mode for.
358
+ *
359
+ * ## An unrecognised value is not silently a default
360
+ *
361
+ * It resolves to the default rung and the caller is TOLD which value it did
362
+ * not understand. `0`, `{}` and silence being indistinguishable from success
363
+ * is `.claude/rules/config-access.md`, and a typo'd
364
+ * `RUNGATE_CD_GUARD=blcok` degrading quietly is that shape exactly. Note the
365
+ * direction moved with the default: an unreadable value now refuses rather
366
+ * than warns, which is the same "err toward refusal" this module takes
367
+ * everywhere else.
368
+ */
369
+ export type CdGuardMode = "warn" | "block" | "off";
370
+
371
+ /** The env var selecting the rung. Absent means `block` — see above. */
372
+ export const CD_GUARD_MODE_VAR = "RUNGATE_CD_GUARD";
373
+
374
+ /**
375
+ * The rung taken when nothing selects one. Declared once so the decision is
376
+ * a single site a mutation can move, and so `cdGuardMode`'s two default
377
+ * paths — absent value and unrecognised value — cannot drift apart.
378
+ */
379
+ export const CD_GUARD_DEFAULT_MODE: CdGuardMode = "block";
380
+
381
+ export interface CdGuardModeReading {
382
+ mode: CdGuardMode;
383
+ /** Set when the configured value was not recognised, naming it. */
384
+ unrecognised?: string;
385
+ }
386
+
387
+ export function cdGuardMode(env: NodeJS.ProcessEnv = process.env): CdGuardModeReading {
388
+ const raw = env[CD_GUARD_MODE_VAR];
389
+ if (raw === undefined || raw === "") return { mode: CD_GUARD_DEFAULT_MODE };
390
+ const v = raw.trim().toLowerCase();
391
+ if (v === "warn" || v === "block" || v === "off") return { mode: v };
392
+ return { mode: CD_GUARD_DEFAULT_MODE, unrecognised: raw };
393
+ }
@@ -0,0 +1,234 @@
1
+ /**
2
+ * A file that is both tracked and ignored (#471).
3
+ *
4
+ * A `.gitignore` rule written with a trailing slash — `node_modules/` — does
5
+ * not match a **symlink** named `node_modules`. `git add .` therefore tracks
6
+ * it, and what lands in the commit is a mode `120000` blob whose entire
7
+ * content is a machine-absolute path:
8
+ *
9
+ * ```
10
+ * $ git ls-files -s node_modules
11
+ * 120000 b8d92fe8221f2696f298301e01225ec1973e5336 0 node_modules
12
+ * $ git cat-file -p b8d92fe8
13
+ * /Users/<someone>/Projects/<their-project>/node_modules
14
+ * ```
15
+ *
16
+ * Reported from a consumer repo with two such entries against a `.gitignore`
17
+ * that named both correctly. **`git status` was clean throughout**, and that
18
+ * is the whole problem: the rule is right, the mental model is right, and the
19
+ * only thing that reveals the divergence is `git ls-files`.
20
+ *
21
+ * Any worktree-isolated agent that symlinks `node_modules` instead of
22
+ * installing hits this, and the harness is what creates those worktrees.
23
+ *
24
+ * ## The obvious detector does not catch the reported case, measured
25
+ *
26
+ * The shape this was filed as is *fail when `git ls-files` returns a path
27
+ * that `git check-ignore` also matches*. That is a real contradiction and it
28
+ * is the first finding below — but run against the reported case it reports
29
+ * nothing, for the same reason the bug exists:
30
+ *
31
+ * ```
32
+ * $ git check-ignore --no-index -v node_modules
33
+ * $ echo $?
34
+ * 1
35
+ * ```
36
+ *
37
+ * `node_modules/` does not match a symlink named `node_modules`, and
38
+ * `check-ignore` says so just as faithfully as `git add` did. Asking it
39
+ * about a path below the link does not help either — `git check-ignore
40
+ * --no-index node_modules/anything` is `fatal: pathspec ... is beyond a
41
+ * symbolic link`. A detector built only on the agreement between those two
42
+ * commands is narrower than the thing it was written to detect, which is the
43
+ * second shape in `.claude/rules/checks-must-be-able-to-fail.md` arriving in
44
+ * the check rather than in the ignore rule.
45
+ *
46
+ * So there are two findings, and the second is the one that catches #471:
47
+ *
48
+ * 1. **tracked and ignored** — a statement of intent contradicting itself,
49
+ * whatever rule produced it. Catches a `git add -f` of an ignored file.
50
+ * 2. **a tracked symlink pointing at an absolute path** — which needs no
51
+ * ignore rule to be wrong. The blob's content is a path on one machine,
52
+ * so the checkout is broken for everyone else, and no `.gitignore` edit
53
+ * can make it right.
54
+ *
55
+ * ## `--no-index`, and why its absence would be a check that cannot fail
56
+ *
57
+ * `git check-ignore` SKIPS files in the index unless `--no-index` is given.
58
+ * Without it the command is asked about tracked paths and answers about
59
+ * untracked ones, so the comparison is between a list and the empty set and
60
+ * can never report anything. The one flag is the difference between this
61
+ * module and a green line in a report.
62
+ *
63
+ * ## Exit codes, and the fail-open that is one `catch` away
64
+ *
65
+ * `git check-ignore` exits 0 when something matched, **1 when nothing
66
+ * matched**, and 128 on an error. A `try { ... } catch { return [] }` around
67
+ * it reads the error case as the clean case, which is the first shape in
68
+ * `.claude/rules/checks-must-be-able-to-fail.md`. So 1 is a result and
69
+ * anything else is a `failure` the caller must surface.
70
+ *
71
+ * ## It does not read `git status`
72
+ *
73
+ * Asserted by a test, not merely intended. `git status` was clean in the
74
+ * reported case, so a detector that consults it cannot see this at all.
75
+ */
76
+ import { spawnSync } from "child_process";
77
+
78
+ /**
79
+ * Why a tracked path is a finding. A path can be both.
80
+ *
81
+ * `absolute-symlink` deliberately does not mention ignore rules: a committed
82
+ * link to `/Users/<someone>/...` is wrong in a repository that never had a
83
+ * rule about it.
84
+ */
85
+ export type FindingReason = "tracked-and-ignored" | "absolute-symlink" | "unreadable-symlink";
86
+
87
+ /** One tracked path that should not be tracked the way it is. */
88
+ export interface Finding {
89
+ path: string;
90
+ /** The index mode: `100644` a file, `100755` executable, `120000` a symlink. */
91
+ mode: string;
92
+ sha: string;
93
+ /**
94
+ * For a symlink, the blob's content — which IS the link target, and is
95
+ * usually an absolute path that means nothing on another machine. Null for
96
+ * anything else: the path and the mode are the finding there.
97
+ */
98
+ linkTarget: string | null;
99
+ reasons: FindingReason[];
100
+ }
101
+
102
+ export interface TrackedIgnoredReading {
103
+ findings: Finding[];
104
+ /**
105
+ * How many tracked paths were compared. An empty corpus and a clean one
106
+ * give the same verdict, and only this tells them apart.
107
+ */
108
+ trackedCount: number;
109
+ /**
110
+ * Non-null when the comparison could not be made. Never conflated with
111
+ * "nothing found": that conflation is the defect this module is about,
112
+ * arriving in the detector instead of in the ignore rule.
113
+ */
114
+ failure: string | null;
115
+ }
116
+
117
+ function run(root: string, args: string[], input?: string): { status: number; stdout: string; stderr: string } {
118
+ const r = spawnSync("git", args, {
119
+ cwd: root,
120
+ input,
121
+ encoding: "utf-8",
122
+ timeout: 120_000,
123
+ maxBuffer: 64 * 1024 * 1024,
124
+ });
125
+ if (r.error) return { status: -1, stdout: "", stderr: r.error.message };
126
+ return { status: r.status ?? -1, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
127
+ }
128
+
129
+ /** `<mode> <sha> <stage>\t<path>` per NUL-separated record. */
130
+ function parseLsFiles(out: string): Array<{ mode: string; sha: string; path: string }> {
131
+ const entries: Array<{ mode: string; sha: string; path: string }> = [];
132
+ for (const record of out.split("\0")) {
133
+ if (record === "") continue;
134
+ const tab = record.indexOf("\t");
135
+ if (tab === -1) continue;
136
+ const [mode, sha] = record.slice(0, tab).split(/\s+/);
137
+ if (!mode || !sha) continue;
138
+ entries.push({ mode, sha, path: record.slice(tab + 1) });
139
+ }
140
+ return entries;
141
+ }
142
+
143
+ /**
144
+ * Every tracked path this repository's ignore rules also match.
145
+ *
146
+ * `root` must be inside a git repository; anything else is a `failure`
147
+ * rather than an empty result.
148
+ */
149
+ export function trackedAndIgnored(root: string): TrackedIgnoredReading {
150
+ const listed = run(root, ["ls-files", "-s", "-z"]);
151
+ if (listed.status !== 0) {
152
+ return {
153
+ findings: [],
154
+ trackedCount: 0,
155
+ failure: `git ls-files failed (${listed.status}): ${listed.stderr.trim() || "no output"}`,
156
+ };
157
+ }
158
+ const tracked = parseLsFiles(listed.stdout);
159
+ if (tracked.length === 0) {
160
+ return { findings: [], trackedCount: 0, failure: null };
161
+ }
162
+
163
+ // `--no-index` or this asks about the wrong set. `--stdin -z` because a
164
+ // path may contain anything, including a newline.
165
+ const checked = run(
166
+ root,
167
+ ["check-ignore", "--no-index", "--stdin", "-z"],
168
+ tracked.map(t => t.path).join("\0") + "\0",
169
+ );
170
+ // 0: at least one matched. 1: none did, which is the clean answer and not
171
+ // an error. Anything else is an error, and reporting it as clean is the
172
+ // fail-open this whole module exists to be the opposite of.
173
+ if (checked.status !== 0 && checked.status !== 1) {
174
+ return {
175
+ findings: [],
176
+ trackedCount: tracked.length,
177
+ failure: `git check-ignore failed (${checked.status}): ${checked.stderr.trim() || "no output"}`,
178
+ };
179
+ }
180
+
181
+ const matched = new Set(checked.stdout.split("\0").filter(p => p !== ""));
182
+ const findings: Finding[] = [];
183
+ for (const entry of tracked) {
184
+ const reasons: FindingReason[] = [];
185
+ if (matched.has(entry.path)) reasons.push("tracked-and-ignored");
186
+
187
+ let linkTarget: string | null = null;
188
+ if (entry.mode === "120000") {
189
+ // The blob of a symlink IS its target. `node_modules` tracked as a
190
+ // directory of files is wasteful; `node_modules` tracked as a link to
191
+ // an absolute path is what breaks on another machine, and the mode is
192
+ // the only thing that tells the two apart.
193
+ const blob = run(root, ["cat-file", "-p", entry.sha]);
194
+ linkTarget = blob.status === 0 ? blob.stdout.trim() : null;
195
+ if (linkTarget === null) {
196
+ // A link whose target could not be read is a finding, not a pass.
197
+ // Treating it as "no target, therefore not absolute" would make a
198
+ // broken `cat-file` the cheapest way to clear this check — the
199
+ // fail-open this module's own docstring warns about, one branch
200
+ // below where it warns about it. Found by security review.
201
+ reasons.push("unreadable-symlink");
202
+ } else if (linkTarget.startsWith("/")) {
203
+ // A relative link is a repository making a statement about itself
204
+ // and is portable. An absolute one is a statement about one
205
+ // filesystem.
206
+ reasons.push("absolute-symlink");
207
+ }
208
+ }
209
+
210
+ if (reasons.length > 0) {
211
+ findings.push({ path: entry.path, mode: entry.mode, sha: entry.sha, linkTarget, reasons });
212
+ }
213
+ }
214
+ return { findings, trackedCount: tracked.length, failure: null };
215
+ }
216
+
217
+ /** The refusal text, naming the mode and — for a link — where it points. */
218
+ export function describeFindings(reading: TrackedIgnoredReading): string[] {
219
+ if (reading.failure !== null) return [`UNMEASURED: ${reading.failure}`];
220
+ return reading.findings.map(f => {
221
+ const kind = f.mode === "120000" ? "symlink" : `mode ${f.mode}`;
222
+ const target = f.linkTarget !== null ? ` -> ${f.linkTarget}` : "";
223
+ const why = f.reasons
224
+ .map(r => {
225
+ if (r === "tracked-and-ignored") return "matched by this repository's own ignore rules";
226
+ if (r === "absolute-symlink") {
227
+ return "a link to an absolute path, which resolves to nothing on another machine";
228
+ }
229
+ return "UNMEASURED: a link whose target could not be read, so it cannot be judged";
230
+ })
231
+ .join("; ");
232
+ return `${f.path} is tracked (${kind}${target}): ${why}`;
233
+ });
234
+ }