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.
Files changed (113) hide show
  1. package/lib/affected-tests.ts +398 -0
  2. package/lib/agent-audit.ts +2 -3
  3. package/lib/agent-worktree.ts +287 -0
  4. package/lib/agents-md-sections.ts +81 -16
  5. package/lib/behavioral-cache.ts +150 -2
  6. package/lib/branch-protection.ts +790 -0
  7. package/lib/brief-ac-alignment.ts +104 -0
  8. package/lib/brief-references.ts +205 -0
  9. package/lib/bun-version.ts +93 -14
  10. package/lib/check-remedy.ts +140 -0
  11. package/lib/ci-checkout.ts +17 -0
  12. package/lib/ci-history-depth.ts +159 -0
  13. package/lib/ci-setup-step.ts +96 -0
  14. package/lib/claude-code-action.ts +85 -0
  15. package/lib/claude-tool-vocabulary.ts +188 -0
  16. package/lib/cli-commands.ts +15 -0
  17. package/lib/commit-sha.ts +42 -0
  18. package/lib/commit-subject.ts +90 -0
  19. package/lib/compliance-report.ts +377 -45
  20. package/lib/compliance.ts +191 -17
  21. package/lib/config-loader.ts +39 -1
  22. package/lib/config-trackable.ts +391 -0
  23. package/lib/conformity.ts +1087 -100
  24. package/lib/containment.ts +238 -0
  25. package/lib/content-hash.ts +24 -0
  26. package/lib/create-sc.ts +249 -16
  27. package/lib/dev-liveness.ts +180 -0
  28. package/lib/discovery-branch-points.ts +432 -0
  29. package/lib/discovery-stability.ts +481 -0
  30. package/lib/distribution-currency.ts +186 -0
  31. package/lib/doc-routing.ts +157 -0
  32. package/lib/evidence-prevalidator.ts +224 -2
  33. package/lib/evidence-satisfiability.ts +534 -12
  34. package/lib/failure-intake.ts +317 -0
  35. package/lib/fallow-availability.ts +157 -0
  36. package/lib/fs-write-capabilities.ts +232 -0
  37. package/lib/gate-run-split.ts +147 -0
  38. package/lib/generators/agents-md.ts +140 -32
  39. package/lib/git-isolation.ts +140 -0
  40. package/lib/github.ts +15 -0
  41. package/lib/google-auth-action.ts +93 -0
  42. package/lib/harness-project.ts +48 -0
  43. package/lib/harness-provenance.ts +255 -0
  44. package/lib/hook-evidence.ts +235 -0
  45. package/lib/hook-scopes.ts +386 -0
  46. package/lib/hook-target-tree.ts +398 -0
  47. package/lib/hook-trees.ts +447 -0
  48. package/lib/js-top-level-code.ts +78 -10
  49. package/lib/junit-checks.ts +52 -0
  50. package/lib/launch-base.ts +253 -0
  51. package/lib/line-citation.ts +372 -0
  52. package/lib/orphan-reaper.ts +468 -0
  53. package/lib/parity-binding.ts +205 -0
  54. package/lib/per-test-timeouts.ts +219 -0
  55. package/lib/plan-coverage.ts +151 -0
  56. package/lib/prior-branch.ts +201 -8
  57. package/lib/process-table.ts +146 -0
  58. package/lib/project-state-derivation.ts +219 -0
  59. package/lib/project-state-root.ts +258 -0
  60. package/lib/published-artifact.ts +525 -0
  61. package/lib/readdir-sorted.ts +45 -0
  62. package/lib/review-execution-reading.ts +206 -0
  63. package/lib/review-tool-agreement.ts +433 -0
  64. package/lib/rule-promotion.ts +234 -0
  65. package/lib/rule-retirement.ts +525 -0
  66. package/lib/run-branch.ts +612 -0
  67. package/lib/rungate-schema.ts +19 -0
  68. package/lib/runner-home.ts +274 -0
  69. package/lib/sc-id-cross-tree.ts +19 -7
  70. package/lib/sc-ids.ts +121 -13
  71. package/lib/sc-reservations.ts +289 -0
  72. package/lib/scaffold/ai-review-findings.ts +403 -0
  73. package/lib/scaffold/ai-review-step.ts +4661 -64
  74. package/lib/scaffold/managed-workflow.ts +587 -192
  75. package/lib/scaffold/owned-files.ts +152 -45
  76. package/lib/scaffold/pre-push-hook.ts +49 -5
  77. package/lib/scaffold/steps.ts +1413 -244
  78. package/lib/scaffold/workflow-census.ts +217 -0
  79. package/lib/scaffold/workflow-drift.ts +217 -0
  80. package/lib/scaffold/write-steps.ts +4 -0
  81. package/lib/scan-budget.ts +247 -0
  82. package/lib/scanner.ts +43 -51
  83. package/lib/scratch-roots.ts +50 -5
  84. package/lib/screenshot-discovery.ts +121 -0
  85. package/lib/screenshot-upload.ts +41 -1
  86. package/lib/secret-patterns.ts +511 -8
  87. package/lib/ship-mode.ts +219 -0
  88. package/lib/source-slice.ts +294 -0
  89. package/lib/stale-cleanup.ts +37 -3
  90. package/lib/suite-flake.ts +278 -0
  91. package/lib/suite-measurement.ts +23 -4
  92. package/lib/suite-run-reading.ts +241 -1
  93. package/lib/suite-timeout-margin.ts +193 -0
  94. package/lib/test-case-bodies.ts +883 -0
  95. package/lib/test-case-deletion.ts +653 -0
  96. package/lib/test-census.ts +97 -29
  97. package/lib/test-command-positions.ts +274 -0
  98. package/lib/test-suite-lock.ts +159 -16
  99. package/lib/tool-probe.ts +31 -9
  100. package/lib/top-level-cd.ts +393 -0
  101. package/lib/tree-entries.ts +89 -0
  102. package/lib/ts-ast.ts +200 -0
  103. package/lib/walk-test-files.ts +97 -0
  104. package/lib/workflow-actions.ts +263 -0
  105. package/lib/worktree-collect.ts +177 -5
  106. package/lib/worktree-repo.ts +36 -1
  107. package/package.json +2 -1
  108. package/scripts/ai-review-findings.ts +45 -0
  109. package/scripts/create-sc.ts +21 -1
  110. package/scripts/extract-constraints.ts +107 -7
  111. package/scripts/generate-code-map.ts +23 -30
  112. package/scripts/scaffold-project.ts +8 -1
  113. 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
+ }