willfire 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kevin Scott
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,59 @@
+# willfire
+
+Predicts the set of CI check entries GitHub Actions will create for a pull
+request — before (or without) the runs happening.
+
+GitHub's dispatch decision is server-side and unpublished: no API tells you
+which workflows will fire for a PR after branch/path/type filters, or which
+job entries they expand into. willfire evaluates the workflow files statically
+against the PR's base branch, changed files, and head commit message.
+
+## Install
+
+```sh
+pnpm add willfire
+```
+
+## Library
+
+```ts
+import { predict } from "willfire";
+import { getOctokit } from "@actions/github"; // or new Octokit({ auth: token })
+
+const { entries, skip } = await predict(getOctokit(token), "owner/repo", 123);
+// entries: [{ workflow, job, status: "run" | "skipped" | "unknown" | "no-dispatch", reason }]
+```
+
+Auth is any token with `contents: read`, `actions: read`, and
+`pull-requests: read` — inside an action, the workflow's `GITHUB_TOKEN`.
+
+## CLI
+
+```sh
+GH_TOKEN=... willfire --repo owner/repo --pr 123 [--json]
+```
+
+## What it handles
+
+Path filters (`paths`, `paths-ignore`, order-sensitive `!` negation), branch
+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 local
+reusable workflows. 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
+from another job's output — are reported as `unknown` rather than guessed.
+
+## Verification
+
+Predictions are verified against real GitHub behavior, not just the docs:
+[willrun-probe](https://github.com/thekevinbot/willrun-probe) holds one
+workflow per dispatch rule, and probe PRs exercise each complication
+(docs-only diffs, negation edges, `[skip ci]`, a 301-file diff, PRs into
+non-default branches). The `verify` script diffs predictions against the
+check entries GitHub actually created. All probe PRs currently pass exactly.
+
+Scope notes: validated on `opened` pull_request events; `synchronize`/`labeled`
+live events, cross-repo reusable workflows, `branches-ignore`, and diffs far
+beyond 301 files are not yet probe-verified.

package/dist/predict.d.ts

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import { Octokit } from "@octokit/rest";
+export interface Entry {
+    workflow: string;
+    job: string;
+    status: "run" | "skipped" | "unknown" | "no-dispatch";
+    reason: string;
+}
+export interface Prediction {
+    entries: Entry[];
+    skip: string | null;
+}
+export declare function patternToRegex(pat: string): RegExp;
+/** Order-sensitive match: last matching pattern wins; ! negates. */
+export declare function matchFilters(value: string, patterns: string[]): boolean;
+type Combo = Record<string, any> | null;
+/** Return list of matrix combination dicts, or null if dynamic. */
+export declare function expandMatrix(strategy: any): Combo[] | null;
+/** Return run|skipped|unknown for a job-level if. */
+export declare function evalIf(cond: any): "run" | "skipped" | "unknown";
+export declare function makeOctokit(): Octokit;
+export declare function predict(octokit: Octokit, repo: string, prNumber: number): Promise<Prediction>;
+export {};

package/dist/predict.js

@@ -0,0 +1,375 @@
+#!/usr/bin/env node
+// Predict the set of CI check entries GitHub Actions will create for a PR.
+//
+// Usage: pnpm predict --repo owner/name --pr N [--json]
+// Auth: GH_TOKEN or GITHUB_TOKEN env var (any token with contents/actions/
+// pull-requests read). Inside an action, pass the workflow's GITHUB_TOKEN.
+//
+// Faithful port of predict.py, which was verified entry-for-entry against
+// live dispatches on thekevinbot/willrun-probe (PRs 1-7).
+import { Octokit } from "@octokit/rest";
+import { parse as parseYaml } from "yaml";
+// ------------------------------------------------- GitHub filter pattern glob
+// Grammar per docs: * (any chars except /), ** (any chars), ? (zero or one of
+// preceding char), + (one or more of preceding char), [ranges], leading ! negates.
+const escapeRegex = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+export function patternToRegex(pat) {
+    let out = "";
+    for (let i = 0; i < pat.length; i++) {
+        const c = pat[i];
+        if (c === "*") {
+            if (pat[i + 1] === "*") {
+                out += ".*";
+                i++;
+            }
+            else {
+                out += "[^/]*";
+            }
+        }
+        else if (c === "?" || c === "+") {
+            out += c;
+        }
+        else if (c === "[") {
+            const j = pat.indexOf("]", i + 1);
+            out += pat.slice(i, j + 1);
+            i = j;
+        }
+        else if (c === "\\") {
+            i++;
+            out += escapeRegex(pat[i]);
+        }
+        else {
+            out += escapeRegex(c);
+        }
+    }
+    return new RegExp(`^${out}$`);
+}
+/** Order-sensitive match: last matching pattern wins; ! negates. */
+export function matchFilters(value, patterns) {
+    let matched = false;
+    for (const pat of patterns) {
+        const neg = pat.startsWith("!");
+        const p = neg ? pat.slice(1) : pat;
+        if (patternToRegex(p).test(value))
+            matched = !neg;
+    }
+    return matched;
+}
+// ------------------------------------------------------------ trigger checks
+const SKIP_RE = /\[(skip ci|ci skip|no ci|skip actions|actions skip)\]/i;
+const SKIP_TRAILER_RE = /^skip-checks:\s*true/im;
+const DEFAULT_TYPES = ["opened", "synchronize", "reopened"];
+const MISSING = Symbol("missing");
+function getPrTrigger(wf) {
+    // YAML 1.1 parsers read `on` as boolean true; the `yaml` package (1.2)
+    // keeps it a string key. Handle both.
+    const on = wf["on"] ?? wf["true"];
+    if (on == null)
+        return MISSING;
+    if (typeof on === "string")
+        return on === "pull_request" ? {} : MISSING;
+    if (Array.isArray(on))
+        return on.includes("pull_request") ? {} : MISSING;
+    if (typeof on === "object") {
+        if ("pull_request" in on)
+            return on["pull_request"] ?? {};
+        return MISSING;
+    }
+    return MISSING;
+}
+function workflowDispatches(wf, ctx) {
+    const trig = getPrTrigger(wf);
+    if (trig === MISSING)
+        return ["no-dispatch", "no pull_request trigger"];
+    const types = trig["types"] ?? DEFAULT_TYPES;
+    if (!types.includes(ctx.action)) {
+        return ["no-dispatch", `action '${ctx.action}' not in types [${types}]`];
+    }
+    if ("branches" in trig && "branches-ignore" in trig) {
+        return ["unknown", "both branches and branches-ignore set"];
+    }
+    if ("branches" in trig && !matchFilters(ctx.baseRef, trig["branches"])) {
+        return ["no-dispatch", `base branch '${ctx.baseRef}' not in branches`];
+    }
+    if ("branches-ignore" in trig && matchFilters(ctx.baseRef, trig["branches-ignore"])) {
+        return ["no-dispatch", "base branch in branches-ignore"];
+    }
+    if ("paths" in trig && "paths-ignore" in trig) {
+        return ["unknown", "both paths and paths-ignore set"];
+    }
+    if ("paths" in trig && !ctx.files.some((f) => matchFilters(f, trig["paths"]))) {
+        return ["no-dispatch", "no changed file matches paths"];
+    }
+    if ("paths-ignore" in trig && ctx.files.every((f) => matchFilters(f, trig["paths-ignore"]))) {
+        return ["no-dispatch", "all changed files match paths-ignore"];
+    }
+    return ["dispatch", "trigger matched"];
+}
+/** Return list of matrix combination dicts, or null if dynamic. */
+export function expandMatrix(strategy) {
+    const matrix = strategy?.matrix;
+    if (matrix == null)
+        return [null];
+    if (typeof matrix === "string")
+        return null; // ${{ fromJSON(...) }}
+    const include = matrix.include ?? [];
+    const exclude = matrix.exclude ?? [];
+    if (typeof include === "string" || typeof exclude === "string")
+        return null;
+    const axes = {};
+    for (const [k, v] of Object.entries(matrix)) {
+        if (k === "include" || k === "exclude")
+            continue;
+        if (!Array.isArray(v))
+            return null;
+        axes[k] = v;
+    }
+    let combos = [{}];
+    for (const [k, vals] of Object.entries(axes)) {
+        combos = combos.flatMap((c) => vals.map((v) => ({ ...c, [k]: v })));
+    }
+    if (Object.keys(axes).length === 0)
+        combos = [];
+    combos = combos.filter((c) => !exclude.some((ex) => Object.entries(ex).every(([k, v]) => c[k] === v)));
+    const extra = [];
+    for (const inc of include) {
+        const overlapping = Object.fromEntries(Object.entries(inc).filter(([k]) => k in axes));
+        const targets = combos.filter((c) => Object.entries(overlapping).every(([k, v]) => c[k] === v));
+        if (Object.keys(overlapping).length > 0 && targets.length > 0) {
+            for (const c of targets)
+                Object.assign(c, inc);
+        }
+        else {
+            extra.push({ ...inc });
+        }
+    }
+    combos.push(...extra);
+    return combos.length > 0 ? combos : [null];
+}
+function renderName(template, combo) {
+    return template.replace(/\$\{\{(.*?)\}\}/g, (whole, inner) => {
+        const expr = String(inner).trim();
+        if (expr.startsWith("matrix.") && combo) {
+            return String(combo[expr.slice("matrix.".length)] ?? "");
+        }
+        return whole;
+    });
+}
+function jobDisplayName(jobId, job, combo) {
+    if ("name" in job && job.name != null)
+        return renderName(String(job.name), combo);
+    let name = jobId;
+    if (combo)
+        name += ` (${Object.values(combo).map(String).join(", ")})`;
+    return name;
+}
+/** Return run|skipped|unknown for a job-level if. */
+export function evalIf(cond) {
+    if (cond == null)
+        return "run";
+    let c = String(cond).trim();
+    c = c.replace(/^\$\{\{(.*)\}\}$/s, "$1").trim();
+    if (c === "false" || c === "False")
+        return "skipped";
+    if (c === "true" || c === "True" || c === "always()")
+        return "run";
+    const m = c.match(/^github\.event_name\s*(==|!=)\s*'([^']*)'$/);
+    if (m) {
+        const eq = m[2] === "pull_request";
+        const hit = m[1] === "==" ? eq : !eq;
+        return hit ? "run" : "skipped";
+    }
+    return "unknown";
+}
+async function expandJobs(wf, ctx, fetchFile, depth = 0, prefix = "") {
+    const entries = [];
+    const jobs = wf.jobs ?? {};
+    const statuses = {};
+    for (const [jobId, jobRaw] of Object.entries(jobs)) {
+        const job = jobRaw ?? {};
+        let status = evalIf(job.if);
+        let reason = job.if != null ? `if: ${JSON.stringify(job.if)}` : "";
+        let needs = job.needs ?? [];
+        if (typeof needs === "string")
+            needs = [needs];
+        const cond = String(job.if ?? "");
+        if (status !== "skipped" && !cond.includes("always()")) {
+            for (const n of needs) {
+                if (statuses[n] === "skipped") {
+                    status = "skipped";
+                    reason = `needs '${n}' which is skipped`;
+                }
+                else if (statuses[n] === "unknown" && status === "run") {
+                    status = "unknown";
+                    reason = `needs '${n}' whose status is unknown`;
+                }
+            }
+        }
+        statuses[jobId] = status;
+        if ("uses" in job) {
+            // reusable workflow call
+            const uses = job.uses;
+            const baseName = prefix + (job.name != null ? String(job.name) : jobId);
+            if (depth >= 1) {
+                entries.push([baseName, "unknown", "nested reusable workflow"]);
+                continue;
+            }
+            const m = uses.match(/^\.\/(.+)$/);
+            if (!m) {
+                entries.push([baseName, "unknown", `non-local reusable: ${uses}`]);
+                continue;
+            }
+            const content = await fetchFile(m[1]);
+            if (content == null) {
+                entries.push([baseName, "unknown", `cannot fetch ${uses}`]);
+                continue;
+            }
+            if (status === "skipped") {
+                entries.push([baseName, "skipped", reason]);
+                continue;
+            }
+            const subWf = parseYaml(content);
+            const sub = await expandJobs(subWf, ctx, fetchFile, depth + 1, `${baseName} / `);
+            entries.push(...sub);
+            continue;
+        }
+        const combos = expandMatrix(job.strategy);
+        if (combos == null) {
+            entries.push([prefix + jobId, "unknown", "dynamic matrix"]);
+            continue;
+        }
+        for (const combo of combos) {
+            entries.push([prefix + jobDisplayName(jobId, job, combo), status, reason]);
+        }
+    }
+    return entries;
+}
+// ------------------------------------------------------------------- pipeline
+export function makeOctokit() {
+    const token = process.env.GH_TOKEN ?? process.env.GITHUB_TOKEN;
+    if (!token)
+        throw new Error("GH_TOKEN or GITHUB_TOKEN must be set");
+    return new Octokit({ auth: token });
+}
+export async function predict(octokit, repo, prNumber) {
+    const [owner, name] = repo.split("/");
+    const base = { owner, repo: name };
+    const { data: pr } = await octokit.rest.pulls.get({ ...base, pull_number: prNumber });
+    const files = await octokit.paginate(octokit.rest.pulls.listFiles, {
+        ...base,
+        pull_number: prNumber,
+        per_page: 100,
+    });
+    const ctx = {
+        action: pr.commits > 1 ? "synchronize" : "opened",
+        baseRef: pr.base.ref,
+        files: files.map((f) => f.filename),
+    };
+    const headSha = pr.head.sha;
+    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 { entries: [], skip: "head commit message contains a skip instruction" };
+    }
+    const fetchFile = async (path) => {
+        try {
+            const { data } = await octokit.rest.repos.getContent({
+                ...base,
+                path,
+                ref: headSha,
+                mediaType: { format: "raw" },
+            });
+            return data;
+        }
+        catch {
+            return null;
+        }
+    };
+    const workflows = await octokit.paginate(octokit.rest.actions.listRepoWorkflows, {
+        ...base,
+        per_page: 100,
+    });
+    const entries = [];
+    for (const w of workflows) {
+        const path = w.path;
+        if (!path.startsWith(".github/workflows/"))
+            continue;
+        if (w.state !== "active") {
+            entries.push({
+                workflow: path,
+                job: "*",
+                status: "no-dispatch",
+                reason: `workflow state: ${w.state}`,
+            });
+            continue;
+        }
+        const content = await fetchFile(path);
+        if (content == null) {
+            entries.push({
+                workflow: path,
+                job: "*",
+                status: "unknown",
+                reason: "cannot fetch workflow file at head",
+            });
+            continue;
+        }
+        let wf;
+        try {
+            wf = parseYaml(content);
+        }
+        catch (e) {
+            entries.push({
+                workflow: path,
+                job: "*",
+                status: "unknown",
+                reason: `YAML parse error: ${e}`,
+            });
+            continue;
+        }
+        const [verdict, reason] = workflowDispatches(wf, ctx);
+        if (verdict !== "dispatch") {
+            entries.push({ workflow: path, job: "*", status: verdict, reason });
+            continue;
+        }
+        for (const [jobName, status, jreason] of await expandJobs(wf, ctx, fetchFile)) {
+            entries.push({ workflow: path, job: jobName, status, reason: jreason || reason });
+        }
+    }
+    return { entries, skip: null };
+}
+// ------------------------------------------------------------------------ CLI
+function parseArgs(argv) {
+    const get = (flag) => {
+        const i = argv.indexOf(flag);
+        return i >= 0 ? argv[i + 1] : undefined;
+    };
+    const repo = get("--repo");
+    const pr = get("--pr");
+    if (!repo || !pr) {
+        console.error("usage: predict --repo owner/name --pr N [--json]");
+        process.exit(2);
+    }
+    return { repo, pr: Number(pr), json: argv.includes("--json") };
+}
+const isMain = /predict\.(ts|js)$|\/willfire$/.test(process.argv[1] ?? "");
+if (isMain) {
+    const args = parseArgs(process.argv.slice(2));
+    const { entries, skip } = await predict(makeOctokit(), args.repo, args.pr);
+    if (args.json) {
+        console.log(JSON.stringify({ entries, skip }, null, 2));
+    }
+    else if (skip) {
+        console.log(`# ${skip} -> nothing dispatches`);
+    }
+    else {
+        for (const e of entries) {
+            if (e.job === "*")
+                console.log(`# ${e.workflow} :: ${e.status} (${e.reason})`);
+            else
+                console.log(`${e.workflow} :: ${e.job} :: ${e.status}`);
+        }
+    }
+}

