rungate 0.5.0 → 0.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/lib/affected-tests.ts +398 -0
- package/lib/agent-audit.ts +2 -3
- package/lib/agent-worktree.ts +287 -0
- package/lib/agents-md-sections.ts +209 -0
- package/lib/behavioral-cache.ts +150 -2
- package/lib/branch-diff.ts +139 -0
- package/lib/branch-protection.ts +790 -0
- package/lib/brief-ac-alignment.ts +104 -0
- package/lib/brief-references.ts +205 -0
- package/lib/bun-version.ts +347 -0
- package/lib/check-remedy.ts +140 -0
- package/lib/ci-checkout.ts +18 -1
- package/lib/ci-history-depth.ts +159 -0
- package/lib/ci-setup-step.ts +96 -0
- package/lib/claude-code-action.ts +85 -0
- package/lib/claude-tool-vocabulary.ts +188 -0
- package/lib/cli-commands.ts +15 -0
- package/lib/commit-sha.ts +42 -0
- package/lib/commit-subject.ts +90 -0
- package/lib/compliance-report.ts +377 -45
- package/lib/compliance.ts +196 -20
- package/lib/config-loader.ts +51 -1
- package/lib/config-trackable.ts +391 -0
- package/lib/conformity.ts +1272 -189
- package/lib/containment.ts +238 -0
- package/lib/content-hash.ts +24 -0
- package/lib/context-docs.ts +143 -28
- package/lib/create-brief.ts +2 -1
- package/lib/create-sc.ts +323 -4
- package/lib/dev-liveness.ts +180 -0
- package/lib/discovery-branch-points.ts +432 -0
- package/lib/discovery-stability.ts +481 -0
- package/lib/distribution-currency.ts +186 -0
- package/lib/doc-routing.ts +157 -0
- package/lib/doc-scan-targets.ts +9 -0
- package/lib/evidence-command-transport.ts +160 -0
- package/lib/evidence-prevalidator.ts +246 -2
- package/lib/evidence-satisfiability.ts +534 -12
- package/lib/failure-intake.ts +317 -0
- package/lib/fallow-availability.ts +286 -0
- package/lib/fs-write-capabilities.ts +232 -0
- package/lib/gate-refusal-currency.ts +112 -0
- package/lib/gate-run-split.ts +147 -0
- package/lib/gate-timeouts.ts +82 -0
- package/lib/generators/agent-briefs.ts +4 -1
- package/lib/generators/agents-md.ts +204 -48
- package/lib/generators/code-map.ts +2 -1
- package/lib/generators/types.ts +8 -0
- package/lib/git-dates.ts +55 -0
- package/lib/git-isolation.ts +140 -0
- package/lib/github.ts +15 -0
- package/lib/google-auth-action.ts +93 -0
- package/lib/harness-project.ts +48 -0
- package/lib/harness-provenance.ts +255 -0
- package/lib/hook-evidence.ts +235 -0
- package/lib/hook-scopes.ts +386 -0
- package/lib/hook-target-tree.ts +398 -0
- package/lib/hook-trees.ts +447 -0
- package/lib/js-top-level-code.ts +78 -10
- package/lib/junit-checks.ts +536 -0
- package/lib/launch-base.ts +253 -0
- package/lib/line-citation.ts +372 -0
- package/lib/local-calendar-day.ts +78 -0
- package/lib/orphan-reaper.ts +468 -0
- package/lib/parity-binding.ts +205 -0
- package/lib/per-test-timeouts.ts +219 -0
- package/lib/plan-coverage.ts +151 -0
- package/lib/prior-branch.ts +201 -8
- package/lib/process-table.ts +146 -0
- package/lib/project-state-derivation.ts +219 -0
- package/lib/project-state-root.ts +258 -0
- package/lib/project-state-shape.ts +59 -0
- package/lib/promote-outputs.ts +6 -2
- package/lib/published-artifact.ts +525 -0
- package/lib/readdir-sorted.ts +45 -0
- package/lib/report-provenance.ts +156 -0
- package/lib/review-execution-reading.ts +206 -0
- package/lib/review-tool-agreement.ts +433 -0
- package/lib/rule-promotion.ts +234 -0
- package/lib/rule-retirement.ts +525 -0
- package/lib/run-branch.ts +612 -0
- package/lib/rungate-schema.ts +19 -0
- package/lib/runner-home.ts +274 -0
- package/lib/sc-claim-forms.ts +75 -0
- package/lib/sc-id-cross-tree.ts +323 -0
- package/lib/sc-ids.ts +121 -13
- package/lib/sc-reservations.ts +289 -0
- package/lib/scaffold/ai-review-findings.ts +403 -0
- package/lib/scaffold/ai-review-step.ts +4777 -0
- package/lib/scaffold/managed-workflow.ts +587 -192
- package/lib/scaffold/owned-files.ts +186 -39
- package/lib/scaffold/pre-push-hook.ts +49 -5
- package/lib/scaffold/rehearsal.ts +205 -71
- package/lib/scaffold/steps.ts +1517 -293
- package/lib/scaffold/workflow-census.ts +217 -0
- package/lib/scaffold/workflow-drift.ts +217 -0
- package/lib/scaffold/write-steps.ts +10 -4
- package/lib/scan-budget.ts +247 -0
- package/lib/scanner.ts +80 -62
- package/lib/scratch-roots.ts +50 -5
- package/lib/screenshot-discovery.ts +121 -0
- package/lib/screenshot-upload.ts +41 -1
- package/lib/secret-patterns.ts +511 -8
- package/lib/ship-mode.ts +219 -0
- package/lib/source-slice.ts +294 -0
- package/lib/spec-listing.ts +148 -0
- package/lib/spec-requirements.ts +209 -0
- package/lib/stale-cleanup.ts +37 -3
- package/lib/suite-flake.ts +278 -0
- package/lib/suite-measurement.ts +23 -4
- package/lib/suite-run-reading.ts +411 -1
- package/lib/suite-timeout-margin.ts +193 -0
- package/lib/test-case-bodies.ts +883 -0
- package/lib/test-case-deletion.ts +653 -0
- package/lib/test-census.ts +97 -29
- package/lib/test-command-positions.ts +274 -0
- package/lib/test-command.ts +133 -0
- package/lib/test-suite-lock.ts +325 -26
- package/lib/tool-probe.ts +142 -0
- package/lib/top-level-cd.ts +393 -0
- package/lib/tracked-vs-ignored.ts +234 -0
- package/lib/tree-entries.ts +89 -0
- package/lib/ts-ast.ts +200 -0
- package/lib/validators/spec-validators.ts +3 -2
- package/lib/walk-test-files.ts +97 -0
- package/lib/workflow-actions.ts +263 -0
- package/lib/worktree-collect.ts +177 -5
- package/lib/worktree-repo.ts +36 -1
- package/package.json +2 -1
- package/scripts/ai-review-findings.ts +45 -0
- package/scripts/audit-specs.ts +247 -12
- package/scripts/audit-transcript.ts +2 -1
- package/scripts/convert-spec.ts +2 -1
- package/scripts/create-sc.ts +37 -7
- package/scripts/create-spec.ts +2 -1
- package/scripts/create-success.ts +2 -1
- package/scripts/extract-constraints.ts +197 -26
- package/scripts/generate-code-map.ts +62 -28
- package/scripts/scaffold-project.ts +12 -2
- package/scripts/split-spec.ts +2 -1
- package/scripts/sync-sc-status.ts +127 -14
- package/scripts/sync-spec-tests.ts +2 -1
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The remedy line a conformity failure carries, and the routing to the rule
|
|
3
|
+
* file that explains the whole family (#813).
|
|
4
|
+
*
|
|
5
|
+
* ## Why this exists
|
|
6
|
+
*
|
|
7
|
+
* The checks in `.claude/rules/self-referential-tests.md`'s Tier 1 assert a
|
|
8
|
+
* property about the REPOSITORY, not about a unit of code. They go red on a
|
|
9
|
+
* pull request that never opened the file they are about: add a spec, and
|
|
10
|
+
* `HYGIENE-4` fails; add a script, and `HYGIENE-3` fails. The agent who needs
|
|
11
|
+
* that document is by definition staring at a test failure, and measured on
|
|
12
|
+
* `e0429b82` not one of those failures named it — two references in the whole
|
|
13
|
+
* executable tree, both prose inside a docblock, against 321 for
|
|
14
|
+
* `checks-must-be-able-to-fail`.
|
|
15
|
+
*
|
|
16
|
+
* So the document was unreachable from the only place it was ever needed.
|
|
17
|
+
*
|
|
18
|
+
* ## The two layers, and why they are not one
|
|
19
|
+
*
|
|
20
|
+
* `lib/conformity.ts` is published, and `lib/scaffold/steps.ts` generates the
|
|
21
|
+
* consumer test that calls it. The rule file has exactly one copy in this tree
|
|
22
|
+
* and no template copy, so it does NOT ship. Hardcoding its path into the
|
|
23
|
+
* published failure text would point every consumer at a file they do not
|
|
24
|
+
* have — a dangling route, which is the defect `test/rule-provenance.test.ts`
|
|
25
|
+
* exists to catch and cannot catch across the package boundary.
|
|
26
|
+
*
|
|
27
|
+
* Hence `fix` and `pointer` are separate:
|
|
28
|
+
*
|
|
29
|
+
* - The **fix** is a claim about the project's own tree and is true anywhere.
|
|
30
|
+
* "Add a row to `.claude/rules/specs-routing.md`" is the real remedy in a
|
|
31
|
+
* consumer exactly as it is here.
|
|
32
|
+
* - The **pointer** is DERIVED, not configured: it is emitted only when the
|
|
33
|
+
* rule file is present under `root`. No new config key, nothing for a
|
|
34
|
+
* consumer to set, absent where it would be wrong, and it begins working
|
|
35
|
+
* for a consumer on the day they adopt the file.
|
|
36
|
+
*
|
|
37
|
+
* A config key was the other option and is worse: it is a second decider about
|
|
38
|
+
* whether the document exists, and the two could disagree — the key set in a
|
|
39
|
+
* project that deleted the file routes an agent to nothing.
|
|
40
|
+
*/
|
|
41
|
+
|
|
42
|
+
import { existsSync } from "fs";
|
|
43
|
+
import { join } from "path";
|
|
44
|
+
|
|
45
|
+
import { stripJsComments } from "./strip-js-comments";
|
|
46
|
+
|
|
47
|
+
/**
|
|
48
|
+
* The document, relative to a project root.
|
|
49
|
+
*
|
|
50
|
+
* Spelled once. A second copy is the thing
|
|
51
|
+
* `.claude/rules/checks-must-be-able-to-fail.md` calls two deciders that
|
|
52
|
+
* agree: the existence probe and the printed path would be free to drift, and
|
|
53
|
+
* the failure mode is silent — a pointer that prints a path nobody checked.
|
|
54
|
+
*/
|
|
55
|
+
export const SELF_REFERENTIAL_RULES = ".claude/rules/self-referential-tests.md";
|
|
56
|
+
|
|
57
|
+
/**
|
|
58
|
+
* The routing sentence, or `""` when this project does not carry the document.
|
|
59
|
+
*
|
|
60
|
+
* Returns the empty string rather than throwing or omitting a field, because
|
|
61
|
+
* every caller is composing a message and an empty segment drops out of a
|
|
62
|
+
* `filter(Boolean).join()` without a branch at each site.
|
|
63
|
+
*/
|
|
64
|
+
export function ruleDocPointer(root: string): string {
|
|
65
|
+
if (!existsSync(join(root, SELF_REFERENTIAL_RULES))) return "";
|
|
66
|
+
return (
|
|
67
|
+
`This check asserts a property of the REPOSITORY, so it can go red on a change ` +
|
|
68
|
+
`that never touched its subject. ${SELF_REFERENTIAL_RULES} lists the others ` +
|
|
69
|
+
`that behave this way and what each one wants.`
|
|
70
|
+
);
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
/**
|
|
74
|
+
* A conformity failure message: what is wrong, what to do, and where the rest
|
|
75
|
+
* of the family is documented.
|
|
76
|
+
*
|
|
77
|
+
* The `fix` is mandatory and takes no default. A default would let a new check
|
|
78
|
+
* be written with no remedy and still look like it had one, which is the
|
|
79
|
+
* failure this module was built to end — `test/check-remedy.test.ts` holds the
|
|
80
|
+
* population of Tier 1 checks for the same reason.
|
|
81
|
+
*/
|
|
82
|
+
export function remedyMessage(opts: {
|
|
83
|
+
root: string;
|
|
84
|
+
check: string;
|
|
85
|
+
violations: string[];
|
|
86
|
+
fix: string;
|
|
87
|
+
}): string {
|
|
88
|
+
const { root, check, violations, fix } = opts;
|
|
89
|
+
const subject = violations.length === 0 ? "(none)" : violations.join(", ");
|
|
90
|
+
return [
|
|
91
|
+
`${check}: ${violations.length} violation(s) — ${subject}`,
|
|
92
|
+
`FIX: ${fix}`,
|
|
93
|
+
ruleDocPointer(root),
|
|
94
|
+
]
|
|
95
|
+
.filter(Boolean)
|
|
96
|
+
.join("\n");
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
/**
|
|
100
|
+
* How far before a call site an `expect(` may open and still be counted as
|
|
101
|
+
* the assertion it belongs to.
|
|
102
|
+
*
|
|
103
|
+
* Generous on purpose. The cost of being too wide is a call site credited to
|
|
104
|
+
* a nearby assertion it does not serve; the cost of being too narrow is a
|
|
105
|
+
* correctly-wired check reported as missing, which trains the next agent to
|
|
106
|
+
* widen the number rather than read it.
|
|
107
|
+
*/
|
|
108
|
+
const EXPECT_WINDOW = 200;
|
|
109
|
+
|
|
110
|
+
/** How far into a call site to look for its `check:` field. */
|
|
111
|
+
const FIELD_WINDOW = 600;
|
|
112
|
+
|
|
113
|
+
/**
|
|
114
|
+
* The `check:` value of every ASSERTED `remedyMessage(...)` call in a source.
|
|
115
|
+
*
|
|
116
|
+
* Pure, and over text rather than a path, because the two properties below
|
|
117
|
+
* are the whole point and neither can be witnessed against the live tree —
|
|
118
|
+
* the live tree has no violating file to find, so a scan that silently lost
|
|
119
|
+
* both would return the right answer today and nothing the day it mattered.
|
|
120
|
+
* `test/check-remedy.test.ts` plants a source for each.
|
|
121
|
+
*
|
|
122
|
+
* - **Comments are not code.** The scan looks for a symbol that this very
|
|
123
|
+
* docblock names. Counting prose would let a file satisfy the guard by
|
|
124
|
+
* describing the call it does not make — a checker that greps for a string
|
|
125
|
+
* cannot tell a use from a mention of one.
|
|
126
|
+
* - **A composed message is not an asserted one.** Building the string and
|
|
127
|
+
* never passing it to `expect` leaves the check failing with nothing while
|
|
128
|
+
* the guard reads green, which is the cheapest wrong way to go green here.
|
|
129
|
+
*/
|
|
130
|
+
export function routedCheckIds(source: string): string[] {
|
|
131
|
+
const src = stripJsComments(source);
|
|
132
|
+
const found: string[] = [];
|
|
133
|
+
const CALL = "remedyMessage(";
|
|
134
|
+
for (let i = src.indexOf(CALL); i !== -1; i = src.indexOf(CALL, i + 1)) {
|
|
135
|
+
if (!src.slice(Math.max(0, i - EXPECT_WINDOW), i).includes("expect(")) continue;
|
|
136
|
+
const field = /check:\s*"([^"]+)"/.exec(src.slice(i, i + FIELD_WINDOW));
|
|
137
|
+
if (field) found.push(field[1]!);
|
|
138
|
+
}
|
|
139
|
+
return found;
|
|
140
|
+
}
|
package/lib/ci-checkout.ts
CHANGED
|
@@ -62,7 +62,7 @@ export interface CheckoutModelResult {
|
|
|
62
62
|
export const UNMODELLED: readonly string[] = [
|
|
63
63
|
"the runner OS — CI is ubuntu-latest and this runs on the developer's machine, so anything platform-dependent (BSD vs GNU flags, path casing, file watchers) is still invisible here",
|
|
64
64
|
"a fresh `bun install` — node_modules is linked from the working tree rather than installed, so a missing or mis-ranged dependency still passes locally",
|
|
65
|
-
"the bun version — CI
|
|
65
|
+
"the bun version — CI installs what `.bun-version` declares (or `ci.bunVersion` when that file is absent; the file wins, and `declaredBunVersion` reports the disagreement when both exist) and this uses whichever bun is on PATH; since #622 the run REPORTS which one it is and whether it matches, but nothing here switches runtimes, so a mismatch is announced rather than removed",
|
|
66
66
|
"the PR merge commit — `actions/checkout@v4` on a pull_request checks out a merge of the head into the base, while this checks out the head alone, so a conflict-free-but-broken merge is not modelled",
|
|
67
67
|
"network and API availability — CI has neither the developer's `gh` credentials (stripped) nor their network conditions",
|
|
68
68
|
"files git ignores — a `.env` or a stray build artefact present locally and absent in CI is carried over only if git can see it",
|
|
@@ -424,3 +424,20 @@ export function prepareCiCheckout(opts: PrepareOptions): PrepareOutcome {
|
|
|
424
424
|
|
|
425
425
|
return { ok: true, dir: dest, model, refs: result.refs, carried };
|
|
426
426
|
}
|
|
427
|
+
|
|
428
|
+
/**
|
|
429
|
+
* The job in a generated ci.yml that actually checks out and runs the suite
|
|
430
|
+
* (#735).
|
|
431
|
+
*
|
|
432
|
+
* `test` normally. When `ci.shards > 1` the suite moves to the `test-shard`
|
|
433
|
+
* matrix and `test` becomes the aggregate that reads the matrix result and
|
|
434
|
+
* runs no tests — so a reader that only knows `test` reports "no
|
|
435
|
+
* actions/checkout step" for a workflow that checks out four times.
|
|
436
|
+
*
|
|
437
|
+
* One exported binding, because the same question is asked by
|
|
438
|
+
* `scripts/contract-parity.ts`. Two readers that agree today are one decider
|
|
439
|
+
* too many (`.claude/rules/checks-must-be-able-to-fail.md`, fourth shape).
|
|
440
|
+
*/
|
|
441
|
+
export function suiteJobName(workflowYaml: string): string {
|
|
442
|
+
return /^ {2}test-shard:\s*$/m.test(workflowYaml) ? "test-shard" : "test";
|
|
443
|
+
}
|
|
@@ -0,0 +1,159 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* How much history a generated CI job keeps, and whether that is enough for
|
|
3
|
+
* the failure intake to report MEASURED (#987).
|
|
4
|
+
*
|
|
5
|
+
* ## The reading this exists to fix
|
|
6
|
+
*
|
|
7
|
+
* `lib/failure-intake.ts` mines `fix:` and `Revert` subjects out of `git log`.
|
|
8
|
+
* Its refusal is `SHALLOW_HISTORY`, taken from
|
|
9
|
+
* `git rev-parse --is-shallow-repository`, and `actions/checkout@v4` with no
|
|
10
|
+
* `fetch-depth` clones to depth 1. So the intake has reported UNMEASURED on
|
|
11
|
+
* every run of every generated workflow since it shipped — uniformly absent
|
|
12
|
+
* rather than occasionally missing, which is why nobody noticed.
|
|
13
|
+
*
|
|
14
|
+
* ## Why this is a module and not a `fetch-depth: 0` on one line
|
|
15
|
+
*
|
|
16
|
+
* Two things were measured on 2026-10-21 against real repositories, and each
|
|
17
|
+
* one falsifies a step of the obvious fix. Both are asserted as cases in
|
|
18
|
+
* `test/ci-history-depth.test.ts` rather than described here.
|
|
19
|
+
*
|
|
20
|
+
* **A bounded depth does not make the intake MEASURED on a repository longer
|
|
21
|
+
* than the depth.** `--is-shallow-repository` is a fact about `.git/shallow`,
|
|
22
|
+
* not about how many commits you fetched: a clone deepened to
|
|
23
|
+
* `MAX_COMMITS_SCANNED` and a clone at depth 1 both answer `true` as long as
|
|
24
|
+
* there is any history past the boundary. #987 proposes `fetch-depth: 500` as
|
|
25
|
+
* the bounded option that "matches what the code actually asks for"; measured
|
|
26
|
+
* on a 520-commit repository, a depth-500 clone holds all 500 commits the
|
|
27
|
+
* intake would read and still reports UNMEASURED. This repository's `main`
|
|
28
|
+
* carries 1090 commits and only grows, so that is its permanent state.
|
|
29
|
+
*
|
|
30
|
+
* The exception, stated because it is the direction this module is
|
|
31
|
+
* deliberately wrong in: when the depth exceeds the whole history, git has
|
|
32
|
+
* nothing left to truncate and removes `.git/shallow`, so the intake reports
|
|
33
|
+
* MEASURED. `ciHistoryReading` below refuses a bounded depth anyway — see its
|
|
34
|
+
* docblock.
|
|
35
|
+
*
|
|
36
|
+
* And it is not even cheaper. Three clones of this repository, each repeated
|
|
37
|
+
* three times: depth 1 took 1.23–1.64s for 6MB, depth 500 took 1.54–2.75s for
|
|
38
|
+
* 9MB, and full history took 1.43–1.64s for 13MB. A bounded deepen makes the
|
|
39
|
+
* server compute a cut of the graph; a full clone is served from a pack it
|
|
40
|
+
* already has. The cheap option is the one that does not work, and the
|
|
41
|
+
* bounded middle is the slowest of the three.
|
|
42
|
+
*
|
|
43
|
+
* **A bounded `git fetch` AFTER the checkout re-shallows a complete clone.**
|
|
44
|
+
* This is the one that makes `fetch-depth: 0` alone inert. The generated job
|
|
45
|
+
* already runs `git fetch --no-tags --depth=200 origin '+refs/heads/main:…'`
|
|
46
|
+
* one step after the checkout, for the conformity ratchet's comparison base.
|
|
47
|
+
* Measured on a complete 40-commit clone: `is-shallow-repository` goes
|
|
48
|
+
* `false` → `true` and `rev-list --count HEAD` drops 40 → 20. Setting
|
|
49
|
+
* `fetch-depth: 0` and leaving that step alone buys nothing at all.
|
|
50
|
+
*
|
|
51
|
+
* So the depth of the base-ref fetch is DERIVED from the checkout's depth
|
|
52
|
+
* here, rather than declared beside it. Two numbers that have to agree, with
|
|
53
|
+
* nothing comparing them, is the defect class this repository pays for most
|
|
54
|
+
* (`.claude/rules/checks-must-be-able-to-fail.md`, fourth shape).
|
|
55
|
+
*
|
|
56
|
+
* ## WHAT THIS DOES NOT COVER
|
|
57
|
+
*
|
|
58
|
+
* - **It does not make the intake's reading good, only present.** Whether the
|
|
59
|
+
* mined set is worth anything is #988, and nothing here touches the
|
|
60
|
+
* classifier.
|
|
61
|
+
* - **It says nothing about a job it cannot see.** The reading is taken from a
|
|
62
|
+
* parsed `CheckoutModel`; a job that acquires history some other way — a
|
|
63
|
+
* cache restore, a submodule, a hand-rolled `git clone` inside `run:` — is
|
|
64
|
+
* invisible to it and will read UNMEASURED while being fine. The direction
|
|
65
|
+
* is deliberate: a false UNMEASURED costs a conversation, a false MEASURED
|
|
66
|
+
* costs the whole point of #987.
|
|
67
|
+
* - **It does not check that the history is ENOUGH**, only that it is
|
|
68
|
+
* untruncated. A repository younger than `MAX_COMMITS_SCANNED` commits
|
|
69
|
+
* reports MEASURED over fewer commits than the intake asked for, which is
|
|
70
|
+
* correct — there is no more history to have — but it is not the same claim.
|
|
71
|
+
* - **It disagrees with the intake on one input, on purpose.** A bounded depth
|
|
72
|
+
* GREATER than the repository's whole history leaves nothing to truncate, so
|
|
73
|
+
* the real `mineFixCommits` reports MEASURED there while this reports
|
|
74
|
+
* UNMEASURED. The disagreement is asserted as a case rather than described.
|
|
75
|
+
* A generator cannot know how long a consumer's history is, still less how
|
|
76
|
+
* long it will be next year, so the only honest reading of a bounded depth
|
|
77
|
+
* at generation time is "this will truncate" — and the cost of being wrong
|
|
78
|
+
* is a young repository being told to keep history it already keeps.
|
|
79
|
+
*/
|
|
80
|
+
import type { CheckoutModel } from "./ci-checkout";
|
|
81
|
+
|
|
82
|
+
/**
|
|
83
|
+
* The `fetch-depth:` the generated suite and gates jobs declare. `0` is
|
|
84
|
+
* `actions/checkout`'s spelling for full history, and per the module docblock
|
|
85
|
+
* it is the only value under which the intake can report MEASURED.
|
|
86
|
+
*
|
|
87
|
+
* One declaring position. The generator reads it, the base-ref fetch derives
|
|
88
|
+
* from it, and the tests compare the emitted YAML against it.
|
|
89
|
+
*/
|
|
90
|
+
export const CI_SUITE_FETCH_DEPTH = 0;
|
|
91
|
+
|
|
92
|
+
/**
|
|
93
|
+
* How deep the post-checkout base-ref fetch may go, given the checkout's own
|
|
94
|
+
* depth.
|
|
95
|
+
*
|
|
96
|
+
* A function rather than a second constant, because the whole finding is that
|
|
97
|
+
* these two cannot be chosen independently: a bounded fetch re-shallows a
|
|
98
|
+
* complete checkout and silently undoes the `fetch-depth` above it. Passing
|
|
99
|
+
* the suite depth in makes that dependency something a mutation can reach.
|
|
100
|
+
*
|
|
101
|
+
* `null` means "no `--depth` flag at all". It is not a wasteful choice when
|
|
102
|
+
* the checkout is already full: the objects are local, so the fetch moves a
|
|
103
|
+
* ref and nothing else.
|
|
104
|
+
*/
|
|
105
|
+
export function baseRefFetchDepth(suiteDepth: number): number | null {
|
|
106
|
+
return suiteDepth === 0 ? null : 200;
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
/** Why a job's history is not a history. Exported so callers compare against the producer's spelling. */
|
|
110
|
+
export const SHALLOW_CHECKOUT = "SHALLOW_CHECKOUT";
|
|
111
|
+
export const RESHALLOWED_BY_FETCH = "RESHALLOWED_BY_FETCH";
|
|
112
|
+
|
|
113
|
+
export interface HistoryReading {
|
|
114
|
+
/** The single discriminator; `reasons` is the other projection of one computation. */
|
|
115
|
+
reading: "MEASURED" | "UNMEASURED";
|
|
116
|
+
reasons: string[];
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
/**
|
|
120
|
+
* THE decider: can the failure intake report MEASURED in a job with this
|
|
121
|
+
* checkout?
|
|
122
|
+
*
|
|
123
|
+
* One binding, so there is one thing to mutate. It reads the `CheckoutModel`
|
|
124
|
+
* `lib/ci-checkout.ts` already parses out of a workflow, rather than
|
|
125
|
+
* re-parsing the YAML — a second reader of the same file would survive any
|
|
126
|
+
* mutation of the first and both would read as covered.
|
|
127
|
+
*
|
|
128
|
+
* This PREDICTS what `mineFixCommits` will say. It is not a second copy of
|
|
129
|
+
* that decision: the prediction is compared against the real intake run over
|
|
130
|
+
* real clones built to this exact model, so the two are held to each other
|
|
131
|
+
* instead of merely agreeing.
|
|
132
|
+
*
|
|
133
|
+
* It is a CONSERVATIVE prediction, and the one input on which it is knowingly
|
|
134
|
+
* wrong is named in WHAT THIS DOES NOT COVER above: a bounded depth longer
|
|
135
|
+
* than the repository's entire history is MEASURED in fact and UNMEASURED
|
|
136
|
+
* here. Refusing every bounded depth is the only reading available at
|
|
137
|
+
* generation time, when the history's length is unknown and unbounded.
|
|
138
|
+
*/
|
|
139
|
+
export function ciHistoryReading(model: CheckoutModel): HistoryReading {
|
|
140
|
+
const reasons: string[] = [];
|
|
141
|
+
|
|
142
|
+
// `depth: null` is `fetch-depth: 0`. Any number — including one larger than
|
|
143
|
+
// MAX_COMMITS_SCANNED — leaves `.git/shallow` on disk, and the intake reads
|
|
144
|
+
// that file and not the commit count.
|
|
145
|
+
if (model.depth !== null) {
|
|
146
|
+
reasons.push(`${SHALLOW_CHECKOUT}: fetch-depth ${model.depth}`);
|
|
147
|
+
}
|
|
148
|
+
|
|
149
|
+
// Order matters to a reader and not to the verdict: a bounded fetch
|
|
150
|
+
// re-shallows whatever the checkout left, so it is a reason on its own even
|
|
151
|
+
// when the checkout above it was full.
|
|
152
|
+
for (const f of model.fetches) {
|
|
153
|
+
if (f.depth !== null) {
|
|
154
|
+
reasons.push(`${RESHALLOWED_BY_FETCH}: git fetch --depth=${f.depth} ${f.refspec}`);
|
|
155
|
+
}
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
return { reading: reasons.length > 0 ? "UNMEASURED" : "MEASURED", reasons };
|
|
159
|
+
}
|
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The one extension point a consumer has INSIDE a rungate-managed CI job
|
|
3
|
+
* (#529).
|
|
4
|
+
*
|
|
5
|
+
* `resolveManagedWrite` preserves whole JOBS a consumer adds and refuses
|
|
6
|
+
* rather than dropping one, so the ownership boundary has always been
|
|
7
|
+
* job-level. That boundary cannot express "run this before the suite": jobs
|
|
8
|
+
* do not share a filesystem, so a consumer-owned job cannot seed the tree the
|
|
9
|
+
* test job tests. The only thing left is to edit the managed job, which works
|
|
10
|
+
* until the next re-scaffold.
|
|
11
|
+
*
|
|
12
|
+
* The repository that filed #529 carries the scar in its own `ci.yml` — a
|
|
13
|
+
* comment above an edited `- run:` line explaining that a re-scaffold will
|
|
14
|
+
* revert it. **A consumer documenting that their own edit will be reverted is
|
|
15
|
+
* the feature request.**
|
|
16
|
+
*
|
|
17
|
+
* ## What this is, in one sentence
|
|
18
|
+
*
|
|
19
|
+
* The generated job always runs `scripts/ci-setup.sh` when the tree has one.
|
|
20
|
+
* Rungate owns 100% of the YAML; the consumer owns a file rungate never reads,
|
|
21
|
+
* never writes and never mentions in an ownership table.
|
|
22
|
+
*
|
|
23
|
+
* ## Why the step is emitted unconditionally, not "when the file exists"
|
|
24
|
+
*
|
|
25
|
+
* The obvious shape is a generation-time `existsSync` — emit the step for
|
|
26
|
+
* trees that have the script, omit it for trees that do not. It produces a
|
|
27
|
+
* tidier file and it is the wrong decision, because **generation happens once
|
|
28
|
+
* and the tree keeps moving.** A consumer who adds `scripts/ci-setup.sh` the
|
|
29
|
+
* week after scaffolding gets a file with no extension point in it, their
|
|
30
|
+
* script never runs, and nothing anywhere says so: a green CI run over a tree
|
|
31
|
+
* that was never set up (`.claude/rules/config-access.md`, *Silent Default
|
|
32
|
+
* Substitution*). The existence question belongs at the moment the answer is
|
|
33
|
+
* used, which is run time.
|
|
34
|
+
*
|
|
35
|
+
* ## Why both arms print
|
|
36
|
+
*
|
|
37
|
+
* `0`, `{}`, `SKIP` and silence are indistinguishable from success. A step
|
|
38
|
+
* that quietly does nothing when the file is absent cannot be told from one
|
|
39
|
+
* that ran a script which happened to do nothing, and an operator debugging a
|
|
40
|
+
* tree that was not seeded has no line to search for. Both branches name the
|
|
41
|
+
* path and say which happened.
|
|
42
|
+
*
|
|
43
|
+
* ## Why `-f` and `bash`, not `-x`
|
|
44
|
+
*
|
|
45
|
+
* The executable bit is one byte of filesystem state that git preserves and
|
|
46
|
+
* most editors, `cp`, and every zip-based download do not. `[ -x ]` turns a
|
|
47
|
+
* missing mode bit into a silently skipped setup — #492's one-byte row, with
|
|
48
|
+
* the guard on the other side. `-f` plus an explicit interpreter has no mode
|
|
49
|
+
* bit in it. A consumer who needs another language execs it from the script.
|
|
50
|
+
*
|
|
51
|
+
* ## Why it is a NAMED step with a block scalar, and not `- run:`
|
|
52
|
+
*
|
|
53
|
+
* `testCommandsNamedByCiWorkflow` reads the suite job's **first** `- run:`
|
|
54
|
+
* line that is not known setup, and calls it the project's test command. A
|
|
55
|
+
* setup step written `- run: bash scripts/ci-setup.sh` would be read as the
|
|
56
|
+
* test command by every position check in the tree, and #621's agreement
|
|
57
|
+
* binding would report the project's test command three different ways. A
|
|
58
|
+
* `- name:` step with a `run: |` body is invisible to that regex, which is
|
|
59
|
+
* why every other multi-line step in the generated files is already written
|
|
60
|
+
* that way. `test/ci-setup-step.test.ts` holds that, rather than this comment.
|
|
61
|
+
*
|
|
62
|
+
* ## Failure is terminal, deliberately
|
|
63
|
+
*
|
|
64
|
+
* No `|| true`. A setup script that fails has left the tree in a state the
|
|
65
|
+
* suite was not written against, and a green suite over it is the least
|
|
66
|
+
* useful thing CI can produce.
|
|
67
|
+
*/
|
|
68
|
+
|
|
69
|
+
/**
|
|
70
|
+
* The conventional path. One declaration: the generator, the prose and every
|
|
71
|
+
* test read this, so a rename cannot half-apply.
|
|
72
|
+
*/
|
|
73
|
+
export const CI_SETUP_SCRIPT = "scripts/ci-setup.sh";
|
|
74
|
+
|
|
75
|
+
/**
|
|
76
|
+
* The step, indented for the `steps:` list of a generated job.
|
|
77
|
+
*
|
|
78
|
+
* Returns the leading newline too, so a call site concatenates it the way the
|
|
79
|
+
* typecheck and global-tools steps beside it are concatenated.
|
|
80
|
+
*/
|
|
81
|
+
export function ciSetupStep(): string {
|
|
82
|
+
return `
|
|
83
|
+
- name: Consumer setup (${CI_SETUP_SCRIPT}, optional)
|
|
84
|
+
run: |
|
|
85
|
+
# rungate's one extension point inside this managed job (#529).
|
|
86
|
+
# The script is yours; this file is not. Re-scaffolding rewrites the
|
|
87
|
+
# YAML around this step and never touches ${CI_SETUP_SCRIPT}.
|
|
88
|
+
# Both branches print: a step that is silent when the file is absent
|
|
89
|
+
# cannot be told from one that ran and did nothing.
|
|
90
|
+
if [ -f ${CI_SETUP_SCRIPT} ]; then
|
|
91
|
+
echo "rungate: running ${CI_SETUP_SCRIPT} before the suite (#529)"
|
|
92
|
+
bash ${CI_SETUP_SCRIPT}
|
|
93
|
+
else
|
|
94
|
+
echo "rungate: no ${CI_SETUP_SCRIPT} in this tree, so no consumer setup ran (#529)"
|
|
95
|
+
fi`;
|
|
96
|
+
}
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The one pin for `anthropics/claude-code-action` (#689).
|
|
3
|
+
*
|
|
4
|
+
* Two workflows pinned this action to two different commits and annotated
|
|
5
|
+
* both `# v1`:
|
|
6
|
+
*
|
|
7
|
+
* | File | Pin | Comment | What it actually was |
|
|
8
|
+
* |---|---|---|---|
|
|
9
|
+
* | `.github/workflows/ai-review.yml` (#631, unmerged) | `5eb090f3` | `# v1` | v1 |
|
|
10
|
+
* | `.github/workflows/claude-review.yml` | `f27be6b6` | `# v1` | v1 as of 2026-10-16 |
|
|
11
|
+
*
|
|
12
|
+
* The comment is the only thing a reader checks. It agreed with itself in both
|
|
13
|
+
* files while naming neither commit, which is `.claude/rules/
|
|
14
|
+
* checks-must-be-able-to-fail.md`'s "two deciders that agree" with a comment
|
|
15
|
+
* standing in for the second decider.
|
|
16
|
+
*
|
|
17
|
+
* ## Why this is a module and not a string in two YAML files
|
|
18
|
+
*
|
|
19
|
+
* It was two strings, and they diverged. This is `lib/bun-version.ts`'s answer
|
|
20
|
+
* (#622) applied to the step beside it: one binding, so a mutation of it can
|
|
21
|
+
* show that the agreement is load-bearing rather than coincidental.
|
|
22
|
+
*
|
|
23
|
+
* A workflow file cannot import, so the agreement is not achieved by
|
|
24
|
+
* substitution — it is CHECKED, by `actionPinParity` in
|
|
25
|
+
* `scripts/contract-parity.ts`, which reads every `.github/workflows/*.yml`
|
|
26
|
+
* and every literal in `lib/` and `scripts/` and compares each to this
|
|
27
|
+
* declaration. That check refuses when it finds no pin at all: zero strings
|
|
28
|
+
* are trivially all equal, and on this tree there is exactly one consumer, so
|
|
29
|
+
* "finding nothing in every file is perfect agreement" is one renamed step
|
|
30
|
+
* away rather than hypothetical.
|
|
31
|
+
*
|
|
32
|
+
* ## How the SHA was established, and the trap in establishing it
|
|
33
|
+
*
|
|
34
|
+
* ```
|
|
35
|
+
* $ gh api repos/anthropics/claude-code-action/git/ref/tags/v1
|
|
36
|
+
* → object.type "tag", object.sha 310805dc335398c705877f09079340090470ff77
|
|
37
|
+
* $ gh api repos/anthropics/claude-code-action/git/tags/310805dc…
|
|
38
|
+
* → object.type "commit", object.sha 5eb090f3c3afd701a0672cd32981197ca27688f6
|
|
39
|
+
* $ gh api repos/anthropics/claude-code-action/commits/v1
|
|
40
|
+
* → sha 5eb090f3c3afd701a0672cd32981197ca27688f6
|
|
41
|
+
* ```
|
|
42
|
+
*
|
|
43
|
+
* `v1` is an ANNOTATED tag, so `refs/tags/v1` points at a tag OBJECT and the
|
|
44
|
+
* commit is one dereference further down. Reading `.object.sha` off the ref
|
|
45
|
+
* and stopping there gives `310805dc`, which is not a commit and cannot be a
|
|
46
|
+
* `uses:` pin at all — #689's own resolution step made exactly that error and
|
|
47
|
+
* concluded from it that neither pinned SHA was v1. One of them was.
|
|
48
|
+
*
|
|
49
|
+
* ## What this does NOT do
|
|
50
|
+
*
|
|
51
|
+
* It does not keep itself fresh. `v1` is a MOVING tag upstream: every release
|
|
52
|
+
* repoints it, so `RESOLVED_ON` dates the reading rather than certifying it.
|
|
53
|
+
* Nothing here fails when the pin goes stale — a check for that needs the
|
|
54
|
+
* network, and whether a staleness refusal belongs in the suite is the
|
|
55
|
+
* decision #377 is open for. Bumping is a deliberate edit to this file, and
|
|
56
|
+
* `actionPinParity` makes every consumer follow it in the same commit.
|
|
57
|
+
*/
|
|
58
|
+
|
|
59
|
+
/** The action, by the name a `uses:` line spells. */
|
|
60
|
+
export const CLAUDE_CODE_ACTION = "anthropics/claude-code-action";
|
|
61
|
+
|
|
62
|
+
/**
|
|
63
|
+
* The commit `refs/tags/v1` dereferences to, resolved on `RESOLVED_ON`.
|
|
64
|
+
* A full 40-character commit SHA, because that is the only form of a `uses:`
|
|
65
|
+
* reference the publisher cannot repoint.
|
|
66
|
+
*/
|
|
67
|
+
export const CLAUDE_CODE_ACTION_SHA = "5eb090f3c3afd701a0672cd32981197ca27688f6";
|
|
68
|
+
|
|
69
|
+
/**
|
|
70
|
+
* The tag that SHA was v1 of, carried here so the trailing `# vN` comment in
|
|
71
|
+
* every workflow is DERIVED from the same declaration as the pin. A comment
|
|
72
|
+
* that can disagree with the pin it annotates is worse than no comment.
|
|
73
|
+
*/
|
|
74
|
+
export const CLAUDE_CODE_ACTION_VERSION = "v1";
|
|
75
|
+
|
|
76
|
+
/** The day the tag was dereferenced. A moving tag's reading needs a date. */
|
|
77
|
+
export const CLAUDE_CODE_ACTION_RESOLVED_ON = "2026-10-19";
|
|
78
|
+
|
|
79
|
+
/**
|
|
80
|
+
* The exact text a workflow's `uses:` value must carry — pin and comment in
|
|
81
|
+
* one rendering, so there is one thing to mutate and no way to update half.
|
|
82
|
+
*/
|
|
83
|
+
export function claudeCodeActionRef(): string {
|
|
84
|
+
return `${CLAUDE_CODE_ACTION}@${CLAUDE_CODE_ACTION_SHA} # ${CLAUDE_CODE_ACTION_VERSION}`;
|
|
85
|
+
}
|