rungate 0.2.1 → 0.4.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/bin/rungate.ts +70 -0
- package/lib/aes-calculator.ts +66 -0
- package/lib/agent-audit.ts +139 -0
- package/lib/agent-brief-validation.ts +359 -0
- package/lib/agents-md-refs.ts +90 -0
- package/lib/bash-file-read.ts +197 -0
- package/lib/behavioral-cache.ts +78 -0
- package/lib/branch-cleanup.ts +234 -0
- package/lib/brief-context-parser.ts +35 -0
- package/lib/brief-precedence.ts +114 -0
- package/lib/canary.ts +117 -0
- package/lib/check-registry.ts +226 -0
- package/lib/ci-checkout.ts +426 -0
- package/lib/cli-commands.ts +137 -0
- package/lib/compliance-backfill.ts +232 -0
- package/lib/compliance-report.ts +605 -0
- package/lib/compliance.ts +361 -0
- package/lib/config-loader.ts +255 -0
- package/lib/config-readers.ts +86 -0
- package/lib/conformity.ts +2161 -137
- package/lib/container-provenance.ts +230 -0
- package/lib/create-brief.ts +150 -0
- package/lib/create-sc.ts +267 -0
- package/lib/decomposition-waves.ts +197 -0
- package/lib/deep-merge.ts +69 -0
- package/lib/dev-liveness.ts +214 -0
- package/lib/directive-extractor.ts +210 -0
- package/lib/distribution-standing.ts +113 -0
- package/lib/doc-hygiene.ts +238 -0
- package/lib/eval-criteria.ts +6 -0
- package/lib/evidence-portability.ts +123 -0
- package/lib/evidence-prevalidator.ts +390 -0
- package/lib/evidence-required.ts +150 -0
- package/lib/evidence-satisfiability.ts +288 -0
- package/lib/frontmatter.ts +163 -0
- package/lib/gap-scanner.ts +348 -0
- package/lib/gate-check-audit.ts +190 -0
- package/lib/gate-enforcement.ts +366 -0
- package/lib/generators/agent-briefs.ts +136 -0
- package/lib/generators/agents-md.ts +511 -0
- package/lib/generators/code-map.ts +60 -0
- package/lib/generators/types.ts +184 -0
- package/lib/git-ref-normalizer.ts +107 -0
- package/lib/github.ts +539 -0
- package/lib/harness-identity.ts +63 -0
- package/lib/hill-climb.ts +164 -0
- package/lib/instruction-effectiveness.ts +131 -0
- package/lib/issue-closure-audit.ts +225 -0
- package/lib/issue-create-override.ts +343 -0
- package/lib/issue-extraction.ts +368 -0
- package/lib/js-top-level-code.ts +250 -0
- package/lib/liveness-contradiction.ts +149 -0
- package/lib/organize.ts +505 -0
- package/lib/paths.ts +197 -6
- package/lib/phase2-decomposition.ts +270 -0
- package/lib/post-fix-verify.ts +157 -0
- package/lib/prior-branch.ts +512 -0
- package/lib/project-state-shape.ts +166 -0
- package/lib/promote-outputs.ts +156 -0
- package/lib/prove-label-gate.ts +128 -0
- package/lib/reachability.ts +302 -0
- package/lib/release-preflight.ts +288 -0
- package/lib/rule-health-pipeline.ts +264 -0
- package/lib/rule-health-trend.ts +161 -0
- package/lib/rule-provenance.ts +149 -0
- package/lib/rule-registry.ts +128 -0
- package/lib/rungate-schema.ts +127 -5
- package/lib/sc-claim-forms.ts +179 -0
- package/lib/sc-cover.ts +150 -0
- package/lib/sc-guard.ts +157 -0
- package/lib/sc-ids.ts +344 -0
- package/lib/scaffold/defaults.ts +165 -0
- package/lib/scaffold/managed-workflow.ts +370 -0
- package/lib/scaffold/owned-files.ts +265 -0
- package/lib/scaffold/pre-push-hook.ts +165 -0
- package/lib/scaffold/steps.ts +2621 -0
- package/lib/scanner.ts +701 -0
- package/lib/scope-denylist.ts +258 -0
- package/lib/screenshot-upload.ts +73 -0
- package/lib/secret-patterns.ts +112 -0
- package/lib/security-verdict.ts +616 -0
- package/lib/signal-phrases.ts +1 -0
- package/lib/spec-change-conformity.ts +80 -0
- package/lib/spec-files.ts +62 -0
- package/lib/spec-registry.ts +133 -0
- package/lib/spec-updater.ts +96 -0
- package/lib/stale-cleanup.ts +224 -0
- package/lib/stale-issue-scanner.ts +36 -0
- package/lib/strip-js-comments.ts +269 -0
- package/lib/suite-measurement.ts +228 -0
- package/lib/task-completion-checks.ts +224 -0
- package/lib/test-suite-lock.ts +1136 -0
- package/lib/transcript-checker.ts +1140 -0
- package/lib/typescript-project.ts +233 -0
- package/lib/validators/spec-validators.ts +171 -0
- package/lib/verdict-capture.ts +73 -0
- package/lib/verified-push.ts +535 -0
- package/lib/workflow-security.ts +174 -0
- package/lib/worktree-cleanup.ts +432 -0
- package/lib/worktree-collect.ts +283 -0
- package/lib/worktree-isolation.ts +82 -0
- package/lib/worktree-repo.ts +300 -0
- package/package.json +27 -3
- package/prompts/ac-adversary.md +14 -2
- package/prompts/aditi.md +5 -0
- package/prompts/blast-radius.md +5 -0
- package/prompts/container-verify.md +5 -0
- package/prompts/discovery.md +4 -0
- package/prompts/environment.md +5 -0
- package/prompts/evidence-hierarchy.md +5 -0
- package/prompts/evidence-validator.md +11 -0
- package/prompts/marcus.md +5 -0
- package/prompts/prevention.md +5 -0
- package/prompts/prove-reproducer.md +12 -0
- package/prompts/quinn-decision-tree.md +5 -0
- package/prompts/quinn-ui-brief.md +5 -0
- package/prompts/quinn.md +5 -0
- package/prompts/rca.md +5 -0
- package/prompts/read-before-write.md +4 -0
- package/prompts/regression.md +5 -0
- package/prompts/serena.md +5 -0
- package/scripts/audit-specs.ts +464 -0
- package/scripts/convert-spec.ts +293 -0
- package/scripts/create-sc.ts +92 -0
- package/scripts/create-spec.ts +166 -0
- package/scripts/extract-constraints.ts +4 -3
- package/scripts/generate-code-map.ts +1 -1
- package/scripts/scaffold-project.ts +138 -1426
- package/scripts/sync-spec-tests.ts +211 -126
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
import { existsSync, readdirSync, readFileSync, writeFileSync, mkdirSync, renameSync, statSync } from "fs";
|
|
2
|
+
import { join, basename } from "path";
|
|
3
|
+
|
|
4
|
+
interface PromoteResult {
|
|
5
|
+
promoted: string[];
|
|
6
|
+
skipped: string[];
|
|
7
|
+
archived: string[];
|
|
8
|
+
errors: string[];
|
|
9
|
+
}
|
|
10
|
+
|
|
11
|
+
export function promoteOutputs(projectRoot: string): PromoteResult {
|
|
12
|
+
const home = process.env.HOME || "";
|
|
13
|
+
const rungatDir = join(home, ".rungate");
|
|
14
|
+
const result: PromoteResult = { promoted: [], skipped: [], archived: [], errors: [] };
|
|
15
|
+
|
|
16
|
+
if (!existsSync(rungatDir)) return result;
|
|
17
|
+
|
|
18
|
+
const archiveDir = join(rungatDir, "_archived");
|
|
19
|
+
const maxAgeDays = 7;
|
|
20
|
+
|
|
21
|
+
const slugDirs = readdirSync(rungatDir, { withFileTypes: true })
|
|
22
|
+
.filter(d => d.isDirectory() && !d.name.startsWith("_"))
|
|
23
|
+
.map(d => join(rungatDir, d.name));
|
|
24
|
+
|
|
25
|
+
for (const dir of slugDirs) {
|
|
26
|
+
const slug = basename(dir);
|
|
27
|
+
|
|
28
|
+
// Council synthesis → docs/council/
|
|
29
|
+
const councilJson = join(dir, "council-synthesis.json");
|
|
30
|
+
if (existsSync(councilJson)) {
|
|
31
|
+
try {
|
|
32
|
+
const data = JSON.parse(readFileSync(councilJson, "utf-8"));
|
|
33
|
+
const topic = data.topic || slug;
|
|
34
|
+
const topicSlug = topic.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 60);
|
|
35
|
+
const date = data.capturedAt?.slice(0, 10) || new Date().toISOString().slice(0, 10);
|
|
36
|
+
const destDir = join(projectRoot, "docs", "council");
|
|
37
|
+
const destFile = join(destDir, `${date}-${topicSlug}.md`);
|
|
38
|
+
|
|
39
|
+
if (!existsSync(destFile)) {
|
|
40
|
+
mkdirSync(destDir, { recursive: true });
|
|
41
|
+
const md = buildCouncilMarkdown(data, date, topic);
|
|
42
|
+
writeFileSync(destFile, md);
|
|
43
|
+
result.promoted.push(`council: ${basename(destFile)}`);
|
|
44
|
+
} else {
|
|
45
|
+
result.skipped.push(`council: ${basename(destFile)} (exists)`);
|
|
46
|
+
}
|
|
47
|
+
} catch (e: any) {
|
|
48
|
+
result.errors.push(`council ${slug}: ${e.message}`);
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
// Research output → docs/research/
|
|
53
|
+
const researchJson = join(dir, "research-output.json");
|
|
54
|
+
if (existsSync(researchJson)) {
|
|
55
|
+
try {
|
|
56
|
+
const data = JSON.parse(readFileSync(researchJson, "utf-8"));
|
|
57
|
+
const topic = data.topic || slug;
|
|
58
|
+
const topicSlug = topic.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 60);
|
|
59
|
+
const destDir = join(projectRoot, "docs", "research");
|
|
60
|
+
const destFile = join(destDir, `${topicSlug}.md`);
|
|
61
|
+
|
|
62
|
+
if (!existsSync(destFile)) {
|
|
63
|
+
mkdirSync(destDir, { recursive: true });
|
|
64
|
+
const md = buildResearchMarkdown(data, topic);
|
|
65
|
+
writeFileSync(destFile, md);
|
|
66
|
+
result.promoted.push(`research: ${basename(destFile)}`);
|
|
67
|
+
} else {
|
|
68
|
+
result.skipped.push(`research: ${basename(destFile)} (exists)`);
|
|
69
|
+
}
|
|
70
|
+
} catch (e: any) {
|
|
71
|
+
result.errors.push(`research ${slug}: ${e.message}`);
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
// Archive stale working dirs (older than maxAgeDays, no active workflow-state)
|
|
77
|
+
for (const dir of slugDirs) {
|
|
78
|
+
const slug = basename(dir);
|
|
79
|
+
try {
|
|
80
|
+
const stat = statSync(dir);
|
|
81
|
+
const ageDays = (Date.now() - stat.mtimeMs) / (1000 * 60 * 60 * 24);
|
|
82
|
+
if (ageDays < maxAgeDays) continue;
|
|
83
|
+
|
|
84
|
+
const wsPath = join(dir, "workflow-state.json");
|
|
85
|
+
if (existsSync(wsPath)) {
|
|
86
|
+
try {
|
|
87
|
+
const ws = JSON.parse(readFileSync(wsPath, "utf-8"));
|
|
88
|
+
if (ws.phase && !["DONE", "SHIPPED", "PROVEN"].includes(ws.phase)) continue;
|
|
89
|
+
} catch { /* unparseable — safe to archive */ }
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
mkdirSync(archiveDir, { recursive: true });
|
|
93
|
+
renameSync(dir, join(archiveDir, slug));
|
|
94
|
+
result.archived.push(slug);
|
|
95
|
+
} catch (e: any) {
|
|
96
|
+
result.errors.push(`archive ${slug}: ${e.message}`);
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
return result;
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
function buildCouncilMarkdown(data: any, date: string, topic: string): string {
|
|
104
|
+
const lines = [
|
|
105
|
+
"---",
|
|
106
|
+
"doc-type: council",
|
|
107
|
+
"status: accepted",
|
|
108
|
+
`created: ${date}`,
|
|
109
|
+
`topic: ${topic}`,
|
|
110
|
+
"---",
|
|
111
|
+
"",
|
|
112
|
+
`# Council: ${topic}`,
|
|
113
|
+
"",
|
|
114
|
+
];
|
|
115
|
+
|
|
116
|
+
if (data.convergencePoints?.length) {
|
|
117
|
+
lines.push("## Convergence", "");
|
|
118
|
+
for (const p of data.convergencePoints) lines.push(`- ${p}`);
|
|
119
|
+
lines.push("");
|
|
120
|
+
}
|
|
121
|
+
if (data.disagreements?.length) {
|
|
122
|
+
lines.push("## Disagreements", "");
|
|
123
|
+
for (const d of data.disagreements) lines.push(`- ${d}`);
|
|
124
|
+
lines.push("");
|
|
125
|
+
}
|
|
126
|
+
if (data.recommendation) {
|
|
127
|
+
lines.push("## Recommendation", "", data.recommendation, "");
|
|
128
|
+
}
|
|
129
|
+
if (data.decisions?.length) {
|
|
130
|
+
lines.push("## Decisions", "");
|
|
131
|
+
for (const d of data.decisions) lines.push(`- ${d}`);
|
|
132
|
+
lines.push("");
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
return lines.join("\n") + "\n";
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
function buildResearchMarkdown(data: any, topic: string): string {
|
|
139
|
+
const lines = [
|
|
140
|
+
"---",
|
|
141
|
+
"doc-type: research",
|
|
142
|
+
"status: active",
|
|
143
|
+
`created: ${new Date().toISOString().slice(0, 10)}`,
|
|
144
|
+
`governs: ${topic}`,
|
|
145
|
+
"---",
|
|
146
|
+
"",
|
|
147
|
+
`# ${topic}`,
|
|
148
|
+
"",
|
|
149
|
+
];
|
|
150
|
+
|
|
151
|
+
if (data.findings) lines.push(data.findings, "");
|
|
152
|
+
if (data.summary) lines.push(data.summary, "");
|
|
153
|
+
if (typeof data === "string") lines.push(data, "");
|
|
154
|
+
|
|
155
|
+
return lines.join("\n") + "\n";
|
|
156
|
+
}
|
|
@@ -0,0 +1,128 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Whether an issue's labels say the close gate must stop (#1390, #395).
|
|
3
|
+
*
|
|
4
|
+
* `needs-prove` marks an issue whose fix has not been demonstrated against a
|
|
5
|
+
* reproducer. `proven` is what `/prove` adds once it has been. An issue
|
|
6
|
+
* carrying the first without the second is one about to be closed on the
|
|
7
|
+
* strength of a passing suite, which is the thing the prove step exists to
|
|
8
|
+
* stop.
|
|
9
|
+
*
|
|
10
|
+
* ## Why this is a function and not four lines in the gate
|
|
11
|
+
*
|
|
12
|
+
* It was four lines in `gates/workflow.test.ts`, and the decision was
|
|
13
|
+
* entangled with the transport that fetched the labels — a GitHub CLI
|
|
14
|
+
* subprocess. Nothing could exercise the rule without a network, a `gh`
|
|
15
|
+
* binary and an authenticated environment, so nothing did. The criterion
|
|
16
|
+
* forbidding that subprocess (SC-502) was ticked over it for its whole life.
|
|
17
|
+
*
|
|
18
|
+
* One exported predicate over a plain string list means the rule can be
|
|
19
|
+
* driven directly, and means there is a single binding to mutate — the
|
|
20
|
+
* property `.claude/rules/checks-must-be-able-to-fail.md` asks for. The
|
|
21
|
+
* transport is `getIssueLabels` in `lib/github.ts` and is now a separate
|
|
22
|
+
* question, which is the point: a decision tangled with its transport is a
|
|
23
|
+
* decision nobody tests.
|
|
24
|
+
*
|
|
25
|
+
* Returns the refusal text, or `null` to allow.
|
|
26
|
+
*/
|
|
27
|
+
export function proveLabelViolation(labels: readonly string[]): string | null {
|
|
28
|
+
const has = (name: string) => labels.includes(name);
|
|
29
|
+
if (!has("needs-prove")) return null;
|
|
30
|
+
if (has("proven")) return null;
|
|
31
|
+
return (
|
|
32
|
+
"Close gate blocked: the issue carries `needs-prove` and not `proven`. " +
|
|
33
|
+
"Run /prove to demonstrate the fix against a reproducer before closing (#1390)."
|
|
34
|
+
);
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/**
|
|
38
|
+
* What the gate does when the label read itself fails (#405).
|
|
39
|
+
*
|
|
40
|
+
* The read used to be wrapped in `catch { return }`, so a missing token, a
|
|
41
|
+
* rate limit, a network blip and a typo'd repo slug all landed in the same
|
|
42
|
+
* place and the gate reported clean. "No blocking label" and "could not find
|
|
43
|
+
* out" were the same outcome, which is shape one in
|
|
44
|
+
* `.claude/rules/checks-must-be-able-to-fail.md`.
|
|
45
|
+
*
|
|
46
|
+
* ## The token-less decision, and why
|
|
47
|
+
*
|
|
48
|
+
* #405 left this open: "whether a token-less local run should refuse or skip.
|
|
49
|
+
* A gate that refuses every local invocation is a gate people will comment
|
|
50
|
+
* out." Three outcomes rather than two, decided on what the environment can
|
|
51
|
+
* actually answer:
|
|
52
|
+
*
|
|
53
|
+
* | token | read | verdict |
|
|
54
|
+
* |---|---|---|
|
|
55
|
+
* | — | n/a | `UNMEASURED` — the environment was never able to answer |
|
|
56
|
+
* | present | threw | `REFUSE` — something that should have worked did not |
|
|
57
|
+
* | present | ok | `ALLOW` or `REFUSE` by `proveLabelViolation` |
|
|
58
|
+
*
|
|
59
|
+
* A token-less run does NOT refuse, because every local `bun test gates/`
|
|
60
|
+
* would block and the gate would be deleted within a week. It does not
|
|
61
|
+
* silently pass either: the verdict is `UNMEASURED` and carries its reason,
|
|
62
|
+
* which is the distinction `.claude/rules/config-access.md` names — `SKIP` is
|
|
63
|
+
* indistinguishable from success and `UNMEASURED` is not.
|
|
64
|
+
*
|
|
65
|
+
* That is safe where it matters because of where the gate actually runs, which
|
|
66
|
+
* was checked rather than assumed:
|
|
67
|
+
*
|
|
68
|
+
* - It is guarded by `isShipPlus()` — `gates/workflow.test.ts:229`, true only
|
|
69
|
+
* when workflow state says `SHIP` or `DONE`. It is reached from
|
|
70
|
+
* `gates/gate-executor.ts`, which spawns `bun test gates/` in the ship
|
|
71
|
+
* pipeline's own process environment, where a token is present.
|
|
72
|
+
* - CI runs `gates/workflow.test.ts` too (`ci.yml` runs a bare `bun test`) and
|
|
73
|
+
* has NO token. It never reaches this code: there is no workflow state in a
|
|
74
|
+
* CI checkout, so `isShipPlus()` is false and the test returns first. The
|
|
75
|
+
* `gates` job does not run this file at all — only the conformity suite and
|
|
76
|
+
* the secret scan.
|
|
77
|
+
*
|
|
78
|
+
* So the authenticated-and-still-failing case is the one real invocations hit,
|
|
79
|
+
* and it is the one that now blocks.
|
|
80
|
+
*
|
|
81
|
+
* `tokenPresent` comes from `resolveGitHubToken` at the call site rather than
|
|
82
|
+
* from a second `process.env` read here — two deciders of one fact survive
|
|
83
|
+
* any mutation of either.
|
|
84
|
+
*/
|
|
85
|
+
export type ProveLabelVerdict = "ALLOW" | "REFUSE" | "UNMEASURED";
|
|
86
|
+
|
|
87
|
+
export interface LabelRead {
|
|
88
|
+
/** Set when the read succeeded. */
|
|
89
|
+
labels?: readonly string[];
|
|
90
|
+
/** Set when it threw. */
|
|
91
|
+
error?: unknown;
|
|
92
|
+
/** Whether the environment had a token at all. */
|
|
93
|
+
tokenPresent: boolean;
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
export interface ProveLabelOutcome {
|
|
97
|
+
verdict: ProveLabelVerdict;
|
|
98
|
+
/** Why, in the words the gate prints. `null` only when allowed. */
|
|
99
|
+
message: string | null;
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
export function proveLabelGateVerdict(read: LabelRead): ProveLabelOutcome {
|
|
103
|
+
if (read.labels !== undefined) {
|
|
104
|
+
const refusal = proveLabelViolation(read.labels);
|
|
105
|
+
return refusal ? { verdict: "REFUSE", message: refusal } : { verdict: "ALLOW", message: null };
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
const detail = read.error instanceof Error ? read.error.message : String(read.error ?? "no error reported");
|
|
109
|
+
|
|
110
|
+
if (!read.tokenPresent) {
|
|
111
|
+
return {
|
|
112
|
+
verdict: "UNMEASURED",
|
|
113
|
+
message:
|
|
114
|
+
"prove-label was NOT checked: no GITHUB_TOKEN or GH_TOKEN in this environment, so the " +
|
|
115
|
+
`issue's labels could not be read (${detail}). This is UNMEASURED, not clean — an issue ` +
|
|
116
|
+
"carrying `needs-prove` would look the same from here.",
|
|
117
|
+
};
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
return {
|
|
121
|
+
verdict: "REFUSE",
|
|
122
|
+
message:
|
|
123
|
+
"Close gate blocked: a token was present and the issue's labels still could not be read " +
|
|
124
|
+
`(${detail}). "No blocking label" and "could not find out" are different facts, and this ` +
|
|
125
|
+
"is the second one — re-run once GitHub is reachable rather than closing on a read that " +
|
|
126
|
+
"never happened (#405).",
|
|
127
|
+
};
|
|
128
|
+
}
|
|
@@ -0,0 +1,302 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Is a marked block actually reachable? (#200, Phase 1)
|
|
3
|
+
*
|
|
4
|
+
* This repo's strong form of verification is marker extraction plus
|
|
5
|
+
* `new Function`: a test slices the source between two comments and executes
|
|
6
|
+
* the slice over a sandbox. It proves the extracted logic refuses for the
|
|
7
|
+
* right reason. It does not prove the block runs.
|
|
8
|
+
*
|
|
9
|
+
* Measured, on 2026-10-08: wrapping the `BLOCKING-GRADES` region of
|
|
10
|
+
* workflows/ship.js in `if (false) { ... }` — with the wrapper placed OUTSIDE
|
|
11
|
+
* the marker comments, so the extracted slice stays byte-identical — left
|
|
12
|
+
* test/blocking-grades.test.ts at 19 pass / 0 fail. The same mutation of
|
|
13
|
+
* `SECURITY-DECISION` left test/security-verdict-blocks.test.ts at
|
|
14
|
+
* 113 pass / 0 fail, and of `COMMIT-STATE-GUARD` left
|
|
15
|
+
* test/record-build-commit.test.ts at 52 pass / 0 fail. Everything those
|
|
16
|
+
* suites observe is a property of the TEXT between the markers, and the text
|
|
17
|
+
* did not change.
|
|
18
|
+
*
|
|
19
|
+
* So this helper never decides from the text. It parses the file, finds where
|
|
20
|
+
* the marked region sits in the resulting tree, and reads two properties off
|
|
21
|
+
* the parse:
|
|
22
|
+
*
|
|
23
|
+
* 1. the region's ancestor chain — `if (false)`, a relocation into a
|
|
24
|
+
* function nobody calls, a loop, a `catch` all change it;
|
|
25
|
+
* 2. the statements that precede the region in each enclosing statement
|
|
26
|
+
* list — an early `return` above the block changes nothing about the
|
|
27
|
+
* chain, and is the one dead-code shape an ancestor check alone misses.
|
|
28
|
+
*
|
|
29
|
+
* None of those mutations changes a single byte between the markers.
|
|
30
|
+
*
|
|
31
|
+
* ## Permitted enclosing constructs — stated, not inferred (AC-3)
|
|
32
|
+
*
|
|
33
|
+
* A permissive list silently restores the defect, so the allowlist is tiny and
|
|
34
|
+
* every entry has a reason attached in `PERMITTED_ENCLOSING`. Anything not on
|
|
35
|
+
* it is a refusal, including constructs nobody has thought of yet: the default
|
|
36
|
+
* is deny. Note that a conditional ancestor is always *in* the chain alongside
|
|
37
|
+
* the `BlockStatement` it owns, so allowing `BlockStatement` generically is
|
|
38
|
+
* safe — an `if`/loop/`catch`/function body is caught by its own entry.
|
|
39
|
+
*
|
|
40
|
+
* Deny-by-default also means a block inside a function that IS called is
|
|
41
|
+
* refused. That is deliberate: nothing here resolves call graphs, so accepting
|
|
42
|
+
* it would mean trusting the author's word, which is the thing this module
|
|
43
|
+
* exists to stop doing.
|
|
44
|
+
*
|
|
45
|
+
* ## What this cannot catch (AC-5)
|
|
46
|
+
*
|
|
47
|
+
* Reachability here is a parse-time property. A block that the parser says is
|
|
48
|
+
* unconditionally reached can still never execute at runtime:
|
|
49
|
+
*
|
|
50
|
+
* - a preceding `if (x) return` whose condition is true on every real input
|
|
51
|
+
* — the terminator scan below only sees UNCONDITIONAL siblings, because a
|
|
52
|
+
* conditional `return` above the block is the normal shape of
|
|
53
|
+
* workflows/ship.js and refusing it would reject the real file;
|
|
54
|
+
* - a preceding call that exits the process or raises on every real input;
|
|
55
|
+
* - a preceding `await` on a promise that never settles;
|
|
56
|
+
* - a top-level guard like `if (!enabled) return` where `enabled` is false
|
|
57
|
+
* in every deployed configuration.
|
|
58
|
+
*
|
|
59
|
+
* No static check sees any of those, and this one does not pretend to. It
|
|
60
|
+
* closes exactly one hole — the block's position in the program is now
|
|
61
|
+
* observed instead of assumed — and leaves the runtime hole open and written
|
|
62
|
+
* down. It is also complementary to, not a replacement for, the `new Function`
|
|
63
|
+
* mutant tests: those prove the logic refuses correctly, this proves the logic
|
|
64
|
+
* is wired in. Both properties are needed; neither implies the other.
|
|
65
|
+
*
|
|
66
|
+
* ## Fail-closed refusals
|
|
67
|
+
*
|
|
68
|
+
* Every refusal leaves through `refuse()`, whose single raise statement — the
|
|
69
|
+
* only one in this file, which the test asserts — is guarded by the one
|
|
70
|
+
* exported `REACHABILITY_REFUSE` constant. That constant exists so
|
|
71
|
+
* test/reachability-refusals.test.ts can build a mutant copy of this file with
|
|
72
|
+
* it set to 0 and show each negative case passing only because the refusal
|
|
73
|
+
* fired — see .claude/rules/checks-must-be-able-to-fail.md.
|
|
74
|
+
*/
|
|
75
|
+
|
|
76
|
+
import { parse } from "acorn";
|
|
77
|
+
|
|
78
|
+
/**
|
|
79
|
+
* The one switch every refusal goes through. Declared on a single line and
|
|
80
|
+
* assigned exactly once, so the test's mutant (`= 0`) neutralises ALL
|
|
81
|
+
* refusals and no branch can quietly bypass the mutation by raising directly.
|
|
82
|
+
*/
|
|
83
|
+
export const REACHABILITY_REFUSE = 1;
|
|
84
|
+
|
|
85
|
+
/** Raised by every refusal in this module. */
|
|
86
|
+
export class ReachabilityRefusal extends Error {
|
|
87
|
+
constructor(reason: string) {
|
|
88
|
+
super(`reachability REFUSED: ${reason}`);
|
|
89
|
+
this.name = "ReachabilityRefusal";
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
/**
|
|
94
|
+
* The complete allowlist of constructs a marked block may sit inside, with the
|
|
95
|
+
* reason each is unconditional. Everything absent from this map is refused.
|
|
96
|
+
*/
|
|
97
|
+
export const PERMITTED_ENCLOSING: Record<string, string> = {
|
|
98
|
+
Program:
|
|
99
|
+
"the module body itself — workflows/ship.js runs top to bottom, so a statement here executes on every run",
|
|
100
|
+
TryStatement:
|
|
101
|
+
"a `try` runs its block unconditionally; the handler is a separate node and is NOT permitted",
|
|
102
|
+
BlockStatement:
|
|
103
|
+
"a bare, `try` or `finally` block body; any conditional owner (if/loop/catch/function) appears in the chain under its own name and is refused there",
|
|
104
|
+
};
|
|
105
|
+
|
|
106
|
+
/**
|
|
107
|
+
* Statements that end control flow for the rest of their statement list. One
|
|
108
|
+
* of these as an UNCONDITIONAL preceding sibling makes everything after it
|
|
109
|
+
* dead, however unconditional the ancestor chain looks.
|
|
110
|
+
*/
|
|
111
|
+
export const UNCONDITIONAL_TERMINATORS: Record<string, string> = {
|
|
112
|
+
ReturnStatement:
|
|
113
|
+
"control leaves the enclosing body here, so nothing later in the same statement list can run — the #200 `early return` mutation",
|
|
114
|
+
ThrowStatement:
|
|
115
|
+
"an error is raised unconditionally, so the rest of the statement list is dead code",
|
|
116
|
+
BreakStatement:
|
|
117
|
+
"control leaves the enclosing loop or switch case, skipping everything after it in the list",
|
|
118
|
+
ContinueStatement:
|
|
119
|
+
"control jumps to the next iteration, skipping everything after it in the list",
|
|
120
|
+
};
|
|
121
|
+
|
|
122
|
+
/**
|
|
123
|
+
* acorn options. `allowReturnOutsideFunction` and `allowAwaitOutsideFunction`
|
|
124
|
+
* are required because workflows/ship.js is a module body that the Workflow
|
|
125
|
+
* runtime wraps in an async function before running it, so it legitimately
|
|
126
|
+
* contains top-level `return` and `await`. Both options only widen what
|
|
127
|
+
* PARSES; neither affects the ancestor chain a parsed block gets.
|
|
128
|
+
*/
|
|
129
|
+
const PARSE_OPTIONS = {
|
|
130
|
+
ecmaVersion: "latest",
|
|
131
|
+
sourceType: "module",
|
|
132
|
+
allowReturnOutsideFunction: true,
|
|
133
|
+
allowAwaitOutsideFunction: true,
|
|
134
|
+
allowHashBang: true,
|
|
135
|
+
} as const;
|
|
136
|
+
|
|
137
|
+
type AstNode = { type: string; start: number; end: number };
|
|
138
|
+
|
|
139
|
+
function refuse(reason: string): void {
|
|
140
|
+
if (REACHABILITY_REFUSE) throw new ReachabilityRefusal(reason);
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
function isNode(value: unknown): value is AstNode {
|
|
144
|
+
return (
|
|
145
|
+
typeof value === "object" &&
|
|
146
|
+
value !== null &&
|
|
147
|
+
typeof (value as AstNode).type === "string" &&
|
|
148
|
+
typeof (value as AstNode).start === "number" &&
|
|
149
|
+
typeof (value as AstNode).end === "number"
|
|
150
|
+
);
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
/** Depth-first walk collecting every node that fully contains `[start, end]`. */
|
|
154
|
+
function ancestorsOf(node: AstNode, start: number, end: number, into: AstNode[]): void {
|
|
155
|
+
if (node.start <= start && node.end >= end) into.push(node);
|
|
156
|
+
for (const value of Object.values(node as unknown as Record<string, unknown>)) {
|
|
157
|
+
if (Array.isArray(value)) {
|
|
158
|
+
for (const child of value) if (isNode(child)) ancestorsOf(child, start, end, into);
|
|
159
|
+
} else if (isNode(value)) {
|
|
160
|
+
ancestorsOf(value, start, end, into);
|
|
161
|
+
}
|
|
162
|
+
}
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
function parseOrRefuse(source: string): AstNode | null {
|
|
166
|
+
try {
|
|
167
|
+
return parse(source, PARSE_OPTIONS) as unknown as AstNode;
|
|
168
|
+
} catch (err) {
|
|
169
|
+
refuse(`the source does not parse as JavaScript: ${(err as Error).message}`);
|
|
170
|
+
return null;
|
|
171
|
+
}
|
|
172
|
+
}
|
|
173
|
+
|
|
174
|
+
function ancestorNodes(source: string, start: number, end: number): AstNode[] {
|
|
175
|
+
const tree = parseOrRefuse(source);
|
|
176
|
+
if (!tree) return []; // mutant path only; the real one refused above.
|
|
177
|
+
|
|
178
|
+
const chain: AstNode[] = [];
|
|
179
|
+
ancestorsOf(tree, start, end, chain);
|
|
180
|
+
|
|
181
|
+
if (chain.length === 0) {
|
|
182
|
+
refuse(
|
|
183
|
+
`no parsed node contains bytes [${start}, ${end}) — the range is outside the program, so its position cannot be read`,
|
|
184
|
+
);
|
|
185
|
+
}
|
|
186
|
+
return chain;
|
|
187
|
+
}
|
|
188
|
+
|
|
189
|
+
/**
|
|
190
|
+
* The parsed ancestors of the byte range `[start, end)`, outermost first.
|
|
191
|
+
*
|
|
192
|
+
* Returns the `type` of every AST node that fully contains the range —
|
|
193
|
+
* `["Program"]` for a top-level statement,
|
|
194
|
+
* `["Program", "IfStatement", "BlockStatement"]` for one inside an `if`.
|
|
195
|
+
* Refuses if the source does not parse; an empty chain is impossible for a
|
|
196
|
+
* valid range, so it is also refused rather than read as "no ancestors".
|
|
197
|
+
*/
|
|
198
|
+
export function enclosingChain(source: string, start: number, end: number): string[] {
|
|
199
|
+
return ancestorNodes(source, start, end).map((node) => node.type);
|
|
200
|
+
}
|
|
201
|
+
|
|
202
|
+
/**
|
|
203
|
+
* The first unconditional terminator that precedes the region in any enclosing
|
|
204
|
+
* statement list, innermost list first. `null` when nothing does.
|
|
205
|
+
*
|
|
206
|
+
* Only DIRECT siblings count. A `return` nested inside a preceding `if` is
|
|
207
|
+
* conditional, and refusing those would reject workflows/ship.js, every marked
|
|
208
|
+
* block of which sits below a guard of exactly that shape.
|
|
209
|
+
*/
|
|
210
|
+
function precedingTerminator(
|
|
211
|
+
chain: AstNode[],
|
|
212
|
+
start: number,
|
|
213
|
+
): { statement: string; owner: string } | null {
|
|
214
|
+
for (const node of [...chain].reverse()) {
|
|
215
|
+
const body = (node as unknown as { body?: unknown }).body;
|
|
216
|
+
if (!Array.isArray(body)) continue;
|
|
217
|
+
for (const statement of body) {
|
|
218
|
+
if (!isNode(statement)) continue;
|
|
219
|
+
if (statement.end > start) break; // reached the region itself
|
|
220
|
+
if (statement.type in UNCONDITIONAL_TERMINATORS) {
|
|
221
|
+
return { statement: statement.type, owner: node.type };
|
|
222
|
+
}
|
|
223
|
+
}
|
|
224
|
+
}
|
|
225
|
+
return null;
|
|
226
|
+
}
|
|
227
|
+
|
|
228
|
+
/**
|
|
229
|
+
* Refuse unless the `${markerName}-START` / `${markerName}-END` region of
|
|
230
|
+
* `source` sits somewhere that runs unconditionally. Returns the ancestor
|
|
231
|
+
* chain on acceptance.
|
|
232
|
+
*
|
|
233
|
+
* The markers are located by text because comments are the only way to name a
|
|
234
|
+
* region — but nothing about the region's CONTENT is inspected, and the
|
|
235
|
+
* accept/refuse decision is read entirely off the parse.
|
|
236
|
+
*/
|
|
237
|
+
export function assertMarkedBlockReachable(source: string, markerName: string): string[] {
|
|
238
|
+
const startMarker = `${markerName}-START`;
|
|
239
|
+
const endMarker = `${markerName}-END`;
|
|
240
|
+
|
|
241
|
+
const startCount = source.split(startMarker).length - 1;
|
|
242
|
+
const endCount = source.split(endMarker).length - 1;
|
|
243
|
+
|
|
244
|
+
// Absent markers first: a typo'd or renamed marker must never read as
|
|
245
|
+
// "nothing to check here, carry on".
|
|
246
|
+
if (startCount === 0) {
|
|
247
|
+
refuse(`${startMarker} is absent from the source`);
|
|
248
|
+
return [];
|
|
249
|
+
}
|
|
250
|
+
if (endCount === 0) {
|
|
251
|
+
refuse(`${endMarker} is absent from the source`);
|
|
252
|
+
return [];
|
|
253
|
+
}
|
|
254
|
+
// #200: nothing asserted this before, so a dead duplicate of the pair
|
|
255
|
+
// elsewhere in the file satisfied the slice while the live copy was
|
|
256
|
+
// unreachable. Ambiguity about WHICH pair is being checked is a refusal.
|
|
257
|
+
if (startCount > 1) {
|
|
258
|
+
refuse(`${startMarker} occurs ${startCount} times — the marked block must be unique`);
|
|
259
|
+
return [];
|
|
260
|
+
}
|
|
261
|
+
if (endCount > 1) {
|
|
262
|
+
refuse(`${endMarker} occurs ${endCount} times — the marked block must be unique`);
|
|
263
|
+
return [];
|
|
264
|
+
}
|
|
265
|
+
|
|
266
|
+
const start = source.indexOf(startMarker) + startMarker.length;
|
|
267
|
+
const end = source.indexOf(endMarker);
|
|
268
|
+
if (end <= start) {
|
|
269
|
+
refuse(`${endMarker} appears before ${startMarker} — the region is inside out`);
|
|
270
|
+
return [];
|
|
271
|
+
}
|
|
272
|
+
|
|
273
|
+
const nodes = ancestorNodes(source, start, end);
|
|
274
|
+
if (nodes.length === 0) return []; // mutant path only; the real one refused above.
|
|
275
|
+
const chain = nodes.map((node) => node.type);
|
|
276
|
+
|
|
277
|
+
if (chain[0] !== "Program") {
|
|
278
|
+
refuse(`the ancestor chain does not start at Program: [${chain.join(" > ")}]`);
|
|
279
|
+
return [];
|
|
280
|
+
}
|
|
281
|
+
|
|
282
|
+
for (const node of chain) {
|
|
283
|
+
if (!(node in PERMITTED_ENCLOSING)) {
|
|
284
|
+
refuse(
|
|
285
|
+
`${markerName} sits inside ${node}, which is not an unconditional construct — ` +
|
|
286
|
+
`chain was [${chain.join(" > ")}], permitted: [${Object.keys(PERMITTED_ENCLOSING).join(", ")}]`,
|
|
287
|
+
);
|
|
288
|
+
return [];
|
|
289
|
+
}
|
|
290
|
+
}
|
|
291
|
+
|
|
292
|
+
const dead = precedingTerminator(nodes, start);
|
|
293
|
+
if (dead) {
|
|
294
|
+
refuse(
|
|
295
|
+
`${markerName} follows an unconditional ${dead.statement} in the same ${dead.owner} — ` +
|
|
296
|
+
`control never reaches it, even though its ancestor chain [${chain.join(" > ")}] is permitted`,
|
|
297
|
+
);
|
|
298
|
+
return [];
|
|
299
|
+
}
|
|
300
|
+
|
|
301
|
+
return chain;
|
|
302
|
+
}
|