willfire 0.1.8 → 0.1.10

package/README.md

@@ -20,10 +20,23 @@ pnpm add willfire
 import { predict } from "willfire";
 import { getOctokit } from "@actions/github"; // or new Octokit({ auth: token })
 
-const { entries, checkNames, skip } = await predict(getOctokit(token), "owner/repo", 123);
+const { entries, checkNames, skip, sources } = await predict(
+  getOctokit(token),
+  "owner/repo",
+  123,
+  { action: context.payload.action }, // "opened" | "synchronize" | "reopened"
+);
 // checkNames: sorted, deduped checkName of every entry with status "run"
+// sources: every repo read, and the commit each ref resolved to
 ```
 
+`action` is optional but worth passing. Omitted, the event action is inferred
+from the PR's commit count, which is wrong in both directions — a PR opened
+from a branch with several commits looks like `synchronize`, a force-push down
+to one commit looks like `opened` — and can never produce `reopened`. That only
+matters to a workflow narrowing `types:`, where it decides whether the workflow
+dispatches at all.
+
 `entries` is a union of two variants, both carrying `workflow` and `reason`:
 
 | variant | `job` | `checkName` | `status` |
@@ -48,6 +61,17 @@ single name is knowable ahead of the run:
   four-level limit;
 - a `name:` interpolating something we cannot evaluate statically.
 
+`sources` is the provenance of the answer: the PR's own repo at the head
+commit, then one entry per cross-repo `uses:` that was read, each carrying both
+the `ref` the workflow wrote and the `sha` it resolved to. A ref is resolved
+before the file behind it is read, so the commit named is the commit used. `v0`
+is a tag someone moves; without the sha, "willfire predicted these checks" is
+not a claim that can be checked against the run afterwards.
+
+A ref that will not resolve is not a source. Its callee is never read, the jobs
+behind it come back `unknown`, and nothing falls back to reading the mutable
+ref.
+
 Duplicate names in `checkNames` are not possible (it is a set), but duplicate
 check names *are* — GitHub happily creates two identically named checks when a
 matrix job's `name:` does not vary per combination. `entries` shows them.
@@ -58,9 +82,13 @@ Auth is any token with `contents: read`, `actions: read`, and
 ## CLI
 
 ```sh
-GH_TOKEN=... willfire --repo owner/repo --pr 123 [--json]
+GH_TOKEN=... willfire --repo owner/repo --pr 123 \
+  [--action opened|synchronize|reopened] [--json]
 ```
 
+Plain-text output is one line per entry, then a `# read owner/repo@ref -> sha`
+line per source. `--json` prints the whole `Prediction`, `sources` included.
+
 ## What it handles
 
 Path filters (`paths`, `paths-ignore`, order-sensitive `!` negation), branch
@@ -68,8 +96,8 @@ filters, event `types`, combined filters, `[skip ci]` and friends, disabled
 workflows, multi-job workflows, static matrix expansion (including
 `exclude`/`include`), `needs` skip-propagation, job-level `if`, and reusable
 workflows — both the local `./.github/workflows/x.yml` form and the cross-repo
-`owner/repo/.github/workflows/x.yml@ref` form, whose callee is fetched from its
-own repo at the pinned tag, branch, or SHA. Jobs whose `if` is false are
+`owner/repo/.github/workflows/x.yml@ref` form, whose ref is resolved to a
+commit and the callee then read at that commit. Jobs whose `if` is false are
 predicted as `skipped` entries, matching how they appear in the checks UI.
 
 Things that cannot be known statically — e.g. a matrix computed at runtime
@@ -124,7 +152,10 @@ the docs do not state:
 
 Scope notes: validated on `opened` pull_request events; `synchronize`/`labeled`
 live events, `branches-ignore`, and diffs far beyond 301 files are not yet
-probe-verified. Reusable-workflow name prefixing is probe-verified to three
+probe-verified — passing `action` explicitly is what makes probing the other
+two possible. `action` accepts the three default `types:` only; `pull_request`
+fires on around twenty actions, and a workflow narrowing to `ready_for_review`
+or `edited` is out of scope either way. Reusable-workflow name prefixing is probe-verified to three
 levels; deeper nesting is inferred. The cross-repo probe calls back into the
 probe repo itself by full `owner/repo@ref` reference, so it pins ref
 resolution but not the owner/repo half of the address.

package/dist/predict.d.ts

