Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
#!/usr/bin/env bun
/**
* Master-push reuse of an identical-tree full-suite run (P2, docs/ci-event-parity.md#master-push-reuse).
*
* bun scripts/ci-reuse.ts --workflow test|e2e --sha <push sha> --repo <owner/name>
* --output <GITHUB_OUTPUT> [--summary <GITHUB_STEP_SUMMARY>] [--record <reuse.json>]
*
* A push to master is a merge commit M or a one-parent (squashed) commit S. Its
* run may reuse the full run of the same workflow that already ran the complete
* full suite on its tree: the workflow_dispatch on the PR head branch
* (full-ci.yml, or a hand-run `gh workflow run`) or an earlier push run.
* Pull-request runs are the cheap tier and never candidates. Fail-closed:
* reuse=true only when
* (a) the push is a merge commit (two parents) or a one-parent commit, and
* its tree equals the candidate's recorded tree;
* (b) the candidate is a same-repository workflow_dispatch or push run
* whose LATEST attempt completed with conclusion success;
* (c) its full-suite job (`full-suite` / `e2e-full-suite`, by name, exactly
* one) concluded success in that latest attempt;
* (d) its tested-tree artifact (`full-suite-tree` / `e2e-full-suite-tree`,
* tree.json) is readable, has profile full, names this run, attempt,
* event, head and workflow, and its tree equals both M's tree and the
* tree of the run's head commit.
* A diagnostic dispatch (test.yml native_only, race_hunt, stress_*; e2e.yml
* full_corpus, order_hunt) skips the full-suite job, so (c) rejects it.
* Candidates on head M^2 (the merged PR head) come first, newest first; then
* recent successful dispatch and push runs whose head tree equals M's tree. S
* has no merged head, so its tree alone decides: the heads with S's tree are
* the heads GitHub names for S (commits/<sha>/pulls), each with the first
* parents that still have that tree (a merge of master that changed no file),
* and the heads of recent dispatch and push runs with that tree. Their newest
* dispatch or push run decides, as in the remote gate: a newer failed or
* in-progress full run gives no reuse, a cancelled run or one that skipped the
* full job looks further back. Any API error, cancelled, failed or in-progress attempt,
* missing or cheap artifact, tree mismatch or root commit gives reuse=false
* with a reason.
*
* Writes reuse, source_run_id, source_run_attempt, source_sha, tree and reason
* to --output, one summary line (the reused run URL, or the fallback reason)
* to --summary, and the reuse record (REUSE_FILE, read by
* scripts/release-gate.ts) to --record. Exit 0 whenever a decision was
* written (a fallback is not an error), 2 on usage.
*
* bun scripts/ci-reuse.ts --gate --sha <HEAD> --tree <tree> --repo <owner/name> [--wait-minutes N] [--poll-seconds S]
*
* Remote-gate reuse (decideGate, runGate): scripts/pregate-remote-gate.sh asks whether Test and E2E already
* passed their complete full runs on this exact tree; exit 0 reuse, 3 a full run on the tree failed, 4 no reuse.
*/
import { appendFileSync, writeFileSync } from 'node:fs';
import { fetchArtifactJson, inert, restClient, type GitHubClient } from './lib/gh-issue.ts';
export const PROFILES = {
test: { file: 'test.yml', workflow: 'Test', job: 'full-suite', artifact: 'full-suite-tree' },
e2e: { file: 'e2e.yml', workflow: 'E2E Tests', job: 'e2e-full-suite', artifact: 'e2e-full-suite-tree' },
} as const;
export type Profile = (typeof PROFILES)[keyof typeof PROFILES];
export const TREE_FILE = 'tree.json';
/** The push run's marker job and artifact when it reused a run; scripts/release-gate.ts reads both. */
export const REUSE_JOB = 'reused-full-suite';
export const REUSE_ARTIFACT = 'reused-full-suite';
export const REUSE_FILE = 'reuse.json';
const MAX_FALLBACK_HEADS = 20;
const SHA = /^[0-9a-f]{40}$/;
/** Full runs have the push shape; pull_request runs are the cheap tier. */
export const CANDIDATE_EVENTS = ['workflow_dispatch', 'push'] as const;
const isCandidate = (run: FullRun) => (CANDIDATE_EVENTS as readonly string[]).includes(run.event);
export interface Commit { tree: string; parents: string[] }
export interface FullRun { id: number; run_number: number; run_attempt: number; status: string; conclusion: string | null; head_sha: string; event: string; head_repository?: { full_name: string } | null }
export interface JobRow { name: string; status?: string; conclusion: string | null; started_at?: string | null }
export interface ReuseDeps {
commit(sha: string): Promise<Commit>;
runsForHead(file: string, sha: string): Promise<FullRun[]>;
recentSuccessfulRuns(file: string): Promise<FullRun[]>;
/** Head commits of the pull requests GitHub associates with commit `sha` (a squashed landing names its pull request); a fork head's runs are refused like any fork run. */
pullHeads(sha: string): Promise<string[]>;
/** The newest workflow_dispatch and push runs of `file`, whatever their status (a failed run counts against its tree too). */
recentRuns(file: string): Promise<FullRun[]>;
jobs(runId: number, attempt: number): Promise<JobRow[]>;
artifact(runId: number, name: string): Promise<{ value?: unknown; reason?: string }>;
}
export type Reason =
| 'identical_tree_full_run' | 'not_merge_commit' | 'api_error' | 'no_candidate' | 'fork_run'
| 'run_in_progress' | 'run_cancelled' | 'run_failed' | 'full_suite_missing' | 'full_suite_ambiguous' | 'full_suite_not_success'
| 'artifact_missing' | 'artifact_mismatch' | 'artifact_not_full' | 'tree_mismatch';
export interface Rejection { run_id: number; reason: Reason; detail: string }
export interface Decision { reuse: boolean; reason: Reason; detail: string; tree?: string; source?: { run_id: number; run_attempt: number; sha: string }; rejected: Rejection[] }
async function reject(deps: ReuseDeps, p: Profile, run: FullRun, repo: string, pushTree: string, headTree: string): Promise<Omit<Rejection, 'run_id'> | undefined> {
const at = `run ${run.id} attempt ${run.run_attempt}`;
if (run.head_repository?.full_name !== repo) return { reason: 'fork_run', detail: `${at} ran for ${run.head_repository?.full_name ?? 'an unknown repository'}, not ${repo}` };
if (run.status !== 'completed') return { reason: 'run_in_progress', detail: `${at} is ${run.status}` };
if (run.conclusion === 'cancelled') return { reason: 'run_cancelled', detail: `${at} was cancelled` };
if (run.conclusion !== 'success') return { reason: 'run_failed', detail: `${at} concluded ${run.conclusion}` };
const jobs = (await deps.jobs(run.id, run.run_attempt)).filter(j => j.name === p.job);
if (jobs.length === 0) return { reason: 'full_suite_missing', detail: `${at} has no ${p.job} job (not a full-profile run)` };
if (jobs.length > 1) return { reason: 'full_suite_ambiguous', detail: `${at} has ${jobs.length} jobs named ${p.job}` };
if (jobs[0]!.conclusion !== 'success') return { reason: 'full_suite_not_success', detail: `${at}'s ${p.job} job concluded ${jobs[0]!.conclusion}` };
const got = await deps.artifact(run.id, p.artifact);
if (got.reason) return { reason: 'artifact_missing', detail: got.reason };
const rec = got.value as Record<string, unknown> | null;
if (!rec || typeof rec !== 'object') return { reason: 'artifact_mismatch', detail: `${at}'s ${p.artifact} ${TREE_FILE} is not a JSON object` };
if (rec.profile !== 'full') return { reason: 'artifact_not_full', detail: `${at}'s ${p.artifact} records profile ${String(rec.profile)}` };
const expected: Array<[string, string | number]> = [['run_id', run.id], ['run_attempt', run.run_attempt], ['sha', run.head_sha], ['event', run.event], ['workflow', p.workflow]];
if (rec.head_sha !== undefined) expected.push(['head_sha', run.head_sha]);
const wrong = expected.filter(([k, v]) => rec[k] !== v);
if (wrong.length) return { reason: 'artifact_mismatch', detail: `${at}'s ${p.artifact} records ${wrong.map(([k, v]) => `${k} ${String(rec[k])} (expected ${v})`).join(', ')}` };
if (rec.tree !== pushTree) return { reason: 'tree_mismatch', detail: `${at} tested tree ${String(rec.tree)}, the push tree is ${pushTree}` };
if (rec.tree !== headTree) return { reason: 'tree_mismatch', detail: `${at} recorded tree ${String(rec.tree)} but its head ${run.head_sha} has tree ${headTree}` };
return undefined;
}
/** The reuse decision for push commit `sha` (pure over its dependencies; every failure is a fallback). */
export async function decide(deps: ReuseDeps, p: Profile, sha: string, repo: string): Promise<Decision> {
const rejected: Rejection[] = [];
let tree: string | undefined;
try {
const push = await deps.commit(sha);
tree = push.tree;
if (push.parents.length === 1) return await decideOneParent(deps, p, sha, tree, repo, rejected);
if (push.parents.length !== 2) return { reuse: false, reason: 'not_merge_commit', detail: `push ${sha} has ${push.parents.length} parent(s); only a merge commit or a one-parent commit can reuse a run`, tree, rejected };
const head = push.parents[1]!;
const headTree = (await deps.commit(head)).tree;
const primary = (await deps.runsForHead(p.file, head)).filter(r => r.head_sha === head && isCandidate(r)).sort((a, b) => b.id - a.id);
for (const run of primary) {
const why = await reject(deps, p, run, repo, tree, headTree);
if (!why) return accept(run, tree, rejected, 'the merged head');
rejected.push({ run_id: run.id, ...why });
}
const tried = new Set(primary.map(r => r.id));
const heads = new Map<string, string>();
for (const run of (await deps.recentSuccessfulRuns(p.file)).sort((a, b) => b.id - a.id)) {
if (tried.has(run.id) || !isCandidate(run) || run.head_sha === head || run.head_sha === sha || run.head_repository?.full_name !== repo) continue;
if (!heads.has(run.head_sha)) {
if (heads.size >= MAX_FALLBACK_HEADS) continue;
heads.set(run.head_sha, (await deps.commit(run.head_sha)).tree);
}
if (heads.get(run.head_sha) !== tree) continue;
const why = await reject(deps, p, run, repo, tree, tree);
if (!why) return accept(run, tree, rejected, `head ${run.head_sha.slice(0, 12)} (same tree as the merged head)`);
rejected.push({ run_id: run.id, ...why });
}
} catch (e) {
return { reuse: false, reason: 'api_error', detail: `reading the push commit, runs, jobs or artifacts failed: ${e instanceof Error ? e.message : String(e)}`, tree, rejected };
}
if (!rejected.length) return { reuse: false, reason: 'no_candidate', detail: `no ${p.workflow} workflow_dispatch or push run exists on the merged head or on another head with tree ${tree}`, tree, rejected };
return { reuse: false, reason: rejected[0]!.reason, detail: rejected.map(r => r.detail).join('; '), tree, rejected };
}
/**
* A one-parent push (a squashed landing, a hand revert, a direct push) has no merged head, so its tree alone decides:
* the newest full run on any head with that tree, as in the remote gate. The landed pull request's head counts, and
* so do its first parents with the same tree, since a merge of master that changed no file leaves the full run on the
* commit before it.
*/
async function decideOneParent(deps: ReuseDeps, p: Profile, sha: string, tree: string, repo: string, rejected: Rejection[]): Promise<Decision> {
const seeds: string[] = [];
for (const head of new Set(await deps.pullHeads(sha))) {
let at = head;
for (let i = 0; i < MAX_FALLBACK_HEADS && at !== sha && !seeds.includes(at); i++) {
const c = await deps.commit(at);
if (c.tree !== tree) break;
seeds.push(at);
if (!c.parents[0]) break;
at = c.parents[0];
}
}
const found = await newestFullRun(deps, p, await sameTreeHeads(deps, p, tree, repo, seeds, sha), tree, repo, rejected);
if (found && !found.why) return accept(found.run, tree, rejected, `head ${found.run.head_sha.slice(0, 12)} (same tree as the one-parent push)`);
if (found?.why) return { reuse: false, reason: found.why.reason, detail: `the newest full run on tree ${tree} decides: ${found.why.detail}`, tree, rejected };
if (!rejected.length) return { reuse: false, reason: 'no_candidate', detail: `no ${p.workflow} workflow_dispatch or push run exists on a head with tree ${tree} (the pull request heads GitHub names for one-parent push ${sha} or recent runs)`, tree, rejected };
return { reuse: false, reason: rejected[0]!.reason, detail: rejected.map(r => r.detail).join('; '), tree, rejected };
}
/** `seeds` plus the heads of recent dispatch and push runs whose commit has `tree`, never `skip` (the push itself). */
async function sameTreeHeads(deps: ReuseDeps, p: Profile, tree: string, repo: string, seeds: string[], skip?: string): Promise<string[]> {
const shas = [...seeds];
const trees = new Map<string, string>();
for (const run of (await deps.recentRuns(p.file)).sort((a, b) => b.id - a.id)) {
if (!isCandidate(run) || run.head_sha === skip || shas.includes(run.head_sha) || run.head_repository?.full_name !== repo || trees.has(run.head_sha)) continue;
if (trees.size >= MAX_FALLBACK_HEADS) break;
trees.set(run.head_sha, (await deps.commit(run.head_sha)).tree);
if (trees.get(run.head_sha) === tree) shas.push(run.head_sha);
}
return shas;
}
/**
* The newest full run across `shas` that decides: a passed complete one (no `why`), or one in progress, failed or with
* a failed full job (`why` says which). A run that skipped its full job or lacks it (a diagnostic dispatch, a push
* that reused) and any other rejected run is recorded in `rejected` and passed over. Undefined when none decides.
*/
async function newestFullRun(deps: ReuseDeps, p: Profile, shas: string[], tree: string, repo: string, rejected: Rejection[]): Promise<{ run: FullRun; why?: Omit<Rejection, 'run_id'> } | undefined> {
const runs = (await Promise.all(shas.map(async sha => (await deps.runsForHead(p.file, sha)).filter(r => r.head_sha === sha && isCandidate(r) && r.head_repository?.full_name === repo)))).flat().sort((a, b) => b.id - a.id);
for (const run of runs) {
const full = (await deps.jobs(run.id, run.run_attempt)).filter(j => j.name === p.job);
if (full.some(j => j.conclusion === 'skipped') || (run.status === 'completed' && full.length === 0)) {
rejected.push({ run_id: run.id, reason: 'full_suite_missing', detail: `run ${run.id} attempt ${run.run_attempt} did not run ${p.job} (not a full-profile run)` });
continue;
}
const why = await reject(deps, p, run, repo, tree, tree);
if (!why || why.reason === 'run_in_progress' || why.reason === 'run_failed' || why.reason === 'full_suite_not_success') return { run, why };
rejected.push({ run_id: run.id, ...why });
}
return undefined;
}
function accept(run: FullRun, tree: string, rejected: Rejection[], where: string): Decision {
return { reuse: true, reason: 'identical_tree_full_run', detail: `run ${run.id} attempt ${run.run_attempt} on ${where} ran the complete full suite on tree ${tree}`, tree, source: { run_id: run.id, run_attempt: run.run_attempt, sha: run.head_sha }, rejected };
}
/**
* Remote-gate reuse (scripts/pregate-remote-gate.sh, docs/ci-event-parity.md#remote-gate-reuse): GitHub's full
* profile is the source of truth, so a clean working tree whose commit `head` (or another head with the same tree)
* already passed the complete full run of a workflow needs no Ubicloud gate. Same fail-closed checks as a push:
* the run's latest attempt and its full-suite job succeeded and its tested-tree artifact records `tree`. Only
* the identical tree reuses; a stamp-only difference goes through gstack-pregate's stamp rule, never through here.
* The newest full run on the tree decides, across `head` and every other recent head with the same tree: in progress
* waits, a failure refuses (no receipt, no VMs), cancelled or not a full run (its full job skipped or absent: a
* diagnostic dispatch, a push that reused) looks further back; a passed run on `head` whose executed-test receipt is
* refused is `rejected`, since no later dispatch of `head` is coming (on another same-tree head it is `none`: `head`'s
* own dispatch can still appear); anything else is `none` and the caller runs the VM gate.
*/
export type GateState = 'reuse' | 'pending' | 'failed' | 'rejected' | 'none';
/**
* Executed test counts; `partial` names the attempt when they cover only the jobs that attempt re-ran, and
* `ledgerAttempt` the earlier attempt that wrote the ledger when it is older than the run's latest attempt.
*/
export interface ExecutedCounts { tests: number; failed: number; partial?: number; ledgerAttempt?: number }
/** The job that writes the executed-identities ledger, in test.yml and e2e.yml. */
export const LEDGER_JOB = 'executed-receipts';
export interface GateDecision { state: GateState; detail: string; tests?: number; failed?: number; partial?: number; url?: string }
export interface GateDeps extends ReuseDeps {
/** Executed (pass, fail) test identities in the run's executed-identities artifact, each job at its newest attempt (`ledgerAttempt` when an earlier attempt wrote it), or why they cannot be read. */
executed(run: FullRun): Promise<ExecutedCounts | { reason: string; transient?: boolean }>;
}
export async function decideGate(deps: GateDeps, p: Profile, head: string, tree: string, repo: string): Promise<GateDecision> {
const rejected: Rejection[] = [];
try {
const headTree = (await deps.commit(head)).tree;
if (headTree !== tree) return { state: 'none', detail: `${p.workflow}: commit ${head} has tree ${headTree} on GitHub, not the working tree ${tree}` };
const found = await newestFullRun(deps, p, await sameTreeHeads(deps, p, tree, repo, [head]), tree, repo, rejected);
if (found && !found.why) {
const d = await gateAccept(deps, p, found.run, tree, repo);
return d.state === 'rejected' && found.run.head_sha !== head ? { ...d, state: 'none' } : d;
}
if (found?.why?.reason === 'run_in_progress') return { state: 'pending', detail: `${p.workflow} ${found.why.detail}` };
if (found?.why) return { state: 'failed', detail: `${p.workflow} ${found.why.detail}`, url: runUrl(repo, found.run) };
} catch (e) {
return { state: 'none', detail: `${p.workflow}: reading commits, runs, jobs or artifacts failed: ${e instanceof Error ? e.message : String(e)}` };
}
return { state: 'none', detail: rejected.length ? `${p.workflow}: ${rejected.map(r => r.detail).join('; ')}` : `${p.workflow}: no workflow_dispatch or push run on ${head} or on another head with tree ${tree}` };
}
const runUrl = (repo: string, run: FullRun) => `https://github.com/${repo}/actions/runs/${run.id}/attempts/${run.run_attempt}`;
async function gateAccept(deps: GateDeps, p: Profile, run: FullRun, tree: string, repo: string): Promise<GateDecision> {
const got = await deps.executed(run);
if ('reason' in got) return { state: got.transient ? 'none' : 'rejected', detail: `${p.workflow}: ${got.reason}` };
const { ledgerAttempt, ...counts } = got;
// A re-run that leaves the ledger job alone carries it into the new attempt with its original start; a ledger job
// that ran again but uploaded nothing leaves the older attempt's ledger behind, now stale.
if (ledgerAttempt !== undefined) {
const started = async (attempt: number) => (await deps.jobs(run.id, attempt)).filter(j => j.name === LEDGER_JOB).map(j => j.started_at);
const [wrote, latest] = await Promise.all([started(ledgerAttempt), started(run.run_attempt)]);
if (wrote.length !== 1 || latest.length !== 1 || !wrote[0] || wrote[0] !== latest[0]) {
return { state: 'rejected', detail: `${p.workflow}: run ${run.id}'s executed-identities.json is from attempt ${ledgerAttempt}, but its ${LEDGER_JOB} job ran again by attempt ${run.run_attempt} without replacing it` };
}
}
if (counts.tests <= 0) return { state: 'rejected', detail: `${p.workflow}: run ${run.id}'s executed-identities artifact lists no executed test` };
return { state: 'reuse', detail: `${p.workflow} run ${runUrl(repo, run)} passed the complete full suite on tree ${tree}`, url: runUrl(repo, run), ...counts };
}
export const GATE_WAIT_MINUTES = 90;
export const GATE_POLL_SECONDS = 60;
/**
* The gate's decision over Test and E2E, waiting while a full run on the tree is still in progress, up to the wait
* bound. A workflow with no full run on the tree does not end the wait: full-ci dispatches Test and E2E separately, so
* its run can still appear, and a failure of the run in progress refuses (exit 3) instead of starting VMs on a tree
* GitHub already failed (#8096). A `rejected` workflow ends the wait at once: reuse needs both. Prints progress
* at least every poll (gstack's stall timeout kills a silent gate) and, on reuse, a last line
* `GBRAIN_REUSE_RESULT tests=<n> failed=<n>`. Exit codes: 0 reuse, 3 a full run on this tree failed, 4 no reuse.
*/
export async function runGate(deps: GateDeps, o: { head: string; tree: string; repo: string; waitMs: number; pollMs: number; log: (line: string) => void; sleep?: (ms: number) => Promise<unknown>; now?: () => number }): Promise<number> {
const now = o.now ?? Date.now;
const deadline = now() + o.waitMs;
for (;;) {
const ds = await Promise.all([PROFILES.test, PROFILES.e2e].map(p => decideGate(deps, p, o.head, o.tree, o.repo)));
const failed = ds.find(d => d.state === 'failed');
if (failed) {
o.log(`[ci-reuse] gate: ${failed.detail} (${failed.url}); the full run on this tree failed, so no receipt and no Ubicloud gate`);
return 3;
}
if (ds.every(d => d.state === 'reuse')) {
for (const d of ds) o.log(`[ci-reuse] gate: ${d.detail} (${d.tests} tests, ${d.failed} failed${d.partial ? `; attempt ${d.partial}, partial count` : ''})`);
o.log(`GBRAIN_REUSE_RESULT tests=${ds.reduce((n, d) => n + d.tests!, 0)} failed=${ds.reduce((n, d) => n + d.failed!, 0)}`);
return 0;
}
const pending = ds.filter(d => d.state === 'pending');
if (!pending.length || ds.some(d => d.state === 'rejected') || now() >= deadline) {
for (const d of ds.filter(x => x.state !== 'reuse')) o.log(`[ci-reuse] gate: no reuse: ${inert(d.detail, 600)}`);
return 4;
}
const none = ds.filter(d => d.state === 'none').map(d => `; no full run to reuse yet (${inert(d.detail, 300)}), so this wait reuses only if one appears and otherwise refuses if the run in progress fails`).join('');
o.log(`[ci-reuse] gate: waiting for ${pending.map(d => d.detail).join('; ')}${none} (${Math.ceil((deadline - now()) / 60_000)} min left)`);
await (o.sleep ?? Bun.sleep)(o.pollMs);
}
}
/**
* Every job of one attempt. The jobs API pages at up to 100, but GitHub has answered a 100-job page of a rerun attempt
* with a 502 on every retry while 30-job pages of the same attempt answered (Release run 39712021085, v0.60.361.0), so a
* 5xx that outlives the client's retries restarts the listing at 30 per page.
*/
export async function attemptJobs(client: GitHubClient, runId: number, attempt: number): Promise<JobRow[]> {
for (const perPage of [100, 30]) {
const out: JobRow[] = [];
try {
for (let page = 1; page * perPage <= 1000; page++) {
const r = await client.request<{ total_count: number; jobs: JobRow[] }>('GET', `repos/{repo}/actions/runs/${runId}/attempts/${attempt}/jobs?per_page=${perPage}&page=${page}`);
out.push(...r.jobs);
if (r.jobs.length < perPage || out.length >= r.total_count) return out;
}
} catch (e) {
if (perPage === 30 || ((e as { status?: number }).status ?? 0) < 500) throw e;
continue;
}
throw new Error(`run ${runId} attempt ${attempt} lists more than 1000 jobs`);
}
throw new Error('unreachable');
}
export function apiDeps(client: GitHubClient): ReuseDeps {
return {
async commit(sha) {
const c = await client.request<{ tree: { sha: string }; parents: Array<{ sha: string }> }>('GET', `repos/{repo}/git/commits/${sha}`);
return { tree: c.tree.sha, parents: c.parents.map(x => x.sha) };
},
async runsForHead(file, sha) {
return (await client.request<{ workflow_runs: FullRun[] }>('GET', `repos/{repo}/actions/workflows/${file}/runs?head_sha=${sha}&per_page=100`)).workflow_runs;
},
async recentSuccessfulRuns(file) {
const pages = await Promise.all(CANDIDATE_EVENTS.map(event => client.request<{ workflow_runs: FullRun[] }>('GET', `repos/{repo}/actions/workflows/${file}/runs?event=${event}&status=success&per_page=100`)));
return pages.flatMap(p => p.workflow_runs);
},
async pullHeads(sha) {
return (await client.request<Array<{ head: { sha: string } }>>('GET', `repos/{repo}/commits/${sha}/pulls`)).map(pr => pr.head.sha);
},
async recentRuns(file) {
const pages = await Promise.all(CANDIDATE_EVENTS.map(event => client.request<{ workflow_runs: FullRun[] }>('GET', `repos/{repo}/actions/workflows/${file}/runs?event=${event}&per_page=100`)));
return pages.flatMap(p => p.workflow_runs);
},
jobs: (runId, attempt) => attemptJobs(client, runId, attempt),
artifact: (runId, name) => fetchArtifactJson(client, runId, name, TREE_FILE),
};
}
export function gateDeps(client: GitHubClient): GateDeps {
return {
...apiDeps(client),
async executed(run) {
const got = await fetchArtifactJson(client, run.id, 'executed-identities', 'executed-identities.json');
if (got.reason) return got.transient ? { reason: got.reason, transient: true } : { reason: got.reason };
const doc = got.value as { head?: { identities?: Array<{ status?: string }> }; issues?: Array<{ kind?: string }>; run?: { id?: unknown; attempt?: unknown } | null; job_latest?: { executed?: unknown; failed?: unknown } } | null;
const ids = doc?.head?.identities;
if (!Array.isArray(ids)) return { reason: `run ${run.id}'s executed-identities.json has no head.identities list` };
const by = doc!.run;
if (by && (by.id !== run.id || typeof by.attempt !== 'number' || by.attempt > run.run_attempt)) {
return { reason: `run ${run.id} attempt ${run.run_attempt}'s executed-identities.json was written by run ${String(by.id)} attempt ${String(by.attempt)}` };
}
const older = by && (by.attempt as number) < run.run_attempt ? { ledgerAttempt: by.attempt as number } : {};
const latest = doc!.job_latest;
if (latest && Number.isSafeInteger(latest.executed) && Number.isSafeInteger(latest.failed)) return { tests: latest.executed as number, failed: latest.failed as number, ...older };
const counts = { tests: ids.filter(i => i.status === 'pass' || i.status === 'fail').length, failed: ids.filter(i => i.status === 'fail').length, ...older };
return Array.isArray(doc!.issues) && doc!.issues.some(i => i?.kind === 'prior-attempt') ? { ...counts, partial: run.run_attempt } : counts;
},
};
}
/** The validated source run of a reuse record, or why the record cannot prove one. */
export function checkRecord(value: unknown, workflow: string, pushSha: string): { run_id: number; run_attempt: number; sha: string } | string {
const rec = value as Record<string, unknown> | null | undefined;
if (!rec || typeof rec !== 'object') return `${REUSE_FILE} is not a JSON object`;
if (rec.reuse !== true) return `${REUSE_FILE} says reuse is not true`;
if (rec.workflow !== workflow) return `${REUSE_FILE} is for workflow ${String(rec.workflow)}, not ${workflow}`;
if (rec.push_sha !== pushSha) return `${REUSE_FILE} is for push ${String(rec.push_sha)}, not ${pushSha}`;
const id = rec.source_run_id, attempt = rec.source_run_attempt, sha = rec.source_sha;
if (!Number.isSafeInteger(id) || (id as number) <= 0 || !Number.isSafeInteger(attempt) || (attempt as number) <= 0 || typeof sha !== 'string' || !SHA.test(sha)) return `${REUSE_FILE} names no valid source run`;
return { run_id: id as number, run_attempt: attempt as number, sha };
}
export function writeDecision(d: Decision, p: Profile, opts: { repo: string; sha: string; output: string; summary?: string; record?: string }): string {
const url = d.source && `https://github.com/${opts.repo}/actions/runs/${d.source.run_id}/attempts/${d.source.run_attempt}`;
appendFileSync(opts.output, [
`reuse=${d.reuse}`, `source_run_id=${d.source?.run_id ?? ''}`, `source_run_attempt=${d.source?.run_attempt ?? ''}`,
`source_sha=${d.source?.sha ?? ''}`, `tree=${d.tree ?? ''}`, `reason=${d.reason}`, '',
].join('\n'));
const line = d.reuse
? `${p.workflow} push ${opts.sha.slice(0, 12)}: reused the complete full-suite run ${url} (head ${d.source!.sha.slice(0, 12)}, identical tree ${d.tree}).`
: `${p.workflow} push ${opts.sha.slice(0, 12)}: full run, no reuse (reason \`${d.reason}\`: ${inert(d.detail, 600)}).`;
if (opts.summary) appendFileSync(opts.summary, `${line}\n`);
if (opts.record) {
writeFileSync(opts.record, `${JSON.stringify({
reuse: d.reuse, workflow: p.workflow, push_sha: opts.sha, tree: d.tree ?? null, reason: d.reason,
source_run_id: d.source?.run_id ?? null, source_run_attempt: d.source?.run_attempt ?? null, source_sha: d.source?.sha ?? null, source_url: url ?? null,
}, null, 2)}\n`);
}
return line;
}
const flag = (name: string) => { const i = process.argv.indexOf(name); return i >= 0 ? process.argv[i + 1] : undefined; };
if (import.meta.main && process.argv.includes('--gate')) {
const head = flag('--sha') ?? '', tree = flag('--tree') ?? '', repo = flag('--repo') ?? '';
const minutes = Number(flag('--wait-minutes') ?? GATE_WAIT_MINUTES), poll = Number(flag('--poll-seconds') ?? GATE_POLL_SECONDS);
if (!SHA.test(head) || !SHA.test(tree) || !/^[\w.-]+\/[\w.-]+$/.test(repo) || !(minutes >= 0) || !(poll > 0)) {
console.log(`Usage: bun scripts/ci-reuse.ts --gate --sha <40-hex HEAD> --tree <40-hex tree> --repo <owner/name> [--wait-minutes ${GATE_WAIT_MINUTES}] [--poll-seconds ${GATE_POLL_SECONDS}]`);
process.exit(2);
}
process.exit(await runGate(gateDeps(restClient(repo)), { head, tree, repo, waitMs: minutes * 60_000, pollMs: poll * 1000, log: line => console.log(line) }));
} else if (import.meta.main) {
const key = flag('--workflow') ?? '';
const sha = flag('--sha') ?? '';
const repo = flag('--repo') ?? '';
const output = flag('--output');
if (!(key === 'test' || key === 'e2e') || !SHA.test(sha) || !/^[\w.-]+\/[\w.-]+$/.test(repo) || !output) {
console.log('Usage: bun scripts/ci-reuse.ts --workflow test|e2e --sha <40-hex push sha> --repo <owner/name> --output <GITHUB_OUTPUT> [--summary <GITHUB_STEP_SUMMARY>] [--record <reuse.json>]');
process.exit(2);
}
const p = PROFILES[key];
const d = await decide(apiDeps(restClient(repo)), p, sha, repo);
console.log(`[ci-reuse] ${writeDecision(d, p, { repo, sha, output, summary: flag('--summary'), record: flag('--record') })}`);
}