willfire 0.1.9 → 0.1.11

package/dist/expr.js

@@ -43,6 +43,10 @@ function truthy(val) {
             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")
@@ -264,10 +268,36 @@ class Parser {
             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.
+        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 = this.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 = this.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;
     }
 }
@@ -332,17 +362,45 @@ function compare(op, left, right) {
         return asBool(a > b);
     return asBool(a >= b);
 }
+/**
+ * `fromJSON(s)` on a known string.
+ *
+ * The result is sorted into the lattice rather than dropped in whole: a scalar
+ * is an ordinary value and stays comparable, `null` has a known truthiness and
+ * no useful value, and only an array or an object needs the `json` point.
+ * Anything unparseable is unknown — a workflow that reaches this at runtime
+ * fails, and predicting a failure is not this function's job.
+ */
+function fromJson(arg) {
+    if (arg.kind !== "value" || typeof arg.v !== "string")
+        return UNKNOWN;
+    let parsed;
+    try {
+        parsed = JSON.parse(arg.v);
+    }
+    catch {
+        return UNKNOWN;
+    }
+    if (parsed === null)
+        return { kind: "falsy" };
+    if (typeof parsed === "object")
+        return { kind: "json", v: parsed };
+    return { kind: "value", v: parsed };
+}
 /**
  * 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.
+ * that unlocks the fleet's `gates` pattern. `fromJSON` is what a dynamic matrix
+ * axis is built out of. `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 === "fromjson" && args.length === 1)
+        return fromJson(args[0]);
     if (name === "contains" && args.length === 2) {
         const [hay, needle] = args;
         if (hay.kind !== "value" || needle.kind !== "value")
@@ -363,26 +421,35 @@ function applyFunction(name, args) {
 }
 // ---------------------------------------------------------------------- entry
 /**
- * Evaluate a condition to a truthiness, or null when it cannot be settled.
+ * Evaluate an expression to a value, or UNKNOWN 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
+ * 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 function evaluate(cond, scope = {}) {
-    const stripped = cond.trim().replace(/^\$\{\{(.*)\}\}$/s, "$1").trim();
+export function evaluateValue(expr, scope = {}) {
+    const stripped = expr.trim().replace(/^\$\{\{(.*)\}\}$/s, "$1").trim();
     if (stripped === "")
-        return null;
+        return UNKNOWN;
     if (stripped.includes("${{"))
-        return null;
+        return UNKNOWN;
     const toks = tokenize(stripped);
     if (toks == null || toks.length === 0)
-        return null;
+        return UNKNOWN;
     const p = new Parser(toks, scope);
     const val = p.or();
-    // Trailing tokens mean the grammar did not cover this condition; whatever
+    // Trailing tokens mean the grammar did not cover this expression; whatever
     // was parsed describes only a prefix of it, so it decides nothing.
     if (!p.done())
-        return null;
-    return truthy(val);
+        return UNKNOWN;
+    return val;
+}
+/** Evaluate a condition to a truthiness, or null when it cannot be settled. */
+export function evaluate(cond, scope = {}) {
+    return truthy(evaluateValue(cond, scope));
 }

