willfire 0.1.12 → 0.1.13

package/dist/expr/parseCmp.js

@@ -0,0 +1,12 @@
+import { compare } from "./compare.js";
+import { parseUnary } from "./parseUnary.js";
+export function parseCmp(cur, scope) {
+    const left = parseUnary(cur, scope);
+    for (const op of ["==", "!=", "<=", ">=", "<", ">"]) {
+        if (cur.eatOp(op)) {
+            const right = parseUnary(cur, scope);
+            return compare(op, left, right);
+        }
+    }
+    return left;
+}

package/dist/expr/parseOr.d.ts

@@ -0,0 +1,11 @@
+import type { Cursor } from "./cursor.js";
+import type { Scope, Val } from "./val.js";
+/**
+ * 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.
+ */
+export declare function parseOr(cur: Cursor, scope: Scope): Val;

package/dist/expr/parseOr.js

@@ -0,0 +1,18 @@
+import { coalesceOr } from "./coalesceOr.js";
+import { parseAnd } from "./parseAnd.js";
+/**
+ * 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.
+ */
+export function parseOr(cur, scope) {
+    let left = parseAnd(cur, scope);
+    while (cur.eatOp("||")) {
+        const right = parseAnd(cur, scope);
+        left = coalesceOr(left, right);
+    }
+    return left;
+}

package/dist/expr/parsePrimary.d.ts

@@ -0,0 +1,4 @@
+import type { Cursor } from "./cursor.js";
+import { type Scope, type Val } from "./val.js";
+/** An atom plus any `[...]` accesses hanging off it, tightest-binding. */
+export declare function parsePrimary(cur: Cursor, scope: Scope): Val;

package/dist/expr/parsePrimary.js

@@ -0,0 +1,16 @@
+import { indexVal } from "./indexVal.js";
+import { parseAtom } from "./parseAtom.js";
+import { parseOr } from "./parseOr.js";
+import { UNKNOWN } from "./val.js";
+/** An atom plus any `[...]` accesses hanging off it, tightest-binding. */
+export function parsePrimary(cur, scope) {
+    let v = parseAtom(cur, scope);
+    while (cur.eatOp("[")) {
+        const idx = parseOr(cur, scope);
+        if (!cur.eatOp("]")) {
+            return UNKNOWN;
+        }
+        v = indexVal(v, idx);
+    }
+    return v;
+}

package/dist/expr/parseUnary.d.ts

@@ -0,0 +1,3 @@
+import type { Cursor } from "./cursor.js";
+import type { Scope, Val } from "./val.js";
+export declare function parseUnary(cur: Cursor, scope: Scope): Val;

package/dist/expr/parseUnary.js

@@ -0,0 +1,11 @@
+import { asBool } from "./asBool.js";
+import { negate } from "./negate.js";
+import { parsePrimary } from "./parsePrimary.js";
+import { truthy } from "./truthy.js";
+export function parseUnary(cur, scope) {
+    if (cur.eatOp("!")) {
+        const v = parseUnary(cur, scope);
+        return asBool(negate(truthy(v)));
+    }
+    return parsePrimary(cur, scope);
+}

package/dist/expr/tokenize.d.ts

@@ -0,0 +1,24 @@
+export type Tok = {
+    t: "str";
+    v: string;
+} | {
+    t: "num";
+    v: number;
+} | {
+    t: "bool";
+    v: boolean;
+} | {
+    t: "null";
+} | {
+    t: "path";
+    v: string;
+} | {
+    t: "op";
+    v: string;
+};
+/**
+ * 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`.
+ */
+export declare function tokenize(src: string): Tok[] | null;

package/dist/expr/tokenize.js

