willfire 0.1.10 → 0.1.12

package/dist/triggers/workflowDispatches.js

@@ -0,0 +1,45 @@
+import { matchFilters } from "../filters/matchFilters.js";
+import { getPrTrigger, MISSING } from "./getPrTrigger.js";
+const DEFAULT_TYPES = ["opened", "synchronize", "reopened"];
+// A predicate: does this workflow produce a run for the PR? Every workflow-level
+// verdict is decidable, so there is no third answer to express. Only job
+// expansion can be genuinely undecidable (dynamic matrix, an unreadable
+// reusable workflow, unresolvable `if`), and that is a per-entry status.
+export function workflowDispatches(wf, ctx) {
+    const trig = getPrTrigger(wf);
+    if (trig === MISSING)
+        return [false, "no pull_request trigger"];
+    const types = trig["types"] ?? DEFAULT_TYPES;
+    if (!types.includes(ctx.action)) {
+        return [false, `action '${ctx.action}' not in types [${types}]`];
+    }
+    // Setting a filter and its -ignore twin on one trigger is invalid config.
+    // GitHub does not fall back to "no filter" or skip the workflow: it creates
+    // the run and concludes `startup_failure`. The run exists, so it dispatches.
+    if ("branches" in trig && "branches-ignore" in trig) {
+        return [true, "both branches and branches-ignore set: startup failure"];
+    }
+    const branchRef = ctx.stackTarget ?? ctx.baseRef;
+    if ("branches" in trig && !matchFilters(branchRef, trig["branches"])) {
+        const label = ctx.stackTarget == null ? "base branch" : "stack target";
+        return [false, `${label} '${branchRef}' not in branches`];
+    }
+    if ("branches-ignore" in trig && matchFilters(branchRef, trig["branches-ignore"])) {
+        return [
+            false,
+            ctx.stackTarget == null
+                ? "base branch in branches-ignore"
+                : `stack target '${branchRef}' in branches-ignore`,
+        ];
+    }
+    if ("paths" in trig && "paths-ignore" in trig) {
+        return [true, "both paths and paths-ignore set: startup failure"];
+    }
+    if ("paths" in trig && !ctx.files.some((f) => matchFilters(f, trig["paths"]))) {
+        return [false, "no changed file matches paths"];
+    }
+    if ("paths-ignore" in trig && ctx.files.every((f) => matchFilters(f, trig["paths-ignore"]))) {
+        return [false, "all changed files match paths-ignore"];
+    }
+    return [true, "trigger matched"];
+}

package/dist/{predict.d.ts → types.d.ts}