package/dist/verify.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/verify.js

@@ -0,0 +1,91 @@
+// Compare predict.ts output against what GitHub Actions actually dispatched.
+//
+// Usage: pnpm verify --repo owner/name --pr N
+//
+// Ground truth: workflow runs for the PR head SHA with a pull_request event,
+// and the job entries inside each run (skipped jobs included).
+import { makeOctokit, predict } from "./predict.js";
+async function actualEntries(octokit, repo, prNumber) {
+    const [owner, name] = repo.split("/");
+    const base = { owner, repo: name };
+    const { data: pr } = await octokit.rest.pulls.get({ ...base, pull_number: prNumber });
+    const runs = await octokit.paginate(octokit.rest.actions.listWorkflowRunsForRepo, {
+        ...base,
+        head_sha: pr.head.sha,
+        event: "pull_request",
+        per_page: 100,
+    });
+    const entries = new Map();
+    const incomplete = [];
+    for (const run of runs) {
+        if (run.status !== "completed")
+            incomplete.push(run.path);
+        const jobs = await octokit.paginate(octokit.rest.actions.listJobsForWorkflowRun, {
+            ...base,
+            run_id: run.id,
+            per_page: 100,
+        });
+        for (const j of jobs) {
+            entries.set(`${run.path} :: ${j.name}`, j.conclusion === "skipped" ? "skipped" : "run");
+        }
+    }
+    return { entries, incomplete };
+}
+const get = (flag) => {
+    const i = process.argv.indexOf(flag);
+    return i >= 0 ? process.argv[i + 1] : undefined;
+};
+const repo = get("--repo");
+const prArg = get("--pr");
+if (!repo || !prArg) {
+    console.error("usage: verify --repo owner/name --pr N");
+    process.exit(2);
+}
+const pr = Number(prArg);
+const octokit = makeOctokit();
+const { entries: predictedRaw } = await predict(octokit, repo, pr);
+const predicted = new Map(predictedRaw
+    .filter((r) => r.job !== "*")
+    .map((r) => [`${r.workflow} :: ${r.job}`, r.status]));
+const unknownWfs = new Set(predictedRaw.filter((r) => r.status === "unknown").map((r) => r.workflow));
+const { entries: actual, incomplete } = await actualEntries(octokit, repo, pr);
+if (incomplete.length > 0) {
+    console.log(`WARNING: runs still in progress: ${incomplete}`);
+}
+let ok = true;
+const keys = [...new Set([...predicted.keys(), ...actual.keys()])].sort();
+for (const key of keys) {
+    const p = predicted.get(key);
+    const a = actual.get(key);
+    const wf = key.split(" :: ")[0];
+    if (p === a) {
+        console.log(`  OK  ${key} :: ${a}`);
+    }
+    else if (p === "unknown") {
+        console.log(`  ?   ${key} :: predicted unknown, actual ${a}`);
+    }
+    else if (p === undefined) {
+        if (unknownWfs.has(wf)) {
+            console.log(`  ?   ${key} :: actual ${a}, workflow had unknown prediction`);
+        }
+        else {
+            ok = false;
+            console.log(`MISS  ${key} :: ran (${a}) but was not predicted`);
+        }
+    }
+    else if (a === undefined) {
+        ok = false;
+        console.log(`OVER  ${key} :: predicted ${p} but never appeared`);
+    }
+    else {
+        ok = false;
+        console.log(`DIFF  ${key} :: predicted ${p}, actual ${a}`);
+    }
+}
+for (const r of predictedRaw) {
+    if (r.job === "*" && r.status === "unknown") {
+        console.log(`  ?   ${r.workflow} :: workflow-level unknown: ${r.reason}`);
+    }
+}
+console.log(ok ? "PASS" : "FAIL");
+process.exit(ok ? 0 : 1);

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "willfire",
+  "version": "0.1.0",
+  "description": "Predict the set of CI check entries GitHub Actions will create for a pull request",
+  "license": "MIT",
+  "author": "Kevin Scott <me@thekevinscott.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thekevinscott/willrun.git"
+  },
+  "keywords": [
+    "github-actions",
+    "ci",
+    "workflow",
+    "pull-request",
+    "prediction"
+  ],
+  "type": "module",
+  "main": "dist/predict.js",
+  "types": "dist/predict.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/predict.d.ts",
+      "default": "./dist/predict.js"
+    }
+  },
+  "bin": {
+    "willfire": "dist/predict.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "pnpm build",
+    "predict": "tsx src/predict.ts",
+    "verify": "tsx src/verify.ts"
+  },
+  "dependencies": {
+    "@octokit/rest": "^22.0.0",
+    "yaml": "^2.6.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  }
+}