@@ -0,0 +1,74 @@
+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`.
+ */
+export 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;
+}

package/dist/expr/truthy.d.ts

@@ -0,0 +1,7 @@
+import type { Val } from "./val.js";
+/**
+ * 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.
+ */
+export declare function truthy(val: Val): boolean | null;

package/dist/expr/truthy.js

@@ -0,0 +1,29 @@
+/**
+ * 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.
+ */
+export function truthy(val) {
+    switch (val.kind) {
+        case "truthy":
+            return true;
+        case "falsy":
+            return false;
+        case "unknown":
+            return null;
+        // GitHub does cast an array or an object to a boolean, but no workflow
+        // asks it to, and the answer is not worth guessing at to find out.
+        case "json":
+            return null;
+        case "value": {
+            const v = val.v;
+            if (typeof v === "boolean") {
+                return v;
+            }
+            if (typeof v === "number") {
+                return v !== 0;
+            }
+            return v !== "";
+        }
+    }
+}

package/dist/expr/val.d.ts

@@ -0,0 +1,72 @@
+/**
+ * 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;
+}
+/**
+ * An array or an object, which only `fromJSON` produces. Kept apart from
+ * `value` because nothing else in the language accepts one: comparison
+ * refuses it, and its truthiness is not modelled. Matrix expansion is the
+ * one consumer, and it asks for the array directly.
+ */
+ | {
+    kind: "json";
+    v: unknown[] | Record<string, unknown>;
+} | {
+    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>;
+    /**
+     * Outputs of jobs this workflow's jobs `needs`, keyed by job id.
+     *
+     * `outputs` is the *complete* set for that job, which is what makes a key
+     * that is absent from it mean the empty string — the same answer the runner
+     * gives for an output no step wrote. Handing in a partial map is therefore a
+     * lie, not a shortcut: leave the job out entirely instead, and every lookup
+     * against it stays unknown.
+     *
+     * The values are raw strings, because that is what a step wrote to
+     * `$GITHUB_OUTPUT` and what the runner substitutes. Parsing eagerly would
+     * break the guards written against them — `!= '[]'` compares a string to a
+     * string, and an array on the left makes it unknown. `fromJSON` is the only
+     * thing that turns one into a structure, at the point the workflow asks.
+     */
+    needs?: Record<string, {
+        outputs: Record<string, string>;
+    }>;
+    /**
+     * Outputs of steps that already ran, keyed by step id. Only one caller can
+     * fill this honestly: the executor's step walk (see ../execute/runSteps.ts),
+     * which is the single place a step has actually run by the time an
+     * expression reads it. The contract is the same as `needs`: a step named
+     * here carries its *complete* output set, so an absent key is the empty
+     * string the runner substitutes, while a step this map does not name stays
+     * unknown. A skipped step is present with no outputs at all — which is
+     * exactly what lets `steps.a.outputs.x || steps.b.outputs.x` coalesce past
+     * it.
+     */
+    steps?: Record<string, {
+        outputs: Record<string, string>;
+    }>;
+}

package/dist/expr/val.js

@@ -0,0 +1 @@
+export const UNKNOWN = { kind: "unknown" };

package/dist/jobs/evalIf.d.ts

@@ -1,4 +1,4 @@
-import { type Scope } from "../expr.js";
+import type { Scope } from "../expr/val.js";
 /**
  * Return run|skipped|unknown for a job-level `if:`.
  *

package/dist/jobs/evalIf.js

@@ -1,4 +1,4 @@
-import { evaluate } from "../expr.js";
+import { evaluate } from "../expr/evaluate.js";
 import { prScope } from "./prScope.js";
 /**
  * Return run|skipped|unknown for a job-level `if:`.

package/dist/jobs/expandJobs.d.ts

@@ -1,4 +1,4 @@
-import { type Scope } from "../expr.js";
+import { type Scope } from "../expr/val.js";
 import type { JobExecutor } from "../execute.js";
 import type { Ctx, ExpandedJob, Workflow, WorkflowReader, WorkflowSource } from "../types.js";
 export declare function expandJobs(wf: Workflow, ctx: Ctx, reader: WorkflowReader, source: WorkflowSource, depth?: number, prefix?: string, prefixResolved?: boolean, scope?: Scope, executor?: JobExecutor): Promise<ExpandedJob[]>;

package/dist/jobs/expandJobs.js

@@ -1,5 +1,5 @@
 import { parse as parseYaml } from "yaml";
-import { UNKNOWN } from "../expr.js";
+import { UNKNOWN } from "../expr/val.js";
 import { expandMatrixDetailed } from "../matrix/expandMatrixDetailed.js";
 import { jobDisplayName } from "../names/jobDisplayName.js";
 import { skippedDisplayName } from "../names/skippedDisplayName.js";

package/dist/jobs/expandWorkflowJobs.d.ts

@@ -1,4 +1,4 @@
-import type { Scope } from "../expr.js";
+import type { Scope } from "../expr/val.js";
 import type { JobExecutor } from "../execute.js";
 import type { Ctx, ExpandedJob, Workflow, WorkflowReader, WorkflowSource } from "../types.js";
 /**

package/dist/jobs/prScope.d.ts

@@ -1,4 +1,4 @@
-import type { Scope } from "../expr.js";
+import type { Scope } from "../expr/val.js";
 /**
  * A scope with the fixed pull-request facts filled in.
  *

package/dist/matrix/expandMatrix.d.ts

@@ -1,4 +1,4 @@
-import type { Scope } from "../expr.js";
+import type { Scope } from "../expr/val.js";
 import type { Combo } from "../types.js";
 /** Return list of matrix combination dicts, or null if dynamic. */
 export declare function expandMatrix(strategy: any, scope?: Scope): Combo[] | null;

package/dist/matrix/expandMatrixDetailed.d.ts

@@ -1,3 +1,3 @@
-import { type Scope } from "../expr.js";
+import type { Scope } from "../expr/val.js";
 import type { DetailedCombos } from "../types.js";
 export declare function expandMatrixDetailed(strategy: any, scope?: Scope): DetailedCombos;

package/dist/matrix/expandMatrixDetailed.js

@@ -1,4 +1,4 @@
-import { evaluateValue } from "../expr.js";
+import { evaluateValue } from "../expr/evaluateValue.js";
 /**
  * The values of one matrix axis, or null when they cannot be known.
  *

package/package.json

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

package/dist/expr.d.ts

@@ -1,117 +0,0 @@
-/**
- * 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;
-}
-/**
- * An array or an object, which only `fromJSON` produces. Kept apart from
- * `value` because nothing else in the language accepts one: comparison
- * refuses it, and its truthiness is not modelled. Matrix expansion is the
- * one consumer, and it asks for the array directly.
- */
- | {
-    kind: "json";
-    v: unknown[] | Record<string, unknown>;
-} | {
-    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>;
-    /**
-     * Outputs of jobs this workflow's jobs `needs`, keyed by job id.
-     *
-     * `outputs` is the *complete* set for that job, which is what makes a key
-     * that is absent from it mean the empty string — the same answer the runner
-     * gives for an output no step wrote. Handing in a partial map is therefore a
-     * lie, not a shortcut: leave the job out entirely instead, and every lookup
-     * against it stays unknown.
-     *
-     * The values are raw strings, because that is what a step wrote to
-     * `$GITHUB_OUTPUT` and what the runner substitutes. Parsing eagerly would
-     * break the guards written against them — `!= '[]'` compares a string to a
-     * string, and an array on the left makes it unknown. `fromJSON` is the only
-     * thing that turns one into a structure, at the point the workflow asks.
-     */
-    needs?: Record<string, {
-        outputs: Record<string, string>;
-    }>;
-    /**
-     * Outputs of steps that already ran, keyed by step id. Only one caller can
-     * fill this honestly: the executor's step walk (see execute.ts), which is
-     * the single place a step has actually run by the time an expression reads
-     * it. The contract is the same as `needs`: a step named here carries its
-     * *complete* output set, so an absent key is the empty string the runner
-     * substitutes, while a step this map does not name stays unknown. A skipped
-     * step is present with no outputs at all — which is exactly what lets
-     * `steps.a.outputs.x || steps.b.outputs.x` coalesce past it.
-     */
-    steps?: Record<string, {
-        outputs: Record<string, string>;
-    }>;
-}
-/**
- * Evaluate an expression to a value, or UNKNOWN when it cannot be settled.
- *
- * The `${{ }}` wrapper is optional in `if:` and stripped when present. An
- * expression that is only *partly* wrapped (`foo ${{ bar }} baz`) is a string
- * interpolation rather than an expression, and is not modelled.
- *
- * A `if:` wants {@link evaluate}, which is this narrowed to truthiness. This
- * one is for the places that need the value itself — a matrix axis written as
- * `${{ fromJSON(...) }}` is an array, and its truthiness says nothing about
- * how many jobs it schedules.
- */
-export declare function evaluateValue(expr: string, scope?: Scope): Val;
-/** Evaluate a condition to a truthiness, or null when it cannot be settled. */
-export declare function evaluate(cond: string, scope?: Scope): boolean | null;