willfire 0.1.6 → 0.1.7

package/dist/expr.d.ts

@@ -0,0 +1,69 @@
+/**
+ * A tri-state evaluator for the slice of GitHub expressions that job `if:`
+ * conditions actually use.
+ *
+ * The point is not to reimplement the expression language. It is to stop
+ * returning `unknown` for conditions that are already decided. A reusable
+ * workflow's jobs commonly guard on the caller's own literals:
+ *
+ *     if: ${{ github.event_name == 'pull_request'
+ *             && (inputs.gates == '' || contains(inputs.gates, '"mutation"'))
+ *             && (needs.detect.outputs.mutation_languages || ...) != '[]' }}
+ *
+ * The last clause needs a job that has not run yet. The middle one does not:
+ * the caller passed `gates` as a literal string, and it does not contain
+ * `"mutation"`, so the clause is false, so the whole `&&` is false whatever
+ * `detect` reports. Deciding that is the difference between a predictable
+ * check name and a hole in the prediction.
+ *
+ * Two ideas carry the whole file:
+ *
+ * 1. **Truthiness can be known when the value is not.** `A && B` with an
+ *    unknown `A` and a false `B` is false either way. So the lattice has four
+ *    points, not three: a concrete value, known-truthy, known-falsy, and
+ *    nothing at all.
+ *
+ * 2. **Unrecognized is unknown, never a guess.** An unparseable condition, an
+ *    unsupported function, a comparison between types we do not model — all
+ *    collapse to `unknown` and leave the caller exactly where it was. This
+ *    adds no tolerance and no third outcome; it converts conditions that are
+ *    already decidable into the answer they already have.
+ */
+/**
+ * A partially-known value.
+ *
+ * `truthy` and `falsy` exist because short-circuiting yields truthiness
+ * without a value: `unknown && false` is falsy, but there is no string to
+ * hand back for it. Collapsing those into `unknown` would throw away the
+ * only fact worth having.
+ */
+export type Val = {
+    kind: "value";
+    v: string | number | boolean;
+} | {
+    kind: "truthy";
+} | {
+    kind: "falsy";
+} | {
+    kind: "unknown";
+};
+export declare const UNKNOWN: Val;
+/** What a bare path resolves against. Anything absent is unknown, not empty. */
+export interface Scope {
+    /**
+     * The inputs the caller passed, plus declared defaults for the ones it did
+     * not. A key mapped to `unknown` is deliberate: the caller supplied it, but
+     * as a `${{ }}` template we cannot evaluate. That is different from absent.
+     */
+    inputs?: Record<string, Val>;
+    /** `github.*` values that are fixed for the run being predicted. */
+    github?: Record<string, string>;
+}
+/**
+ * Evaluate a condition to a truthiness, or null when it cannot be settled.
+ *
+ * The `${{ }}` wrapper is optional in `if:` and stripped when present. A
+ * condition that is only *partly* wrapped (`foo ${{ bar }} baz`) is a string
+ * interpolation rather than an expression, and is not modelled.
+ */
+export declare function evaluate(cond: string, scope?: Scope): boolean | null;

package/dist/expr.js

