willfire 0.1.2 → 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.
@@ -347,8 +353,8 @@ export async function predict(octokit, repo, prNumber) {
             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 };
@@ -379,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.2",
+  "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>",