willfire 0.1.7 → 0.1.9

package/README.md

@@ -20,10 +20,19 @@ pnpm add willfire
 import { predict } from "willfire";
 import { getOctokit } from "@actions/github"; // or new Octokit({ auth: token })
 
-const { entries, checkNames, skip } = await predict(getOctokit(token), "owner/repo", 123);
+const { entries, checkNames, skip } = await predict(getOctokit(token), "owner/repo", 123, {
+  action: context.payload.action, // "opened" | "synchronize" | "reopened"
+});
 // checkNames: sorted, deduped checkName of every entry with status "run"
 ```
 
+`action` is optional but worth passing. Omitted, the event action is inferred
+from the PR's commit count, which is wrong in both directions — a PR opened
+from a branch with several commits looks like `synchronize`, a force-push down
+to one commit looks like `opened` — and can never produce `reopened`. That only
+matters to a workflow narrowing `types:`, where it decides whether the workflow
+dispatches at all.
+
 `entries` is a union of two variants, both carrying `workflow` and `reason`:
 
 | variant | `job` | `checkName` | `status` |
@@ -58,7 +67,8 @@ Auth is any token with `contents: read`, `actions: read`, and
 ## CLI
 
 ```sh
-GH_TOKEN=... willfire --repo owner/repo --pr 123 [--json]
+GH_TOKEN=... willfire --repo owner/repo --pr 123 \
+  [--action opened|synchronize|reopened] [--json]
 ```
 
 ## What it handles
@@ -124,7 +134,10 @@ the docs do not state:
 
 Scope notes: validated on `opened` pull_request events; `synchronize`/`labeled`
 live events, `branches-ignore`, and diffs far beyond 301 files are not yet
-probe-verified. Reusable-workflow name prefixing is probe-verified to three
+probe-verified — passing `action` explicitly is what makes probing the other
+two possible. `action` accepts the three default `types:` only; `pull_request`
+fires on around twenty actions, and a workflow narrowing to `ready_for_review`
+or `edited` is out of scope either way. Reusable-workflow name prefixing is probe-verified to three
 levels; deeper nesting is inferred. The cross-repo probe calls back into the
 probe repo itself by full `owner/repo@ref` reference, so it pins ref
 resolution but not the owner/repo half of the address.

package/dist/predict.d.ts

@@ -41,6 +41,11 @@ export interface WorkflowEntry extends EntryBase {
  * These can be genuinely undecidable statically — dynamic matrix, a reusable
  * workflow we cannot read, unresolvable `if`, or `needs` on any of those — so
  * `"unknown"` lives here and only here.
+ *
+ * `"no-dispatch"` is the mirror image, and lives on {@link WorkflowEntry} and
+ * only there. It is a verdict about whether the run happens at all, which is
+ * settled before any job is looked at — so by the time there is a job entry to
+ * label, the answer is already yes.
  */
 export interface JobEntry extends EntryBase {
     job: JobName;
@@ -54,7 +59,7 @@ export interface JobEntry extends EntryBase {
      * interpolates something we cannot evaluate ahead of the run.
      */
     checkName: string | null;
-    status: "run" | "skipped" | "unknown" | "no-dispatch";
+    status: "run" | "skipped" | "unknown";
 }
 export type Entry = WorkflowEntry | JobEntry;
 /** Narrow to the workflow-level variant without inspecting the sentinel. */
@@ -74,6 +79,30 @@ export interface Prediction {
 export declare function patternToRegex(pat: string): RegExp;
 /** Order-sensitive match: last matching pattern wins; ! negates. */
 export declare function matchFilters(value: string, patterns: string[]): boolean;
+/**
+ * The `pull_request` actions a caller can name.
+ *
+ * Deliberately the three default types and no more. `pull_request` fires on
+ * around twenty actions — `ready_for_review`, `edited`, `labeled` — and a
+ * workflow that narrows `types:` to one of those is not predictable today
+ * regardless of what is passed here. Widening this union later is a
+ * non-breaking change; narrowing it would not be, so it starts narrow.
+ */
+export type PrEventAction = "opened" | "synchronize" | "reopened";
+/** Options every caller may omit. */
+export interface PredictOptions {
+    /**
+     * The literal event action the run was triggered by — `github.event.action`
+     * inside an Action, or `--action` on the CLI.
+     *
+     * Omitting it falls back to inferring from the commit count, which is a
+     * guess and is wrong in both directions: a PR opened from a branch with
+     * several commits looks like `synchronize`, a force-push down to one commit
+     * looks like `opened`, and `reopened` is never produced. That only matters
+     * to a workflow narrowing `types:`, where it matters completely.
+     */
+    action?: PrEventAction;
+}
 export interface Ctx {
     action: string;
     baseRef: string;
@@ -148,5 +177,5 @@ export declare function parseUses(uses: string): UsesTarget | null;
  */
 export declare function expandWorkflowJobs(wf: Workflow, ctx: Ctx, fetchWorkflow: FetchWorkflow, source: WorkflowSource): Promise<ExpandedJob[]>;
 export declare function makeOctokit(): Octokit;
-export declare function predict(octokit: Octokit, repo: string, prNumber: number): Promise<Prediction>;
+export declare function predict(octokit: Octokit, repo: string, prNumber: number, opts?: PredictOptions): Promise<Prediction>;
 export {};

package/dist/predict.js

@@ -171,7 +171,10 @@ function expandMatrixDetailed(strategy) {
         }
     }
     combos.push(...extra);
-    return combos.length > 0 ? combos : [null];
+    // Zero combinations is a real answer, not a missing one: an empty axis, or an
+    // `exclude` that removes everything, schedules no jobs at all. Only an absent
+    // `matrix:` key means "one unsuffixed job", and that returned above.
+    return combos;
 }
 /** Return list of matrix combination dicts, or null if dynamic. */
 export function expandMatrix(strategy) {
@@ -532,7 +535,7 @@ export function makeOctokit() {
         throw new Error("GH_TOKEN or GITHUB_TOKEN must be set");
     return new Octokit({ auth: token });
 }
-export async function predict(octokit, repo, prNumber) {
+export async function predict(octokit, repo, prNumber, opts = {}) {
     const [owner, name] = repo.split("/");
     const base = { owner, repo: name };
     const { data: pr } = await octokit.rest.pulls.get({ ...base, pull_number: prNumber });
@@ -542,7 +545,9 @@ export async function predict(octokit, repo, prNumber) {
         per_page: 100,
     });
     const ctx = {
-        action: pr.commits > 1 ? "synchronize" : "opened",
+        // The caller's answer wins whenever it has one. The commit-count fallback
+        // is a guess kept only so existing callers keep working.
+        action: opts.action ?? (pr.commits > 1 ? "synchronize" : "opened"),
         baseRef: pr.base.ref,
         files: files.map((f) => f.filename),
     };
@@ -659,6 +664,8 @@ function finalizePrediction(entries, skip) {
     return { entries: final, checkNames: [...names].sort(), skip };
 }
 // ------------------------------------------------------------------------ CLI
+const USAGE = "usage: predict --repo owner/name --pr N [--action opened|synchronize|reopened] [--json]";
+const isPrEventAction = (v) => v === "opened" || v === "synchronize" || v === "reopened";
 function parseArgs(argv) {
     const get = (flag) => {
         const i = argv.indexOf(flag);
@@ -667,15 +674,26 @@ function parseArgs(argv) {
     const repo = get("--repo");
     const pr = get("--pr");
     if (!repo || !pr) {
-        console.error("usage: predict --repo owner/name --pr N [--json]");
+        console.error(USAGE);
         process.exit(2);
     }
-    return { repo, pr: Number(pr), json: argv.includes("--json") };
+    // An unrecognised action is refused rather than ignored. Silently falling
+    // back to the guess would turn a typo into a wrong prediction, which is the
+    // failure this flag exists to remove.
+    const action = get("--action");
+    if (action !== undefined && !isPrEventAction(action)) {
+        console.error(`unknown --action: ${action}`);
+        console.error(USAGE);
+        process.exit(2);
+    }
+    return { repo, pr: Number(pr), json: argv.includes("--json"), action };
 }
 const isMain = /predict\.(ts|js)$|\/willfire$/.test(process.argv[1] ?? "");
 if (isMain) {
     const args = parseArgs(process.argv.slice(2));
-    const { entries, checkNames, skip } = await predict(makeOctokit(), args.repo, args.pr);
+    const { entries, checkNames, skip } = await predict(makeOctokit(), args.repo, args.pr, {
+        action: args.action,
+    });
     if (args.json) {
         console.log(JSON.stringify({ entries, checkNames, skip }, null, 2));
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "willfire",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Predict the set of CI check entries GitHub Actions will create for a pull request",
   "license": "MIT",
   "packageManager": "pnpm@10.33.0",