@@ -0,0 +1,388 @@
+/**
+ * A tri-state evaluator for the slice of GitHub expressions that job `if:`
+ * conditions actually use.
+ *
+ * The point is not to reimplement the expression language. It is to stop
+ * returning `unknown` for conditions that are already decided. A reusable
+ * workflow's jobs commonly guard on the caller's own literals:
+ *
+ *     if: ${{ github.event_name == 'pull_request'
+ *             && (inputs.gates == '' || contains(inputs.gates, '"mutation"'))
+ *             && (needs.detect.outputs.mutation_languages || ...) != '[]' }}
+ *
+ * The last clause needs a job that has not run yet. The middle one does not:
+ * the caller passed `gates` as a literal string, and it does not contain
+ * `"mutation"`, so the clause is false, so the whole `&&` is false whatever
+ * `detect` reports. Deciding that is the difference between a predictable
+ * check name and a hole in the prediction.
+ *
+ * Two ideas carry the whole file:
+ *
+ * 1. **Truthiness can be known when the value is not.** `A && B` with an
+ *    unknown `A` and a false `B` is false either way. So the lattice has four
+ *    points, not three: a concrete value, known-truthy, known-falsy, and
+ *    nothing at all.
+ *
+ * 2. **Unrecognized is unknown, never a guess.** An unparseable condition, an
+ *    unsupported function, a comparison between types we do not model — all
+ *    collapse to `unknown` and leave the caller exactly where it was. This
+ *    adds no tolerance and no third outcome; it converts conditions that are
+ *    already decidable into the answer they already have.
+ */
+export const UNKNOWN = { kind: "unknown" };
+/**
+ * GitHub's truthiness: empty string, zero, `false` and null are false, and
+ * every other value is true. `'0'` and `'false'` are non-empty strings, so
+ * both are true — the same trap as JavaScript, kept deliberately identical.
+ */
+function truthy(val) {
+    switch (val.kind) {
+        case "truthy":
+            return true;
+        case "falsy":
+            return false;
+        case "unknown":
+            return null;
+        case "value": {
+            const v = val.v;
+            if (typeof v === "boolean")
+                return v;
+            if (typeof v === "number")
+                return v !== 0;
+            return v !== "";
+        }
+    }
+}
+/**
+ * Wrap a decided answer as a concrete boolean value.
+ *
+ * Comparison, negation and the string functions all yield a real boolean, so
+ * they produce a `value` — which keeps `!x == true` comparable. Only
+ * short-circuiting produces the bare `truthy`/`falsy` points, because that is
+ * the one case where truthiness is known and the value is not.
+ */
+function asBool(b) {
+    return b === null ? UNKNOWN : { kind: "value", v: b };
+}
+const OPS = ["&&", "||", "==", "!=", "<=", ">=", "!", "<", ">", "(", ")", ","];
+/**
+ * Split a condition into tokens, or return null if it contains something this
+ * evaluator has no token for. Returning null rather than throwing keeps the
+ * "unrecognized is unknown" rule in one place at the top of `evaluate`.
+ */
+function tokenize(src) {
+    const out = [];
+    let i = 0;
+    while (i < src.length) {
+        const c = src[i];
+        if (c === " " || c === "\t" || c === "\n" || c === "\r") {
+            i++;
+            continue;
+        }
+        // Single-quoted string. GitHub escapes an inner quote by doubling it.
+        if (c === "'") {
+            let j = i + 1;
+            let s = "";
+            for (;;) {
+                if (j >= src.length)
+                    return null; // unterminated
+                if (src[j] === "'") {
+                    if (src[j + 1] === "'") {
+                        s += "'";
+                        j += 2;
+                        continue;
+                    }
+                    j++;
+                    break;
+                }
+                s += src[j];
+                j++;
+            }
+            out.push({ t: "str", v: s });
+            i = j;
+            continue;
+        }
+        const op = OPS.find((o) => src.startsWith(o, i));
+        if (op != null) {
+            out.push({ t: "op", v: op });
+            i += op.length;
+            continue;
+        }
+        const word = /^[A-Za-z_][A-Za-z0-9_.\-]*/.exec(src.slice(i));
+        if (word != null) {
+            const w = word[0];
+            i += w.length;
+            const lower = w.toLowerCase();
+            if (lower === "true")
+                out.push({ t: "bool", v: true });
+            else if (lower === "false")
+                out.push({ t: "bool", v: false });
+            else if (lower === "null")
+                out.push({ t: "null" });
+            else
+                out.push({ t: "path", v: w });
+            continue;
+        }
+        const num = /^-?\d+(\.\d+)?/.exec(src.slice(i));
+        if (num != null) {
+            out.push({ t: "num", v: Number(num[0]) });
+            i += num[0].length;
+            continue;
+        }
+        return null; // a character we have no token for
+    }
+    return out;
+}
+// --------------------------------------------------------------------- parser
+/**
+ * Recursive descent over GitHub's precedence order, loosest first:
+ * `||`, then `&&`, then comparison, then `!`, then a primary.
+ *
+ * `&&` and `||` are value operators, not boolean ones — `a || b` yields the
+ * first truthy operand, which is why `(x || y) != '[]'` parses as a
+ * comparison against a coalesced value rather than a boolean.
+ */
+class Parser {
+    toks;
+    scope;
+    pos = 0;
+    constructor(toks, scope) {
+        this.toks = toks;
+        this.scope = scope;
+    }
+    peek() {
+        return this.toks[this.pos];
+    }
+    eatOp(v) {
+        const t = this.peek();
+        if (t != null && t.t === "op" && t.v === v) {
+            this.pos++;
+            return true;
+        }
+        return false;
+    }
+    done() {
+        return this.pos >= this.toks.length;
+    }
+    or() {
+        let left = this.and();
+        while (this.eatOp("||")) {
+            const right = this.and();
+            left = coalesceOr(left, right);
+        }
+        return left;
+    }
+    and() {
+        let left = this.cmp();
+        while (this.eatOp("&&")) {
+            const right = this.cmp();
+            left = coalesceAnd(left, right);
+        }
+        return left;
+    }
+    cmp() {
+        const left = this.unary();
+        for (const op of ["==", "!=", "<=", ">=", "<", ">"]) {
+            if (this.eatOp(op)) {
+                const right = this.unary();
+                return compare(op, left, right);
+            }
+        }
+        return left;
+    }
+    unary() {
+        if (this.eatOp("!")) {
+            const v = this.unary();
+            return asBool(negate(truthy(v)));
+        }
+        return this.primary();
+    }
+    primary() {
+        const t = this.peek();
+        if (t == null)
+            return UNKNOWN;
+        if (t.t === "op" && t.v === "(") {
+            this.pos++;
+            const v = this.or();
+            if (!this.eatOp(")"))
+                return UNKNOWN;
+            return v;
+        }
+        if (t.t === "str") {
+            this.pos++;
+            return { kind: "value", v: t.v };
+        }
+        if (t.t === "num") {
+            this.pos++;
+            return { kind: "value", v: t.v };
+        }
+        if (t.t === "bool") {
+            this.pos++;
+            return { kind: "value", v: t.v };
+        }
+        if (t.t === "null") {
+            this.pos++;
+            return { kind: "value", v: "" };
+        }
+        if (t.t === "path") {
+            this.pos++;
+            // A `(` right after a name makes it a call, not a path.
+            if (this.eatOp("("))
+                return this.call(t.v);
+            return this.lookup(t.v);
+        }
+        return UNKNOWN;
+    }
+    /**
+     * A function call. Arguments are always parsed, even for functions we cannot
+     * evaluate — the tokens have to be consumed either way or the rest of the
+     * expression parses against the wrong position.
+     */
+    call(name) {
+        const args = [];
+        if (!this.eatOp(")")) {
+            for (;;) {
+                args.push(this.or());
+                if (this.eatOp(","))
+                    continue;
+                if (this.eatOp(")"))
+                    break;
+                return UNKNOWN; // malformed argument list
+            }
+        }
+        return applyFunction(name.toLowerCase(), args);
+    }
+    lookup(path) {
+        const dot = path.indexOf(".");
+        if (dot < 0)
+            return UNKNOWN;
+        const head = path.slice(0, dot);
+        const rest = path.slice(dot + 1);
+        if (head === "inputs")
+            return this.scope.inputs?.[rest] ?? UNKNOWN;
+        if (head === "github") {
+            const v = this.scope.github?.[rest];
+            return v === undefined ? UNKNOWN : { kind: "value", v };
+        }
+        // `needs.*`, `steps.*`, `matrix.*`, `env.*`, `vars.*`, `secrets.*`: all
+        // require something that has not happened yet at prediction time. This is
+        // the seam where a `needs` context would attach if willfire ever computes
+        // a called workflow's outputs ahead of the run.
+        return UNKNOWN;
+    }
+}
+function negate(b) {
+    return b === null ? null : !b;
+}
+/**
+ * `A && B`. Short-circuits from either side: a falsy left decides it, and so
+ * does a falsy right, because a truthy left would then yield the falsy right.
+ * Only "left unknown, right not falsy" is genuinely undecided.
+ */
+function coalesceAnd(left, right) {
+    const l = truthy(left);
+    if (l === false)
+        return left;
+    if (l === true)
+        return right;
+    return truthy(right) === false ? { kind: "falsy" } : UNKNOWN;
+}
+/**
+ * `A || B`. The mirror image: a truthy left decides it, and so does a truthy
+ * right, since a falsy left would then yield the truthy right.
+ */
+function coalesceOr(left, right) {
+    const l = truthy(left);
+    if (l === true)
+        return left;
+    if (l === false)
+        return right;
+    return truthy(right) === true ? { kind: "truthy" } : UNKNOWN;
+}
+/**
+ * Comparison, deliberately narrow: both sides must be concrete and of the same
+ * primitive type.
+ *
+ * GitHub coerces across types when it compares, and the corner cases are
+ * genuinely surprising (`'' == 0` is true). Every comparison that matters in
+ * practice is string-to-string — `inputs.gates == ''`,
+ * `github.event_name == 'pull_request'` — so modelling the coercion table
+ * would add risk without adding reach. Mixed types return unknown.
+ */
+function compare(op, left, right) {
+    if (left.kind !== "value" || right.kind !== "value")
+        return UNKNOWN;
+    const a = left.v;
+    const b = right.v;
+    if (typeof a !== typeof b)
+        return UNKNOWN;
+    if (op === "==")
+        return asBool(a === b);
+    if (op === "!=")
+        return asBool(a !== b);
+    // Ordering on booleans is not modelled. GitHub coerces them to numbers, and
+    // the answer is never one a workflow author meant to ask for.
+    if (typeof a === "boolean" || typeof b === "boolean")
+        return UNKNOWN;
+    if (op === "<")
+        return asBool(a < b);
+    if (op === "<=")
+        return asBool(a <= b);
+    if (op === ">")
+        return asBool(a > b);
+    return asBool(a >= b);
+}
+/**
+ * The functions worth modelling.
+ *
+ * `always()` is true by definition. `contains` on two known strings is the one
+ * that unlocks the fleet's `gates` pattern. `success()`, `failure()` and
+ * `cancelled()` depend on jobs that have not run, and everything else is
+ * simply not modelled — all unknown.
+ */
+function applyFunction(name, args) {
+    if (name === "always")
+        return { kind: "value", v: true };
+    if (name === "contains" && args.length === 2) {
+        const [hay, needle] = args;
+        if (hay.kind !== "value" || needle.kind !== "value")
+            return UNKNOWN;
+        if (typeof hay.v !== "string" || typeof needle.v !== "string")
+            return UNKNOWN;
+        return asBool(hay.v.includes(needle.v));
+    }
+    if ((name === "startswith" || name === "endswith") && args.length === 2) {
+        const [s, part] = args;
+        if (s.kind !== "value" || part.kind !== "value")
+            return UNKNOWN;
+        if (typeof s.v !== "string" || typeof part.v !== "string")
+            return UNKNOWN;
+        return asBool(name === "startswith" ? s.v.startsWith(part.v) : s.v.endsWith(part.v));
+    }
+    return UNKNOWN;
+}
+// ---------------------------------------------------------------------- entry
+/**
+ * Evaluate a condition to a truthiness, or null when it cannot be settled.
+ *
+ * The `${{ }}` wrapper is optional in `if:` and stripped when present. A
+ * condition that is only *partly* wrapped (`foo ${{ bar }} baz`) is a string
+ * interpolation rather than an expression, and is not modelled.
+ */
+export function evaluate(cond, scope = {}) {
+    const stripped = cond.trim().replace(/^\$\{\{(.*)\}\}$/s, "$1").trim();
+    if (stripped === "")
+        return null;
+    if (stripped.includes("${{"))
+        return null;
+    const toks = tokenize(stripped);
+    if (toks == null || toks.length === 0)
+        return null;
+    const p = new Parser(toks, scope);
+    const val = p.or();
+    // Trailing tokens mean the grammar did not cover this condition; whatever
+    // was parsed describes only a prefix of it, so it decides nothing.
+    if (!p.done())
+        return null;
+    return truthy(val);
+}

