rungate 0.6.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 +81 -16
- package/lib/behavioral-cache.ts +150 -2
- 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 +93 -14
- package/lib/check-remedy.ts +140 -0
- package/lib/ci-checkout.ts +17 -0
- 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 +191 -17
- package/lib/config-loader.ts +39 -1
- package/lib/config-trackable.ts +391 -0
- package/lib/conformity.ts +1087 -100
- package/lib/containment.ts +238 -0
- package/lib/content-hash.ts +24 -0
- package/lib/create-sc.ts +249 -16
- 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/evidence-prevalidator.ts +224 -2
- package/lib/evidence-satisfiability.ts +534 -12
- package/lib/failure-intake.ts +317 -0
- package/lib/fallow-availability.ts +157 -0
- package/lib/fs-write-capabilities.ts +232 -0
- package/lib/gate-run-split.ts +147 -0
- package/lib/generators/agents-md.ts +140 -32
- 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 +52 -0
- package/lib/launch-base.ts +253 -0
- package/lib/line-citation.ts +372 -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/published-artifact.ts +525 -0
- package/lib/readdir-sorted.ts +45 -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-id-cross-tree.ts +19 -7
- 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 +4661 -64
- package/lib/scaffold/managed-workflow.ts +587 -192
- package/lib/scaffold/owned-files.ts +152 -45
- package/lib/scaffold/pre-push-hook.ts +49 -5
- package/lib/scaffold/steps.ts +1413 -244
- package/lib/scaffold/workflow-census.ts +217 -0
- package/lib/scaffold/workflow-drift.ts +217 -0
- package/lib/scaffold/write-steps.ts +4 -0
- package/lib/scan-budget.ts +247 -0
- package/lib/scanner.ts +43 -51
- 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/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 +241 -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-suite-lock.ts +159 -16
- package/lib/tool-probe.ts +31 -9
- package/lib/top-level-cd.ts +393 -0
- package/lib/tree-entries.ts +89 -0
- package/lib/ts-ast.ts +200 -0
- 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/create-sc.ts +21 -1
- package/scripts/extract-constraints.ts +107 -7
- package/scripts/generate-code-map.ts +23 -30
- package/scripts/scaffold-project.ts +8 -1
- package/scripts/sync-sc-status.ts +77 -16
package/lib/ts-ast.ts
ADDED
|
@@ -0,0 +1,200 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Parse TypeScript source into an ESTree AST, for detectors that must not be
|
|
3
|
+
* fooled by their own fixtures.
|
|
4
|
+
*
|
|
5
|
+
* ## Why an AST and not a regex (#968)
|
|
6
|
+
*
|
|
7
|
+
* The two detectors built on this module both replace a regex that was
|
|
8
|
+
* narrower than its own subject, and both were narrower in the SAME way: the
|
|
9
|
+
* regex described one spelling of a construct and the construct has several.
|
|
10
|
+
* `/\}\s*,\s*([0-9_]+)\s*\)\s*;/` describes `}, 60_000);` and not
|
|
11
|
+
* `}, TIMEOUT);`, `}, 60 * 1000);`, `}, 60_000)` without the semicolon, or
|
|
12
|
+
* `}, { timeout: 60_000 });` — all four of which were MEASURED on bun 1.3.14
|
|
13
|
+
* to raise the per-test budget exactly as the matched form does. Widening the
|
|
14
|
+
* regex to `\}\s*,\s*([^)]+)\)` covers them, and also covers
|
|
15
|
+
* `expect(() => { f(); }, "message").toThrow()`, which is not a timeout at
|
|
16
|
+
* all. A detector widened until it refuses everything is the same failure
|
|
17
|
+
* wearing the opposite sign.
|
|
18
|
+
*
|
|
19
|
+
* An AST ends the trade. "The third argument of a call rooted at `test`" is
|
|
20
|
+
* exact in every spelling and matches nothing else, so widening costs no
|
|
21
|
+
* precision rather than trading one for the other.
|
|
22
|
+
*
|
|
23
|
+
* It also closes the self-reference trap that
|
|
24
|
+
* `test/scratch-paths-unique.test.ts` documents at length: a detector that
|
|
25
|
+
* reads source text sees its own negative fixtures as hits, which is why that
|
|
26
|
+
* file had to exclude itself from its own scan. In an AST, `"mkdirSync("`
|
|
27
|
+
* inside a fixture is a `Literal`, and a call is a `CallExpression`. They are
|
|
28
|
+
* different node types and no amount of comment-stripping is required to tell
|
|
29
|
+
* them apart.
|
|
30
|
+
*
|
|
31
|
+
* ## Why transpile first
|
|
32
|
+
*
|
|
33
|
+
* acorn parses JavaScript. `lib/reachability.ts` uses it directly because its
|
|
34
|
+
* subject is `workflows/*.js`. These detectors read `.ts` test files, so the
|
|
35
|
+
* types come off first with `Bun.Transpiler`, which is in-process and adds no
|
|
36
|
+
* dependency.
|
|
37
|
+
*
|
|
38
|
+
* The consequence to know: **positions refer to the TRANSPILED text, not the
|
|
39
|
+
* original.** `parseTsModule` returns the transpiled source alongside the tree
|
|
40
|
+
* for exactly that reason — slicing a node out of the original source would
|
|
41
|
+
* silently read the wrong characters. Callers slice `js`, never their input.
|
|
42
|
+
*/
|
|
43
|
+
|
|
44
|
+
import { parse } from "acorn";
|
|
45
|
+
|
|
46
|
+
/** The minimum of an ESTree node this module's walk relies on. */
|
|
47
|
+
export interface AstNode {
|
|
48
|
+
type: string;
|
|
49
|
+
start: number;
|
|
50
|
+
end: number;
|
|
51
|
+
[key: string]: unknown;
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
/**
|
|
55
|
+
* A parsed module: the tree, and the text its positions index into.
|
|
56
|
+
*
|
|
57
|
+
* `null` from `parseTsModule` means the source did not transpile or did not
|
|
58
|
+
* parse. Every caller treats that as a REFUSAL rather than as "no findings" —
|
|
59
|
+
* a parser that stopped parsing and a file that is clean produce the same
|
|
60
|
+
* empty list, and that is the whole defect class #968 is about.
|
|
61
|
+
*/
|
|
62
|
+
export interface ParsedModule {
|
|
63
|
+
tree: AstNode;
|
|
64
|
+
/** The transpiled JavaScript. Node `start`/`end` index into THIS string. */
|
|
65
|
+
js: string;
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
const PARSE_OPTIONS = {
|
|
69
|
+
ecmaVersion: "latest",
|
|
70
|
+
sourceType: "module",
|
|
71
|
+
allowReturnOutsideFunction: true,
|
|
72
|
+
allowAwaitOutsideFunction: true,
|
|
73
|
+
allowHashBang: true,
|
|
74
|
+
} as const;
|
|
75
|
+
|
|
76
|
+
function isNode(value: unknown): value is AstNode {
|
|
77
|
+
return (
|
|
78
|
+
typeof value === "object" &&
|
|
79
|
+
value !== null &&
|
|
80
|
+
typeof (value as AstNode).type === "string" &&
|
|
81
|
+
typeof (value as AstNode).start === "number" &&
|
|
82
|
+
typeof (value as AstNode).end === "number"
|
|
83
|
+
);
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
/**
|
|
87
|
+
* Transpile TypeScript to JavaScript and parse it, or `null` if either step
|
|
88
|
+
* fails.
|
|
89
|
+
*/
|
|
90
|
+
export function parseTsModule(source: string): ParsedModule | null {
|
|
91
|
+
let js: string;
|
|
92
|
+
try {
|
|
93
|
+
js = new Bun.Transpiler({ loader: "ts" }).transformSync(source);
|
|
94
|
+
} catch {
|
|
95
|
+
return null;
|
|
96
|
+
}
|
|
97
|
+
try {
|
|
98
|
+
return { tree: parse(js, PARSE_OPTIONS) as unknown as AstNode, js };
|
|
99
|
+
} catch {
|
|
100
|
+
return null;
|
|
101
|
+
}
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
/** Every node in the tree, depth-first, parents before children. */
|
|
105
|
+
export function* walkNodes(node: AstNode): Generator<AstNode> {
|
|
106
|
+
yield node;
|
|
107
|
+
for (const value of Object.values(node)) {
|
|
108
|
+
if (Array.isArray(value)) {
|
|
109
|
+
for (const child of value) if (isNode(child)) yield* walkNodes(child);
|
|
110
|
+
} else if (isNode(value)) {
|
|
111
|
+
yield* walkNodes(value);
|
|
112
|
+
}
|
|
113
|
+
}
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
/**
|
|
117
|
+
* The identifier a callee is rooted at, following member access and call
|
|
118
|
+
* chains: `test` for `test`, `test.only`, `test.each([1])`,
|
|
119
|
+
* `test.skip.each([1])`. `null` when the root is not a plain identifier.
|
|
120
|
+
*
|
|
121
|
+
* This is what makes "a per-test timeout" one question instead of a list of
|
|
122
|
+
* spellings to keep current.
|
|
123
|
+
*/
|
|
124
|
+
export function calleeRoot(callee: unknown): string | null {
|
|
125
|
+
let node = callee;
|
|
126
|
+
for (;;) {
|
|
127
|
+
if (!isNode(node)) return null;
|
|
128
|
+
if (node.type === "Identifier") return String(node.name);
|
|
129
|
+
if (node.type === "MemberExpression") node = node.object;
|
|
130
|
+
else if (node.type === "CallExpression") node = node.callee;
|
|
131
|
+
else if (node.type === "TaggedTemplateExpression") node = node.tag;
|
|
132
|
+
else return null;
|
|
133
|
+
}
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
/**
|
|
137
|
+
* The property name accessed directly on the root identifier, or `null` when
|
|
138
|
+
* the callee IS the root. `rootProperty(bt.test.only)` is `"test"`.
|
|
139
|
+
*
|
|
140
|
+
* Needed so a namespace import (`import * as bt from "bun:test"`, then
|
|
141
|
+
* `bt.test(…)`) resolves to the same question as a named one, rather than
|
|
142
|
+
* being a spelling the detector cannot see.
|
|
143
|
+
*/
|
|
144
|
+
export function rootProperty(callee: unknown): string | null {
|
|
145
|
+
let node = callee;
|
|
146
|
+
let property: string | null = null;
|
|
147
|
+
for (;;) {
|
|
148
|
+
if (!isNode(node)) return null;
|
|
149
|
+
if (node.type === "Identifier") return property;
|
|
150
|
+
if (node.type === "MemberExpression") {
|
|
151
|
+
const prop = node.property as AstNode | undefined;
|
|
152
|
+
// Computed access (`bt["test"]`) is deliberately not resolved — see
|
|
153
|
+
// the UNRESOLVED boundary in lib/per-test-timeouts.ts.
|
|
154
|
+
property = !node.computed && prop?.type === "Identifier" ? String(prop.name) : null;
|
|
155
|
+
node = node.object;
|
|
156
|
+
} else if (node.type === "CallExpression") node = node.callee;
|
|
157
|
+
else if (node.type === "TaggedTemplateExpression") node = node.tag;
|
|
158
|
+
else return null;
|
|
159
|
+
}
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
/** What a module specifier was bound to, local name → how it was imported. */
|
|
163
|
+
export interface ImportBinding {
|
|
164
|
+
/** The module specifier, e.g. `"bun:test"`. */
|
|
165
|
+
module: string;
|
|
166
|
+
/**
|
|
167
|
+
* The name as the module exports it, or `"*"` for a namespace binding and
|
|
168
|
+
* `"default"` for a default binding.
|
|
169
|
+
*/
|
|
170
|
+
imported: string;
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
/**
|
|
174
|
+
* Every import binding in the module, keyed by the LOCAL name.
|
|
175
|
+
*
|
|
176
|
+
* This is what closes the alias hole: `import { test as t } from "bun:test"`
|
|
177
|
+
* binds local `t` to imported `test`, and a detector matching the local
|
|
178
|
+
* identifier reports clean on its own subject.
|
|
179
|
+
*/
|
|
180
|
+
export function importBindings(tree: AstNode): Map<string, ImportBinding> {
|
|
181
|
+
const out = new Map<string, ImportBinding>();
|
|
182
|
+
for (const node of walkNodes(tree)) {
|
|
183
|
+
if (node.type !== "ImportDeclaration") continue;
|
|
184
|
+
const src = node.source as AstNode | undefined;
|
|
185
|
+
if (src?.type !== "Literal" || typeof src.value !== "string") continue;
|
|
186
|
+
const module = src.value;
|
|
187
|
+
for (const s of (node.specifiers ?? []) as AstNode[]) {
|
|
188
|
+
const local = (s.local as AstNode | undefined)?.name;
|
|
189
|
+
if (typeof local !== "string") continue;
|
|
190
|
+
const imported =
|
|
191
|
+
s.type === "ImportNamespaceSpecifier"
|
|
192
|
+
? "*"
|
|
193
|
+
: s.type === "ImportDefaultSpecifier"
|
|
194
|
+
? "default"
|
|
195
|
+
: String((s.imported as AstNode | undefined)?.name ?? local);
|
|
196
|
+
out.set(local, { module, imported });
|
|
197
|
+
}
|
|
198
|
+
}
|
|
199
|
+
return out;
|
|
200
|
+
}
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Every test file under a directory, at any depth (#733).
|
|
3
|
+
*
|
|
4
|
+
* A LEAF module, in the shape `lib/git-dates.ts` established (#508) and
|
|
5
|
+
* `lib/local-calendar-day.ts` followed: one exported walk, no relative
|
|
6
|
+
* imports, so there is exactly one thing to mutate and every call site names
|
|
7
|
+
* the same rule.
|
|
8
|
+
*
|
|
9
|
+
* ## Why this exists
|
|
10
|
+
*
|
|
11
|
+
* `scripts/sync-sc-status.ts` walked `specs/` recursively and `test/` flat —
|
|
12
|
+
* three times, in three places, each `readdirSync(d).filter(f =>
|
|
13
|
+
* f.endsWith(".test.ts"))`. Measured on `main` at `eb3612a3`: 59 `.test.ts`
|
|
14
|
+
* files in `test/unit` and **50** (spec, id) credits the credit rule could
|
|
15
|
+
* not see.
|
|
16
|
+
*
|
|
17
|
+
* Nothing was red. `lib/sc-cover.ts` reaches the same verdict by a second
|
|
18
|
+
* route — it runs `matchPattern(d)` and executes the assertion — and a
|
|
19
|
+
* conformity matcher happens to pass for all 50, so the working route
|
|
20
|
+
* covered for the broken one and the checkboxes were right anyway. Two
|
|
21
|
+
* routes to one verdict with no comparison between them is
|
|
22
|
+
* `.claude/rules/checks-must-be-able-to-fail.md`'s fourth shape, and the
|
|
23
|
+
* only reason it surfaced at all is that somebody counted the files.
|
|
24
|
+
*
|
|
25
|
+
* ## Why the skip set is a parameter and not a constant in here
|
|
26
|
+
*
|
|
27
|
+
* `test/fixtures/` must earn no SC credit — a scaffolding tree that plants
|
|
28
|
+
* example criteria would otherwise tick real checkboxes. But "which
|
|
29
|
+
* directories are uninteresting" is the CALLER's question:
|
|
30
|
+
* `lib/test-census.ts` counts declarations and deliberately descends into
|
|
31
|
+
* places the credit rule must not. Baking one answer in here would make the
|
|
32
|
+
* next caller add a second walk, which is the defect this module exists to
|
|
33
|
+
* remove.
|
|
34
|
+
*/
|
|
35
|
+
import { readdirSync } from "fs";
|
|
36
|
+
import { join } from "path";
|
|
37
|
+
|
|
38
|
+
/**
|
|
39
|
+
* Directories the SC credit rule does not descend into.
|
|
40
|
+
*
|
|
41
|
+
* `fixtures` is the load-bearing entry: a planted criterion in a scaffolding
|
|
42
|
+
* tree is example text, not a claim about this project. The rest are the
|
|
43
|
+
* ordinary noise any walk of a repository has to decline.
|
|
44
|
+
*/
|
|
45
|
+
export const TEST_WALK_SKIP: ReadonlySet<string> = new Set([
|
|
46
|
+
"fixtures",
|
|
47
|
+
"node_modules",
|
|
48
|
+
"dist",
|
|
49
|
+
"build",
|
|
50
|
+
"coverage",
|
|
51
|
+
]);
|
|
52
|
+
|
|
53
|
+
/** What counts as a test file to the credit rule. */
|
|
54
|
+
const TEST_FILE = /\.test\.ts$/;
|
|
55
|
+
|
|
56
|
+
/**
|
|
57
|
+
* Every test file under `dir`, as paths relative to `dir`, sorted.
|
|
58
|
+
*
|
|
59
|
+
* Sorted deliberately, and it is not cosmetic: `readdir` order is a property
|
|
60
|
+
* of the filesystem, so two walks of one tree agree without anybody having
|
|
61
|
+
* asked for an order. A caller that reports these paths to a human — all
|
|
62
|
+
* three in `sync-sc-status.ts` do — would otherwise produce output that
|
|
63
|
+
* reorders between machines for no reason anyone can see (#500's
|
|
64
|
+
* determinism row: comparing two walks of the same tree proves nothing, so
|
|
65
|
+
* the ORDER has to be the thing that is fixed).
|
|
66
|
+
*
|
|
67
|
+
* A directory that does not exist yields `[]` rather than throwing, because
|
|
68
|
+
* an unscaffolded project legitimately has no `test/`. A directory that
|
|
69
|
+
* exists and cannot be read is a different fact and is allowed to throw —
|
|
70
|
+
* an empty list there would be a permission error reported as a clean tree.
|
|
71
|
+
*/
|
|
72
|
+
export function walkTestFiles(dir: string, skip: ReadonlySet<string> = TEST_WALK_SKIP): string[] {
|
|
73
|
+
const out: string[] = [];
|
|
74
|
+
const walk = (abs: string, rel: string) => {
|
|
75
|
+
let entries;
|
|
76
|
+
try {
|
|
77
|
+
entries = readdirSync(abs, { withFileTypes: true });
|
|
78
|
+
} catch (e: any) {
|
|
79
|
+
// Only an absent directory is tolerated, and only at the root. Anything
|
|
80
|
+
// else — EACCES, ENOTDIR — is a reading nobody took, and returning []
|
|
81
|
+
// for it would report an unreadable tree as a tree with no tests.
|
|
82
|
+
if (e?.code === "ENOENT") return;
|
|
83
|
+
throw e;
|
|
84
|
+
}
|
|
85
|
+
for (const e of entries) {
|
|
86
|
+
const next = rel ? `${rel}/${e.name}` : e.name;
|
|
87
|
+
if (e.isDirectory()) {
|
|
88
|
+
if (skip.has(e.name) || e.name.startsWith(".")) continue;
|
|
89
|
+
walk(join(abs, e.name), next);
|
|
90
|
+
} else if (e.isFile() && TEST_FILE.test(e.name)) {
|
|
91
|
+
out.push(next);
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
};
|
|
95
|
+
walk(dir, "");
|
|
96
|
+
return out.sort();
|
|
97
|
+
}
|
|
@@ -0,0 +1,263 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Every action the scaffold's generated workflows reference, and how each is
|
|
3
|
+
* pinned (#377).
|
|
4
|
+
*
|
|
5
|
+
* In the shape `lib/bun-version.ts` (#622) and `lib/claude-code-action.ts`
|
|
6
|
+
* (#689) established: one declaration, so there is one thing to mutate and
|
|
7
|
+
* every position is CHECKED against it rather than agreeing with it by
|
|
8
|
+
* coincidence.
|
|
9
|
+
*
|
|
10
|
+
* It imports two per-action declaration modules and nothing else, and that is
|
|
11
|
+
* the point rather than an exception (#631). `lib/claude-code-action.ts` and
|
|
12
|
+
* `lib/google-auth-action.ts` each carry their own SHA, the date it was
|
|
13
|
+
* resolved and the trap in resolving it, and `actionPinParity` compares every
|
|
14
|
+
* position in the tree to them. Re-typing either value here would make this
|
|
15
|
+
* file a second position — #689's defect reinstated inside the registry that
|
|
16
|
+
* exists to prevent it. So this list says WHICH actions the generator may
|
|
17
|
+
* emit and HOW each is pinned; the two modules say WHAT the pin is.
|
|
18
|
+
*
|
|
19
|
+
* **This reaches every consumer.** `createCiWorkflows` writes `ci.yml` and
|
|
20
|
+
* `gates.yml` into every scaffolded project, so an unpinned action here is an
|
|
21
|
+
* unpinned action in every project rungate touches. That is the whole of why
|
|
22
|
+
* #377 was filed separately from #364 rather than fixed alongside it.
|
|
23
|
+
*
|
|
24
|
+
* ## The decision, made rather than left as an omission
|
|
25
|
+
*
|
|
26
|
+
* #377 named three options and asked for one to be chosen out loud. **Option
|
|
27
|
+
* 2: third-party actions are pinned to a full commit SHA; first-party
|
|
28
|
+
* `actions/*` stay on a major tag.**
|
|
29
|
+
*
|
|
30
|
+
* The argument for the split:
|
|
31
|
+
*
|
|
32
|
+
* - **`actions/*` is GitHub's own namespace, running on GitHub's own
|
|
33
|
+
* runner.** The tag is how security patches reach a consumer who is not
|
|
34
|
+
* watching — pinning it converts an automatic fix into a manual one, across
|
|
35
|
+
* every scaffolded project, with nothing in any of them refreshing it.
|
|
36
|
+
* - **A third party has a smaller security team and a different release
|
|
37
|
+
* discipline**, and `oven-sh/setup-bun` executes arbitrary setup code in
|
|
38
|
+
* the job. That is the exposure worth paying maintenance for, and it is
|
|
39
|
+
* one action rather than a class.
|
|
40
|
+
*
|
|
41
|
+
* **The counter-argument, recorded because it is real and this file is where
|
|
42
|
+
* someone will come to reverse the decision.** GitHub's own hardening guide
|
|
43
|
+
* says pin *all* actions to a SHA, and "first-party" is a trust assumption
|
|
44
|
+
* that can fail short of a platform compromise: a malicious commit to
|
|
45
|
+
* `actions/checkout` would run in every consumer's job without GitHub's
|
|
46
|
+
* infrastructure being owned. The split above trades that residual risk for
|
|
47
|
+
* a maintenance contract this project can actually honour. If that trade
|
|
48
|
+
* stops being worth it, change `PINNING` below — every position follows in
|
|
49
|
+
* the same commit, which is the point of the declaration.
|
|
50
|
+
*
|
|
51
|
+
* ## What this does NOT do
|
|
52
|
+
*
|
|
53
|
+
* It does not keep itself fresh, and neither does the suite. Staleness is a
|
|
54
|
+
* network fact: nothing readable from this tree can tell a current SHA from
|
|
55
|
+
* one that is three releases behind. A refusal keyed to a date would be a
|
|
56
|
+
* test that goes red on a day nobody changed anything, which is a test people
|
|
57
|
+
* switch off.
|
|
58
|
+
*
|
|
59
|
+
* `scripts/check-action-pins.ts` is the network check. What the suite can and
|
|
60
|
+
* does hold is the structure: one declaration, every position agreeing with
|
|
61
|
+
* it, every third-party pin a full SHA carrying its version and the date it
|
|
62
|
+
* was read. `resolvedOn` dates a reading; it does not certify it.
|
|
63
|
+
*
|
|
64
|
+
* ## When the check runs, and how a pin gets bumped (#789)
|
|
65
|
+
*
|
|
66
|
+
* #377 shipped that script and left it *"run deliberately"*, which is the
|
|
67
|
+
* same sentence as "never": nothing in this repository invoked it, and a
|
|
68
|
+
* rule nothing executes is not a rule (`.claude/rules/config-access.md` says
|
|
69
|
+
* this about ADRs; it was true of this line too).
|
|
70
|
+
*
|
|
71
|
+
* `.github/workflows/action-pins.yml` runs it weekly and on demand. It is
|
|
72
|
+
* **this repository's workflow and is not generated into consumers**, on
|
|
73
|
+
* purpose: a consumer's pin comes from the rungate version they installed,
|
|
74
|
+
* not from a question they ask GitHub themselves, and a scheduled job in
|
|
75
|
+
* every scaffolded project would hand each of them a red workflow they
|
|
76
|
+
* cannot fix. `test/action-pin-freshness-schedule.test.ts` asserts it is
|
|
77
|
+
* absent from the generator's output, so adding it to the templates is a
|
|
78
|
+
* scope change rather than a tightening.
|
|
79
|
+
*
|
|
80
|
+
* `workflow_dispatch` as well as `schedule`, because GitHub disables a
|
|
81
|
+
* schedule after 60 days of repository inactivity and a check you cannot
|
|
82
|
+
* trigger by hand fails silently on exactly the week nobody pushed.
|
|
83
|
+
*/
|
|
84
|
+
import {
|
|
85
|
+
CLAUDE_CODE_ACTION,
|
|
86
|
+
CLAUDE_CODE_ACTION_RESOLVED_ON,
|
|
87
|
+
CLAUDE_CODE_ACTION_SHA,
|
|
88
|
+
CLAUDE_CODE_ACTION_VERSION,
|
|
89
|
+
} from "./claude-code-action";
|
|
90
|
+
import {
|
|
91
|
+
GOOGLE_AUTH_ACTION,
|
|
92
|
+
GOOGLE_AUTH_ACTION_RESOLVED_ON,
|
|
93
|
+
GOOGLE_AUTH_ACTION_SHA,
|
|
94
|
+
GOOGLE_AUTH_ACTION_VERSION,
|
|
95
|
+
} from "./google-auth-action";
|
|
96
|
+
|
|
97
|
+
/**
|
|
98
|
+
* What to do when the freshness check says a pin is stale.
|
|
99
|
+
*
|
|
100
|
+
* ONE declaring position. The script prints this and no sentence of its own
|
|
101
|
+
* — two near-identical procedures is the shape where somebody updates the
|
|
102
|
+
* copy an operator does not read. It names the three fields together because
|
|
103
|
+
* bumping `sha` without `resolvedOn` leaves a reading dated to a commit it
|
|
104
|
+
* was not taken against, which is worse than no date at all.
|
|
105
|
+
*/
|
|
106
|
+
export const BUMP_PROCEDURE =
|
|
107
|
+
"Update lib/workflow-actions.ts — sha, version and resolvedOn together, in one edit — then " +
|
|
108
|
+
"re-run the scaffold so every generated position follows in the same commit. Consumers bump " +
|
|
109
|
+
"by upgrading rungate; they do not carry this check themselves (#789).";
|
|
110
|
+
|
|
111
|
+
/** How one action is referenced, and why. */
|
|
112
|
+
export type PinStyle =
|
|
113
|
+
/** A full 40-character commit SHA — the only form a publisher cannot repoint. */
|
|
114
|
+
| "sha"
|
|
115
|
+
/** A major tag, so upstream security patches reach consumers unattended. */
|
|
116
|
+
| "tag";
|
|
117
|
+
|
|
118
|
+
export interface ActionPin {
|
|
119
|
+
/** The action, by the name a `uses:` line spells. */
|
|
120
|
+
action: string;
|
|
121
|
+
style: PinStyle;
|
|
122
|
+
/** The tag this is, or is pinned as. Rendered as the trailing comment on a SHA pin. */
|
|
123
|
+
version: string;
|
|
124
|
+
/** The commit the tag dereferenced to. REQUIRED when `style` is `sha`. */
|
|
125
|
+
sha?: string;
|
|
126
|
+
/** The day the tag was dereferenced. REQUIRED when `style` is `sha`. */
|
|
127
|
+
resolvedOn?: string;
|
|
128
|
+
/** Why this style, in one sentence, for the reader deciding whether to change it. */
|
|
129
|
+
why: string;
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
/**
|
|
133
|
+
* The declared set.
|
|
134
|
+
*
|
|
135
|
+
* `test/generated-workflow-pins.test.ts` asserts every `uses:` the generator
|
|
136
|
+
* emits is declared here, so adding an action to a template without adding it
|
|
137
|
+
* to this list fails — which is the "detector narrower than what it detects"
|
|
138
|
+
* shape #377 warned about, closed by construction rather than by a list of
|
|
139
|
+
* the three actions that happen to be in use today.
|
|
140
|
+
*/
|
|
141
|
+
export const PINNING: readonly ActionPin[] = [
|
|
142
|
+
{
|
|
143
|
+
action: "actions/checkout",
|
|
144
|
+
style: "tag",
|
|
145
|
+
version: "v4",
|
|
146
|
+
why: "GitHub's own namespace on GitHub's own runner; the tag is how a security patch reaches a consumer who is not watching",
|
|
147
|
+
},
|
|
148
|
+
{
|
|
149
|
+
action: "oven-sh/setup-bun",
|
|
150
|
+
style: "sha",
|
|
151
|
+
version: "v2",
|
|
152
|
+
// `refs/tags/v2` is a LIGHTWEIGHT tag here — `object.type` is `commit`,
|
|
153
|
+
// so `.object.sha` IS the commit and no dereference is needed. Both
|
|
154
|
+
// routes were run and agreed:
|
|
155
|
+
// gh api repos/oven-sh/setup-bun/git/ref/tags/v2 --jq .object.sha
|
|
156
|
+
// gh api repos/oven-sh/setup-bun/commits/v2 --jq .sha
|
|
157
|
+
// Recorded because #689's pin is an ANNOTATED tag, where reading
|
|
158
|
+
// `.object.sha` and stopping gives a tag object that cannot be a `uses:`
|
|
159
|
+
// pin at all — and that error was made there. Which kind a tag is, is
|
|
160
|
+
// not something to assume.
|
|
161
|
+
sha: "0c5077e51419868618aeaa5fe8019c62421857d6",
|
|
162
|
+
resolvedOn: "2026-10-19",
|
|
163
|
+
why: "third-party, executes setup code in the job, and one action is a maintenance cost this project can honour",
|
|
164
|
+
},
|
|
165
|
+
// The two actions the ai-review job runs (#631). Their SHAs are IMPORTED,
|
|
166
|
+
// never re-typed: `lib/claude-code-action.ts` and `lib/google-auth-action.ts`
|
|
167
|
+
// are each the one declaration for their action, and `actionPinParity`
|
|
168
|
+
// compares every position in the tree to them. A literal here would be a
|
|
169
|
+
// second position, which is #689's defect reinstated inside the registry
|
|
170
|
+
// that exists to prevent it. What this list adds is the OTHER property —
|
|
171
|
+
// that an action the generator emits is an action somebody decided on, and
|
|
172
|
+
// that the weekly freshness check in `scripts/check-action-pins.ts` asks
|
|
173
|
+
// GitHub about it without anyone remembering to add it.
|
|
174
|
+
{
|
|
175
|
+
action: CLAUDE_CODE_ACTION,
|
|
176
|
+
style: "sha",
|
|
177
|
+
version: CLAUDE_CODE_ACTION_VERSION,
|
|
178
|
+
sha: CLAUDE_CODE_ACTION_SHA,
|
|
179
|
+
resolvedOn: CLAUDE_CODE_ACTION_RESOLVED_ON,
|
|
180
|
+
why: "third-party, runs an autonomous agent over pull-request content, and a repointable tag would change what reviews a consumer's code without a commit saying so (#689)",
|
|
181
|
+
},
|
|
182
|
+
{
|
|
183
|
+
action: GOOGLE_AUTH_ACTION,
|
|
184
|
+
style: "sha",
|
|
185
|
+
version: GOOGLE_AUTH_ACTION_VERSION,
|
|
186
|
+
sha: GOOGLE_AUTH_ACTION_SHA,
|
|
187
|
+
resolvedOn: GOOGLE_AUTH_ACTION_RESOLVED_ON,
|
|
188
|
+
why: "third-party, and it is the step that mints the federated credential — a repointable tag on the one action holding the token is the pin that matters most (#631)",
|
|
189
|
+
},
|
|
190
|
+
] as const;
|
|
191
|
+
|
|
192
|
+
/** A full commit SHA, which is the only `uses:` form a publisher cannot repoint. */
|
|
193
|
+
export const FULL_SHA = /^[0-9a-f]{40}$/;
|
|
194
|
+
|
|
195
|
+
export function actionPin(action: string): ActionPin | null {
|
|
196
|
+
return PINNING.find(p => p.action === action) ?? null;
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
/**
|
|
200
|
+
* The exact text a `uses:` value must carry for one action.
|
|
201
|
+
*
|
|
202
|
+
* Pin and comment in ONE rendering, so there is no way to update half of a
|
|
203
|
+
* SHA pin and leave the version comment describing the other half — #689's
|
|
204
|
+
* defect, where the comment was the only thing a reader checked and it
|
|
205
|
+
* agreed with itself across two different commits.
|
|
206
|
+
*/
|
|
207
|
+
export function actionRef(action: string): string {
|
|
208
|
+
const pin = actionPin(action);
|
|
209
|
+
if (!pin) {
|
|
210
|
+
throw new Error(
|
|
211
|
+
`${action} is not declared in lib/workflow-actions.ts. Every action a generated ` +
|
|
212
|
+
`workflow references must be declared there with a pin style and a reason, or ` +
|
|
213
|
+
`consumers inherit a reference nobody decided on (#377).`,
|
|
214
|
+
);
|
|
215
|
+
}
|
|
216
|
+
if (pin.style === "tag") return `${pin.action}@${pin.version}`;
|
|
217
|
+
if (!pin.sha || !FULL_SHA.test(pin.sha)) {
|
|
218
|
+
throw new Error(
|
|
219
|
+
`${action} declares style 'sha' and carries ${pin.sha ? `'${pin.sha}'` : "no sha"}. ` +
|
|
220
|
+
`A short sha or a tag is repointable, which is the thing the style exists to prevent.`,
|
|
221
|
+
);
|
|
222
|
+
}
|
|
223
|
+
return `${pin.action}@${pin.sha} # ${pin.version}`;
|
|
224
|
+
}
|
|
225
|
+
|
|
226
|
+
/** Every `uses:` reference in a workflow document, as `{ action, ref, line }`. */
|
|
227
|
+
export function usesReferences(text: string): { action: string; ref: string; line: number }[] {
|
|
228
|
+
const out: { action: string; ref: string; line: number }[] = [];
|
|
229
|
+
text.split("\n").forEach((raw, i) => {
|
|
230
|
+
// Anchored on `uses:` so a sentence in a header comment is prose and not
|
|
231
|
+
// a position (#235). A commented-out step is excluded for the same
|
|
232
|
+
// reason: it references nothing at run time.
|
|
233
|
+
const m = /^\s*(?:-\s+)?uses:\s*([A-Za-z0-9._\/-]+)@(\S+)/.exec(raw);
|
|
234
|
+
if (!m) return;
|
|
235
|
+
out.push({ action: m[1], ref: m[2], line: i + 1 });
|
|
236
|
+
});
|
|
237
|
+
return out;
|
|
238
|
+
}
|
|
239
|
+
|
|
240
|
+
/**
|
|
241
|
+
* Every way a workflow document disagrees with the declaration.
|
|
242
|
+
*
|
|
243
|
+
* Returns the offending POSITIONS, named. "2 violations" does not send
|
|
244
|
+
* anybody to a line.
|
|
245
|
+
*/
|
|
246
|
+
export function pinViolations(text: string, file: string): string[] {
|
|
247
|
+
const out: string[] = [];
|
|
248
|
+
for (const u of usesReferences(text)) {
|
|
249
|
+
const pin = actionPin(u.action);
|
|
250
|
+
if (!pin) {
|
|
251
|
+
out.push(`${file}:${u.line} uses ${u.action}, which lib/workflow-actions.ts does not declare`);
|
|
252
|
+
continue;
|
|
253
|
+
}
|
|
254
|
+
const expected = actionRef(u.action).split("@")[1].split(" ")[0];
|
|
255
|
+
if (u.ref !== expected) {
|
|
256
|
+
out.push(
|
|
257
|
+
`${file}:${u.line} pins ${u.action}@${u.ref}; the declaration says ${expected}` +
|
|
258
|
+
(pin.style === "sha" ? ` (${pin.version}, read ${pin.resolvedOn})` : ""),
|
|
259
|
+
);
|
|
260
|
+
}
|
|
261
|
+
}
|
|
262
|
+
return out;
|
|
263
|
+
}
|