rungate 0.4.1 → 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/config/behavioral-sc-map.json +170 -0
- package/config/brief-policies.json +28 -0
- package/config/ceremony-profiles.json +207 -0
- package/config/check-registry.json +114 -0
- package/config/matcher-registry.json +142 -0
- package/config/prove-evidence.schema.json +65 -0
- package/config/spec-policies.json +36 -0
- package/config/universal-rules.yaml +15 -0
- package/config/workflow-schema.json +279 -0
- 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/cli-commands.ts +7 -1
- package/lib/compliance.ts +13 -11
- package/lib/config-loader.ts +12 -0
- package/lib/conformity.ts +1147 -116
- 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/github.ts +195 -0
- package/lib/js-top-level-code.ts +27 -2
- package/lib/junit-checks.ts +484 -0
- package/lib/local-calendar-day.ts +78 -0
- package/lib/package-closure.ts +278 -2
- package/lib/project-state-shape.ts +59 -0
- package/lib/promote-outputs.ts +6 -2
- package/lib/release-preflight.ts +196 -0
- 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/defaults.ts +40 -0
- package/lib/scaffold/managed-workflow.ts +125 -27
- package/lib/scaffold/owned-files.ts +48 -2
- package/lib/scaffold/profiles.ts +94 -0
- package/lib/scaffold/rehearsal.ts +232 -73
- package/lib/scaffold/steps.ts +777 -152
- package/lib/scaffold/write-steps.ts +56 -13
- package/lib/scanner.ts +38 -12
- package/lib/source-anchor.ts +144 -0
- package/lib/spec-listing.ts +148 -0
- package/lib/spec-requirements.ts +209 -0
- package/lib/success-doc.ts +779 -0
- package/lib/suite-run-reading.ts +364 -0
- package/lib/test-census.ts +199 -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/trajectory.ts +377 -0
- package/lib/validators/spec-validators.ts +35 -6
- package/lib/workflow-security.ts +101 -0
- package/lib/workflow-test-harness.ts +349 -0
- package/package.json +6 -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 +163 -0
- package/scripts/extract-constraints.ts +90 -19
- package/scripts/generate-code-map.ts +53 -12
- package/scripts/scaffold-project.ts +31 -4
- package/scripts/split-spec.ts +2 -1
- package/scripts/sync-sc-status.ts +57 -5
- package/scripts/sync-spec-tests.ts +2 -1
- package/specs/SPEC-TEMPLATE.md +200 -0
- package/templates/SUCCESS-TEMPLATE.md +72 -0
- package/templates/agent-briefs/_shared.md +9 -0
- package/templates/agent-briefs/aditi.md +46 -0
- package/templates/agent-briefs/discovery.md +37 -0
- package/templates/agent-briefs/marcus.md +39 -0
- package/templates/agent-briefs/quinn.md +67 -0
- package/templates/agent-briefs/rook.md +40 -0
- package/templates/agent-briefs/serena.md +39 -0
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The one test command for a project (#488).
|
|
3
|
+
*
|
|
4
|
+
* The scaffold read `dev.testCmd` in four places and wrote it into
|
|
5
|
+
* everything an agent reads — AGENTS.md's Commands table, the agent briefs,
|
|
6
|
+
* the ship workflow — and then generated a CI workflow that ran `bun test`
|
|
7
|
+
* regardless. `createCiWorkflows` had `harness` in scope and reached for
|
|
8
|
+
* `harness?.ci?.bunVersion`, `?.runner` and `?.branches` four lines above
|
|
9
|
+
* the hardcode.
|
|
10
|
+
*
|
|
11
|
+
* The divergence is silent in both directions. If the consumer's command is
|
|
12
|
+
* a superset, CI is weaker than the gate every agent was told about. If
|
|
13
|
+
* `bun test` does not work in their project at all, CI is red for a reason
|
|
14
|
+
* no config change can fix, because the field that would fix it is not
|
|
15
|
+
* read.
|
|
16
|
+
*
|
|
17
|
+
* ## Why this is a module and not four `||` chains that agree
|
|
18
|
+
*
|
|
19
|
+
* They did not agree. Four sites resolved the same question four ways:
|
|
20
|
+
*
|
|
21
|
+
* | Site | Ladder |
|
|
22
|
+
* |---|---|
|
|
23
|
+
* | `createCiWorkflows` | `"bun test"` |
|
|
24
|
+
* | `generateAgentsMdContent` | `dev.testCmd \|\| "bun test"` |
|
|
25
|
+
* | `scanProject` | `package.json scripts.test \|\| "bun test"` |
|
|
26
|
+
* | `generateAgentBriefs` | `dev.testCmd \|\| scan.testCmd \|\| "bun test"` |
|
|
27
|
+
*
|
|
28
|
+
* So a consumer with a `scripts.test` and no `dev.testCmd` was told one
|
|
29
|
+
* command by AGENTS.md and another by CI, and two sites that happen to
|
|
30
|
+
* agree today are one decider too many — only a mutation of a SHARED
|
|
31
|
+
* binding can show that the agreement is load-bearing rather than
|
|
32
|
+
* coincidental. This is #87's fix for the type check, applied to the step
|
|
33
|
+
* directly below the one #87 collapsed.
|
|
34
|
+
*
|
|
35
|
+
* ## The rungs, and what each one is not
|
|
36
|
+
*
|
|
37
|
+
* 1. **`dev.testCmd` from the rungate config.** The operator said so, in
|
|
38
|
+
* the field the harness documents for exactly this.
|
|
39
|
+
* 2. **`package.json` `scripts.test`, verbatim.** The value, not `bun run
|
|
40
|
+
* test`. That is the existing behaviour of `scanProject`, so this rung
|
|
41
|
+
* is a collapse rather than a new judgement — and `bun run test` would
|
|
42
|
+
* fire `pretest`/`posttest`, which on this repo means CI running
|
|
43
|
+
* `sync-sc-status.ts` and writing to the tree.
|
|
44
|
+
* 3. **`bun test`.** Unchanged for every consumer that declares neither.
|
|
45
|
+
*
|
|
46
|
+
* ## What this does NOT cover
|
|
47
|
+
*
|
|
48
|
+
* `workflows/ship.js` resolves `test.command || dev.testCmd || 'bun test'`
|
|
49
|
+
* and cannot import (#69). It is the fifth site and it stays its own, which
|
|
50
|
+
* is a known gap rather than an oversight — the subprocess boundary is how
|
|
51
|
+
* workflows comply with `.claude/rules/config-access.md`.
|
|
52
|
+
*/
|
|
53
|
+
import { existsSync, readFileSync } from "fs";
|
|
54
|
+
import { join } from "path";
|
|
55
|
+
import { tryLoadRungateConfig } from "./config-loader";
|
|
56
|
+
|
|
57
|
+
export type TestCommandSource = "config" | "package-script" | "default";
|
|
58
|
+
|
|
59
|
+
export interface TestCommandDecision {
|
|
60
|
+
/** The shell command. Never null — every project can run something. */
|
|
61
|
+
command: string;
|
|
62
|
+
source: TestCommandSource;
|
|
63
|
+
/** Why this command and not another. */
|
|
64
|
+
reason: string;
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
export const DEFAULT_TEST_COMMAND = "bun test";
|
|
68
|
+
|
|
69
|
+
export function testCommandDecision(root: string): TestCommandDecision {
|
|
70
|
+
// Through the loader, never a constructed path to `.claude/rungate*`
|
|
71
|
+
// (`.claude/rules/config-access.md`). It also means both config layouts
|
|
72
|
+
// are honoured — a consumer who followed the documented migration to the
|
|
73
|
+
// directory form is the exact population a monolith-only read loses.
|
|
74
|
+
//
|
|
75
|
+
// It THROWS on a malformed config, deliberately: a corrupt config is
|
|
76
|
+
// never a missing config, and `catch {}` here is the conversion that rule
|
|
77
|
+
// exists to forbid. The one caller that must survive corruption is the
|
|
78
|
+
// config REPAIR step, and it calls `inferredTestCommand` instead — see
|
|
79
|
+
// below for why that is not a loophole.
|
|
80
|
+
const config = tryLoadRungateConfig(root) as { dev?: { testCmd?: unknown } } | null;
|
|
81
|
+
const declared = config?.dev?.testCmd;
|
|
82
|
+
if (typeof declared === "string" && declared.trim() !== "") {
|
|
83
|
+
return {
|
|
84
|
+
command: declared,
|
|
85
|
+
source: "config",
|
|
86
|
+
reason: "the project declares `dev.testCmd`, which beats anything inferred",
|
|
87
|
+
};
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
return inferredTestCommand(root);
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
/**
|
|
94
|
+
* The same decision with the config rung removed — what this project's test
|
|
95
|
+
* command would be if the config said nothing.
|
|
96
|
+
*
|
|
97
|
+
* Exactly one caller, and it is not a convenience: `generateOrAuditProjectHarness`
|
|
98
|
+
* chooses the value to WRITE into `dev.testCmd`, so asking the loader for
|
|
99
|
+
* `dev.testCmd` first is circular, and it runs against trees whose config is
|
|
100
|
+
* malformed — that is what it exists to repair. Routing it through the
|
|
101
|
+
* throwing loader killed the repair with `SyntaxError: JSON Parse error` in
|
|
102
|
+
* the step whose job is to fix that file.
|
|
103
|
+
*
|
|
104
|
+
* Split rather than flagged, because a boolean parameter makes the two
|
|
105
|
+
* behaviours one call site's argument rather than two named things, and the
|
|
106
|
+
* shared rungs stay shared either way.
|
|
107
|
+
*/
|
|
108
|
+
export function inferredTestCommand(root: string): TestCommandDecision {
|
|
109
|
+
const pkgPath = join(root, "package.json");
|
|
110
|
+
if (existsSync(pkgPath)) {
|
|
111
|
+
try {
|
|
112
|
+
const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
|
|
113
|
+
const script = pkg?.scripts?.test;
|
|
114
|
+
if (typeof script === "string" && script.trim() !== "") {
|
|
115
|
+
return {
|
|
116
|
+
command: script,
|
|
117
|
+
source: "package-script",
|
|
118
|
+
reason: "the project declares a `test` script and no `dev.testCmd`",
|
|
119
|
+
};
|
|
120
|
+
}
|
|
121
|
+
} catch {
|
|
122
|
+
// An unreadable package.json is not a reason to lose the test command.
|
|
123
|
+
// The default below needs no package.json at all, and this module's
|
|
124
|
+
// neighbours already shrug at this rather than killing the scaffold.
|
|
125
|
+
}
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
return {
|
|
129
|
+
command: DEFAULT_TEST_COMMAND,
|
|
130
|
+
source: "default",
|
|
131
|
+
reason: "the project declares neither `dev.testCmd` nor a `test` script",
|
|
132
|
+
};
|
|
133
|
+
}
|
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
|
+
}
|