@@ -41,6 +41,11 @@ export interface WorkflowEntry extends EntryBase {
  * These can be genuinely undecidable statically — dynamic matrix, a reusable
  * workflow we cannot read, unresolvable `if`, or `needs` on any of those — so
  * `"unknown"` lives here and only here.
+ *
+ * `"no-dispatch"` is the mirror image, and lives on {@link WorkflowEntry} and
+ * only there. It is a verdict about whether the run happens at all, which is
+ * settled before any job is looked at — so by the time there is a job entry to
+ * label, the answer is already yes.
  */
 export interface JobEntry extends EntryBase {
     job: JobName;
@@ -54,7 +59,7 @@ export interface JobEntry extends EntryBase {
      * interpolates something we cannot evaluate ahead of the run.
      */
     checkName: string | null;
-    status: "run" | "skipped" | "unknown" | "no-dispatch";
+    status: "run" | "skipped" | "unknown";
 }
 export type Entry = WorkflowEntry | JobEntry;
 /** Narrow to the workflow-level variant without inspecting the sentinel. */
@@ -70,10 +75,43 @@ export interface Prediction {
      */
     checkNames: string[];
     skip: string | null;
+    /**
+     * Every repo this prediction read, and the commit each ref resolved to —
+     * the PR's own head first, then any cross-repo `uses:` reached from it.
+     *
+     * Provenance, not input. `v0` is a moving tag, so "willfire said these
+     * checks" is only reconcilable against a run if it also says which commits
+     * it read to say it. Sorted by `owner/repo@ref`.
+     */
+    sources: WorkflowSource[];
 }
 export declare function patternToRegex(pat: string): RegExp;
 /** Order-sensitive match: last matching pattern wins; ! negates. */
 export declare function matchFilters(value: string, patterns: string[]): boolean;
+/**
+ * The `pull_request` actions a caller can name.
+ *
+ * Deliberately the three default types and no more. `pull_request` fires on
+ * around twenty actions — `ready_for_review`, `edited`, `labeled` — and a
+ * workflow that narrows `types:` to one of those is not predictable today
+ * regardless of what is passed here. Widening this union later is a
+ * non-breaking change; narrowing it would not be, so it starts narrow.
+ */
+export type PrEventAction = "opened" | "synchronize" | "reopened";
+/** Options every caller may omit. */
+export interface PredictOptions {
+    /**
+     * The literal event action the run was triggered by — `github.event.action`
+     * inside an Action, or `--action` on the CLI.
+     *
+     * Omitting it falls back to inferring from the commit count, which is a
+     * guess and is wrong in both directions: a PR opened from a branch with
+     * several commits looks like `synchronize`, a force-push down to one commit
+     * looks like `opened`, and `reopened` is never produced. That only matters
+     * to a workflow narrowing `types:`, where it matters completely.
+     */
+    action?: PrEventAction;
+}
 export interface Ctx {
     action: string;
     baseRef: string;
@@ -112,20 +150,54 @@ export interface ExpandedJob {
  * `owner/repo/path@ref` resolves against *that* repo at *that* ref — probe
  * verified, see `src/names.test.ts`.
  */
-export interface WorkflowSource {
+export interface SourceRef {
     owner: string;
     repo: string;
     /** Tag, branch, or SHA — whatever `@` was pinned to. */
     ref: string;
 }
+/**
+ * A source whose ref has been resolved to the commit it names.
+ *
+ * Expansion walks these and never a bare {@link SourceRef}: `v0` is a moving
+ * tag, so two reads an hour apart can be two different programs, and a
+ * prediction that cannot name the commit it read cannot be reconciled against
+ * the run afterwards. Making the SHA required is what stops an unresolved ref
+ * being expanded against by accident.
+ */
+export interface WorkflowSource extends SourceRef {
+    /** The commit `ref` names. Equal to `ref` when it was already a SHA. */
+    sha: string;
+}
 /** Read one workflow file, or null if it is not reachable. Must not throw. */
 export type FetchWorkflow = (path: string, source: WorkflowSource) => Promise<string | null>;
+/**
+ * Resolve a tag, branch, or SHA to the commit it names, or null when it cannot
+ * be resolved. Must not throw.
+ *
+ * Null is not a cue to fall back to the mutable ref. It leaves every entry
+ * behind that source unresolved, which turns the gate red — reading a ref we
+ * cannot name is the thing this exists to stop.
+ */
+export type ResolveRef = (source: SourceRef) => Promise<string | null>;
+/**
+ * The two reads expansion needs from the outside world, bundled so the recursion
+ * carries one parameter instead of two.
+ */
+export interface WorkflowReader {
+    fetchWorkflow: FetchWorkflow;
+    resolveRef: ResolveRef;
+}
 /** A `uses:` that named a workflow file we know how to go and get. */
 export interface UsesTarget {
     /** Path inside the target repo, e.g. `.github/workflows/x.yml`. */
     path: string;
-    /** null for a local `./` call: the caller's own repo and ref. */
-    source: WorkflowSource | null;
+    /**
+     * null for a local `./` call: the caller's own repo and ref, already
+     * resolved. Non-null sources arrive unresolved — the ref is whatever the
+     * `uses:` string spelled.
+     */
+    source: SourceRef | null;
 }
 /**
  * Split a job-level `uses:` into the file it names and the repo it lives in.
@@ -146,7 +218,7 @@ export declare function parseUses(uses: string): UsesTarget | null;
  * names can be tested against recorded GitHub behaviour without a network
  * round-trip; `predict` is the API you want.
  */
-export declare function expandWorkflowJobs(wf: Workflow, ctx: Ctx, fetchWorkflow: FetchWorkflow, source: WorkflowSource): Promise<ExpandedJob[]>;
+export declare function expandWorkflowJobs(wf: Workflow, ctx: Ctx, reader: WorkflowReader, source: WorkflowSource): Promise<ExpandedJob[]>;
 export declare function makeOctokit(): Octokit;
-export declare function predict(octokit: Octokit, repo: string, prNumber: number): Promise<Prediction>;
+export declare function predict(octokit: Octokit, repo: string, prNumber: number, opts?: PredictOptions): Promise<Prediction>;
 export {};

package/dist/predict.js

@@ -363,6 +363,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,7 +400,7 @@ 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 = {}) {
     const entries = [];
     const jobs = wf.jobs ?? {};
     const statuses = {};
@@ -466,18 +471,34 @@ 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);
+                            subScope = { inputs: calleeInputs(job.with, subWf ?? {}) };
+                        }
+                        catch (e) {
+                            failure = `YAML parse error in ${uses}: ${e}`;
+                        }
                     }
                 }
             }
