willfire 0.1.4 → 0.1.6

package/README.md

@@ -43,7 +43,9 @@ single name is knowable ahead of the run:
 
 - a matrix computed at runtime (`fromJSON` of another job's output), reported
   as one `unknown` entry for that job and nothing else;
-- a non-local reusable workflow, whose callee jobs we do not fetch;
+- a reusable workflow we cannot read — private, deleted, a ref that does not
+  exist, a `uses:` built from an expression, or one nested past GitHub's
+  four-level limit;
 - a `name:` interpolating something we cannot evaluate statically.
 
 Duplicate names in `checkNames` are not possible (it is a set), but duplicate
@@ -64,26 +66,44 @@ GH_TOKEN=... willfire --repo owner/repo --pr 123 [--json]
 Path filters (`paths`, `paths-ignore`, order-sensitive `!` negation), branch
 filters, event `types`, combined filters, `[skip ci]` and friends, disabled
 workflows, multi-job workflows, static matrix expansion (including
-`exclude`/`include`), `needs` skip-propagation, job-level `if`, and local
-reusable workflows. Jobs whose `if` is false are predicted as `skipped`
-entries, matching how they appear in the checks UI.
+`exclude`/`include`), `needs` skip-propagation, job-level `if`, and reusable
+workflows — both the local `./.github/workflows/x.yml` form and the cross-repo
+`owner/repo/.github/workflows/x.yml@ref` form, whose callee is fetched from its
+own repo at the pinned tag, branch, or SHA. Jobs whose `if` is false are
+predicted as `skipped` entries, matching how they appear in the checks UI.
 
 Things that cannot be known statically — e.g. a matrix computed at runtime
 from another job's output — are reported as `unknown` rather than guessed.
 
