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.
- package/lib/affected-tests.ts +398 -0
- package/lib/agent-audit.ts +2 -3
- package/lib/agent-worktree.ts +287 -0
- package/lib/agents-md-sections.ts +209 -0
- package/lib/behavioral-cache.ts +150 -2
- package/lib/branch-diff.ts +139 -0
- package/lib/branch-protection.ts +790 -0
- package/lib/brief-ac-alignment.ts +104 -0
- package/lib/brief-references.ts +205 -0
- package/lib/bun-version.ts +347 -0
- package/lib/check-remedy.ts +140 -0
- package/lib/ci-checkout.ts +18 -1
- package/lib/ci-history-depth.ts +159 -0
- package/lib/ci-setup-step.ts +96 -0
- package/lib/claude-code-action.ts +85 -0
- package/lib/claude-tool-vocabulary.ts +188 -0
- package/lib/cli-commands.ts +15 -0
- package/lib/commit-sha.ts +42 -0
- package/lib/commit-subject.ts +90 -0
- package/lib/compliance-report.ts +377 -45
- package/lib/compliance.ts +196 -20
- package/lib/config-loader.ts +51 -1
- package/lib/config-trackable.ts +391 -0
- package/lib/conformity.ts +1272 -189
- package/lib/containment.ts +238 -0
- package/lib/content-hash.ts +24 -0
- package/lib/context-docs.ts +143 -28
- package/lib/create-brief.ts +2 -1
- package/lib/create-sc.ts +323 -4
- package/lib/dev-liveness.ts +180 -0
- package/lib/discovery-branch-points.ts +432 -0
- package/lib/discovery-stability.ts +481 -0
- package/lib/distribution-currency.ts +186 -0
- package/lib/doc-routing.ts +157 -0
- package/lib/doc-scan-targets.ts +9 -0
- package/lib/evidence-command-transport.ts +160 -0
- package/lib/evidence-prevalidator.ts +246 -2
- package/lib/evidence-satisfiability.ts +534 -12
- package/lib/failure-intake.ts +317 -0
- package/lib/fallow-availability.ts +286 -0
- package/lib/fs-write-capabilities.ts +232 -0
- package/lib/gate-refusal-currency.ts +112 -0
- package/lib/gate-run-split.ts +147 -0
- package/lib/gate-timeouts.ts +82 -0
- package/lib/generators/agent-briefs.ts +4 -1
- package/lib/generators/agents-md.ts +204 -48
- package/lib/generators/code-map.ts +2 -1
- package/lib/generators/types.ts +8 -0
- package/lib/git-dates.ts +55 -0
- package/lib/git-isolation.ts +140 -0
- package/lib/github.ts +15 -0
- package/lib/google-auth-action.ts +93 -0
- package/lib/harness-project.ts +48 -0
- package/lib/harness-provenance.ts +255 -0
- package/lib/hook-evidence.ts +235 -0
- package/lib/hook-scopes.ts +386 -0
- package/lib/hook-target-tree.ts +398 -0
- package/lib/hook-trees.ts +447 -0
- package/lib/js-top-level-code.ts +78 -10
- package/lib/junit-checks.ts +536 -0
- package/lib/launch-base.ts +253 -0
- package/lib/line-citation.ts +372 -0
- package/lib/local-calendar-day.ts +78 -0
- package/lib/orphan-reaper.ts +468 -0
- package/lib/parity-binding.ts +205 -0
- package/lib/per-test-timeouts.ts +219 -0
- package/lib/plan-coverage.ts +151 -0
- package/lib/prior-branch.ts +201 -8
- package/lib/process-table.ts +146 -0
- package/lib/project-state-derivation.ts +219 -0
- package/lib/project-state-root.ts +258 -0
- package/lib/project-state-shape.ts +59 -0
- package/lib/promote-outputs.ts +6 -2
- package/lib/published-artifact.ts +525 -0
- package/lib/readdir-sorted.ts +45 -0
- package/lib/report-provenance.ts +156 -0
- package/lib/review-execution-reading.ts +206 -0
- package/lib/review-tool-agreement.ts +433 -0
- package/lib/rule-promotion.ts +234 -0
- package/lib/rule-retirement.ts +525 -0
- package/lib/run-branch.ts +612 -0
- package/lib/rungate-schema.ts +19 -0
- package/lib/runner-home.ts +274 -0
- package/lib/sc-claim-forms.ts +75 -0
- package/lib/sc-id-cross-tree.ts +323 -0
- package/lib/sc-ids.ts +121 -13
- package/lib/sc-reservations.ts +289 -0
- package/lib/scaffold/ai-review-findings.ts +403 -0
- package/lib/scaffold/ai-review-step.ts +4777 -0
- package/lib/scaffold/managed-workflow.ts +587 -192
- package/lib/scaffold/owned-files.ts +186 -39
- package/lib/scaffold/pre-push-hook.ts +49 -5
- package/lib/scaffold/rehearsal.ts +205 -71
- package/lib/scaffold/steps.ts +1517 -293
- package/lib/scaffold/workflow-census.ts +217 -0
- package/lib/scaffold/workflow-drift.ts +217 -0
- package/lib/scaffold/write-steps.ts +10 -4
- package/lib/scan-budget.ts +247 -0
- package/lib/scanner.ts +80 -62
- package/lib/scratch-roots.ts +50 -5
- package/lib/screenshot-discovery.ts +121 -0
- package/lib/screenshot-upload.ts +41 -1
- package/lib/secret-patterns.ts +511 -8
- package/lib/ship-mode.ts +219 -0
- package/lib/source-slice.ts +294 -0
- package/lib/spec-listing.ts +148 -0
- package/lib/spec-requirements.ts +209 -0
- package/lib/stale-cleanup.ts +37 -3
- package/lib/suite-flake.ts +278 -0
- package/lib/suite-measurement.ts +23 -4
- package/lib/suite-run-reading.ts +411 -1
- package/lib/suite-timeout-margin.ts +193 -0
- package/lib/test-case-bodies.ts +883 -0
- package/lib/test-case-deletion.ts +653 -0
- package/lib/test-census.ts +97 -29
- package/lib/test-command-positions.ts +274 -0
- package/lib/test-command.ts +133 -0
- package/lib/test-suite-lock.ts +325 -26
- package/lib/tool-probe.ts +142 -0
- package/lib/top-level-cd.ts +393 -0
- package/lib/tracked-vs-ignored.ts +234 -0
- package/lib/tree-entries.ts +89 -0
- package/lib/ts-ast.ts +200 -0
- package/lib/validators/spec-validators.ts +3 -2
- package/lib/walk-test-files.ts +97 -0
- package/lib/workflow-actions.ts +263 -0
- package/lib/worktree-collect.ts +177 -5
- package/lib/worktree-repo.ts +36 -1
- package/package.json +2 -1
- package/scripts/ai-review-findings.ts +45 -0
- 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 +37 -7
- package/scripts/create-spec.ts +2 -1
- package/scripts/create-success.ts +2 -1
- package/scripts/extract-constraints.ts +197 -26
- package/scripts/generate-code-map.ts +62 -28
- package/scripts/scaffold-project.ts +12 -2
- package/scripts/split-spec.ts +2 -1
- package/scripts/sync-sc-status.ts +127 -14
- 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,
|
|
@@ -36,6 +37,7 @@ import { execFileSync } from "child_process";
|
|
|
36
37
|
import { createHash } from "crypto";
|
|
37
38
|
import { tmpdir } from "os";
|
|
38
39
|
import { join } from "path";
|
|
40
|
+
import { readProcessTable, type ProcessRow } from "./process-table";
|
|
39
41
|
|
|
40
42
|
/**
|
|
41
43
|
* Suites allowed to run AT ONCE. Measured, not chosen: one full suite peaks at
|
|
@@ -537,27 +539,169 @@ function segmentIsFullSuite(segment: string, depth = 0): boolean {
|
|
|
537
539
|
*/
|
|
538
540
|
const LIVENESS_GRACE_SECONDS = 25;
|
|
539
541
|
|
|
542
|
+
/** The spelling of a suite that the command line itself carries. */
|
|
543
|
+
const SPELLED_BUN = /(^|\/|\s)bun\s+(run\s+)?test(\s|$)/;
|
|
544
|
+
|
|
545
|
+
/** `test` or `run test` as the first arguments after argv[0]. */
|
|
546
|
+
const SUITE_ARGUMENTS = /^\s+(run\s+)?test(\s|$)/;
|
|
547
|
+
|
|
548
|
+
/** What one `ps` command line is. `unknown` is a reading, not a default. */
|
|
549
|
+
export type PsLineReading = "suite" | "not-suite" | "unknown";
|
|
550
|
+
|
|
551
|
+
/** How argv[0] is resolved to the file it actually names. Injected for tests. */
|
|
552
|
+
export type ExecutableResolver = (path: string) => string;
|
|
553
|
+
|
|
554
|
+
/**
|
|
555
|
+
* The one place a `ps` line is judged to be a running suite (#707).
|
|
556
|
+
*
|
|
557
|
+
* Exported so there is exactly one binding to mutate and one thing for a
|
|
558
|
+
* case to drive over a table of real command lines. `suiteLiveness` reads
|
|
559
|
+
* the process table; this decides what a line means, and the two questions
|
|
560
|
+
* are separable only because they are separate functions. **The orphan
|
|
561
|
+
* reaper in `lib/orphan-reaper.ts` asks this same binding**, so the thing
|
|
562
|
+
* that decides what keeps a slot and the thing that decides what may be
|
|
563
|
+
* killed cannot drift apart — which is the whole of the #690/#707 pairing.
|
|
564
|
+
*
|
|
565
|
+
* ## Widening the leading boundary buys nothing, and that is still true
|
|
566
|
+
*
|
|
567
|
+
* `/tmp/brun test` is the documented workaround for #690, and `brun` is
|
|
568
|
+
* b-r-u-n: it **does not contain `bun` at all**, so no loosening of a
|
|
569
|
+
* pattern written over the string `bun` can ever match it. Measured:
|
|
570
|
+
* `"brun".includes("bun")` is `false`. #727 established this and reverted
|
|
571
|
+
* the widening, and nothing below re-litigates it — `SPELLED_BUN` is
|
|
572
|
+
* unchanged.
|
|
573
|
+
*
|
|
574
|
+
* ## What is new: ask the filesystem what the executable IS
|
|
575
|
+
*
|
|
576
|
+
* The workaround is a SYMLINK — measured on this machine, 2026-10-21:
|
|
577
|
+
* `/tmp/brun -> /opt/homebrew/bin/bun`, which `realpath`s to
|
|
578
|
+
* `/opt/homebrew/Cellar/bun/<version>/bin/bun`. So the name is an evasion
|
|
579
|
+
* and the identity is not. When a line's ARGUMENTS are a suite invocation
|
|
580
|
+
* (`<exe> test …` or `<exe> run test …`) but argv[0] is not spelled `bun`,
|
|
581
|
+
* this resolves argv[0] on disk and reads the basename of what it points
|
|
582
|
+
* at. A renamed or symlinked launcher is a `suite`; a resolution that
|
|
583
|
+
* cannot be taken is `unknown`.
|
|
584
|
+
*
|
|
585
|
+
* This is the liveness signal "that is not the process name at all" which
|
|
586
|
+
* the previous revision of this comment asked for, arriving as the
|
|
587
|
+
* executable's identity rather than as a heartbeat. A heartbeat was the
|
|
588
|
+
* other candidate and it is not available at this layer: the slot is taken
|
|
589
|
+
* by a PreToolUse hook that exits immediately, and a session running a
|
|
590
|
+
* foreground suite makes no tool calls while it waits, so nothing exists
|
|
591
|
+
* that could refresh the file.
|
|
592
|
+
*
|
|
593
|
+
* ## The two directions, and why they are not symmetric
|
|
594
|
+
*
|
|
595
|
+
* A resolution that fails, or an argv[0] that is not an absolute path, is
|
|
596
|
+
* `unknown` — and so is a binary whose resolved basename is something else,
|
|
597
|
+
* because a *copy* of bun under another name resolves to itself and no
|
|
598
|
+
* cheap reading can tell it from an unrelated program called with a `test`
|
|
599
|
+
* argument. The two consumers read that third state in OPPOSITE directions,
|
|
600
|
+
* deliberately:
|
|
601
|
+
*
|
|
602
|
+
* - **Keeping a slot** needs "not positively idle", so `unknown` keeps it.
|
|
603
|
+
* Over-detection costs at most one wedged slot for a TTL. Missing a suite
|
|
604
|
+
* that IS there reclaims a live slot and lets two real suites run against
|
|
605
|
+
* a cap of one, which is the OOM condition this whole mechanism prevents.
|
|
606
|
+
* - **Killing a process** needs "positively a suite", so `unknown` is never
|
|
607
|
+
* reaped. Over-detection there costs somebody else's work.
|
|
608
|
+
*
|
|
609
|
+
* The cost of the conservative reading is bounded and worth naming: one
|
|
610
|
+
* long-lived unrelated `/usr/bin/foo test` process makes the machine read
|
|
611
|
+
* `unknown`, which switches the early liveness reclaim off and leaves the
|
|
612
|
+
* 420-second TTL as the only staleness rule. That is the pre-#74 behaviour,
|
|
613
|
+
* not a new failure mode.
|
|
614
|
+
*/
|
|
615
|
+
export function classifyPsLine(
|
|
616
|
+
line: string,
|
|
617
|
+
options: { resolveExecutable?: ExecutableResolver } = {},
|
|
618
|
+
): PsLineReading {
|
|
619
|
+
if (SPELLED_BUN.test(line)) return "suite";
|
|
620
|
+
|
|
621
|
+
const space = line.indexOf(" ");
|
|
622
|
+
if (space <= 0) return "not-suite";
|
|
623
|
+
const argv0 = line.slice(0, space);
|
|
624
|
+
if (!SUITE_ARGUMENTS.test(line.slice(space))) return "not-suite";
|
|
625
|
+
|
|
626
|
+
// The arguments say "suite" and the name does not. Everything from here is
|
|
627
|
+
// a question about the file on disk, which is the thing a rename cannot
|
|
628
|
+
// change.
|
|
629
|
+
if (!argv0.startsWith("/")) return "unknown";
|
|
630
|
+
let resolved: string;
|
|
631
|
+
try {
|
|
632
|
+
resolved = (options.resolveExecutable ?? realpathSync)(argv0);
|
|
633
|
+
} catch {
|
|
634
|
+
return "unknown";
|
|
635
|
+
}
|
|
636
|
+
return resolved.slice(resolved.lastIndexOf("/") + 1) === "bun" ? "suite" : "unknown";
|
|
637
|
+
}
|
|
638
|
+
|
|
639
|
+
/**
|
|
640
|
+
* `psLineIsSuite` as it has always behaved: a projection of the reading
|
|
641
|
+
* above, kept because callers and cases already name it.
|
|
642
|
+
*
|
|
643
|
+
* It is a PROJECTION and not a second decider — there is one `classifyPsLine`
|
|
644
|
+
* and this restates its answer — so a mutation of the classifier moves this
|
|
645
|
+
* too, which is the property that makes the battery able to see either.
|
|
646
|
+
*/
|
|
647
|
+
export function psLineIsSuite(
|
|
648
|
+
line: string,
|
|
649
|
+
options: { resolveExecutable?: ExecutableResolver } = {},
|
|
650
|
+
): boolean {
|
|
651
|
+
return classifyPsLine(line, options) === "suite";
|
|
652
|
+
}
|
|
653
|
+
|
|
654
|
+
/** What the machine as a whole is doing. `unknown` is a reading. */
|
|
655
|
+
export type SuiteLiveness = "running" | "idle" | "unknown";
|
|
656
|
+
|
|
657
|
+
export interface LivenessOptions {
|
|
658
|
+
rows?: ProcessRow[];
|
|
659
|
+
readRows?: () => ProcessRow[];
|
|
660
|
+
resolveExecutable?: ExecutableResolver;
|
|
661
|
+
}
|
|
662
|
+
|
|
540
663
|
/**
|
|
541
|
-
*
|
|
664
|
+
* Whether any full suite is running anywhere on this machine.
|
|
542
665
|
*
|
|
543
|
-
* ONLY THE
|
|
544
|
-
* bun processes to sessions is unreliable — the agentgrit suite
|
|
545
|
-
* dangling bun processes per run, which is why slots are files
|
|
546
|
-
* process count. This does not attribute anything: a slot
|
|
547
|
-
* suite, so if NO suite is running at all, every slot is
|
|
666
|
+
* ONLY THE `idle` CASE IS ACTED ON, deliberately. #67 established that
|
|
667
|
+
* attributing bun processes to sessions is unreliable — the agentgrit suite
|
|
668
|
+
* leaks ~31 dangling bun processes per run, which is why slots are files
|
|
669
|
+
* rather than a process count. This does not attribute anything: a slot
|
|
670
|
+
* means a running suite, so if NO suite is running at all, every slot is
|
|
671
|
+
* provably false.
|
|
548
672
|
*
|
|
549
|
-
*
|
|
550
|
-
*
|
|
551
|
-
*
|
|
673
|
+
* `idle` is therefore a POSITIVE claim and it is made only when the whole
|
|
674
|
+
* table was read and every row was classified. One unclassifiable row makes
|
|
675
|
+
* the reading `unknown`, because `idle` is the only reading that lets a live
|
|
676
|
+
* slot be taken away from somebody.
|
|
677
|
+
*/
|
|
678
|
+
export function suiteLiveness(options: LivenessOptions = {}): SuiteLiveness {
|
|
679
|
+
let rows: ProcessRow[];
|
|
680
|
+
try {
|
|
681
|
+
rows = options.rows ?? (options.readRows ?? readProcessTable)();
|
|
682
|
+
} catch {
|
|
683
|
+
return "unknown";
|
|
684
|
+
}
|
|
685
|
+
let sawUnknown = false;
|
|
686
|
+
for (const row of rows) {
|
|
687
|
+
const reading = classifyPsLine(row.command, options);
|
|
688
|
+
if (reading === "suite") return "running";
|
|
689
|
+
if (reading === "unknown") sawUnknown = true;
|
|
690
|
+
}
|
|
691
|
+
return sawUnknown ? "unknown" : "idle";
|
|
692
|
+
}
|
|
693
|
+
|
|
694
|
+
/**
|
|
695
|
+
* True when the machine is NOT positively idle.
|
|
552
696
|
*
|
|
553
|
-
*
|
|
554
|
-
* caller
|
|
697
|
+
* The collapse is one-sided on purpose: `unknown` reads as `true` here, so a
|
|
698
|
+
* caller that only wants "may I take this slot away" gets the safe answer
|
|
699
|
+
* without having to remember which way round the third state goes. A caller
|
|
700
|
+
* that needs to tell `unknown` from `running` asks `suiteLiveness` — and the
|
|
701
|
+
* reaper does, because the opposite collapse would kill on a guess.
|
|
555
702
|
*/
|
|
556
|
-
export function anySuiteRunning(): boolean {
|
|
557
|
-
|
|
558
|
-
return out
|
|
559
|
-
.split("\n")
|
|
560
|
-
.some(line => /(^|\/|\s)bun\s+(run\s+)?test(\s|$)/.test(line));
|
|
703
|
+
export function anySuiteRunning(options: LivenessOptions = {}): boolean {
|
|
704
|
+
return suiteLiveness(options) !== "idle";
|
|
561
705
|
}
|
|
562
706
|
|
|
563
707
|
/**
|
|
@@ -708,6 +852,13 @@ export function acquireFullSuiteSlot(
|
|
|
708
852
|
|
|
709
853
|
export interface GateDecision {
|
|
710
854
|
allow: boolean;
|
|
855
|
+
/**
|
|
856
|
+
* Present when the run was allowed because it is not a run of THIS
|
|
857
|
+
* repository (#510). Allowed-and-quiet would make an exemption
|
|
858
|
+
* indistinguishable from a budget that was never spent, so it is named
|
|
859
|
+
* here and recorded on disk.
|
|
860
|
+
*/
|
|
861
|
+
exempt?: string;
|
|
711
862
|
/** Present when refused — shown verbatim to the caller. Never silent. */
|
|
712
863
|
reason?: string;
|
|
713
864
|
/**
|
|
@@ -860,6 +1011,117 @@ export interface GateOptions extends LockOptions {
|
|
|
860
1011
|
runId?: string;
|
|
861
1012
|
/** Overrides the per-run ceiling. Tests only; there is no environment path. */
|
|
862
1013
|
maxRunsPerPipeline?: number;
|
|
1014
|
+
/**
|
|
1015
|
+
* The working directory the command will run in (#510). Used to decide
|
|
1016
|
+
* whether this is a run of the guarded repository or of a scratch tree
|
|
1017
|
+
* somewhere else. Absent means UNKNOWN, which is charged — the budget
|
|
1018
|
+
* fails closed, as the rest of this module does.
|
|
1019
|
+
*/
|
|
1020
|
+
cwd?: string;
|
|
1021
|
+
/** Injected scope, so a test need not build a git repository to drive it. */
|
|
1022
|
+
scope?: RunScope;
|
|
1023
|
+
}
|
|
1024
|
+
|
|
1025
|
+
/**
|
|
1026
|
+
* Whose suite this is.
|
|
1027
|
+
*
|
|
1028
|
+
* - `project` — a tree of the repository this guard belongs to, including
|
|
1029
|
+
* every one of its worktrees. Charged.
|
|
1030
|
+
* - `scratch` — a directory that EXISTS and is not part of it: a `git
|
|
1031
|
+
* archive` export under /tmp, a fixture repo a test just created, another
|
|
1032
|
+
* checkout entirely. Not charged.
|
|
1033
|
+
* - `unknown` — the question could not be answered: no cwd, a path that is
|
|
1034
|
+
* not there, a git that would not run. Charged, because a guard that opens
|
|
1035
|
+
* on an error is the shape this repo keeps finding.
|
|
1036
|
+
*
|
|
1037
|
+
* The line between the last two is "I looked and it is not this repository"
|
|
1038
|
+
* against "I could not look". A `git archive` export has no `.git` and is
|
|
1039
|
+
* the case that filed #510, so a git-less directory must be scratch — but
|
|
1040
|
+
* only once something has confirmed the directory is really there.
|
|
1041
|
+
*/
|
|
1042
|
+
export type RunScope = "project" | "scratch" | "unknown";
|
|
1043
|
+
|
|
1044
|
+
/** The guarded repository's shared git directory, resolved once. */
|
|
1045
|
+
function projectCommonDir(): string | null {
|
|
1046
|
+
try {
|
|
1047
|
+
const out = execFileSync("git", ["rev-parse", "--path-format=absolute", "--git-common-dir"], {
|
|
1048
|
+
cwd: join(import.meta.dir, ".."),
|
|
1049
|
+
encoding: "utf-8",
|
|
1050
|
+
timeout: 10_000,
|
|
1051
|
+
stdio: ["ignore", "pipe", "pipe"],
|
|
1052
|
+
});
|
|
1053
|
+
return realpathSync(out.trim());
|
|
1054
|
+
} catch {
|
|
1055
|
+
return null;
|
|
1056
|
+
}
|
|
1057
|
+
}
|
|
1058
|
+
|
|
1059
|
+
/**
|
|
1060
|
+
* Is this working directory part of the repository the guard is installed in?
|
|
1061
|
+
*
|
|
1062
|
+
* The comparison is the **shared git directory**, not the path: all 110
|
|
1063
|
+
* worktrees of this repository answer with one `.git`, and they are all real
|
|
1064
|
+
* runs that must be charged. A `git archive` export has no `.git` at all, and
|
|
1065
|
+
* a fixture built by `git init` has its own — both scratch.
|
|
1066
|
+
*
|
|
1067
|
+
* ## Why this is not a /tmp denylist
|
|
1068
|
+
*
|
|
1069
|
+
* A path prefix is a detector narrower than what it detects: a reviewer's
|
|
1070
|
+
* probe under `~/scratch` would be charged, and a real checkout under /tmp
|
|
1071
|
+
* would be exempt. The question is "whose suite is this", and git already
|
|
1072
|
+
* answers it exactly.
|
|
1073
|
+
*/
|
|
1074
|
+
export function runScope(cwd: string | undefined, projectDir?: string | null): RunScope {
|
|
1075
|
+
if (!cwd) return "unknown";
|
|
1076
|
+
try {
|
|
1077
|
+
if (!statSync(cwd).isDirectory()) return "unknown";
|
|
1078
|
+
} catch {
|
|
1079
|
+
return "unknown";
|
|
1080
|
+
}
|
|
1081
|
+
const project = projectDir === undefined ? projectCommonDir() : projectDir;
|
|
1082
|
+
if (project === null) return "unknown";
|
|
1083
|
+
try {
|
|
1084
|
+
const out = execFileSync("git", ["rev-parse", "--path-format=absolute", "--git-common-dir"], {
|
|
1085
|
+
cwd,
|
|
1086
|
+
encoding: "utf-8",
|
|
1087
|
+
timeout: 10_000,
|
|
1088
|
+
stdio: ["ignore", "pipe", "pipe"],
|
|
1089
|
+
});
|
|
1090
|
+
return realpathSync(out.trim()) === project ? "project" : "scratch";
|
|
1091
|
+
} catch {
|
|
1092
|
+
// The directory is there and git will not claim it: not a repository at
|
|
1093
|
+
// all, which is what a `git archive` export is. Not a run of the guarded
|
|
1094
|
+
// project, and charging it is the thing #510 is about.
|
|
1095
|
+
return "scratch";
|
|
1096
|
+
}
|
|
1097
|
+
}
|
|
1098
|
+
|
|
1099
|
+
/** Where exempted runs are recorded, so the exemption is auditable. */
|
|
1100
|
+
export function scratchRunsPath(lockDir: string): string {
|
|
1101
|
+
return join(lockDir, "full-suite.scratch-runs.json");
|
|
1102
|
+
}
|
|
1103
|
+
|
|
1104
|
+
/**
|
|
1105
|
+
* Record an exempted run. Best-effort, like the budget counter — but it is
|
|
1106
|
+
* the only trace an exemption leaves, so losing it costs visibility rather
|
|
1107
|
+
* than enforcement.
|
|
1108
|
+
*/
|
|
1109
|
+
function recordScratchRun(lockDir: string, now: number, cwd: string | undefined): void {
|
|
1110
|
+
try {
|
|
1111
|
+
const path = scratchRunsPath(lockDir);
|
|
1112
|
+
let runs: Array<{ at: number; cwd: string }> = [];
|
|
1113
|
+
try {
|
|
1114
|
+
const parsed = JSON.parse(readFileSync(path, "utf-8"));
|
|
1115
|
+
if (Array.isArray(parsed?.runs)) runs = parsed.runs;
|
|
1116
|
+
} catch {
|
|
1117
|
+
// An unreadable or absent log starts a new one. This file is a record,
|
|
1118
|
+
// never an input to a decision, so a lost entry cannot open a gate.
|
|
1119
|
+
}
|
|
1120
|
+
runs.push({ at: now, cwd: cwd ?? "" });
|
|
1121
|
+
writeFileSync(path, JSON.stringify({ runs: runs.slice(-200) }));
|
|
1122
|
+
} catch {
|
|
1123
|
+
// Recording must never be able to block a run it is not guarding.
|
|
1124
|
+
}
|
|
863
1125
|
}
|
|
864
1126
|
|
|
865
1127
|
interface BudgetView {
|
|
@@ -1045,19 +1307,53 @@ export function evaluateFullSuiteRequest(
|
|
|
1045
1307
|
command: string,
|
|
1046
1308
|
options: GateOptions = {},
|
|
1047
1309
|
): GateDecision {
|
|
1048
|
-
|
|
1049
|
-
|
|
1050
|
-
//
|
|
1310
|
+
// Targeted runs are neither capped nor counted, so there is nothing to
|
|
1311
|
+
// spend. Asked FIRST, because the scope question below costs a subprocess
|
|
1312
|
+
// and the overwhelming majority of Bash commands are not suites at all.
|
|
1051
1313
|
if (!isFullSuiteCommand(command)) return { allow: true };
|
|
1052
1314
|
|
|
1053
1315
|
const lockDir = options.lockDir ?? defaultLockDir();
|
|
1054
1316
|
const now = options.now ?? Date.now();
|
|
1055
1317
|
|
|
1318
|
+
// A full suite of somebody else's tree is not this repository's suite
|
|
1319
|
+
// (#510). A reviewer's mutation probe on a `git archive` export is twenty
|
|
1320
|
+
// tests and under a second, and charging it against a budget sized for a
|
|
1321
|
+
// 400-second 12,000-test run made careful review the thing the guard
|
|
1322
|
+
// rationed. Scope is decided here and only here: `wouldAllowFullSuite`
|
|
1323
|
+
// below must not answer the same question, or there would be two deciders
|
|
1324
|
+
// and no behavioural test could tell them apart.
|
|
1325
|
+
//
|
|
1326
|
+
// It exempts the BUDGET and not the concurrency slot, and the distinction
|
|
1327
|
+
// is the whole of the design. The budget is a rate — the wrong unit for a
|
|
1328
|
+
// one-second probe. The slot is simultaneity, which is what rebooted the
|
|
1329
|
+
// machine in #67, and a scratch tree can be a full clone. Two further
|
|
1330
|
+
// reasons it must not skip the slot: `TestSuiteRelease` releases on the
|
|
1331
|
+
// same `isFullSuiteCommand` predicate with no notion of scope, so an
|
|
1332
|
+
// acquire this side skipped would free a slot somebody else is holding;
|
|
1333
|
+
// and "cd into /tmp to escape the cap" would be a bypass anyone could
|
|
1334
|
+
// reach for.
|
|
1335
|
+
const scope = options.scope ?? runScope(options.cwd);
|
|
1336
|
+
|
|
1337
|
+
const predicted = scope === "scratch" ? { allow: true } : wouldAllowFullSuite(sessionId, command, options);
|
|
1338
|
+
if (!predicted.allow) return predicted;
|
|
1339
|
+
|
|
1056
1340
|
// The prediction above is advisory; this is the atomic claim. Another session
|
|
1057
1341
|
// can take the last slot in between, and then the acquirer's answer wins.
|
|
1058
1342
|
const slot = acquireFullSuiteSlot(sessionId, options);
|
|
1059
1343
|
if (!slot.ok) return concurrencyRefusal(sessionId, slot.holders ?? []);
|
|
1060
1344
|
|
|
1345
|
+
if (scope === "scratch") {
|
|
1346
|
+
recordScratchRun(lockDir, now, options.cwd);
|
|
1347
|
+
return {
|
|
1348
|
+
allow: true,
|
|
1349
|
+
exempt:
|
|
1350
|
+
`not a run of this repository (${options.cwd ?? "unknown cwd"}), so it is not charged ` +
|
|
1351
|
+
`against DIR-L29 — recorded in ${scratchRunsPath(lockDir)}. It still holds a ` +
|
|
1352
|
+
`concurrency slot, which is what the cap is actually for.`,
|
|
1353
|
+
...(slot.degraded ? { warning: degradedWarning(lockDir) } : {}),
|
|
1354
|
+
};
|
|
1355
|
+
}
|
|
1356
|
+
|
|
1061
1357
|
try {
|
|
1062
1358
|
// Only the in-window runs are carried forward, and never more than the
|
|
1063
1359
|
// tracked maximum, so neither a long session nor a poisoned file can leave
|
|
@@ -1078,17 +1374,20 @@ export function evaluateFullSuiteRequest(
|
|
|
1078
1374
|
}
|
|
1079
1375
|
|
|
1080
1376
|
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
|
-
};
|
|
1377
|
+
return { allow: true, warning: degradedWarning(lockDir) };
|
|
1088
1378
|
}
|
|
1089
1379
|
return { allow: true };
|
|
1090
1380
|
}
|
|
1091
1381
|
|
|
1382
|
+
/** One wording for the degraded case, so the two exits cannot drift apart. */
|
|
1383
|
+
function degradedWarning(lockDir: string): string {
|
|
1384
|
+
return (
|
|
1385
|
+
`Concurrency guard DEGRADED — lock directory ${lockDir} is unusable, so this run ` +
|
|
1386
|
+
`was allowed without taking a slot. The cap is not being enforced right now. ` +
|
|
1387
|
+
`Check with other sessions before starting a full suite.`
|
|
1388
|
+
);
|
|
1389
|
+
}
|
|
1390
|
+
|
|
1092
1391
|
/**
|
|
1093
1392
|
* Give up ONE slot for a finished suite. Releasing one you do not hold is a no-op.
|
|
1094
1393
|
*
|
|
@@ -0,0 +1,142 @@
|
|
|
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
|
+
/**
|
|
69
|
+
* The one place that decides `available` from `outcome`.
|
|
70
|
+
*
|
|
71
|
+
* Every return below goes through it, and so does every caller that needs to
|
|
72
|
+
* state a reading it did not spawn — a test forcing a tool absent, a consumer
|
|
73
|
+
* replaying a recorded probe. Without it `available` is a field anyone can set,
|
|
74
|
+
* and a probe reporting `{ outcome: "absent", available: true }` would be a
|
|
75
|
+
* contradiction nothing could refuse. It is a projection of the reading, and
|
|
76
|
+
* the projection has an owner.
|
|
77
|
+
*/
|
|
78
|
+
export function toolProbe(fields: {
|
|
79
|
+
outcome: ToolProbeOutcome;
|
|
80
|
+
tool: string;
|
|
81
|
+
exitCode?: number | null;
|
|
82
|
+
reason: string;
|
|
83
|
+
}): ToolProbe {
|
|
84
|
+
return {
|
|
85
|
+
outcome: fields.outcome,
|
|
86
|
+
available: fields.outcome === "available",
|
|
87
|
+
tool: fields.tool,
|
|
88
|
+
exitCode: fields.exitCode ?? null,
|
|
89
|
+
reason: fields.reason,
|
|
90
|
+
};
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
/** The probe's own budget. A tool that cannot answer in five seconds is not ready to be used in a gate. */
|
|
94
|
+
export const TOOL_PROBE_TIMEOUT_MS = 5_000;
|
|
95
|
+
|
|
96
|
+
export function probeExternalTool(command: string, args: string[] = [], opts?: ToolProbeOptions): ToolProbe {
|
|
97
|
+
const tool = [command, ...args].join(" ");
|
|
98
|
+
let exitCode: number | null = null;
|
|
99
|
+
let stdout = "";
|
|
100
|
+
let stderr = "";
|
|
101
|
+
|
|
102
|
+
try {
|
|
103
|
+
const result = Bun.spawnSync([command, ...args], {
|
|
104
|
+
timeout: opts?.timeoutMs ?? TOOL_PROBE_TIMEOUT_MS,
|
|
105
|
+
stdout: "pipe",
|
|
106
|
+
stderr: "pipe",
|
|
107
|
+
});
|
|
108
|
+
exitCode = typeof result.exitCode === "number" ? result.exitCode : null;
|
|
109
|
+
stdout = result.stdout?.toString() ?? "";
|
|
110
|
+
stderr = result.stderr?.toString() ?? "";
|
|
111
|
+
} catch (e) {
|
|
112
|
+
// No process was created at all. That is the one condition that means the
|
|
113
|
+
// tool is not here, and it is why this branch is not merged with a
|
|
114
|
+
// non-zero exit below.
|
|
115
|
+
const message = e instanceof Error ? e.message : String(e);
|
|
116
|
+
return toolProbe({
|
|
117
|
+
outcome: "absent",
|
|
118
|
+
tool,
|
|
119
|
+
exitCode: null,
|
|
120
|
+
reason: `${command} is not on PATH: ${message.split("\n")[0]}`,
|
|
121
|
+
});
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
if (exitCode === 0 || stdout.trim().length > 0) {
|
|
125
|
+
return toolProbe({
|
|
126
|
+
outcome: "available",
|
|
127
|
+
tool,
|
|
128
|
+
exitCode,
|
|
129
|
+
reason: `${tool} ran and answered (exit ${exitCode})`,
|
|
130
|
+
});
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
return toolProbe({
|
|
134
|
+
outcome: "errored",
|
|
135
|
+
tool,
|
|
136
|
+
exitCode,
|
|
137
|
+
reason:
|
|
138
|
+
`${tool} ran and did not succeed (exit ${exitCode})` +
|
|
139
|
+
(stderr.trim() ? `: ${stderr.trim().split("\n")[0].slice(0, 200)}` : "") +
|
|
140
|
+
` — the tool was reachable, so this is not the same as it being absent`,
|
|
141
|
+
});
|
|
142
|
+
}
|