willfire 0.1.19 → 0.1.21

package/dist/jobs/expandJobs.js

@@ -1,5 +1,7 @@
 import { parse as parseYaml } from "yaml";
+import { evaluateValue } from "../expr/evaluateValue.js";
 import { UNKNOWN } from "../expr/val.js";
+import { renderTemplate } from "../execute.js";
 import { expandMatrixDetailed } from "../matrix/expandMatrixDetailed.js";
 import { jobDisplayName } from "../names/jobDisplayName.js";
 import { skippedDisplayName } from "../names/skippedDisplayName.js";
@@ -7,25 +9,30 @@ import { parseUses } from "../uses/parseUses.js";
 import { evalIf } from "./evalIf.js";
 import { prScope } from "./prScope.js";
 /**
- * A `with:` value as the callee will see it.
- *
- * A value carrying `${{ }}` is left unknown rather than evaluated. Resolving
- * it would mean evaluating the caller's own expression context, and every
- * caller in practice passes plain literals — so the reach that would buy is
- * not worth the surface. Unknown here is the same unknown as before this
- * existed; nothing regresses.
+ * A `with:` value as the callee will see it, evaluated in the caller's scope.
+ * A whole-expression value keeps its evaluated type; mixed text renders to a
+ * string, all or nothing; anything unresolvable stays unknown.
  */