package/dist/predict.d.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { Octokit } from "@octokit/rest";
+import { type ExecutionGrant, type JobExecutor } from "./execute.js";
 import { type Scope } from "./expr.js";
 interface EntryBase {
     workflow: string;
@@ -75,6 +76,15 @@ export interface Prediction {
      */
     checkNames: string[];
     skip: string | null;
+    /**
+     * Every repo this prediction read, and the commit each ref resolved to —
+     * the PR's own head first, then any cross-repo `uses:` reached from it.
+     *
+     * Provenance, not input. `v0` is a moving tag, so "willfire said these
+     * checks" is only reconcilable against a run if it also says which commits
+     * it read to say it. Sorted by `owner/repo@ref`.
+     */
+    sources: WorkflowSource[];
 }
 export declare function patternToRegex(pat: string): RegExp;
 /** Order-sensitive match: last matching pattern wins; ! negates. */
@@ -102,6 +112,17 @@ export interface PredictOptions {
      * to a workflow narrowing `types:`, where it matters completely.
      */
     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.
+     */
+    execute?: ExecutionGrant[];
 }
 export interface Ctx {
     action: string;
@@ -111,13 +132,14 @@ export interface Ctx {
 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;
+export declare function expandMatrix(strategy: any, scope?: Scope): Combo[] | null;
 /**
  * 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.*`.
+ * `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";
 /**
@@ -141,20 +163,54 @@ export interface ExpandedJob {
  * `owner/repo/path@ref` resolves against *that* repo at *that* ref — probe
  * verified, see `src/names.test.ts`.
  */
-export interface WorkflowSource {
+export interface SourceRef {
     owner: string;
     repo: string;
     /** Tag, branch, or SHA — whatever `@` was pinned to. */
     ref: string;
 }
+/**
+ * A source whose ref has been resolved to the commit it names.
+ *
+ * Expansion walks these and never a bare {@link SourceRef}: `v0` is a moving
+ * tag, so two reads an hour apart can be two different programs, and a
+ * prediction that cannot name the commit it read cannot be reconciled against
+ * the run afterwards. Making the SHA required is what stops an unresolved ref
+ * being expanded against by accident.
+ */
+export interface WorkflowSource extends SourceRef {
+    /** The commit `ref` names. Equal to `ref` when it was already a SHA. */
+    sha: string;
+}
 /** Read one workflow file, or null if it is not reachable. Must not throw. */
 export type FetchWorkflow = (path: string, source: WorkflowSource) => Promise<string | null>;
+/**
+ * Resolve a tag, branch, or SHA to the commit it names, or null when it cannot
+ * be resolved. Must not throw.
+ *
+ * Null is not a cue to fall back to the mutable ref. It leaves every entry
+ * behind that source unresolved, which turns the gate red — reading a ref we
+ * cannot name is the thing this exists to stop.
+ */
+export type ResolveRef = (source: SourceRef) => Promise<string | null>;
+/**
+ * The two reads expansion needs from the outside world, bundled so the recursion
+ * carries one parameter instead of two.
+ */
+export interface WorkflowReader {
+    fetchWorkflow: FetchWorkflow;
+    resolveRef: ResolveRef;
+}
 /** A `uses:` that named a workflow file we know how to go and get. */
 export interface UsesTarget {
     /** Path inside the target repo, e.g. `.github/workflows/x.yml`. */
     path: string;
-    /** null for a local `./` call: the caller's own repo and ref. */
-    source: WorkflowSource | null;
+    /**
+     * null for a local `./` call: the caller's own repo and ref, already
+     * resolved. Non-null sources arrive unresolved — the ref is whatever the
+     * `uses:` string spelled.
+     */
+    source: SourceRef | null;
 }
 /**
  * Split a job-level `uses:` into the file it names and the repo it lives in.
@@ -174,8 +230,13 @@ export declare function parseUses(uses: string): UsesTarget | null;
  * Expand one already-parsed workflow into its job entries. Exported so check
  * names can be tested against recorded GitHub behaviour without a network
  * round-trip; `predict` is the API you want.
+ *
+ * `scope` seeds what this workflow's own `${{ }}` resolve against — notably
+ * `needs`, the outputs of jobs that have not run. Nothing here works out what
+ * those are; a caller that knows hands them in, and a caller that does not
+ * leaves them out and gets `unknown` where they would have been used.
  */
-export declare function expandWorkflowJobs(wf: Workflow, ctx: Ctx, fetchWorkflow: FetchWorkflow, source: WorkflowSource): Promise<ExpandedJob[]>;
+export declare function expandWorkflowJobs(wf: Workflow, ctx: Ctx, reader: WorkflowReader, source: WorkflowSource, scope?: Scope, executor?: JobExecutor): Promise<ExpandedJob[]>;
 export declare function makeOctokit(): Octokit;
 export declare function predict(octokit: Octokit, repo: string, prNumber: number, opts?: PredictOptions): Promise<Prediction>;
 export {};