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.
Files changed (55) hide show
  1. package/lib/agents-md-sections.ts +144 -0
  2. package/lib/branch-diff.ts +139 -0
  3. package/lib/bun-version.ts +268 -0
  4. package/lib/ci-checkout.ts +1 -1
  5. package/lib/compliance.ts +13 -11
  6. package/lib/config-loader.ts +12 -0
  7. package/lib/conformity.ts +184 -88
  8. package/lib/context-docs.ts +143 -28
  9. package/lib/create-brief.ts +2 -1
  10. package/lib/create-sc.ts +90 -4
  11. package/lib/doc-scan-targets.ts +9 -0
  12. package/lib/evidence-command-transport.ts +160 -0
  13. package/lib/evidence-prevalidator.ts +22 -0
  14. package/lib/fallow-availability.ts +129 -0
  15. package/lib/gate-refusal-currency.ts +112 -0
  16. package/lib/gate-timeouts.ts +82 -0
  17. package/lib/generators/agent-briefs.ts +4 -1
  18. package/lib/generators/agents-md.ts +71 -23
  19. package/lib/generators/code-map.ts +2 -1
  20. package/lib/generators/types.ts +8 -0
  21. package/lib/git-dates.ts +55 -0
  22. package/lib/junit-checks.ts +484 -0
  23. package/lib/local-calendar-day.ts +78 -0
  24. package/lib/project-state-shape.ts +59 -0
  25. package/lib/promote-outputs.ts +6 -2
  26. package/lib/report-provenance.ts +156 -0
  27. package/lib/sc-claim-forms.ts +75 -0
  28. package/lib/sc-id-cross-tree.ts +311 -0
  29. package/lib/scaffold/ai-review-step.ts +180 -0
  30. package/lib/scaffold/owned-files.ts +42 -2
  31. package/lib/scaffold/rehearsal.ts +205 -71
  32. package/lib/scaffold/steps.ts +128 -73
  33. package/lib/scaffold/write-steps.ts +6 -4
  34. package/lib/scanner.ts +38 -12
  35. package/lib/spec-listing.ts +148 -0
  36. package/lib/spec-requirements.ts +209 -0
  37. package/lib/suite-run-reading.ts +170 -0
  38. package/lib/test-command.ts +133 -0
  39. package/lib/test-suite-lock.ts +166 -10
  40. package/lib/tool-probe.ts +120 -0
  41. package/lib/tracked-vs-ignored.ts +234 -0
  42. package/lib/validators/spec-validators.ts +3 -2
  43. package/package.json +1 -1
  44. package/scripts/audit-specs.ts +247 -12
  45. package/scripts/audit-transcript.ts +2 -1
  46. package/scripts/convert-spec.ts +2 -1
  47. package/scripts/create-sc.ts +17 -7
  48. package/scripts/create-spec.ts +2 -1
  49. package/scripts/create-success.ts +2 -1
  50. package/scripts/extract-constraints.ts +90 -19
  51. package/scripts/generate-code-map.ts +53 -12
  52. package/scripts/scaffold-project.ts +4 -1
  53. package/scripts/split-spec.ts +2 -1
  54. package/scripts/sync-sc-status.ts +57 -5
  55. package/scripts/sync-spec-tests.ts +2 -1
@@ -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
- const predicted = wouldAllowFullSuite(sessionId, command, options);
1049
- if (!predicted.allow) return predicted;
1050
- // Targeted runs are neither capped nor counted, so there is nothing to spend.
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 = new Date().toISOString().split("T")[0];
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 = new Date().toISOString().split("T")[0];
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);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "rungate",
3
- "version": "0.5.0",
3
+ "version": "0.6.0",
4
4
  "type": "module",
5
5
  "description": "Ship harness — conformity tests, scaffold, and agent briefs for AI-first development",
6
6
  "repository": {