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
package/lib/github.ts
CHANGED
|
@@ -37,6 +37,16 @@ export interface GitHubClient {
|
|
|
37
37
|
update: (params: { owner: string; repo: string; pull_number: number; [key: string]: any }) => Promise<{ data: any }>;
|
|
38
38
|
list: (params: { owner: string; repo: string; [key: string]: any }) => Promise<{ data: any[] }>;
|
|
39
39
|
};
|
|
40
|
+
checks: {
|
|
41
|
+
/**
|
|
42
|
+
* Check runs for one ref (#46).
|
|
43
|
+
*
|
|
44
|
+
* `ref` is passed a commit SHA and never a branch name. The endpoint
|
|
45
|
+
* accepts both, and the branch form is the whole defect this gate would
|
|
46
|
+
* otherwise introduce — see `readCi`.
|
|
47
|
+
*/
|
|
48
|
+
listForRef: (params: { owner: string; repo: string; ref: string; per_page?: number }) => Promise<{ data: { total_count: number; check_runs: any[] } }>;
|
|
49
|
+
};
|
|
40
50
|
};
|
|
41
51
|
/**
|
|
42
52
|
* The GraphQL endpoint, for the handful of operations REST does not expose.
|
|
@@ -537,3 +547,188 @@ export async function listPRs(client: GitHubClient, repoSlug: string, opts?: Lis
|
|
|
537
547
|
});
|
|
538
548
|
return response.data;
|
|
539
549
|
}
|
|
550
|
+
|
|
551
|
+
// ── CI verification (#46) ────────────────────────────────────
|
|
552
|
+
|
|
553
|
+
/**
|
|
554
|
+
* One check run, reduced to the four fields a verdict depends on.
|
|
555
|
+
*
|
|
556
|
+
* `headSha` is carried even though the query is already keyed on a SHA. It is
|
|
557
|
+
* the field `readCi` re-checks, and re-checking it is the point: see below.
|
|
558
|
+
*/
|
|
559
|
+
export interface CheckRunSummary {
|
|
560
|
+
name: string;
|
|
561
|
+
/** `queued` | `in_progress` | `completed`, per the checks API. */
|
|
562
|
+
status: string;
|
|
563
|
+
/** `null` until the run completes. Never treat null as success. */
|
|
564
|
+
conclusion: string | null;
|
|
565
|
+
headSha: string;
|
|
566
|
+
url?: string;
|
|
567
|
+
}
|
|
568
|
+
|
|
569
|
+
export interface CiReading {
|
|
570
|
+
verdict: "PASS" | "FAIL" | "UNMEASURED";
|
|
571
|
+
/** The commit the verdict is ABOUT. A reading without this is not a reading. */
|
|
572
|
+
sha: string;
|
|
573
|
+
/** A sentence naming why, in every branch including PASS. */
|
|
574
|
+
reason: string;
|
|
575
|
+
checks: CheckRunSummary[];
|
|
576
|
+
failed: string[];
|
|
577
|
+
pending: string[];
|
|
578
|
+
/** Checks that completed without concluding either way — skipped, neutral. */
|
|
579
|
+
inconclusive: string[];
|
|
580
|
+
}
|
|
581
|
+
|
|
582
|
+
/**
|
|
583
|
+
* Conclusions that mean the check ran and said no.
|
|
584
|
+
*
|
|
585
|
+
* `cancelled` is in here deliberately. A cancelled run measured nothing, so
|
|
586
|
+
* the tempting reading is UNMEASURED — but on this repo's CI a cancellation is
|
|
587
|
+
* almost always `concurrency: cancel-in-progress` superseding the run, and
|
|
588
|
+
* calling that "unmeasured" lets a superseded commit's gate pass on a reading
|
|
589
|
+
* about a commit nobody is shipping. FAIL is the direction that costs a re-run
|
|
590
|
+
* rather than a bad merge.
|
|
591
|
+
*/
|
|
592
|
+
const CI_FAILURE_CONCLUSIONS = new Set([
|
|
593
|
+
"failure",
|
|
594
|
+
"timed_out",
|
|
595
|
+
"cancelled",
|
|
596
|
+
"action_required",
|
|
597
|
+
"startup_failure",
|
|
598
|
+
"stale",
|
|
599
|
+
]);
|
|
600
|
+
|
|
601
|
+
/**
|
|
602
|
+
* Conclusions that completed without answering the question.
|
|
603
|
+
*
|
|
604
|
+
* `skipped` is the one that matters. A skipped check is the single most
|
|
605
|
+
* convincing-looking way for this gate to certify nothing: the run exists, it
|
|
606
|
+
* completed, it did not fail, and a verdict computed as "no failures" calls it
|
|
607
|
+
* PASS. It measured nothing, so the reading is UNMEASURED.
|
|
608
|
+
*/
|
|
609
|
+
const CI_INCONCLUSIVE_CONCLUSIONS = new Set(["skipped", "neutral"]);
|
|
610
|
+
|
|
611
|
+
/**
|
|
612
|
+
* The verdict for one commit, from the checks recorded against it.
|
|
613
|
+
*
|
|
614
|
+
* Pure, and separate from the fetching, because every interesting decision
|
|
615
|
+
* here is a classification rather than a network call — and the classification
|
|
616
|
+
* is the part that has to be wrong-proof.
|
|
617
|
+
*
|
|
618
|
+
* **There is no branch that arrives at PASS by not finding a failure.** PASS
|
|
619
|
+
* requires at least one check, every check belonging to this exact commit,
|
|
620
|
+
* every check `completed`, and every conclusion `success`. Absence, pending,
|
|
621
|
+
* skipped and null all land elsewhere. That is the whole design: the natural
|
|
622
|
+
* implementation of "did CI pass" is `!checks.some(failed)`, which returns
|
|
623
|
+
* true for a commit CI has never heard of.
|
|
624
|
+
*
|
|
625
|
+
* **A check whose `headSha` differs is discarded, not counted.** The checks
|
|
626
|
+
* API accepts a branch name as `ref` and will happily answer about whatever
|
|
627
|
+
* commit that branch pointed at when CI last ran — so a gate keyed on the
|
|
628
|
+
* branch certifies the previous push. Filtering here means that even a caller
|
|
629
|
+
* who passes a branch name gets UNMEASURED rather than a stale PASS.
|
|
630
|
+
*/
|
|
631
|
+
export function readCi(sha: string, checks: CheckRunSummary[]): CiReading {
|
|
632
|
+
const base = { sha, checks, failed: [] as string[], pending: [] as string[], inconclusive: [] as string[] };
|
|
633
|
+
|
|
634
|
+
if (!sha || !/^[0-9a-f]{7,40}$/i.test(sha)) {
|
|
635
|
+
return { ...base, verdict: "UNMEASURED", reason: `"${sha}" is not a commit SHA, so there is nothing to ask CI about — a ref that is not a SHA would be answered about whatever commit it last pointed at` };
|
|
636
|
+
}
|
|
637
|
+
|
|
638
|
+
const mine = checks.filter(c => c.headSha === sha);
|
|
639
|
+
const foreign = checks.filter(c => c.headSha !== sha);
|
|
640
|
+
if (mine.length === 0) {
|
|
641
|
+
return {
|
|
642
|
+
...base,
|
|
643
|
+
verdict: "UNMEASURED",
|
|
644
|
+
reason: foreign.length > 0
|
|
645
|
+
? `every check found belongs to a different commit (${[...new Set(foreign.map(c => c.headSha))].join(", ")}), not ${sha} — this is the stale reading, not a pass`
|
|
646
|
+
: `no check has been recorded for ${sha} — CI has not reported on this commit, which is not the same as reporting success`,
|
|
647
|
+
};
|
|
648
|
+
}
|
|
649
|
+
|
|
650
|
+
const failed = mine.filter(c => c.conclusion !== null && CI_FAILURE_CONCLUSIONS.has(c.conclusion)).map(c => c.name);
|
|
651
|
+
const pending = mine.filter(c => c.status !== "completed").map(c => c.name);
|
|
652
|
+
const inconclusive = mine
|
|
653
|
+
.filter(c => c.status === "completed" && (c.conclusion === null || CI_INCONCLUSIVE_CONCLUSIONS.has(c.conclusion)))
|
|
654
|
+
.map(c => c.name);
|
|
655
|
+
const full = { ...base, checks: mine, failed, pending, inconclusive };
|
|
656
|
+
|
|
657
|
+
// A failure first, even with others still running. More waiting cannot
|
|
658
|
+
// un-fail a check, and reporting UNMEASURED here would turn a known red into
|
|
659
|
+
// "we did not find out".
|
|
660
|
+
if (failed.length > 0) {
|
|
661
|
+
return { ...full, verdict: "FAIL", reason: `CI failed on ${sha}: ${failed.join(", ")}` };
|
|
662
|
+
}
|
|
663
|
+
if (pending.length > 0) {
|
|
664
|
+
return { ...full, verdict: "UNMEASURED", reason: `CI has not finished on ${sha} — still running: ${pending.join(", ")}` };
|
|
665
|
+
}
|
|
666
|
+
if (inconclusive.length > 0) {
|
|
667
|
+
return { ...full, verdict: "UNMEASURED", reason: `CI completed on ${sha} without measuring: ${inconclusive.join(", ")} neither passed nor failed` };
|
|
668
|
+
}
|
|
669
|
+
return { ...full, verdict: "PASS", reason: `all ${mine.length} check${mine.length === 1 ? "" : "s"} passed on ${sha}: ${mine.map(c => c.name).join(", ")}` };
|
|
670
|
+
}
|
|
671
|
+
|
|
672
|
+
/** The check runs GitHub has recorded against one commit. */
|
|
673
|
+
export async function listCheckRuns(client: GitHubClient, repoSlug: string, sha: string): Promise<CheckRunSummary[]> {
|
|
674
|
+
const { owner, repo } = parseOwnerRepo(repoSlug);
|
|
675
|
+
const response = await client.rest.checks.listForRef({ owner, repo, ref: sha, per_page: 100 });
|
|
676
|
+
return (response.data?.check_runs ?? []).map((c: any) => ({
|
|
677
|
+
name: String(c.name ?? "<unnamed>"),
|
|
678
|
+
status: String(c.status ?? "unknown"),
|
|
679
|
+
conclusion: c.conclusion === undefined ? null : c.conclusion,
|
|
680
|
+
headSha: String(c.head_sha ?? ""),
|
|
681
|
+
url: typeof c.html_url === "string" ? c.html_url : undefined,
|
|
682
|
+
}));
|
|
683
|
+
}
|
|
684
|
+
|
|
685
|
+
export interface WaitForCiOptions {
|
|
686
|
+
timeoutMs: number;
|
|
687
|
+
intervalMs: number;
|
|
688
|
+
/** Injected so a test can run the loop without waiting for it. */
|
|
689
|
+
sleep?: (ms: number) => Promise<void>;
|
|
690
|
+
now?: () => number;
|
|
691
|
+
}
|
|
692
|
+
|
|
693
|
+
/**
|
|
694
|
+
* Poll until CI has an answer for this commit, or until the wait runs out.
|
|
695
|
+
*
|
|
696
|
+
* Polling, and not a webhook, because a local harness has no inbound endpoint
|
|
697
|
+
* for a webhook to arrive at — the choice is not whether to poll but who does
|
|
698
|
+
* and whether the wait is bounded. `gh run watch` polls too, and blocks
|
|
699
|
+
* without a bound.
|
|
700
|
+
*
|
|
701
|
+
* **A timeout returns the last reading, which is UNMEASURED.** It never
|
|
702
|
+
* upgrades to PASS, and it never degrades to FAIL either: running out of
|
|
703
|
+
* patience is not evidence about the code. The returned reason names what was
|
|
704
|
+
* still pending, so the operator can see what it was waiting for.
|
|
705
|
+
*/
|
|
706
|
+
export async function waitForCi(
|
|
707
|
+
client: GitHubClient,
|
|
708
|
+
repoSlug: string,
|
|
709
|
+
sha: string,
|
|
710
|
+
opts: WaitForCiOptions,
|
|
711
|
+
): Promise<CiReading> {
|
|
712
|
+
const sleep = opts.sleep ?? ((ms: number) => new Promise<void>(r => setTimeout(r, ms)));
|
|
713
|
+
const now = opts.now ?? (() => Date.now());
|
|
714
|
+
const deadline = now() + Math.max(0, opts.timeoutMs);
|
|
715
|
+
let reading = readCi(sha, await listCheckRuns(client, repoSlug, sha));
|
|
716
|
+
|
|
717
|
+
// Only a pending or absent reading is worth waiting on. A FAIL will not
|
|
718
|
+
// improve, a PASS will not get better, and an inconclusive check has already
|
|
719
|
+
// finished — polling those is time spent to reach the same answer.
|
|
720
|
+
const worthWaiting = (r: CiReading) => r.verdict === "UNMEASURED" && (r.pending.length > 0 || r.checks.length === 0);
|
|
721
|
+
|
|
722
|
+
while (worthWaiting(reading) && now() < deadline) {
|
|
723
|
+
await sleep(Math.min(opts.intervalMs, Math.max(0, deadline - now())));
|
|
724
|
+
reading = readCi(sha, await listCheckRuns(client, repoSlug, sha));
|
|
725
|
+
}
|
|
726
|
+
if (worthWaiting(reading)) {
|
|
727
|
+
const waited = Math.round(opts.timeoutMs / 1000);
|
|
728
|
+
return {
|
|
729
|
+
...reading,
|
|
730
|
+
reason: `${reading.reason} — gave up after ${waited}s, which is a statement about the wait and not about the code`,
|
|
731
|
+
};
|
|
732
|
+
}
|
|
733
|
+
return reading;
|
|
734
|
+
}
|
package/lib/js-top-level-code.ts
CHANGED
|
@@ -35,7 +35,26 @@ function regexCanFollow(prev: string): boolean {
|
|
|
35
35
|
return !/[A-Za-z0-9_$)\]]/.test(prev);
|
|
36
36
|
}
|
|
37
37
|
|
|
38
|
-
|
|
38
|
+
/**
|
|
39
|
+
* `keepStringContents` leaves quoted string bodies intact while still blanking
|
|
40
|
+
* comments, regex literals and template text.
|
|
41
|
+
*
|
|
42
|
+
* Added for #484, which needs the opposite half of what every other caller
|
|
43
|
+
* wants: the path segments in `join(__dirname, "..", "config", "x.json")` are
|
|
44
|
+
* the payload, and the reason it needs this tokenizer at all is that the same
|
|
45
|
+
* expression written in a DOC COMMENT must not be read as a call. The first
|
|
46
|
+
* draft of that check scanned raw source and reported its own module docstring
|
|
47
|
+
* as a violation — #454 is the same mistake in CONFIG-1, two weeks earlier.
|
|
48
|
+
*
|
|
49
|
+
* It is an option on this function rather than a second stripper in that
|
|
50
|
+
* module on purpose. Two functions that each decide what a comment is are two
|
|
51
|
+
* deciders, and the one that is wrong is invisible — see
|
|
52
|
+
* `.claude/rules/checks-must-be-able-to-fail.md`.
|
|
53
|
+
*/
|
|
54
|
+
export function stripStringsAndComments(
|
|
55
|
+
src: string,
|
|
56
|
+
{ keepStringContents = false }: { keepStringContents?: boolean } = {},
|
|
57
|
+
): string {
|
|
39
58
|
let out = "";
|
|
40
59
|
let i = 0;
|
|
41
60
|
// Stack of brace depths, one entry per template literal currently open. An
|
|
@@ -100,13 +119,19 @@ export function stripStringsAndComments(src: string): string {
|
|
|
100
119
|
i++;
|
|
101
120
|
while (i < src.length) {
|
|
102
121
|
if (src[i] === "\\") {
|
|
122
|
+
// Carry the escape through verbatim under `keepStringContents`.
|
|
123
|
+
// Dropping both characters turned `"a\"b"` into `ab`, which is not
|
|
124
|
+
// a shorter version of the segment — it is a DIFFERENT path, and a
|
|
125
|
+
// caller resolving it would report a file the code never reads.
|
|
126
|
+
// Silently wrong beats loudly wrong only in the wrong direction.
|
|
127
|
+
if (keepStringContents) out += src.slice(i, i + 2);
|
|
103
128
|
i += 2;
|
|
104
129
|
continue;
|
|
105
130
|
}
|
|
106
131
|
if (src[i] === quote) break;
|
|
107
132
|
// Unterminated strings must not swallow the rest of the file.
|
|
108
133
|
if (src[i] === "\n") break;
|
|
109
|
-
out += src[i]
|
|
134
|
+
out += keepStringContents ? src[i] : "";
|
|
110
135
|
i++;
|
|
111
136
|
}
|
|
112
137
|
if (src[i] === quote) {
|