package/dist/predict.d.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { Octokit } from "@octokit/rest";
+import { type Scope } from "./expr.js";
 interface EntryBase {
     workflow: string;
     reason: string;
@@ -82,8 +83,14 @@ type Workflow = Record<string, any>;
 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";
+/**
+ * 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.*`.
+ */
+export declare function evalIf(cond: any, scope?: Scope): "run" | "skipped" | "unknown";
 /**
  * One expanded job, before it is paired with its workflow. Named `ExpandedJob`
  * because `JobEntry` is now the exported job-level variant of `Entry`.

package/dist/predict.js

@@ -12,6 +12,7 @@
 // src/names.test.ts.
 import { Octokit } from "@octokit/rest";
 import { parse as parseYaml } from "yaml";
+import { evaluate, 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. */
@@ -272,23 +273,83 @@ function skippedDisplayName(jobId, job) {
     const raw = job != null && job.name != null ? String(job.name) : null;
     return { name: raw ?? jobId, resolved: true };
 }
-/** Return run|skipped|unknown for a job-level if. */
-export function evalIf(cond) {
+/**
+ * The `github.*` values that are fixed for everything this module predicts.
+ * `predict` only ever answers for a pull request, so `event_name` is not a
+ * variable — which is what lets a `github.event_name == 'pull_request'` guard
+ * resolve instead of hanging the job on an unknown.
+ */
+const PR_GITHUB_CONTEXT = { event_name: "pull_request" };
+/**
+ * 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.*`.
+ */
+export function evalIf(cond, scope = {}) {
     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";
+    const verdict = evaluate(String(cond), {
+        inputs: scope.inputs,
+        github: { ...PR_GITHUB_CONTEXT, ...scope.github },
+    });
+    if (verdict === null)
+        return "unknown";
+    return verdict ? "run" : "skipped";
+}
+/**
+ * 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.
+ */
+function inputLiteral(raw) {
+    if (raw == null)
+        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 };
+    return UNKNOWN;
+}
+/** The `on.workflow_call.inputs` block, tolerating the YAML 1.1 `on` -> true key. */
+function workflowCallInputs(wf) {
+    const on = wf?.["on"] ?? wf?.["true"];
+    if (on == null || typeof on !== "object")
+        return {};
+    const call = on["workflow_call"];
+    if (call == null || typeof call !== "object")
+        return {};
+    const inputs = call["inputs"];
+    return inputs != null && typeof inputs === "object" ? inputs : {};
+}
+/**
+ * What `inputs.*` resolves to inside a called workflow: what the caller passed,
+ * over the defaults the callee declares.
+ *
+ * A declared input the caller omits falls back to its `default`. A declared
+ * input with no default and no caller value is unknown rather than empty — the
+ * workflow would be invalid if it were required, and guessing empty would
+ * silently decide guards that are not decided.
+ */
+function calleeInputs(withBlock, subWf) {
+    const out = {};
+    for (const [name, decl] of Object.entries(workflowCallInputs(subWf))) {
+        out[name] =
+            decl != null && typeof decl === "object" && "default" in decl
+                ? inputLiteral(decl["default"])
+                : UNKNOWN;
+    }
+    if (withBlock != null && typeof withBlock === "object") {
+        for (const [name, raw] of Object.entries(withBlock)) {
+            out[name] = inputLiteral(raw);
+        }
     }
-    return "unknown";
+    return out;
 }
 /**
  * GitHub allows a reusable-workflow call chain four levels deep. Past that the
@@ -331,13 +392,13 @@ export function parseUses(uses) {
         return null;
     return { path, source: { owner, repo, ref } };
 }
-async function expandJobs(wf, ctx, fetchWorkflow, source, depth = 0, prefix = "", prefixResolved = true) {
+async function expandJobs(wf, ctx, fetchWorkflow, source, depth = 0, prefix = "", prefixResolved = true, scope = {}) {
     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 status = evalIf(job.if, scope);
         let reason = job.if != null ? `if: ${JSON.stringify(job.if)}` : "";
         let needs = job.needs ?? [];
         if (typeof needs === "string")
@@ -392,6 +453,8 @@ async function expandJobs(wf, ctx, fetchWorkflow, source, depth = 0, prefix = ""
             // Where the callee's own `./` calls will resolve. A remote `uses:` moves
             // this to the callee's repo and pinned ref; a local one leaves it alone.
             let subSource = source;
+            // What `inputs.*` means on the other side of the call.
+            let subScope = {};
             const target = parseUses(uses);
             if (depth + 1 > MAX_REUSABLE_DEPTH) {
                 failure = `reusable workflow nested deeper than ${MAX_REUSABLE_DEPTH} levels`;
@@ -408,6 +471,7 @@ async function expandJobs(wf, ctx, fetchWorkflow, source, depth = 0, prefix = ""
                 else {
                     try {
                         subWf = parseYaml(content);
+                        subScope = { inputs: calleeInputs(job.with, subWf ?? {}) };
                     }
                     catch (e) {
                         failure = `YAML parse error in ${uses}: ${e}`;
@@ -427,7 +491,7 @@ async function expandJobs(wf, ctx, fetchWorkflow, source, depth = 0, prefix = ""
                     });
                     continue;
                 }
-                entries.push(...(await expandJobs(subWf, ctx, fetchWorkflow, subSource, depth + 1, `${baseName} / `, nameResolved)));
+                entries.push(...(await expandJobs(subWf, ctx, fetchWorkflow, subSource, depth + 1, `${baseName} / `, nameResolved, subScope)));
             }
             continue;
         }

package/package.json

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