-function inputLiteral(raw) {
-    if (raw == null) {
+function inputValue(raw, scope) {
+    if (raw === null || raw === undefined) {
         return { kind: "value", v: "" };
     }
     if (typeof raw === "boolean" || typeof raw === "number") {
         return { kind: "value", v: raw };
     }
-    if (typeof raw === "string") {
-        return raw.includes("${{") ? UNKNOWN : { kind: "value", v: raw };
+    if (typeof raw !== "string") {
+        return UNKNOWN;
+    }
+    if (!raw.includes("${{")) {
+        return { kind: "value", v: raw };
     }
-    return UNKNOWN;
+    const t = raw.trim();
+    // `${{a}} x ${{b}}` fails this test and takes the render path instead.
+    if (t.startsWith("${{") && t.indexOf("}}") === t.length - 2) {
+        return evaluateValue(t.slice(3, -2), prScope(scope));
+    }
+    const rendered = renderTemplate(raw, prScope(scope));
+    return rendered === null ? UNKNOWN : { kind: "value", v: rendered };
 }
 /** The `on.workflow_call.inputs` block, tolerating the YAML 1.1 `on` -> true key. */
 function workflowCallInputs(wf) {
@@ -49,17 +56,18 @@ function workflowCallInputs(wf) {
  * workflow would be invalid if it were required, and guessing empty would
  * silently decide guards that are not decided.
  */
-function calleeInputs(withBlock, subWf) {
+function calleeInputs(withBlock, subWf, scope) {
     const out = {};
     for (const [name, decl] of Object.entries(workflowCallInputs(subWf))) {
         out[name] =
             decl != null && typeof decl === "object" && "default" in decl
-                ? inputLiteral(decl["default"])
+                ? // Defaults live in the callee, out of the caller's context's reach.
+                    inputValue(decl["default"], {})
                 : UNKNOWN;
     }
     if (withBlock != null && typeof withBlock === "object") {
         for (const [name, raw] of Object.entries(withBlock)) {
-            out[name] = inputLiteral(raw);
+            out[name] = inputValue(raw, scope);
         }
     }
     return out;
@@ -76,35 +84,44 @@ 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);
+const NEEDS_OUTPUTS_RE = /needs\s*\.\s*([A-Za-z_][A-Za-z0-9_-]*)\s*\.\s*outputs\b/g;
+/**
+ * The jobs some sibling reads outputs from — the only jobs worth executing.
+ * Matching over the serialized job catches every read site without modelling
+ * any; a false positive costs one wasted run, never a verdict.
+ */
+function neededJobIds(jobs) {
+    const needed = new Set();
+    for (const job of Object.values(jobs)) {
+        for (const m of JSON.stringify(job ?? {}).matchAll(NEEDS_OUTPUTS_RE)) {
+            needed.add(m[1]);
+        }
+    }
+    return needed;
+}
 export 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.
+    // Selection is derived, never configured: execute exactly the jobs some
+    // sibling's `needs.*.outputs` read depends on, under the same `evalIf`
+    // verdict the main loop applies.
     let scoped = scope;
     const execFailures = {};
     if (executor != null) {
+        const needed = neededJobIds(jobs);
         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;
+            // A reusable-call job has no steps of its own to run.
+            const runnable = needed.has(jobId) && !("uses" in job) && evalIf(job.if, scoped) === "run";
+            if (runnable) {
+                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;
+                }
             }
         }
     }
@@ -206,7 +223,10 @@ export async function expandJobs(wf, ctx, reader, source, depth = 0, prefix = ""
                             // `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 };
+                            subScope = {
+                                inputs: calleeInputs(job.with, subWf ?? {}, scoped),
+                                github: scoped.github,
+                            };
                         }
                         catch (e) {
                             failure = `YAML parse error in ${uses}: ${e}`;

package/dist/matrix/expandMatrixDetailed.js

@@ -21,6 +21,26 @@ function axisValues(v, scope) {
     }
     return val.v;
 }
+/**
+ * An `include:`/`exclude:` block: a literal list or an expression evaluating
+ * to one. Absent means empty; anything unresolvable fails the expansion.
+ */
+function comboList(v, scope) {
+    if (v === null || v === undefined) {
+        return [];
+    }
+    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;
+}
 export function expandMatrixDetailed(strategy, scope = {}) {
     const matrix = strategy?.matrix;
     if (matrix == null) {
@@ -32,9 +52,9 @@ export function expandMatrixDetailed(strategy, scope = {}) {
     if (typeof matrix === "string") {
         return null;
     }
-    const include = matrix.include ?? [];
-    const exclude = matrix.exclude ?? [];
-    if (typeof include === "string" || typeof exclude === "string") {
+    const include = comboList(matrix.include, scope);
+    const exclude = comboList(matrix.exclude, scope);
+    if (include === null || exclude === null) {
         return null;
     }
     const axes = {};

package/dist/predict/makeLiveExecutor.d.ts

@@ -0,0 +1,20 @@
+import type { Octokit } from "@octokit/rest";
+import { type JobExecutor, type RunCommand } from "../execute.js";
+import type { ResolveRef, WorkflowSource } from "../types.js";
+export interface LiveExecutorOpts {
+    /** How steps run; the hermetic docker sandbox by default. */
+    runCommand?: RunCommand;
+    /**
+     * Auth for history clones. `undefined` reads `GH_TOKEN` / `GITHUB_TOKEN`
+     * from the environment; `null` clones anonymously.
+     */
+    token?: string | null;
+    /** Where clones come from — a seam for tests that serve `file://` fixtures. */
+    remoteUrl?: (source: WorkflowSource) => string;
+}
+/**
+ * The executor `predict` uses by default. Repo-authored steps run in the
+ * docker sandbox; infrastructure subprocesses (`tar`, `git`) run on the host,
+ * since the clone needs the network the sandbox denies.
+ */
+export declare function makeLiveExecutor(octokit: Octokit, workspace: WorkflowSource, resolveRef: ResolveRef, opts?: LiveExecutorOpts): JobExecutor;

package/dist/predict/makeLiveExecutor.js

@@ -0,0 +1,38 @@
+import { makeCloneProvider, makeExecutor, makeTreeProvider, runShell, } from "../execute.js";
+import { makeSandboxRunner, SANDBOX_NODE_MAJOR } from "../sandbox.js";
+/**
+ * The executor `predict` uses by default. Repo-authored steps run in the
+ * docker sandbox; infrastructure subprocesses (`tar`, `git`) run on the host,
+ * since the clone needs the network the sandbox denies.
+ */
+export function makeLiveExecutor(octokit, workspace, resolveRef, opts = {}) {
+    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.
+            return null;
+        }
+    };
+    const token = opts.token !== undefined
+        ? opts.token
+        : (process.env.GH_TOKEN ?? process.env.GITHUB_TOKEN ?? null);
+    const tarballs = makeTreeProvider(download, runShell);
+    const clones = makeCloneProvider(runShell, token, opts.remoteUrl === undefined ? {} : { remoteUrl: opts.remoteUrl });
+    const provideTree = (src, o) => o?.history === true ? clones(src, o) : tarballs(src, o);
+    return makeExecutor({
+        workspace,
+        deps: {
+            provideTree,
+            runCommand: opts.runCommand ?? makeSandboxRunner(),
+            resolveRef,
+            nodeMajor: SANDBOX_NODE_MAJOR,
+        },
+    });
+}

package/dist/predict/predict.js

@@ -7,10 +7,10 @@
 // src/names.test.ts.
 import { parse as parseYaml } from "yaml";
 import { jobName } from "../entries/jobName.js";
-import { makeExecutor, makeTreeProvider, runShell } from "../execute.js";
 import { expandJobs } from "../jobs/expandJobs.js";
 import { workflowDispatches } from "../triggers/workflowDispatches.js";
 import { finalizePrediction } from "./finalizePrediction.js";
+import { makeLiveExecutor } from "./makeLiveExecutor.js";
 import { sourceKey } from "./sourceKey.js";
 import { stackTargetRef } from "./stackTargetRef.js";
 const SKIP_RE = /\[(skip ci|ci skip|no ci|skip actions|actions skip)\]/i;
@@ -114,36 +114,10 @@ export async function predict(octokit, repo, prNumber, opts = {}) {
         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 !== undefined && 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,
-            },
-        });
-    }
+    // Execution is on by default and costs nothing until a workflow needs it.
+    const executor = opts.executor === undefined
+        ? makeLiveExecutor(octokit, headSource, resolveRef)
+        : (opts.executor ?? undefined);
     const workflows = await octokit.paginate(octokit.rest.actions.listRepoWorkflows, {
         ...base,
         per_page: 100,

package/dist/sandbox.d.ts

@@ -0,0 +1,35 @@
+/**
+ * A `RunCommand` that runs each step inside a hermetic docker container: no
+ * network, no capabilities, a read-only root, and only the host paths in
+ * `RunSpec.mounts`, bound at their own paths. Code that can reach nothing and
+ * keep nothing needs no per-repo grant — this is what lets execution be on by
+ * default instead of configured.
+ */
+import type { RunCommand, RunSpec } from "./execute.js";
+/**
+ * The node major the image ships — also the refusal boundary for `setup-node`
+ * and `node2x` runtimes asking for any other major.
+ */
+export declare const SANDBOX_NODE_MAJOR = 24;
+export declare const DOCKERFILE = "FROM node:24-slim\nRUN apt-get update && apt-get install -y --no-install-recommends git ca-certificates python3 && rm -rf /var/lib/apt/lists/*\n";
+export interface SandboxConfig {
+    dockerBin: string;
+    uid: number;
+    gid: number;
+    dockerfile: string;
+}
+export declare function sandboxConfig(opts?: Partial<SandboxConfig>): SandboxConfig;
+/** The tag names the dockerfile that built it, so a change is a new image. */
+export declare function imageTag(dockerfile: string): string;
+/**
+ * The complete `docker run` argv for one step. `PATH` and `HOME` in
+ * `spec.env` are host facts; the container gets its image's PATH and a
+ * writable `HOME=/tmp` instead.
+ */
+export declare function sandboxArgv(spec: RunSpec, cfg: SandboxConfig): string[];
+/**
+ * Provisions the image lazily, once, and remembers a failure: every later
+ * spec gets 125 (docker's "could not start" band) with the reason rather
+ * than retrying a build that already failed.
+ */
+export declare function makeSandboxRunner(opts?: Partial<SandboxConfig>): RunCommand;

package/dist/sandbox.js

@@ -0,0 +1,130 @@
+/**
+ * A `RunCommand` that runs each step inside a hermetic docker container: no
+ * network, no capabilities, a read-only root, and only the host paths in
+ * `RunSpec.mounts`, bound at their own paths. Code that can reach nothing and
+ * keep nothing needs no per-repo grant — this is what lets execution be on by
+ * default instead of configured.
+ */
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+/**
+ * The node major the image ships — also the refusal boundary for `setup-node`
+ * and `node2x` runtimes asking for any other major.
+ */
+export const SANDBOX_NODE_MAJOR = 24;
+// git and python3: checkout's postcondition and the interpreters a script on
+// a GitHub-hosted runner takes for granted.
+export const DOCKERFILE = `FROM node:${SANDBOX_NODE_MAJOR}-slim
+RUN apt-get update && apt-get install -y --no-install-recommends git ca-certificates python3 && rm -rf /var/lib/apt/lists/*
+`;
+export function sandboxConfig(opts = {}) {
+    return {
+        dockerBin: opts.dockerBin ?? "docker",
+        uid: opts.uid ?? process.getuid(),
+        gid: opts.gid ?? process.getgid(),
+        dockerfile: opts.dockerfile ?? DOCKERFILE,
+    };
+}
+/** The tag names the dockerfile that built it, so a change is a new image. */
+export function imageTag(dockerfile) {
+    const hash = createHash("sha256").update(dockerfile).digest("hex");
+    return `willfire-sandbox:${hash.slice(0, 12)}`;
+}
+/**
+ * The complete `docker run` argv for one step. `PATH` and `HOME` in
+ * `spec.env` are host facts; the container gets its image's PATH and a
+ * writable `HOME=/tmp` instead.
+ */
+export function sandboxArgv(spec, cfg) {
+    const argv = [
+        "run",
+        "--rm",
+        "--network",
+        "none",
+        "--cap-drop",
+        "ALL",
+        "--security-opt",
+        "no-new-privileges",
+        "--read-only",
+        "--tmpfs",
+        "/tmp",
+        "--user",
+        `${cfg.uid}:${cfg.gid}`,
+    ];
+    for (const m of spec.mounts ?? []) {
+        argv.push("-v", `${m.path}:${m.path}${m.writable ? "" : ":ro"}`);
+    }
+    argv.push("-w", spec.cwd);
+    for (const [k, v] of Object.entries(spec.env)) {
+        if (k !== "PATH" && k !== "HOME") {
+            argv.push("-e", `${k}=${v}`);
+        }
+    }
+    argv.push("-e", "HOME=/tmp");
+    argv.push(imageTag(cfg.dockerfile));
+    if (spec.shell === "bash") {
+        argv.push("bash", "--noprofile", "--norc", "-e", "-o", "pipefail", "-c", spec.script);
+    }
+    else {
+        argv.push("sh", "-e", "-c", spec.script);
+    }
+    return argv;
+}
+// The client itself runs with the host environment — it needs the host PATH
+// and any DOCKER_HOST to find the daemon.
+function runDocker(bin, argv, stdin) {
+    return new Promise((resolvePromise) => {
+        const child = spawn(bin, argv, {
+            env: process.env,
+            stdio: [stdin === undefined ? "ignore" : "pipe", "ignore", "pipe"],
+        });
+        let stderr = "";
+        child.stderr.on("data", (d) => {
+            stderr += String(d);
+            if (stderr.length > 4096) {
+                stderr = stderr.slice(-4096);
+            }
+        });
+        child.on("spawn", () => {
+            if (stdin !== undefined) {
+                child.stdin.write(stdin);
+                child.stdin.end();
+            }
+        });
+        child.on("error", () => resolvePromise({ code: 127, stderr }));
+        child.on("close", (code) => resolvePromise({ code: code ?? 1, stderr }));
+    });
+}
+/**
+ * Provisions the image lazily, once, and remembers a failure: every later
+ * spec gets 125 (docker's "could not start" band) with the reason rather
+ * than retrying a build that already failed.
+ */
+export function makeSandboxRunner(opts = {}) {
+    const cfg = sandboxConfig(opts);
+    const tag = imageTag(cfg.dockerfile);
+    let ensured = null;
+    const ensureImage = () => {
+        ensured ??= (async () => {
+            const inspect = await runDocker(cfg.dockerBin, ["image", "inspect", tag]);
+            if (inspect.code === 0) {
+                return null;
+            }
+            const build = await runDocker(cfg.dockerBin, ["build", "-t", tag, "-"], cfg.dockerfile);
+            if (build.code === 0) {
+                return null;
+            }
+            const trimmed = build.stderr.trim();
+            const tail = trimmed.slice(trimmed.lastIndexOf("\n") + 1);
+            return `cannot build sandbox image ${tag}${tail === "" ? "" : ` (${tail})`}`;
+        })();
+        return ensured;
+    };
+    return async (spec) => {
+        const failure = await ensureImage();
+        if (failure !== null) {
+            return { code: 125, stderr: failure };
+        }
+        return runDocker(cfg.dockerBin, sandboxArgv(spec, cfg));
+    };
+}

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import type { ExecutionGrant } from "./execute.js";
+import type { JobExecutor } from "./execute.js";
 export interface EntryBase {
     workflow: string;
     reason: string;
@@ -117,16 +117,11 @@ export interface PredictOptions {
      */
     action?: PrEventAction;
     /**
-     * Jobs willfire may *execute* to resolve what reading cannot — the fleet's
-     * `detect` job, whose outputs feed every dynamic matrix downstream of it.
-     *
-     * Off by default, and mechanism only: willfire has no opinion about which
-     * jobs are safe to run. The caller that knows names them, one repo and job
-     * id at a time (see {@link ExecutionGrant}), and an execution that fails
-     * for any reason leaves the dependent entries exactly as unresolved as
-     * they were — with the failure spelled into their reasons.
+     * The executor that resolves what reading cannot. Omitted, prediction
+     * builds the live sandboxed one; `null` disables execution; passing a
+     * {@link JobExecutor} is a test seam, not configuration.
      */
-    execute?: ExecutionGrant[];
+    executor?: JobExecutor | null;
 }
 export interface Ctx {
     action: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "willfire",
-  "version": "0.1.19",
+  "version": "0.1.21",
   "description": "Predict the set of CI check entries GitHub Actions will create for a pull request",
   "license": "MIT",
   "packageManager": "pnpm@10.33.0",
@@ -36,6 +36,7 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
+    "lint": "eslint .",
     "predict": "tsx src/cli.ts",
     "prepare": "pnpm build",
     "test": "vitest run",
@@ -51,9 +52,11 @@
   "devDependencies": {
     "@types/node": "^22.0.0",
     "@vitest/coverage-v8": "^4.1.10",
+    "eslint": "^10.9.1",
     "testing-conventions": "^0.0.91",
     "tsx": "^4.19.0",
     "typescript": "^5.6.0",
+    "typescript-eslint": "^8.68.0",
     "vitest": "^4.1.10"
   }
 }