willfire 0.1.9 → 0.1.11

package/dist/predict.js

@@ -12,7 +12,8 @@
 // src/names.test.ts.
 import { Octokit } from "@octokit/rest";
 import { parse as parseYaml } from "yaml";
-import { evaluate, UNKNOWN } from "./expr.js";
+import { makeExecutor, makeTreeProvider, parseGrant, runShell, } from "./execute.js";
+import { evaluate, evaluateValue, UNKNOWN } from "./expr.js";
 /** Tag a job display name. Rejects the workflow-level sentinel. */
 export const jobName = (name) => name;
 /** Narrow to the workflow-level variant without inspecting the sentinel. */
@@ -126,12 +127,34 @@ function workflowDispatches(wf, ctx) {
     }
     return [true, "trigger matched"];
 }
-function expandMatrixDetailed(strategy) {
+/**
+ * The values of one matrix axis, or null when they cannot be known.
+ *
+ * A plain list is itself. An axis written as an expression —
+ * `language: ${{ fromJSON(needs.detect.outputs.coverage_languages) }}` — is
+ * the values another job computed, and is knowable exactly when the scope
+ * carries that job's outputs. Anything else stays null, which is what makes
+ * the whole job `unknown` rather than a guess at how many checks it creates.
+ */
+function axisValues(v, scope) {
+    if (Array.isArray(v))
+        return v;
+    if (typeof v !== "string")
+        return null;
+    const val = evaluateValue(v, scope);
+    if (val.kind !== "json" || !Array.isArray(val.v))
+        return null;
+    return val.v;
+}
+function expandMatrixDetailed(strategy, scope = {}) {
     const matrix = strategy?.matrix;
     if (matrix == null)
         return [null];
+    // `matrix: ${{ ... }}` — the whole matrix as one expression, rather than the
+    // per-axis form below. It yields include-style entries, not axes, so it is a
+    // separate expansion and is not modelled.
     if (typeof matrix === "string")
-        return null; // ${{ fromJSON(...) }}
+        return null;
     const include = matrix.include ?? [];
     const exclude = matrix.exclude ?? [];
     if (typeof include === "string" || typeof exclude === "string")
@@ -140,9 +163,10 @@ function expandMatrixDetailed(strategy) {
     for (const [k, v] of Object.entries(matrix)) {
         if (k === "include" || k === "exclude")
             continue;
-        if (!Array.isArray(v))
+        const vals = axisValues(v, scope);
+        if (vals == null)
             return null;
-        axes[k] = v;
+        axes[k] = vals;
     }
     const axisKeys = Object.keys(axes);
     let combos = [{ values: {}, displayKeys: axisKeys }];
@@ -177,8 +201,8 @@ function expandMatrixDetailed(strategy) {
     return combos;
 }
 /** Return list of matrix combination dicts, or null if dynamic. */
-export function expandMatrix(strategy) {
-    const detailed = expandMatrixDetailed(strategy);
+export function expandMatrix(strategy, scope = {}) {
+    const detailed = expandMatrixDetailed(strategy, scope);
     return detailed == null ? null : detailed.map((c) => (c == null ? null : c.values));
 }
 /**
@@ -283,20 +307,30 @@ function skippedDisplayName(jobId, job) {
  * resolve instead of hanging the job on an unknown.
  */
 const PR_GITHUB_CONTEXT = { event_name: "pull_request" };
+/**
+ * A scope with the fixed pull-request facts filled in.
+ *
+ * Every `${{ }}` this module evaluates — a job `if:`, a matrix axis — is
+ * evaluated for the same event, so they all get the same `github.*`. Anything
+ * the caller states wins; there is nothing here worth overriding, but a scope
+ * that silently ignored what it was handed would be the wrong shape.
+ */
+const prScope = (scope) => ({
+    ...scope,
+    github: { ...PR_GITHUB_CONTEXT, ...scope.github },
+});
 /**
  * Return run|skipped|unknown for a job-level `if:`.
  *
- * `scope` carries the inputs the calling workflow passed down. Without it a
- * reusable workflow's guards are all unknown, because every one of them is
- * written against `inputs.*`.
+ * `scope` carries the inputs the calling workflow passed down, and any job
+ * outputs the caller knows. Without it a reusable workflow's guards are all
+ * unknown, because every one of them is written against `inputs.*` or
+ * `needs.*`.
  */
 export function evalIf(cond, scope = {}) {
     if (cond == null)
         return "run";
-    const verdict = evaluate(String(cond), {
-        inputs: scope.inputs,
-        github: { ...PR_GITHUB_CONTEXT, ...scope.github },
-    });
+    const verdict = evaluate(String(cond), prScope(scope));
     if (verdict === null)
         return "unknown";
     return verdict ? "run" : "skipped";
@@ -363,6 +397,11 @@ function calleeInputs(withBlock, subWf) {
  * mixes the two is counted the same way.
  */
 const MAX_REUSABLE_DEPTH = 4;
+/** `ref` is already a commit id, so resolving it is a no-op. */
+const SHA_RE = /^[0-9a-f]{40}$/i;
+const isSha = (ref) => SHA_RE.test(ref);
+/** Identity of a source as written, before resolution. */
+const sourceKey = (s) => `${s.owner}/${s.repo}@${s.ref}`;
 /**
  * Split a job-level `uses:` into the file it names and the repo it lives in.
  *
@@ -395,13 +434,43 @@ export function parseUses(uses) {
         return null;
     return { path, source: { owner, repo, ref } };
 }
-async function expandJobs(wf, ctx, fetchWorkflow, source, depth = 0, prefix = "", prefixResolved = true, scope = {}) {
+async function expandJobs(wf, ctx, reader, source, depth = 0, prefix = "", prefixResolved = true, scope = {}, executor) {
     const entries = [];
     const jobs = wf.jobs ?? {};
     const statuses = {};
+    // Execute what the caller granted, before anything reads `needs`. The
+    // grant names the repo the workflow *file* lives in, so a granted callee
+    // job fires here in the recursion, where `source` is that repo. The guard
+    // is the same `evalIf` the main loop applies — same scope, same verdict —
+    // so a job is executed exactly when it is predicted to run. A job that
+    // would not run is not executed; a job that fails to execute contributes
+    // nothing but its reason, which `execNote` threads into the entries that
+    // needed it.
+    let scoped = scope;
+    const execFailures = {};
+    if (executor != null) {
+        for (const [jobId, jobRaw] of Object.entries(jobs)) {
+            if (!executor.granted(source, jobId))
+                continue;
+            const job = jobRaw ?? {};
+            if (evalIf(job.if, scoped) !== "run")
+                continue;
+            const res = await executor.executeJob(jobId, job, wf, scoped);
+            if (res.ok) {
+                scoped = { ...scoped, needs: { ...scoped.needs, [jobId]: { outputs: res.outputs } } };
+            }
+            else {
+                execFailures[jobId] = res.reason;
+            }
+        }
+    }
+    const execNote = (needs) => {
+        const failed = needs.find((n) => n in execFailures);
+        return failed == null ? "" : `; executing '${failed}' failed: ${execFailures[failed]}`;
+    };
     for (const [jobId, jobRaw] of Object.entries(jobs)) {
         const job = jobRaw ?? {};
-        let status = evalIf(job.if, scope);
+        let status = evalIf(job.if, scoped);
         let reason = job.if != null ? `if: ${JSON.stringify(job.if)}` : "";
         let needs = job.needs ?? [];
         if (typeof needs === "string")
@@ -433,7 +502,7 @@ async function expandJobs(wf, ctx, fetchWorkflow, source, depth = 0, prefix = ""
             });
             continue;
         }
-        const combos = expandMatrixDetailed(job.strategy);
+        const combos = expandMatrixDetailed(job.strategy, prScope(scoped));
         if ("uses" in job) {
             // Reusable workflow call. The calling job produces no check of its own;
             // each called job becomes `<calling job name> / <called job name>`, and
@@ -446,7 +515,7 @@ async function expandJobs(wf, ctx, fetchWorkflow, source, depth = 0, prefix = ""
                     job: prefix + jobId,
                     checkName: null,
                     status: "unknown",
-                    reason: "dynamic matrix on reusable workflow call",
+                    reason: "dynamic matrix on reusable workflow call" + execNote(needs),
                 });
                 continue;
             }
@@ -466,18 +535,37 @@ async function expandJobs(wf, ctx, fetchWorkflow, source, depth = 0, prefix = ""
                 failure = `unresolvable reusable reference: ${uses}`;
             }
             else {
-                subSource = target.source ?? source;
-                const content = await fetchWorkflow(target.path, subSource);
-                if (content == null) {
-                    failure = `cannot fetch ${uses}`;
+                // A local `./` call stays on the caller's source, which is already
+                // pinned to a commit. A cross-repo one arrives as whatever the `uses:`
+                // string spelled — `@v0` — and has to be resolved before anything is
+                // read from it, so the file that gets read and the commit the
+                // prediction names are the same one.
+                let resolved = source;
+                if (target.source != null) {
+                    const { ref } = target.source;
+                    const sha = isSha(ref) ? ref : await reader.resolveRef(target.source);
+                    resolved = sha == null ? null : { ...target.source, sha };
+                }
+                if (resolved == null) {
+                    failure = `cannot resolve ref for ${uses}`;
                 }
                 else {
-                    try {
-                        subWf = parseYaml(content);
-                        subScope = { inputs: calleeInputs(job.with, subWf ?? {}) };
+                    subSource = resolved;
+                    const content = await reader.fetchWorkflow(target.path, subSource);
+                    if (content == null) {
+                        failure = `cannot fetch ${uses}`;
                     }
-                    catch (e) {
-                        failure = `YAML parse error in ${uses}: ${e}`;
+                    else {
+                        try {
+                            subWf = parseYaml(content);
+                            // `inputs.*` changes at the call boundary; `github.*` does not.
+                            // A callee's jobs run in the caller's repo, so the facts seeded
+                            // at the top of the prediction stay true all the way down.
+                            subScope = { inputs: calleeInputs(job.with, subWf ?? {}), github: scoped.github };
+                        }
+                        catch (e) {
+                            failure = `YAML parse error in ${uses}: ${e}`;
+                        }
                     }
                 }
             }
@@ -494,7 +582,7 @@ async function expandJobs(wf, ctx, fetchWorkflow, source, depth = 0, prefix = ""
                     });
                     continue;
                 }
-                entries.push(...(await expandJobs(subWf, ctx, fetchWorkflow, subSource, depth + 1, `${baseName} / `, nameResolved, subScope)));
+                entries.push(...(await expandJobs(subWf, ctx, reader, subSource, depth + 1, `${baseName} / `, nameResolved, subScope, executor)));
             }
             continue;
         }
@@ -503,7 +591,7 @@ async function expandJobs(wf, ctx, fetchWorkflow, source, depth = 0, prefix = ""
                 job: prefix + jobId,
                 checkName: null,
                 status: "unknown",
-                reason: "dynamic matrix",
+                reason: "dynamic matrix" + execNote(needs),
             });
             continue;
         }
@@ -524,9 +612,14 @@ async function expandJobs(wf, ctx, fetchWorkflow, source, depth = 0, prefix = ""
  * Expand one already-parsed workflow into its job entries. Exported so check
  * names can be tested against recorded GitHub behaviour without a network
  * round-trip; `predict` is the API you want.
+ *
+ * `scope` seeds what this workflow's own `${{ }}` resolve against — notably
+ * `needs`, the outputs of jobs that have not run. Nothing here works out what
+ * those are; a caller that knows hands them in, and a caller that does not
+ * leaves them out and gets `unknown` where they would have been used.
  */
-export function expandWorkflowJobs(wf, ctx, fetchWorkflow, source) {
-    return expandJobs(wf, ctx, fetchWorkflow, source);
+export function expandWorkflowJobs(wf, ctx, reader, source, scope = {}, executor) {
+    return expandJobs(wf, ctx, reader, source, 0, "", true, scope, executor);
 }
 // ------------------------------------------------------------------- pipeline
 export function makeOctokit() {
@@ -552,22 +645,60 @@ export async function predict(octokit, repo, prNumber, opts = {}) {
         files: files.map((f) => f.filename),
     };
     const headSha = pr.head.sha;
+    /**
+     * The PR's own repo at the head commit — where expansion starts, and already
+     * a commit id, so its `ref` and `sha` are the same string.
+     */
+    const headSource = { owner, repo: name, ref: headSha, sha: headSha };
+    // Provenance for the answer, filled as expansion reaches each source. The head
+    // is in from the start: it is read even on the skip path, where the commit
+    // message is what decides the verdict.
+    const sources = new Map([[sourceKey(headSource), headSource]]);
     const { data: headCommit } = await octokit.rest.repos.getCommit({
         ...base,
         ref: headSha,
     });
     const headMsg = headCommit.commit.message;
     if (SKIP_RE.test(headMsg) || SKIP_TRAILER_RE.test(headMsg)) {
-        return finalizePrediction([], "head commit message contains a skip instruction");
+        return finalizePrediction([], "head commit message contains a skip instruction", sources);
     }
-    /** The PR's own repo at the head commit — where expansion starts. */
-    const headSource = { owner, repo: name, ref: headSha };
+    // A `uses:` naming a tag is the same lookup from every caller that writes it,
+    // so resolve each `owner/repo@ref` once. Misses are cached too: a ref that
+    // cannot be resolved will not start resolving on the second ask.
+    const refCache = new Map();
+    const resolveRef = async (src) => {
+        const key = sourceKey(src);
+        const hit = refCache.get(key);
+        if (hit !== undefined)
+            return hit;
+        let sha;
+        try {
+            const { data } = await octokit.rest.repos.getCommit({
+                owner: src.owner,
+                repo: src.repo,
+                ref: src.ref,
+            });
+            sha = data.sha;
+        }
+        catch {
+            // Deleted tag, private repo, rate limit, network: all one answer here.
+            // The caller turns it into an `unknown` entry rather than throwing.
+            sha = null;
+        }
+        refCache.set(key, sha);
+        if (sha != null)
+            sources.set(key, { ...src, sha });
+        return sha;
+    };
     // One callee is commonly reached from several callers — a fleet repo calls
     // the same `testing-conventions@v0` from eight workflows — so remember what
-    // each `owner/repo/path@ref` resolved to, misses included.
+    // each `owner/repo/path@sha` resolved to, misses included.
     const cache = new Map();
     const fetchWorkflow = async (path, src) => {
-        const key = `${src.owner}/${src.repo}/${path}@${src.ref}`;
+        // Keyed and fetched on the commit, never the ref that named it. Two callers
+        // writing `@v0` and `@abc123` for the same commit are one read, and a tag
+        // that moves mid-prediction cannot hand back two different files.
+        const key = `${src.owner}/${src.repo}/${path}@${src.sha}`;
         const hit = cache.get(key);
         if (hit !== undefined)
             return hit;
@@ -577,7 +708,7 @@ export async function predict(octokit, repo, prNumber, opts = {}) {
                 owner: src.owner,
                 repo: src.repo,
                 path,
-                ref: src.ref,
+                ref: src.sha,
                 mediaType: { format: "raw" },
             });
             content = data;
@@ -590,10 +721,48 @@ export async function predict(octokit, repo, prNumber, opts = {}) {
         cache.set(key, content);
         return content;
     };
+    const reader = { fetchWorkflow, resolveRef };
+    // The executor exists only when the caller granted something. Trees come
+    // from the tarball endpoint at the resolved commit, and every subprocess —
+    // `tar` included — goes through the one `runShell` seam.
+    let executor;
+    if (opts.execute != null && opts.execute.length > 0) {
+        const download = async (src) => {
+            try {
+                const { data } = await octokit.rest.repos.downloadTarballArchive({
+                    owner: src.owner,
+                    repo: src.repo,
+                    ref: src.sha,
+                });
+                return new Uint8Array(data);
+            }
+            catch {
+                // Private, deleted, rate limit, network: one answer, and the entries
+                // behind it stay unresolved with the failure named.
+                return null;
+            }
+        };
+        executor = makeExecutor({
+            grants: opts.execute,
+            workspace: headSource,
+            deps: {
+                provideTree: makeTreeProvider(download, runShell),
+                runCommand: runShell,
+                resolveRef,
+            },
+        });
+    }
     const workflows = await octokit.paginate(octokit.rest.actions.listRepoWorkflows, {
         ...base,
         per_page: 100,
     });
+    // `github.repository` is fixed for everything predicted here: reusable
+    // workflows and composite actions all run in the repo the PR is against.
+    // Seeding it once makes guards like the fleet's hermetic-vs-published
+    // `github.repository ==` checks decidable everywhere, granted or not.
+    const prFacts = {
+        github: { repository: `${headSource.owner}/${headSource.repo}` },
+    };
     const entries = [];
     for (const w of workflows) {
         const path = w.path;
@@ -642,7 +811,7 @@ export async function predict(octokit, repo, prNumber, opts = {}) {
             entries.push({ workflow: path, job: "*", status: "no-dispatch", reason });
             continue;
         }
-        for (const j of await expandJobs(wf, ctx, fetchWorkflow, headSource)) {
+        for (const j of await expandJobs(wf, ctx, reader, headSource, 0, "", true, prFacts, executor)) {
             entries.push({
                 workflow: path,
                 job: jobName(j.job),
@@ -652,19 +821,25 @@ export async function predict(octokit, repo, prNumber, opts = {}) {
             });
         }
     }
-    return finalizePrediction(entries, null);
+    return finalizePrediction(entries, null, sources);
 }
-function finalizePrediction(entries, skip) {
+function finalizePrediction(entries, skip, sources) {
     const final = entries.map(finalize);
     const names = new Set();
     for (const e of final) {
         if (e.status === "run" && e.checkName != null)
             names.add(e.checkName);
     }
-    return { entries: final, checkNames: [...names].sort(), skip };
+    return {
+        entries: final,
+        checkNames: [...names].sort(),
+        skip,
+        sources: [...sources.values()].sort((a, b) => sourceKey(a).localeCompare(sourceKey(b))),
+    };
 }
 // ------------------------------------------------------------------------ CLI
-const USAGE = "usage: predict --repo owner/name --pr N [--action opened|synchronize|reopened] [--json]";
+const USAGE = "usage: predict --repo owner/name --pr N [--action opened|synchronize|reopened]" +
+    " [--execute owner/repo:job1,job2]... [--json]";
 const isPrEventAction = (v) => v === "opened" || v === "synchronize" || v === "reopened";
 function parseArgs(argv) {
     const get = (flag) => {
@@ -686,28 +861,52 @@ function parseArgs(argv) {
         console.error(USAGE);
         process.exit(2);
     }
-    return { repo, pr: Number(pr), json: argv.includes("--json"), action };
+    // Repeatable, one grant per flag. A malformed grant is refused for the same
+    // reason a bad --action is: silently dropping it would predict without the
+    // execution the caller thought they asked for.
+    const execute = [];
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] !== "--execute")
+            continue;
+        const spec = argv[i + 1];
+        const grant = spec == null ? null : parseGrant(spec);
+        if (grant == null) {
+            console.error(`bad --execute: ${spec}`);
+            console.error(USAGE);
+            process.exit(2);
+        }
+        execute.push(grant);
+    }
+    return { repo, pr: Number(pr), json: argv.includes("--json"), action, execute };
 }
 const isMain = /predict\.(ts|js)$|\/willfire$/.test(process.argv[1] ?? "");
 if (isMain) {
     const args = parseArgs(process.argv.slice(2));
-    const { entries, checkNames, skip } = await predict(makeOctokit(), args.repo, args.pr, {
+    const prediction = await predict(makeOctokit(), args.repo, args.pr, {
         action: args.action,
+        execute: args.execute,
     });
+    const { entries, skip, sources } = prediction;
     if (args.json) {
-        console.log(JSON.stringify({ entries, checkNames, skip }, null, 2));
-    }
-    else if (skip) {
-        console.log(`# ${skip} -> nothing dispatches`);
+        console.log(JSON.stringify(prediction, null, 2));
     }
     else {
-        for (const e of entries) {
-            if (isWorkflowEntry(e))
-                console.log(`# ${e.workflow} :: ${e.status} (${e.reason})`);
-            else {
-                const name = e.checkName ?? `${e.job} (name unresolved)`;
-                console.log(`${e.workflow} :: ${name} :: ${e.status}`);
+        if (skip) {
+            console.log(`# ${skip} -> nothing dispatches`);
+        }
+        else {
+            for (const e of entries) {
+                if (isWorkflowEntry(e))
+                    console.log(`# ${e.workflow} :: ${e.status} (${e.reason})`);
+                else {
+                    const name = e.checkName ?? `${e.job} (name unresolved)`;
+                    console.log(`${e.workflow} :: ${name} :: ${e.status}`);
+                }
             }
         }
+        // Last, and on the skip path too, so a red gate's first question — which
+        // commits was this read from? — is answered wherever the reader lands.
+        for (const s of sources)
+            console.log(`# read ${s.owner}/${s.repo}@${s.ref} -> ${s.sha}`);
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "willfire",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Predict the set of CI check entries GitHub Actions will create for a pull request",
   "license": "MIT",
   "packageManager": "pnpm@10.33.0",