rungate 0.5.0 → 0.6.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.
- package/lib/agents-md-sections.ts +144 -0
- package/lib/branch-diff.ts +139 -0
- package/lib/bun-version.ts +268 -0
- package/lib/ci-checkout.ts +1 -1
- package/lib/compliance.ts +13 -11
- package/lib/config-loader.ts +12 -0
- package/lib/conformity.ts +184 -88
- package/lib/context-docs.ts +143 -28
- package/lib/create-brief.ts +2 -1
- package/lib/create-sc.ts +90 -4
- package/lib/doc-scan-targets.ts +9 -0
- package/lib/evidence-command-transport.ts +160 -0
- package/lib/evidence-prevalidator.ts +22 -0
- package/lib/fallow-availability.ts +129 -0
- package/lib/gate-refusal-currency.ts +112 -0
- package/lib/gate-timeouts.ts +82 -0
- package/lib/generators/agent-briefs.ts +4 -1
- package/lib/generators/agents-md.ts +71 -23
- package/lib/generators/code-map.ts +2 -1
- package/lib/generators/types.ts +8 -0
- package/lib/git-dates.ts +55 -0
- package/lib/junit-checks.ts +484 -0
- package/lib/local-calendar-day.ts +78 -0
- package/lib/project-state-shape.ts +59 -0
- package/lib/promote-outputs.ts +6 -2
- package/lib/report-provenance.ts +156 -0
- package/lib/sc-claim-forms.ts +75 -0
- package/lib/sc-id-cross-tree.ts +311 -0
- package/lib/scaffold/ai-review-step.ts +180 -0
- package/lib/scaffold/owned-files.ts +42 -2
- package/lib/scaffold/rehearsal.ts +205 -71
- package/lib/scaffold/steps.ts +128 -73
- package/lib/scaffold/write-steps.ts +6 -4
- package/lib/scanner.ts +38 -12
- package/lib/spec-listing.ts +148 -0
- package/lib/spec-requirements.ts +209 -0
- package/lib/suite-run-reading.ts +170 -0
- package/lib/test-command.ts +133 -0
- package/lib/test-suite-lock.ts +166 -10
- package/lib/tool-probe.ts +120 -0
- package/lib/tracked-vs-ignored.ts +234 -0
- package/lib/validators/spec-validators.ts +3 -2
- package/package.json +1 -1
- package/scripts/audit-specs.ts +247 -12
- package/scripts/audit-transcript.ts +2 -1
- package/scripts/convert-spec.ts +2 -1
- package/scripts/create-sc.ts +17 -7
- package/scripts/create-spec.ts +2 -1
- package/scripts/create-success.ts +2 -1
- package/scripts/extract-constraints.ts +90 -19
- package/scripts/generate-code-map.ts +53 -12
- package/scripts/scaffold-project.ts +4 -1
- package/scripts/split-spec.ts +2 -1
- package/scripts/sync-sc-status.ts +57 -5
- package/scripts/sync-spec-tests.ts +2 -1
package/lib/test-suite-lock.ts
CHANGED
|
@@ -26,6 +26,7 @@ import {
|
|
|
26
26
|
mkdirSync,
|
|
27
27
|
openSync,
|
|
28
28
|
readFileSync,
|
|
29
|
+
realpathSync,
|
|
29
30
|
renameSync,
|
|
30
31
|
statSync,
|
|
31
32
|
unlinkSync,
|
|
@@ -708,6 +709,13 @@ export function acquireFullSuiteSlot(
|
|
|
708
709
|
|
|
709
710
|
export interface GateDecision {
|
|
710
711
|
allow: boolean;
|
|
712
|
+
/**
|
|
713
|
+
* Present when the run was allowed because it is not a run of THIS
|
|
714
|
+
* repository (#510). Allowed-and-quiet would make an exemption
|
|
715
|
+
* indistinguishable from a budget that was never spent, so it is named
|
|
716
|
+
* here and recorded on disk.
|
|
717
|
+
*/
|
|
718
|
+
exempt?: string;
|
|
711
719
|
/** Present when refused — shown verbatim to the caller. Never silent. */
|
|
712
720
|
reason?: string;
|
|
713
721
|
/**
|
|
@@ -860,6 +868,117 @@ export interface GateOptions extends LockOptions {
|
|
|
860
868
|
runId?: string;
|
|
861
869
|
/** Overrides the per-run ceiling. Tests only; there is no environment path. */
|
|
862
870
|
maxRunsPerPipeline?: number;
|
|
871
|
+
/**
|
|
872
|
+
* The working directory the command will run in (#510). Used to decide
|
|
873
|
+
* whether this is a run of the guarded repository or of a scratch tree
|
|
874
|
+
* somewhere else. Absent means UNKNOWN, which is charged — the budget
|
|
875
|
+
* fails closed, as the rest of this module does.
|
|
876
|
+
*/
|
|
877
|
+
cwd?: string;
|
|
878
|
+
/** Injected scope, so a test need not build a git repository to drive it. */
|
|
879
|
+
scope?: RunScope;
|
|
880
|
+
}
|
|
881
|
+
|
|
882
|
+
/**
|
|
883
|
+
* Whose suite this is.
|
|
884
|
+
*
|
|
885
|
+
* - `project` — a tree of the repository this guard belongs to, including
|
|
886
|
+
* every one of its worktrees. Charged.
|
|
887
|
+
* - `scratch` — a directory that EXISTS and is not part of it: a `git
|
|
888
|
+
* archive` export under /tmp, a fixture repo a test just created, another
|
|
889
|
+
* checkout entirely. Not charged.
|
|
890
|
+
* - `unknown` — the question could not be answered: no cwd, a path that is
|
|
891
|
+
* not there, a git that would not run. Charged, because a guard that opens
|
|
892
|
+
* on an error is the shape this repo keeps finding.
|
|
893
|
+
*
|
|
894
|
+
* The line between the last two is "I looked and it is not this repository"
|
|
895
|
+
* against "I could not look". A `git archive` export has no `.git` and is
|
|
896
|
+
* the case that filed #510, so a git-less directory must be scratch — but
|
|
897
|
+
* only once something has confirmed the directory is really there.
|
|
898
|
+
*/
|
|
899
|
+
export type RunScope = "project" | "scratch" | "unknown";
|
|
900
|
+
|
|
901
|
+
/** The guarded repository's shared git directory, resolved once. */
|
|
902
|
+
function projectCommonDir(): string | null {
|
|
903
|
+
try {
|
|
904
|
+
const out = execFileSync("git", ["rev-parse", "--path-format=absolute", "--git-common-dir"], {
|
|
905
|
+
cwd: join(import.meta.dir, ".."),
|
|
906
|
+
encoding: "utf-8",
|
|
907
|
+
timeout: 10_000,
|
|
908
|
+
stdio: ["ignore", "pipe", "pipe"],
|
|
909
|
+
});
|
|
910
|
+
return realpathSync(out.trim());
|
|
911
|
+
} catch {
|
|
912
|
+
return null;
|
|
913
|
+
}
|
|
914
|
+
}
|
|
915
|
+
|
|
916
|
+
/**
|
|
917
|
+
* Is this working directory part of the repository the guard is installed in?
|
|
918
|
+
*
|
|
919
|
+
* The comparison is the **shared git directory**, not the path: all 110
|
|
920
|
+
* worktrees of this repository answer with one `.git`, and they are all real
|
|
921
|
+
* runs that must be charged. A `git archive` export has no `.git` at all, and
|
|
922
|
+
* a fixture built by `git init` has its own — both scratch.
|
|
923
|
+
*
|
|
924
|
+
* ## Why this is not a /tmp denylist
|
|
925
|
+
*
|
|
926
|
+
* A path prefix is a detector narrower than what it detects: a reviewer's
|
|
927
|
+
* probe under `~/scratch` would be charged, and a real checkout under /tmp
|
|
928
|
+
* would be exempt. The question is "whose suite is this", and git already
|
|
929
|
+
* answers it exactly.
|
|
930
|
+
*/
|
|
931
|
+
export function runScope(cwd: string | undefined, projectDir?: string | null): RunScope {
|
|
932
|
+
if (!cwd) return "unknown";
|
|
933
|
+
try {
|
|
934
|
+
if (!statSync(cwd).isDirectory()) return "unknown";
|
|
935
|
+
} catch {
|
|
936
|
+
return "unknown";
|
|
937
|
+
}
|
|
938
|
+
const project = projectDir === undefined ? projectCommonDir() : projectDir;
|
|
939
|
+
if (project === null) return "unknown";
|
|
940
|
+
try {
|
|
941
|
+
const out = execFileSync("git", ["rev-parse", "--path-format=absolute", "--git-common-dir"], {
|
|
942
|
+
cwd,
|
|
943
|
+
encoding: "utf-8",
|
|
944
|
+
timeout: 10_000,
|
|
945
|
+
stdio: ["ignore", "pipe", "pipe"],
|
|
946
|
+
});
|
|
947
|
+
return realpathSync(out.trim()) === project ? "project" : "scratch";
|
|
948
|
+
} catch {
|
|
949
|
+
// The directory is there and git will not claim it: not a repository at
|
|
950
|
+
// all, which is what a `git archive` export is. Not a run of the guarded
|
|
951
|
+
// project, and charging it is the thing #510 is about.
|
|
952
|
+
return "scratch";
|
|
953
|
+
}
|
|
954
|
+
}
|
|
955
|
+
|
|
956
|
+
/** Where exempted runs are recorded, so the exemption is auditable. */
|
|
957
|
+
export function scratchRunsPath(lockDir: string): string {
|
|
958
|
+
return join(lockDir, "full-suite.scratch-runs.json");
|
|
959
|
+
}
|
|
960
|
+
|
|
961
|
+
/**
|
|
962
|
+
* Record an exempted run. Best-effort, like the budget counter — but it is
|
|
963
|
+
* the only trace an exemption leaves, so losing it costs visibility rather
|
|
964
|
+
* than enforcement.
|
|
965
|
+
*/
|
|
966
|
+
function recordScratchRun(lockDir: string, now: number, cwd: string | undefined): void {
|
|
967
|
+
try {
|
|
968
|
+
const path = scratchRunsPath(lockDir);
|
|
969
|
+
let runs: Array<{ at: number; cwd: string }> = [];
|
|
970
|
+
try {
|
|
971
|
+
const parsed = JSON.parse(readFileSync(path, "utf-8"));
|
|
972
|
+
if (Array.isArray(parsed?.runs)) runs = parsed.runs;
|
|
973
|
+
} catch {
|
|
974
|
+
// An unreadable or absent log starts a new one. This file is a record,
|
|
975
|
+
// never an input to a decision, so a lost entry cannot open a gate.
|
|
976
|
+
}
|
|
977
|
+
runs.push({ at: now, cwd: cwd ?? "" });
|
|
978
|
+
writeFileSync(path, JSON.stringify({ runs: runs.slice(-200) }));
|
|
979
|
+
} catch {
|
|
980
|
+
// Recording must never be able to block a run it is not guarding.
|
|
981
|
+
}
|
|
863
982
|
}
|
|
864
983
|
|
|
865
984
|
interface BudgetView {
|
|
@@ -1045,19 +1164,53 @@ export function evaluateFullSuiteRequest(
|
|
|
1045
1164
|
command: string,
|
|
1046
1165
|
options: GateOptions = {},
|
|
1047
1166
|
): GateDecision {
|
|
1048
|
-
|
|
1049
|
-
|
|
1050
|
-
//
|
|
1167
|
+
// Targeted runs are neither capped nor counted, so there is nothing to
|
|
1168
|
+
// spend. Asked FIRST, because the scope question below costs a subprocess
|
|
1169
|
+
// and the overwhelming majority of Bash commands are not suites at all.
|
|
1051
1170
|
if (!isFullSuiteCommand(command)) return { allow: true };
|
|
1052
1171
|
|
|
1053
1172
|
const lockDir = options.lockDir ?? defaultLockDir();
|
|
1054
1173
|
const now = options.now ?? Date.now();
|
|
1055
1174
|
|
|
1175
|
+
// A full suite of somebody else's tree is not this repository's suite
|
|
1176
|
+
// (#510). A reviewer's mutation probe on a `git archive` export is twenty
|
|
1177
|
+
// tests and under a second, and charging it against a budget sized for a
|
|
1178
|
+
// 400-second 12,000-test run made careful review the thing the guard
|
|
1179
|
+
// rationed. Scope is decided here and only here: `wouldAllowFullSuite`
|
|
1180
|
+
// below must not answer the same question, or there would be two deciders
|
|
1181
|
+
// and no behavioural test could tell them apart.
|
|
1182
|
+
//
|
|
1183
|
+
// It exempts the BUDGET and not the concurrency slot, and the distinction
|
|
1184
|
+
// is the whole of the design. The budget is a rate — the wrong unit for a
|
|
1185
|
+
// one-second probe. The slot is simultaneity, which is what rebooted the
|
|
1186
|
+
// machine in #67, and a scratch tree can be a full clone. Two further
|
|
1187
|
+
// reasons it must not skip the slot: `TestSuiteRelease` releases on the
|
|
1188
|
+
// same `isFullSuiteCommand` predicate with no notion of scope, so an
|
|
1189
|
+
// acquire this side skipped would free a slot somebody else is holding;
|
|
1190
|
+
// and "cd into /tmp to escape the cap" would be a bypass anyone could
|
|
1191
|
+
// reach for.
|
|
1192
|
+
const scope = options.scope ?? runScope(options.cwd);
|
|
1193
|
+
|
|
1194
|
+
const predicted = scope === "scratch" ? { allow: true } : wouldAllowFullSuite(sessionId, command, options);
|
|
1195
|
+
if (!predicted.allow) return predicted;
|
|
1196
|
+
|
|
1056
1197
|
// The prediction above is advisory; this is the atomic claim. Another session
|
|
1057
1198
|
// can take the last slot in between, and then the acquirer's answer wins.
|
|
1058
1199
|
const slot = acquireFullSuiteSlot(sessionId, options);
|
|
1059
1200
|
if (!slot.ok) return concurrencyRefusal(sessionId, slot.holders ?? []);
|
|
1060
1201
|
|
|
1202
|
+
if (scope === "scratch") {
|
|
1203
|
+
recordScratchRun(lockDir, now, options.cwd);
|
|
1204
|
+
return {
|
|
1205
|
+
allow: true,
|
|
1206
|
+
exempt:
|
|
1207
|
+
`not a run of this repository (${options.cwd ?? "unknown cwd"}), so it is not charged ` +
|
|
1208
|
+
`against DIR-L29 — recorded in ${scratchRunsPath(lockDir)}. It still holds a ` +
|
|
1209
|
+
`concurrency slot, which is what the cap is actually for.`,
|
|
1210
|
+
...(slot.degraded ? { warning: degradedWarning(lockDir) } : {}),
|
|
1211
|
+
};
|
|
1212
|
+
}
|
|
1213
|
+
|
|
1061
1214
|
try {
|
|
1062
1215
|
// Only the in-window runs are carried forward, and never more than the
|
|
1063
1216
|
// tracked maximum, so neither a long session nor a poisoned file can leave
|
|
@@ -1078,17 +1231,20 @@ export function evaluateFullSuiteRequest(
|
|
|
1078
1231
|
}
|
|
1079
1232
|
|
|
1080
1233
|
if (slot.degraded) {
|
|
1081
|
-
return {
|
|
1082
|
-
allow: true,
|
|
1083
|
-
warning:
|
|
1084
|
-
`Concurrency guard DEGRADED — lock directory ${lockDir} is unusable, so this run ` +
|
|
1085
|
-
`was allowed without taking a slot. The cap is not being enforced right now. ` +
|
|
1086
|
-
`Check with other sessions before starting a full suite.`,
|
|
1087
|
-
};
|
|
1234
|
+
return { allow: true, warning: degradedWarning(lockDir) };
|
|
1088
1235
|
}
|
|
1089
1236
|
return { allow: true };
|
|
1090
1237
|
}
|
|
1091
1238
|
|
|
1239
|
+
/** One wording for the degraded case, so the two exits cannot drift apart. */
|
|
1240
|
+
function degradedWarning(lockDir: string): string {
|
|
1241
|
+
return (
|
|
1242
|
+
`Concurrency guard DEGRADED — lock directory ${lockDir} is unusable, so this run ` +
|
|
1243
|
+
`was allowed without taking a slot. The cap is not being enforced right now. ` +
|
|
1244
|
+
`Check with other sessions before starting a full suite.`
|
|
1245
|
+
);
|
|
1246
|
+
}
|
|
1247
|
+
|
|
1092
1248
|
/**
|
|
1093
1249
|
* Give up ONE slot for a finished suite. Releasing one you do not hold is a no-op.
|
|
1094
1250
|
*
|
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Asking whether an external tool is there, with three answers instead of one
|
|
3
|
+
* (#626 AC-10, #597).
|
|
4
|
+
*
|
|
5
|
+
* `lib/compliance.ts` asked it with a boolean:
|
|
6
|
+
*
|
|
7
|
+
* function checkToolAvailable(command, args): boolean {
|
|
8
|
+
* try {
|
|
9
|
+
* const result = Bun.spawnSync([command, ...args], { timeout: 5_000 });
|
|
10
|
+
* return result.exitCode === 0 || result.stdout.toString().length > 0;
|
|
11
|
+
* } catch { return false; }
|
|
12
|
+
* }
|
|
13
|
+
*
|
|
14
|
+
* `false` meant "the tool is not installed", "the tool is installed and the
|
|
15
|
+
* probe failed", and "npx went to the registry and the registry was slow"
|
|
16
|
+
* alike. That is the fail-open shape `.claude/rules/checks-must-be-able-to-fail.md`
|
|
17
|
+
* opens with, in the place it costs the most: three Layer 1 compliance tests
|
|
18
|
+
* go red or green in CI depending on whether `npx @reporails/cli version`
|
|
19
|
+
* reaches the network, and the verdict cannot say which of the three happened
|
|
20
|
+
* — proven on #597 by re-running an identical SHA red to green with no code
|
|
21
|
+
* change.
|
|
22
|
+
*
|
|
23
|
+
* So the probe has three outcomes and a `reason`, and the boolean every
|
|
24
|
+
* existing caller wants is derived from the outcome rather than being the
|
|
25
|
+
* whole reading. A consumer that only needs "can I run this" keeps working;
|
|
26
|
+
* a consumer that needs to report UNMEASURED now has something to report it
|
|
27
|
+
* from.
|
|
28
|
+
*
|
|
29
|
+
* ## Why `absent` is decided by the spawn failing, not by an exit code
|
|
30
|
+
*
|
|
31
|
+
* A tool that is not on `PATH` makes `Bun.spawnSync` throw before any process
|
|
32
|
+
* exists; a tool that is there and unhappy exits non-zero. Those are the two
|
|
33
|
+
* facts, and they arrive by two different routes, which is what makes the
|
|
34
|
+
* distinction honest rather than a reading of an exit code nobody standardised.
|
|
35
|
+
*
|
|
36
|
+
* `npx <pkg> version` is the awkward case and is deliberately NOT special-cased:
|
|
37
|
+
* `npx` is always present, so an uninstalled package surfaces as `errored`, not
|
|
38
|
+
* `absent`. That is the truth about what was observed — the probe ran and did
|
|
39
|
+
* not succeed — and inventing `absent` from a parse of npx's stderr would be a
|
|
40
|
+
* detector narrower than what it detects.
|
|
41
|
+
*/
|
|
42
|
+
|
|
43
|
+
/** The three things a probe can find. Ordered as they are reported. */
|
|
44
|
+
export const TOOL_PROBE_OUTCOMES = ["available", "absent", "errored"] as const;
|
|
45
|
+
|
|
46
|
+
export type ToolProbeOutcome = (typeof TOOL_PROBE_OUTCOMES)[number];
|
|
47
|
+
|
|
48
|
+
export interface ToolProbe {
|
|
49
|
+
outcome: ToolProbeOutcome;
|
|
50
|
+
/**
|
|
51
|
+
* The old boolean, derived. Present so a caller that genuinely only needs
|
|
52
|
+
* "can I run this" does not have to re-derive it — and so the collapse is
|
|
53
|
+
* visible as a projection of the reading rather than as the reading itself.
|
|
54
|
+
*/
|
|
55
|
+
available: boolean;
|
|
56
|
+
/** The command probed, as it was asked for. */
|
|
57
|
+
tool: string;
|
|
58
|
+
/** The exit code, or null when no process ever existed. */
|
|
59
|
+
exitCode: number | null;
|
|
60
|
+
/** One line a log reader can act on. */
|
|
61
|
+
reason: string;
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
export interface ToolProbeOptions {
|
|
65
|
+
timeoutMs?: number;
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/** The probe's own budget. A tool that cannot answer in five seconds is not ready to be used in a gate. */
|
|
69
|
+
export const TOOL_PROBE_TIMEOUT_MS = 5_000;
|
|
70
|
+
|
|
71
|
+
export function probeExternalTool(command: string, args: string[] = [], opts?: ToolProbeOptions): ToolProbe {
|
|
72
|
+
const tool = [command, ...args].join(" ");
|
|
73
|
+
let exitCode: number | null = null;
|
|
74
|
+
let stdout = "";
|
|
75
|
+
let stderr = "";
|
|
76
|
+
|
|
77
|
+
try {
|
|
78
|
+
const result = Bun.spawnSync([command, ...args], {
|
|
79
|
+
timeout: opts?.timeoutMs ?? TOOL_PROBE_TIMEOUT_MS,
|
|
80
|
+
stdout: "pipe",
|
|
81
|
+
stderr: "pipe",
|
|
82
|
+
});
|
|
83
|
+
exitCode = typeof result.exitCode === "number" ? result.exitCode : null;
|
|
84
|
+
stdout = result.stdout?.toString() ?? "";
|
|
85
|
+
stderr = result.stderr?.toString() ?? "";
|
|
86
|
+
} catch (e) {
|
|
87
|
+
// No process was created at all. That is the one condition that means the
|
|
88
|
+
// tool is not here, and it is why this branch is not merged with a
|
|
89
|
+
// non-zero exit below.
|
|
90
|
+
const message = e instanceof Error ? e.message : String(e);
|
|
91
|
+
return {
|
|
92
|
+
outcome: "absent",
|
|
93
|
+
available: false,
|
|
94
|
+
tool,
|
|
95
|
+
exitCode: null,
|
|
96
|
+
reason: `${command} is not on PATH: ${message.split("\n")[0]}`,
|
|
97
|
+
};
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
if (exitCode === 0 || stdout.trim().length > 0) {
|
|
101
|
+
return {
|
|
102
|
+
outcome: "available",
|
|
103
|
+
available: true,
|
|
104
|
+
tool,
|
|
105
|
+
exitCode,
|
|
106
|
+
reason: `${tool} ran and answered (exit ${exitCode})`,
|
|
107
|
+
};
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
return {
|
|
111
|
+
outcome: "errored",
|
|
112
|
+
available: false,
|
|
113
|
+
tool,
|
|
114
|
+
exitCode,
|
|
115
|
+
reason:
|
|
116
|
+
`${tool} ran and did not succeed (exit ${exitCode})` +
|
|
117
|
+
(stderr.trim() ? `: ${stderr.trim().split("\n")[0].slice(0, 200)}` : "") +
|
|
118
|
+
` — the tool was reachable, so this is not the same as it being absent`,
|
|
119
|
+
};
|
|
120
|
+
}
|
|
@@ -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
|
+
}
|
|
@@ -6,6 +6,7 @@
|
|
|
6
6
|
*/
|
|
7
7
|
import { existsSync, readFileSync, writeFileSync, readdirSync } from "fs";
|
|
8
8
|
import { join } from "path";
|
|
9
|
+
import { localCalendarDay } from "../local-calendar-day";
|
|
9
10
|
|
|
10
11
|
/**
|
|
11
12
|
* SC-278: Detect specs that exceed 500 lines and suggest splitting.
|
|
@@ -54,7 +55,7 @@ export function checkGovernsAlignment(specsDir: string, actions: string[]): void
|
|
|
54
55
|
export function addFrontmatterToSpecs(specsDir: string, actions: string[]): void {
|
|
55
56
|
if (!existsSync(specsDir)) return;
|
|
56
57
|
|
|
57
|
-
const today =
|
|
58
|
+
const today = localCalendarDay();
|
|
58
59
|
|
|
59
60
|
for (const file of readdirSync(specsDir).filter(f => f.endsWith(".md"))) {
|
|
60
61
|
const filePath = join(specsDir, file);
|
|
@@ -133,7 +134,7 @@ export function detectUnconvertedSpecs(specsDir: string, actions: string[]): voi
|
|
|
133
134
|
export function addFrontmatterToAdrs(adrDir: string, actions: string[]): void {
|
|
134
135
|
if (!existsSync(adrDir)) return;
|
|
135
136
|
|
|
136
|
-
const today =
|
|
137
|
+
const today = localCalendarDay();
|
|
137
138
|
|
|
138
139
|
for (const file of readdirSync(adrDir).filter(f => f.endsWith(".md"))) {
|
|
139
140
|
const filePath = join(adrDir, file);
|