willfire 0.1.11 → 0.1.13

package/dist/expr/lookup.js

@@ -0,0 +1,51 @@
+import { UNKNOWN } from "./val.js";
+export function lookup(scope, 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 scope.inputs?.[rest] ?? UNKNOWN;
+    }
+    if (head === "github") {
+        const v = scope.github?.[rest];
+        return v === undefined ? UNKNOWN : { kind: "value", v };
+    }
+    if (head === "needs") {
+        // Only `needs.<job>.outputs.<name>` is modelled. `needs.<job>.result`
+        // is a verdict on a run that has not happened; anything else is not a
+        // shape the context has.
+        const parts = rest.split(".");
+        if (parts.length !== 3 || parts[1] !== "outputs") {
+            return UNKNOWN;
+        }
+        const job = scope.needs?.[parts[0]];
+        if (job == null) {
+            return UNKNOWN;
+        }
+        // A known job's missing output is the empty string, not a hole: the
+        // caller promised the set is complete, and that is what the runner
+        // substitutes for an output no step wrote.
+        return { kind: "value", v: job.outputs[parts[2]] ?? "" };
+    }
+    if (head === "steps") {
+        // The same shape as `needs`, for the same reason: only
+        // `steps.<id>.outputs.<name>` is modelled. `steps.<id>.outcome` and
+        // `.conclusion` are verdicts on how a step ran, which the executor does
+        // not track — a failed step fails the whole execution instead.
+        const parts = rest.split(".");
+        if (parts.length !== 3 || parts[1] !== "outputs") {
+            return UNKNOWN;
+        }
+        const step = scope.steps?.[parts[0]];
+        if (step == null) {
+            return UNKNOWN;
+        }
+        return { kind: "value", v: step.outputs[parts[2]] ?? "" };
+    }
+    // `matrix.*`, `env.*`, `vars.*`, `secrets.*`: all require something that
+    // has not happened yet at prediction time.
+    return UNKNOWN;
+}

package/dist/expr/negate.d.ts

@@ -0,0 +1 @@
+export declare function negate(b: boolean | null): boolean | null;

package/dist/expr/negate.js

@@ -0,0 +1,3 @@
+export function negate(b) {
+    return b === null ? null : !b;
+}

package/dist/expr/parseAnd.d.ts

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

package/dist/expr/parseAnd.js

@@ -0,0 +1,10 @@
+import { coalesceAnd } from "./coalesceAnd.js";
+import { parseCmp } from "./parseCmp.js";
+export function parseAnd(cur, scope) {
+    let left = parseCmp(cur, scope);
+    while (cur.eatOp("&&")) {
+        const right = parseCmp(cur, scope);
+        left = coalesceAnd(left, right);
+    }
+    return left;
+}

package/dist/expr/parseAtom.d.ts

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

package/dist/expr/parseAtom.js

@@ -0,0 +1,43 @@
+import { lookup } from "./lookup.js";
+import { parseCall } from "./parseCall.js";
+import { parseOr } from "./parseOr.js";
+import { UNKNOWN } from "./val.js";
+export function parseAtom(cur, scope) {
+    const t = cur.peek();
+    if (t == null) {
+        return UNKNOWN;
+    }
+    if (t.t === "op" && t.v === "(") {
+        cur.advance();
+        const v = parseOr(cur, scope);
+        if (!cur.eatOp(")")) {
+            return UNKNOWN;
+        }
+        return v;
+    }
+    if (t.t === "str") {
+        cur.advance();
+        return { kind: "value", v: t.v };
+    }
+    if (t.t === "num") {
+        cur.advance();
+        return { kind: "value", v: t.v };
+    }
+    if (t.t === "bool") {
+        cur.advance();
+        return { kind: "value", v: t.v };
+    }
+    if (t.t === "null") {
+        cur.advance();
+        return { kind: "value", v: "" };
+    }
+    if (t.t === "path") {
+        cur.advance();
+        // A `(` right after a name makes it a call, not a path.
+        if (cur.eatOp("(")) {
+            return parseCall(cur, scope, t.v);
+        }
+        return lookup(scope, t.v);
+    }
+    return UNKNOWN;
+}

package/dist/expr/parseCall.d.ts

@@ -0,0 +1,9 @@
+import type { Cursor } from "./cursor.js";
+import { type Scope, type Val } from "./val.js";
+/**
+ * A function call, entered after its `(` was consumed. 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.
+ */
+export declare function parseCall(cur: Cursor, scope: Scope, name: string): Val;