@@ -1,7 +1,5 @@
-#!/usr/bin/env node
-import { Octokit } from "@octokit/rest";
-import { type Scope } from "./expr.js";
-interface EntryBase {
+import type { ExecutionGrant } from "./execute.js";
+export interface EntryBase {
     workflow: string;
     reason: string;
 }
@@ -13,13 +11,11 @@ interface EntryBase {
  * structurally admit `{ job: "*", status: "unknown" }` as a `JobEntry` — the
  * exact shape this split exists to forbid. TypeScript cannot spell "string
  * but not `"*"`", so the job side is branded instead. Build one with
- * {@link jobName}; reading one is just a string.
+ * `jobName`; reading one is just a string.
  */
 export type JobName = string & {
     readonly __jobName: true;
 };
-/** Tag a job display name. Rejects the workflow-level sentinel. */
-export declare const jobName: <S extends string>(name: S extends "*" ? never : S) => JobName;
 /**
  * A verdict about the workflow as a whole: it produces no run at all, or it
  * produces a run that expands into no job entries.
@@ -62,10 +58,6 @@ export interface JobEntry extends EntryBase {
     status: "run" | "skipped" | "unknown";
 }
 export type Entry = WorkflowEntry | JobEntry;
-/** Narrow to the workflow-level variant without inspecting the sentinel. */
-export declare const isWorkflowEntry: (e: Entry) => e is WorkflowEntry;
-/** Narrow to the job-level variant without inspecting the sentinel. */
-export declare const isJobEntry: (e: Entry) => e is JobEntry;
 export interface Prediction {
     entries: Entry[];
     /**
@@ -85,9 +77,22 @@ export interface Prediction {
      */
     sources: WorkflowSource[];
 }
-export declare function patternToRegex(pat: string): RegExp;
-/** Order-sensitive match: last matching pattern wins; ! negates. */
-export declare function matchFilters(value: string, patterns: string[]): boolean;
+/**
+ * Internal entry shapes. `checkName` is optional while entries are being
+ * accumulated so that workflow-level pushes stay one-liners; `finalize`
+ * settles the omitted ones to null.
+ *
+ * Deliberately a union of two Omits rather than `Omit<Entry, "checkName">`.
+ * `Omit` over a union collapses to its common keys, which would re-widen
+ * `job`/`status` back into the single flat shape that let
+ * `{ job: "*", status: "unknown" }` typecheck. The push sites are exactly
+ * where that has to stay illegal, so the draft type keeps the variants apart.
+ */
+export type DraftWorkflowEntry = Omit<WorkflowEntry, "checkName">;
+export type DraftJobEntry = Omit<JobEntry, "checkName"> & {
+    checkName?: string | null;
+};
+export type DraftEntry = DraftWorkflowEntry | DraftJobEntry;
 /**
  * The `pull_request` actions a caller can name.
  *
@@ -111,24 +116,64 @@ 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;
     baseRef: string;
+    /**
+     * The branch the PR's stack ultimately targets, set only when GitHub's
+     * stacked-PR machinery is engaged (see `stackTargetRef`). Branch
+     * filters match against this instead of `baseRef` (#30).
+     */
+    stackTarget?: string;
     files: string[];
 }
-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 type Workflow = Record<string, any>;
+export type Combo = Record<string, any> | null;
 /**
- * Return run|skipped|unknown for a job-level `if:`.
+ * A matrix combination plus the keys that appear in its check-name
+ * parenthetical. The two differ: a key contributed by an `include` entry that
+ * merged into an existing axis-product combination is readable as
+ * `${{ matrix.key }}` but is NOT shown in the name.
  *
- * `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.*`.
+ * Probe-verified with `a: [x]` plus `include: [{a: x, extra: e1},
+ * {a: z, extra: e2}]` -> checks `m-include2 (x)` and `m-include2 (z, e2)`.
+ * The merged combination shows the axis key only; the combination the include
+ * created from scratch shows all of its own keys.
  */
-export declare function evalIf(cond: any, scope?: Scope): "run" | "skipped" | "unknown";
+export interface DetailedCombo {
+    values: Record<string, any>;
+    displayKeys: string[];
+}
+/**
+ * null element = no matrix at all (a single, unsuffixed job).
+ *
+ * An *empty* array is different, and different again from a null return: it
+ * means the matrix is present and expanded to zero combinations, so the job
+ * schedules nothing. `[null]` would claim one check under the bare job name,
+ * which is a name GitHub never creates for a matrix job.
+ */
+export type DetailedCombos = Array<DetailedCombo | null> | null;
+export interface Rendered {
+    text: string;
+    /** false when an expression was left in place because we cannot evaluate it. */
+    resolved: boolean;
+}
+export interface DisplayName {
+    name: string;
+    resolved: boolean;
+}
 /**
  * One expanded job, before it is paired with its workflow. Named `ExpandedJob`
  * because `JobEntry` is now the exported job-level variant of `Entry`.
@@ -199,26 +244,10 @@ export interface UsesTarget {
      */
     source: SourceRef | null;
 }
