willfire 0.1.1 → 0.1.3

package/README.md

@@ -21,9 +21,19 @@ import { predict } from "willfire";
 import { getOctokit } from "@actions/github"; // or new Octokit({ auth: token })
 
 const { entries, skip } = await predict(getOctokit(token), "owner/repo", 123);
-// entries: [{ workflow, job, status: "run" | "skipped" | "unknown" | "no-dispatch", reason }]
 ```
 
+`entries` is a union of two variants, both carrying `workflow` and `reason`:
+
+| variant | `job` | `status` |
+| --- | --- | --- |
+| `WorkflowEntry` | `"*"` | `"run" \| "skipped" \| "no-dispatch"` |
+| `JobEntry` | the job's display name | `"run" \| "skipped" \| "unknown" \| "no-dispatch"` |
+
+`"unknown"` is job-level only: every workflow-level verdict is decidable, so a
+`WorkflowEntry` cannot express one. Narrow with the exported `isWorkflowEntry`
+and `isJobEntry` guards rather than testing the `"*"` sentinel yourself.
+
 Auth is any token with `contents: read`, `actions: read`, and
 `pull-requests: read` — inside an action, the workflow's `GITHUB_TOKEN`.
 

package/dist/predict.d.ts

@@ -1,11 +1,53 @@
 #!/usr/bin/env node
 import { Octokit } from "@octokit/rest";
-export interface Entry {
+interface EntryBase {
     workflow: string;
-    job: string;
-    status: "run" | "skipped" | "unknown" | "no-dispatch";
     reason: string;
 }
+/**
+ * A job's display name, e.g. `test (18)`.
+ *
+ * Nominally distinct from `string` for one reason: `Entry` is a closed union
+ * and `"*"` is the workflow-level sentinel, so a plain `string` here would
+ * 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.
+ */
+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.
+ *
+ * There is no `"unknown"` here, and that is the point. Every workflow-level
+ * verdict is decidable, and this type is what enforces it — the previous
+ * single-interface shape let `{ job: "*", status: "unknown" }` typecheck, which
+ * is what shipped and what pr-monitor#17 had to grow a `tolerated` bucket for.
+ */
+export interface WorkflowEntry extends EntryBase {
+    job: "*";
+    status: "run" | "skipped" | "no-dispatch";
+}
+/**
+ * A verdict about one job entry inside a workflow that does dispatch.
+ *
+ * These can be genuinely undecidable statically — dynamic matrix, non-local
+ * reusable workflow, unresolvable `if`, or `needs` on any of those — so
+ * `"unknown"` lives here and only here.
+ */
+export interface JobEntry extends EntryBase {
+    job: JobName;
+    status: "run" | "skipped" | "unknown" | "no-dispatch";
+}
+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[];
     skip: string | null;

package/dist/predict.js

@@ -9,6 +9,12 @@
 // live dispatches on thekevinbot/willrun-probe (PRs 1-7).
 import { Octokit } from "@octokit/rest";
 import { parse as parseYaml } from "yaml";
+/** 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. */
+export const isWorkflowEntry = (e) => e.job === "*";
+/** Narrow to the job-level variant without inspecting the sentinel. */
+export const isJobEntry = (e) => e.job !== "*";
 // ------------------------------------------------- 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.
@@ -77,33 +83,40 @@ function getPrTrigger(wf) {
     }
     return MISSING;
 }
+// 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, non-local reusable
+// workflow, unresolvable `if`), and that is a per-entry status.
 function workflowDispatches(wf, ctx) {
     const trig = getPrTrigger(wf);
     if (trig === MISSING)
-        return ["no-dispatch", "no pull_request trigger"];
+        return [false, "no pull_request trigger"];
     const types = trig["types"] ?? DEFAULT_TYPES;
     if (!types.includes(ctx.action)) {
-        return ["no-dispatch", `action '${ctx.action}' not in types [${types}]`];
+        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 ["unknown", "both branches and branches-ignore set"];
+        return [true, "both branches and branches-ignore set: startup failure"];
     }
     if ("branches" in trig && !matchFilters(ctx.baseRef, trig["branches"])) {
-        return ["no-dispatch", `base branch '${ctx.baseRef}' not in branches`];
+        return [false, `base branch '${ctx.baseRef}' not in branches`];
     }
     if ("branches-ignore" in trig && matchFilters(ctx.baseRef, trig["branches-ignore"])) {
-        return ["no-dispatch", "base branch in branches-ignore"];
+        return [false, "base branch in branches-ignore"];
     }
     if ("paths" in trig && "paths-ignore" in trig) {
-        return ["unknown", "both paths and paths-ignore set"];
+        return [true, "both paths and paths-ignore set: startup failure"];
     }
     if ("paths" in trig && !ctx.files.some((f) => matchFilters(f, trig["paths"]))) {
-        return ["no-dispatch", "no changed file matches paths"];
+        return [false, "no changed file matches paths"];
     }
     if ("paths-ignore" in trig && ctx.files.every((f) => matchFilters(f, trig["paths-ignore"]))) {
-        return ["no-dispatch", "all changed files match paths-ignore"];
+        return [false, "all changed files match paths-ignore"];
     }
-    return ["dispatch", "trigger matched"];
+    return [true, "trigger matched"];
 }
 /** Return list of matrix combination dicts, or null if dynamic. */
 export function expandMatrix(strategy) {
@@ -308,11 +321,14 @@ export async function predict(octokit, repo, prNumber) {
         }
         const content = await fetchFile(path);
         if (content == null) {
+            // The Actions API keeps listing a workflow as `active` after its file is
+            // deleted. There is no file at head, so there is nothing to dispatch —
+            // the same verdict as the disabled case above, reached a different way.
             entries.push({
                 workflow: path,
                 job: "*",
-                status: "unknown",
-                reason: "cannot fetch workflow file at head",
+                status: "no-dispatch",
+                reason: "no workflow file at head",
             });
             continue;
         }
@@ -321,21 +337,24 @@ export async function predict(octokit, repo, prNumber) {
             wf = parseYaml(content);
         }
         catch (e) {
+            // GitHub creates a run for an unparseable workflow file and concludes it
+            // `startup_failure`. The run exists but has no jobs, so this is a
+            // workflow-level "it dispatches" with nothing to expand.
             entries.push({
                 workflow: path,
                 job: "*",
-                status: "unknown",
+                status: "run",
                 reason: `YAML parse error: ${e}`,
             });
             continue;
         }
-        const [verdict, reason] = workflowDispatches(wf, ctx);
-        if (verdict !== "dispatch") {
-            entries.push({ workflow: path, job: "*", status: verdict, reason });
+        const [dispatches, reason] = workflowDispatches(wf, ctx);
+        if (!dispatches) {
+            entries.push({ workflow: path, job: "*", status: "no-dispatch", reason });
             continue;
         }
-        for (const [jobName, status, jreason] of await expandJobs(wf, ctx, fetchFile)) {
-            entries.push({ workflow: path, job: jobName, status, reason: jreason || reason });
+        for (const [name, status, jreason] of await expandJobs(wf, ctx, fetchFile)) {
+            entries.push({ workflow: path, job: jobName(name), status, reason: jreason || reason });
         }
     }
     return { entries, skip: null };
@@ -366,7 +385,7 @@ if (isMain) {
     }
     else {
         for (const e of entries) {
-            if (e.job === "*")
+            if (isWorkflowEntry(e))
                 console.log(`# ${e.workflow} :: ${e.status} (${e.reason})`);
             else
                 console.log(`${e.workflow} :: ${e.job} :: ${e.status}`);

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 { makeOctokit, predict } from "./predict.js";
+import { isJobEntry, makeOctokit, predict } from "./predict.js";
 async function actualEntries(octokit, repo, prNumber) {
     const [owner, name] = repo.split("/");
     const base = { owner, repo: name };
@@ -44,9 +44,7 @@ if (!repo || !prArg) {
 const pr = Number(prArg);
 const octokit = makeOctokit();
 const { entries: predictedRaw } = await predict(octokit, repo, pr);
-const predicted = new Map(predictedRaw
-    .filter((r) => r.job !== "*")
-    .map((r) => [`${r.workflow} :: ${r.job}`, r.status]));
+const predicted = new Map(predictedRaw.filter(isJobEntry).map((r) => [`${r.workflow} :: ${r.job}`, r.status]));
 const unknownWfs = new Set(predictedRaw.filter((r) => r.status === "unknown").map((r) => r.workflow));
 const { entries: actual, incomplete } = await actualEntries(octokit, repo, pr);
 if (incomplete.length > 0) {
@@ -82,10 +80,5 @@ for (const key of keys) {
         console.log(`DIFF  ${key} :: predicted ${p}, actual ${a}`);
     }
 }
-for (const r of predictedRaw) {
-    if (r.job === "*" && r.status === "unknown") {
-        console.log(`  ?   ${r.workflow} :: workflow-level unknown: ${r.reason}`);
-    }
-}
 console.log(ok ? "PASS" : "FAIL");
 process.exit(ok ? 0 : 1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "willfire",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Predict the set of CI check entries GitHub Actions will create for a pull request",
   "license": "MIT",
   "author": "Kevin Scott <me@thekevinscott.com>",