package/dist/expr/parseCall.js

@@ -0,0 +1,25 @@
+import { applyFunction } from "./applyFunction.js";
+import { parseOr } from "./parseOr.js";
+import { UNKNOWN } from "./val.js";
+/**
+ * A function call, entered after its `(` was consumed. 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.
+ */
+export function parseCall(cur, scope, name) {
+    const args = [];
+    if (!cur.eatOp(")")) {
+        for (;;) {
+            args.push(parseOr(cur, scope));
+            if (cur.eatOp(",")) {
+                continue;
+            }
+            if (cur.eatOp(")")) {
+                break;
+            }
+            return UNKNOWN; // malformed argument list
+        }
+    }
+    return applyFunction(name.toLowerCase(), args);
+}

package/dist/expr/parseCmp.d.ts

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

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/filters/index.d.ts

@@ -0,0 +1,2 @@
+export { patternToRegex } from "./patternToRegex.js";
+export { matchFilters } from "./matchFilters.js";

package/dist/filters/index.js

@@ -0,0 +1,2 @@
+export { patternToRegex } from "./patternToRegex.js";
+export { matchFilters } from "./matchFilters.js";

package/dist/filters/matchFilters.d.ts

@@ -0,0 +1,2 @@
+/** Order-sensitive match: last matching pattern wins; ! negates. */
+export declare function matchFilters(value: string, patterns: string[]): boolean;

package/dist/filters/matchFilters.js

@@ -0,0 +1,12 @@
+import { patternToRegex } from "./patternToRegex.js";
+/** 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;
+}

package/dist/filters/patternToRegex.d.ts

@@ -0,0 +1 @@
+export declare function patternToRegex(pat: string): RegExp;

package/dist/filters/patternToRegex.js

@@ -0,0 +1,35 @@
+// 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}$`);
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { jobName, isWorkflowEntry, isJobEntry } from "./entries/index.js";
+export { patternToRegex, matchFilters } from "./filters/index.js";
+export { expandMatrix } from "./matrix/index.js";
+export { evalIf, expandWorkflowJobs } from "./jobs/index.js";
+export { parseUses } from "./uses/index.js";
+export { makeOctokit, predict } from "./predict/index.js";
+export type { JobName, WorkflowEntry, JobEntry, Entry, Prediction, PrEventAction, PredictOptions, Ctx, ExpandedJob, SourceRef, WorkflowSource, FetchWorkflow, ResolveRef, WorkflowReader, UsesTarget, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+export { jobName, isWorkflowEntry, isJobEntry } from "./entries/index.js";
+export { patternToRegex, matchFilters } from "./filters/index.js";
+export { expandMatrix } from "./matrix/index.js";
+export { evalIf, expandWorkflowJobs } from "./jobs/index.js";
+export { parseUses } from "./uses/index.js";
+export { makeOctokit, predict } from "./predict/index.js";

package/dist/jobs/evalIf.d.ts

@@ -0,0 +1,10 @@
+import type { Scope } from "../expr/val.js";
+/**
+ * Return run|skipped|unknown for a job-level `if:`.
+ *
+ * `scope` carries the inputs the calling workflow passed down, and any job
+ * outputs the caller knows. Without it a reusable workflow's guards are all
+ * unknown, because every one of them is written against `inputs.*` or
+ * `needs.*`.
+ */
+export declare function evalIf(cond: any, scope?: Scope): "run" | "skipped" | "unknown";

package/dist/jobs/evalIf.js

@@ -0,0 +1,18 @@
+import { evaluate } from "../expr/evaluate.js";
+import { prScope } from "./prScope.js";
+/**
+ * Return run|skipped|unknown for a job-level `if:`.
+ *
+ * `scope` carries the inputs the calling workflow passed down, and any job
+ * outputs the caller knows. Without it a reusable workflow's guards are all
+ * unknown, because every one of them is written against `inputs.*` or
+ * `needs.*`.
+ */
+export function evalIf(cond, scope = {}) {
+    if (cond == null)
+        return "run";
+    const verdict = evaluate(String(cond), prScope(scope));
+    if (verdict === null)
+        return "unknown";
+    return verdict ? "run" : "skipped";
+}

package/dist/jobs/expandJobs.d.ts

@@ -0,0 +1,4 @@
+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[]>;