-/**
- * Split a job-level `uses:` into the file it names and the repo it lives in.
- *
- * Two spellings are legal:
- *
- *   `./.github/workflows/x.yml`              -> the caller's repo, same commit
- *   `owner/repo/.github/workflows/x.yml@ref` -> another repo, at `ref`
- *
- * The ref is taken from the last `@` so a branch containing a slash
- * (`@feature/foo`) survives. Returns null for anything else — including a
- * reference built from an expression, which we cannot evaluate and so must not
- * guess a fetch target for.
- */
-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.
- */
-export declare function expandWorkflowJobs(wf: Workflow, ctx: Ctx, reader: WorkflowReader, source: WorkflowSource): Promise<ExpandedJob[]>;
-export declare function makeOctokit(): Octokit;
-export declare function predict(octokit: Octokit, repo: string, prNumber: number, opts?: PredictOptions): Promise<Prediction>;
-export {};
+/** The two fields the stack walk reads off a PR, whichever route listed it. */
+export interface StackNode {
+    base: {
+        ref: string;
+    };
+    merge_commit_sha: string | null;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/uses/index.d.ts

@@ -0,0 +1 @@
+export { parseUses } from "./parseUses.js";

package/dist/uses/index.js

@@ -0,0 +1 @@
+export { parseUses } from "./parseUses.js";

package/dist/uses/parseUses.d.ts

@@ -0,0 +1,15 @@
+import type { UsesTarget } from "../types.js";
+/**
+ * Split a job-level `uses:` into the file it names and the repo it lives in.
+ *
+ * Two spellings are legal:
+ *
+ *   `./.github/workflows/x.yml`              -> the caller's repo, same commit
+ *   `owner/repo/.github/workflows/x.yml@ref` -> another repo, at `ref`
+ *
+ * The ref is taken from the last `@` so a branch containing a slash
+ * (`@feature/foo`) survives. Returns null for anything else — including a
+ * reference built from an expression, which we cannot evaluate and so must not
+ * guess a fetch target for.
+ */
+export declare function parseUses(uses: string): UsesTarget | null;

package/dist/uses/parseUses.js

@@ -0,0 +1,33 @@
+import { EXPRESSION_RE } from "../names/jobDisplayName.js";
+/**
+ * Split a job-level `uses:` into the file it names and the repo it lives in.
+ *
+ * Two spellings are legal:
+ *
+ *   `./.github/workflows/x.yml`              -> the caller's repo, same commit
+ *   `owner/repo/.github/workflows/x.yml@ref` -> another repo, at `ref`
+ *
+ * The ref is taken from the last `@` so a branch containing a slash
+ * (`@feature/foo`) survives. Returns null for anything else — including a
+ * reference built from an expression, which we cannot evaluate and so must not
+ * guess a fetch target for.
+ */
+export function parseUses(uses) {
+    if (EXPRESSION_RE.test(uses))
+        return null;
+    if (uses.startsWith("./")) {
+        const path = uses.slice(2);
+        return path === "" ? null : { path, source: null };
+    }
+    const at = uses.lastIndexOf("@");
+    if (at <= 0)
+        return null;
+    const ref = uses.slice(at + 1);
+    if (ref === "")
+        return null;
+    const [owner, repo, ...rest] = uses.slice(0, at).split("/");
+    const path = rest.join("/");
+    if (!owner || !repo || path === "")
+        return null;
+    return { path, source: { owner, repo, ref } };
+}

package/dist/verify.js

@@ -4,7 +4,7 @@
 //
 // Ground truth: workflow runs for the PR head SHA with a pull_request event,
 // and the job entries inside each run (skipped jobs included).
-import { isJobEntry, makeOctokit, predict } from "./predict.js";
+import { isJobEntry, makeOctokit, predict } from "./index.js";
 async function actualEntries(octokit, repo, prNumber) {
     const [owner, name] = repo.split("/");
     const base = { owner, repo: name };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "willfire",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "Predict the set of CI check entries GitHub Actions will create for a pull request",
   "license": "MIT",
   "packageManager": "pnpm@10.33.0",
@@ -17,16 +17,16 @@
     "prediction"
   ],
   "type": "module",
-  "main": "dist/predict.js",
-  "types": "dist/predict.d.ts",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/predict.d.ts",
-      "default": "./dist/predict.js"
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
     }
   },
   "bin": {
-    "willfire": "dist/predict.js"
+    "willfire": "dist/cli.js"
   },
   "files": [
     "dist"
@@ -36,7 +36,7 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
-    "predict": "tsx src/predict.ts",
+    "predict": "tsx src/cli.ts",
     "prepare": "pnpm build",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",