@@ -494,7 +515,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)));
             }
             continue;
         }
@@ -525,8 +546,8 @@ async function expandJobs(wf, ctx, fetchWorkflow, source, depth = 0, prefix = ""
  * names can be tested against recorded GitHub behaviour without a network
  * round-trip; `predict` is the API you want.
  */
-export function expandWorkflowJobs(wf, ctx, fetchWorkflow, source) {
-    return expandJobs(wf, ctx, fetchWorkflow, source);
+export function expandWorkflowJobs(wf, ctx, reader, source) {
+    return expandJobs(wf, ctx, reader, source);
 }
 // ------------------------------------------------------------------- pipeline
 export function makeOctokit() {
@@ -535,7 +556,7 @@ export function makeOctokit() {
         throw new Error("GH_TOKEN or GITHUB_TOKEN must be set");
     return new Octokit({ auth: token });
 }
-export async function predict(octokit, repo, prNumber) {
+export async function predict(octokit, repo, prNumber, opts = {}) {
     const [owner, name] = repo.split("/");
     const base = { owner, repo: name };
     const { data: pr } = await octokit.rest.pulls.get({ ...base, pull_number: prNumber });
@@ -545,27 +566,67 @@ export async function predict(octokit, repo, prNumber) {
         per_page: 100,
     });
     const ctx = {
-        action: pr.commits > 1 ? "synchronize" : "opened",
+        // The caller's answer wins whenever it has one. The commit-count fallback
+        // is a guess kept only so existing callers keep working.
+        action: opts.action ?? (pr.commits > 1 ? "synchronize" : "opened"),
         baseRef: pr.base.ref,
         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;
@@ -575,7 +636,7 @@ export async function predict(octokit, repo, prNumber) {
                 owner: src.owner,
                 repo: src.repo,
                 path,
-                ref: src.ref,
+                ref: src.sha,
                 mediaType: { format: "raw" },
             });
             content = data;
@@ -588,6 +649,7 @@ export async function predict(octokit, repo, prNumber) {
         cache.set(key, content);
         return content;
     };
+    const reader = { fetchWorkflow, resolveRef };
     const workflows = await octokit.paginate(octokit.rest.actions.listRepoWorkflows, {
         ...base,
         per_page: 100,
@@ -640,7 +702,7 @@ export async function predict(octokit, repo, prNumber) {
             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)) {
             entries.push({
                 workflow: path,
                 job: jobName(j.job),
@@ -650,18 +712,25 @@ export async function predict(octokit, repo, prNumber) {
             });
         }
     }
-    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 isPrEventAction = (v) => v === "opened" || v === "synchronize" || v === "reopened";
 function parseArgs(argv) {
     const get = (flag) => {
         const i = argv.indexOf(flag);
@@ -670,29 +739,47 @@ function parseArgs(argv) {
     const repo = get("--repo");
     const pr = get("--pr");
     if (!repo || !pr) {
-        console.error("usage: predict --repo owner/name --pr N [--json]");
+        console.error(USAGE);
         process.exit(2);
     }
-    return { repo, pr: Number(pr), json: argv.includes("--json") };
+    // An unrecognised action is refused rather than ignored. Silently falling
+    // back to the guess would turn a typo into a wrong prediction, which is the
+    // failure this flag exists to remove.
+    const action = get("--action");
+    if (action !== undefined && !isPrEventAction(action)) {
+        console.error(`unknown --action: ${action}`);
+        console.error(USAGE);
+        process.exit(2);
+    }
+    return { repo, pr: Number(pr), json: argv.includes("--json"), action };
 }
 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,
+    });
+    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.8",
+  "version": "0.1.10",
   "description": "Predict the set of CI check entries GitHub Actions will create for a pull request",
   "license": "MIT",
   "packageManager": "pnpm@10.33.0",