+## Development
+
+```sh
+pnpm install
+pnpm typecheck        # tsc over src/, tests included
+pnpm test             # vitest, once
+pnpm test:coverage    # the 100% floor CI enforces
+```
+
+Unit tests are colocated with their source (`foo.ts` ↔ `foo.test.ts`) at 100%
+coverage, per the
+[testing-conventions](https://github.com/thekevinscott/testing-conventions)
+standard. `.github/workflows/conventions.yml` enforces that in CI;
+`testing-conventions.toml` holds the thresholds.
+
 ## Verification
 
-Predictions are verified against real GitHub behavior, not just the docs:
+The unit suite fixes the behavior. What fixes the *expectations* is the probe:
+predictions are verified against real GitHub behavior, not just the docs.
 [willrun-probe](https://github.com/thekevinbot/willrun-probe) holds one
 workflow per dispatch rule, and probe PRs exercise each complication
 (docs-only diffs, negation edges, `[skip ci]`, a 301-file diff, PRs into
 non-default branches). The `verify` script diffs predictions against the
 check entries GitHub actually created. All probe PRs currently pass exactly.
 
-Check-name resolution is verified the same way, on probe PR #8. `pnpm test`
-replays those probe workflows through the resolver and asserts the exact job
-names the live run produced. Several of the rules it pins are ones the docs do
-not state:
+Check-name resolution is verified the same way, on probe PRs #8 and #9.
+`pnpm test` replays those probe workflows through the resolver and asserts the
+exact job names the live run produced. Several of the rules it pins are ones
+the docs do not state:
 
 - a `name:` containing *any* `${{ }}` expression suppresses the matrix
   parenthetical, even an expression that never reads the matrix — a literal
@@ -94,9 +114,17 @@ not state:
 - object matrix values flatten to their own values, so `{os: linux, arch: x64}`
   renders as `(linux, x64)`;
 - a skipped job is never set up, so its matrix does not expand and its `name:`
-  is not interpolated: one check, expression text and all.
+  is not interpolated: one check, expression text and all;
+- a cross-repo `uses:` names the same `<caller> / <callee>` checks a local one
+  does, at whichever tag, branch, or SHA the `@ref` pinned — and a relative
+  `uses: ./...` *inside* that callee resolves against the callee's repo and
+  ref, not the caller's. Probe PR #9 settles the second one: the caller's copy
+  of the callee's file was present at head, under a different job name, and
+  GitHub did not use it.
 
 Scope notes: validated on `opened` pull_request events; `synchronize`/`labeled`
-live events, cross-repo reusable workflows, `branches-ignore`, and diffs far
-beyond 301 files are not yet probe-verified. Reusable-workflow name prefixing
-is probe-verified to three levels; deeper nesting is inferred.
+live events, `branches-ignore`, and diffs far beyond 301 files are not yet
+probe-verified. 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

@@ -37,8 +37,8 @@ export interface WorkflowEntry extends EntryBase {
 /**
  * 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
+ * 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.
  */
 export interface JobEntry extends EntryBase {
@@ -49,8 +49,8 @@ export interface JobEntry extends EntryBase {
      * `<caller> / <callee>` prefixing for reusable workflows.
      *
      * null when there is no single statically-knowable name: a matrix computed
-     * at runtime, a non-local reusable workflow, or a `name:` that interpolates
-     * something we cannot evaluate ahead of the run.
+     * at runtime, a reusable workflow we could not fetch, or a `name:` that
+     * interpolates something we cannot evaluate ahead of the run.
      */
     checkName: string | null;
     status: "run" | "skipped" | "unknown" | "no-dispatch";
@@ -96,12 +96,50 @@ export interface ExpandedJob {
     status: "run" | "skipped" | "unknown";
     reason: string;
 }
+/**
+ * Which repo and ref a workflow file is read from.
+ *
+ * Expansion carries one of these rather than a bare path because `uses:` can
+ * cross repositories. A local `uses: ./...` keeps the current source, so a
+ * relative call inside a workflow that was itself reached by
+ * `owner/repo/path@ref` resolves against *that* repo at *that* ref — probe
+ * verified, see `src/names.test.ts`.
+ */
+export interface WorkflowSource {
+    owner: string;
+    repo: string;
+    /** Tag, branch, or SHA — whatever `@` was pinned to. */
+    ref: 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>;
+/** 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;
+}
+/**
+ * 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, fetchFile: (path: string) => Promise<string | null>): Promise<ExpandedJob[]>;
+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 {};

package/dist/predict.js

@@ -7,8 +7,9 @@
 //
 // Faithful port of predict.py, which was verified entry-for-entry against
 // live dispatches on thekevinbot/willrun-probe (PRs 1-7). Check-name
-// resolution was verified the same way on probe PR 8; the rules it turned up
-// are pinned in src/names.test.ts.
+// resolution was verified the same way on probe PR 8, and cross-repo reusable
+// workflow calls on probe PR 9; the rules they turned up are pinned in
+// src/names.test.ts.
 import { Octokit } from "@octokit/rest";
 import { parse as parseYaml } from "yaml";
 /** Tag a job display name. Rejects the workflow-level sentinel. */
@@ -91,8 +92,8 @@ function getPrTrigger(wf) {
 }
 // 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.
+// expansion can be genuinely undecidable (dynamic matrix, an unreadable
+// reusable workflow, unresolvable `if`), and that is a per-entry status.
 function workflowDispatches(wf, ctx) {
     const trig = getPrTrigger(wf);
     if (trig === MISSING)
@@ -293,9 +294,44 @@ export function evalIf(cond) {
  * GitHub allows a reusable-workflow call chain four levels deep. Past that the
  * run itself fails, so anything deeper is not a name we could predict anyway.
  * Probe-verified to three levels: `call-nested / Mid Call / inner`.
+ *
+ * A cross-repo hop costs the same one level as a local one, so a chain that
+ * mixes the two is counted the same way.
  */
 const MAX_REUSABLE_DEPTH = 4;
-async function expandJobs(wf, ctx, fetchFile, depth = 0, prefix = "", prefixResolved = true) {
+/**
+ * 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 } };
+}
+async function expandJobs(wf, ctx, fetchWorkflow, source, depth = 0, prefix = "", prefixResolved = true) {
     const entries = [];
     const jobs = wf.jobs ?? {};
     const statuses = {};
@@ -337,7 +373,9 @@ async function expandJobs(wf, ctx, fetchFile, depth = 0, prefix = "", prefixReso
         if ("uses" in job) {
             // Reusable workflow call. The calling job produces no check of its own;
             // each called job becomes `<calling job name> / <called job name>`, and
-            // a matrix on the *caller* multiplies the whole callee set.
+            // a matrix on the *caller* multiplies the whole callee set. A cross-repo
+            // call names its checks exactly the same way a local one does — probe
+            // PR #9, `call-remote-tag / r-inner` alongside `call-plain / inner`.
             const uses = job.uses;
             if (combos == null) {
                 entries.push({
@@ -351,15 +389,19 @@ async function expandJobs(wf, ctx, fetchFile, depth = 0, prefix = "", prefixReso
             // Resolve the called workflow once, not once per matrix combination.
             let subWf = null;
             let failure = null;
-            const m = uses.match(/^\.\/(.+)$/);
+            // Where the callee's own `./` calls will resolve. A remote `uses:` moves
+            // this to the callee's repo and pinned ref; a local one leaves it alone.
+            let subSource = source;
+            const target = parseUses(uses);
             if (depth + 1 > MAX_REUSABLE_DEPTH) {
                 failure = `reusable workflow nested deeper than ${MAX_REUSABLE_DEPTH} levels`;
             }
-            else if (!m) {
-                failure = `non-local reusable: ${uses}`;
+            else if (target == null) {
+                failure = `unresolvable reusable reference: ${uses}`;
             }
             else {
-                const content = await fetchFile(m[1]);
+                subSource = target.source ?? source;
+                const content = await fetchWorkflow(target.path, subSource);
                 if (content == null) {
                     failure = `cannot fetch ${uses}`;
                 }
@@ -385,7 +427,7 @@ async function expandJobs(wf, ctx, fetchFile, depth = 0, prefix = "", prefixReso
                     });
                     continue;
                 }
-                entries.push(...(await expandJobs(subWf, ctx, fetchFile, depth + 1, `${baseName} / `, nameResolved)));
+                entries.push(...(await expandJobs(subWf, ctx, fetchWorkflow, subSource, depth + 1, `${baseName} / `, nameResolved)));
             }
             continue;
         }
@@ -416,8 +458,8 @@ async function expandJobs(wf, ctx, fetchFile, depth = 0, prefix = "", prefixReso
  * names can be tested against recorded GitHub behaviour without a network
  * round-trip; `predict` is the API you want.
  */
-export function expandWorkflowJobs(wf, ctx, fetchFile) {
-    return expandJobs(wf, ctx, fetchFile);
+export function expandWorkflowJobs(wf, ctx, fetchWorkflow, source) {
+    return expandJobs(wf, ctx, fetchWorkflow, source);
 }
 // ------------------------------------------------------------------- pipeline
 export function makeOctokit() {
@@ -449,19 +491,35 @@ export async function predict(octokit, repo, prNumber) {
     if (SKIP_RE.test(headMsg) || SKIP_TRAILER_RE.test(headMsg)) {
         return finalizePrediction([], "head commit message contains a skip instruction");
     }
-    const fetchFile = async (path) => {
+    /** The PR's own repo at the head commit — where expansion starts. */
+    const headSource = { owner, repo: name, ref: headSha };
+    // One callee is commonly reached from several callers — a fleet repo calls
+    // the same `testing-conventions@v0` from eight workflows — so remember what
+    // each `owner/repo/path@ref` resolved to, misses included.
+    const cache = new Map();
+    const fetchWorkflow = async (path, src) => {
+        const key = `${src.owner}/${src.repo}/${path}@${src.ref}`;
+        const hit = cache.get(key);
+        if (hit !== undefined)
+            return hit;
+        let content;
         try {
             const { data } = await octokit.rest.repos.getContent({
-                ...base,
+                owner: src.owner,
+                repo: src.repo,
                 path,
-                ref: headSha,
+                ref: src.ref,
                 mediaType: { format: "raw" },
             });
-            return data;
+            content = data;
         }
         catch {
-            return null;
+            // Private, deleted, bad ref, rate limit, network: all one answer here.
+            // The caller turns it into an `unknown` entry rather than throwing.
+            content = null;
         }
+        cache.set(key, content);
+        return content;
     };
     const workflows = await octokit.paginate(octokit.rest.actions.listRepoWorkflows, {
         ...base,
@@ -481,7 +539,7 @@ export async function predict(octokit, repo, prNumber) {
             });
             continue;
         }
-        const content = await fetchFile(path);
+        const content = await fetchWorkflow(path, headSource);
         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 —
@@ -515,7 +573,7 @@ export async function predict(octokit, repo, prNumber) {
             entries.push({ workflow: path, job: "*", status: "no-dispatch", reason });
             continue;
         }
-        for (const j of await expandJobs(wf, ctx, fetchFile)) {
+        for (const j of await expandJobs(wf, ctx, fetchWorkflow, headSource)) {
             entries.push({
                 workflow: path,
                 job: jobName(j.job),

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "willfire",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Predict the set of CI check entries GitHub Actions will create for a pull request",
   "license": "MIT",
+  "packageManager": "pnpm@10.33.0",
   "author": "Kevin Scott <me@thekevinscott.com>",
   "repository": {
     "type": "git",
@@ -35,10 +36,11 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
-    "prepublishOnly": "pnpm build",
-    "typecheck": "tsc -p tsconfig.json",
-    "test": "node --import tsx --test src/*.test.ts",
     "predict": "tsx src/predict.ts",
+    "prepare": "pnpm build",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc -p tsconfig.json",
     "verify": "tsx src/verify.ts"
   },
   "dependencies": {
@@ -47,7 +49,10 @@
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^4.1.10",
+    "testing-conventions": "^0.0.91",
     "tsx": "^4.19.0",
-    "typescript": "^5.6.0"
+    "typescript": "^5.6.0",
+    "vitest": "^4.1.10"
   }
 }