willfire 0.1.11 → 0.1.13

package/dist/predict/makeOctokit.js

@@ -0,0 +1,7 @@
+import { Octokit } from "@octokit/rest";
+export function makeOctokit() {
+    const token = process.env.GH_TOKEN ?? process.env.GITHUB_TOKEN;
+    if (!token)
+        throw new Error("GH_TOKEN or GITHUB_TOKEN must be set");
+    return new Octokit({ auth: token });
+}

package/dist/predict/predict.d.ts

@@ -0,0 +1,3 @@
+import type { Octokit } from "@octokit/rest";
+import type { Prediction, PredictOptions } from "../types.js";
+export declare function predict(octokit: Octokit, repo: string, prNumber: number, opts?: PredictOptions): Promise<Prediction>;

package/dist/predict/predict.js

@@ -0,0 +1,214 @@
+// Predict the set of CI check entries GitHub Actions will create for a PR.
+//
+// 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, and cross-repo reusable
+// workflow calls on probe PR 9; the rules they turned up are pinned in
+// src/names.test.ts.
+import { parse as parseYaml } from "yaml";
+import { jobName } from "../entries/jobName.js";
+import { makeExecutor, makeTreeProvider, runShell } from "../execute.js";
+import { expandJobs } from "../jobs/expandJobs.js";
+import { workflowDispatches } from "../triggers/workflowDispatches.js";
+import { finalizePrediction } from "./finalizePrediction.js";
+import { sourceKey } from "./sourceKey.js";
+import { stackTargetRef } from "./stackTargetRef.js";
+const SKIP_RE = /\[(skip ci|ci skip|no ci|skip actions|actions skip)\]/i;
+const SKIP_TRAILER_RE = /^skip-checks:\s*true/im;
+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 });
+    const files = await octokit.paginate(octokit.rest.pulls.listFiles, {
+        ...base,
+        pull_number: prNumber,
+        per_page: 100,
+    });
+    const stackTarget = await stackTargetRef(octokit, owner, name, pr);
+    const ctx = {
+        // 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,
+        ...(stackTarget != null ? { stackTarget } : {}),
+        files: files.map((f) => f.filename),
+    };
+    const headSha = pr.head.sha;
+    /**
+     * The PR's own repo at the head commit — where expansion starts, and already
+     * a commit id, so its `ref` and `sha` are the same string.
+     */
+    const headSource = { owner, repo: name, ref: headSha, sha: headSha };
+    // Provenance for the answer, filled as expansion reaches each source. The head
+    // is in from the start: it is read even on the skip path, where the commit
+    // message is what decides the verdict.
+    const sources = new Map([[sourceKey(headSource), headSource]]);
+    const { data: headCommit } = await octokit.rest.repos.getCommit({
+        ...base,
+        ref: headSha,
+    });
+    const headMsg = headCommit.commit.message;
+    if (SKIP_RE.test(headMsg) || SKIP_TRAILER_RE.test(headMsg)) {
+        return finalizePrediction([], "head commit message contains a skip instruction", sources);
+    }
+    // A `uses:` naming a tag is the same lookup from every caller that writes it,
+    // so resolve each `owner/repo@ref` once. Misses are cached too: a ref that
+    // cannot be resolved will not start resolving on the second ask.
+    const refCache = new Map();
+    const resolveRef = async (src) => {
+        const key = sourceKey(src);
+        const hit = refCache.get(key);
+        if (hit !== undefined)
+            return hit;
+        let sha;
+        try {
+            const { data } = await octokit.rest.repos.getCommit({
+                owner: src.owner,
+                repo: src.repo,
+                ref: src.ref,
+            });
+            sha = data.sha;
+        }
+        catch {
+            // Deleted tag, private repo, rate limit, network: all one answer here.
+            // The caller turns it into an `unknown` entry rather than throwing.
+            sha = null;
+        }
+        refCache.set(key, sha);
+        if (sha != null)
+            sources.set(key, { ...src, sha });
+        return sha;
+    };
+    // 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@sha` resolved to, misses included.
+    const cache = new Map();
+    const fetchWorkflow = async (path, src) => {
+        // Keyed and fetched on the commit, never the ref that named it. Two callers
+        // writing `@v0` and `@abc123` for the same commit are one read, and a tag
+        // that moves mid-prediction cannot hand back two different files.
+        const key = `${src.owner}/${src.repo}/${path}@${src.sha}`;
+        const hit = cache.get(key);
+        if (hit !== undefined)
+            return hit;
+        let content;
+        try {
+            const { data } = await octokit.rest.repos.getContent({
+                owner: src.owner,
+                repo: src.repo,
+                path,
+                ref: src.sha,
+                mediaType: { format: "raw" },
+            });
+            content = data;
+        }
+        catch {
+            // 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 reader = { fetchWorkflow, resolveRef };
+    // The executor exists only when the caller granted something. Trees come
+    // from the tarball endpoint at the resolved commit, and every subprocess —
+    // `tar` included — goes through the one `runShell` seam.
+    let executor;
+    if (opts.execute != null && opts.execute.length > 0) {
+        const download = async (src) => {
+            try {
+                const { data } = await octokit.rest.repos.downloadTarballArchive({
+                    owner: src.owner,
+                    repo: src.repo,
+                    ref: src.sha,
+                });
+                return new Uint8Array(data);
+            }
+            catch {
+                // Private, deleted, rate limit, network: one answer, and the entries
+                // behind it stay unresolved with the failure named.
+                return null;
+            }
+        };
+        executor = makeExecutor({
+            grants: opts.execute,
+            workspace: headSource,
+            deps: {
+                provideTree: makeTreeProvider(download, runShell),
+                runCommand: runShell,
+                resolveRef,
+            },
+        });
+    }
+    const workflows = await octokit.paginate(octokit.rest.actions.listRepoWorkflows, {
+        ...base,
+        per_page: 100,
+    });
+    // `github.repository` is fixed for everything predicted here: reusable
+    // workflows and composite actions all run in the repo the PR is against.
+    // Seeding it once makes guards like the fleet's hermetic-vs-published
+    // `github.repository ==` checks decidable everywhere, granted or not.
+    const prFacts = {
+        github: { repository: `${headSource.owner}/${headSource.repo}` },
+    };
+    const entries = [];
+    for (const w of workflows) {
+        const path = w.path;
+        if (!path.startsWith(".github/workflows/"))
+            continue;
+        if (w.state !== "active") {
+            entries.push({
+                workflow: path,
+                job: "*",
+                status: "no-dispatch",
+                reason: `workflow state: ${w.state}`,
+            });
+            continue;
+        }
+        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 —
+            // the same verdict as the disabled case above, reached a different way.
+            entries.push({
+                workflow: path,
+                job: "*",
+                status: "no-dispatch",
+                reason: "no workflow file at head",
+            });
+            continue;
+        }
+        let wf;
+        try {
+            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: "run",
+                reason: `YAML parse error: ${e}`,
+            });
+            continue;
+        }
+        const [dispatches, reason] = workflowDispatches(wf, ctx);
+        if (!dispatches) {
+            entries.push({ workflow: path, job: "*", status: "no-dispatch", reason });
+            continue;
+        }
+        for (const j of await expandJobs(wf, ctx, reader, headSource, 0, "", true, prFacts, executor)) {
+            entries.push({
+                workflow: path,
+                job: jobName(j.job),
+                checkName: j.checkName,
+                status: j.status,
+                reason: j.reason || reason,
+            });
+        }
+    }
+    return finalizePrediction(entries, null, sources);
+}

package/dist/predict/sourceKey.d.ts

@@ -0,0 +1,3 @@
+import type { SourceRef } from "../types.js";
+/** Identity of a source as written, before resolution. */
+export declare const sourceKey: (s: SourceRef) => string;

package/dist/predict/sourceKey.js

@@ -0,0 +1,2 @@
+/** Identity of a source as written, before resolution. */
+export const sourceKey = (s) => `${s.owner}/${s.repo}@${s.ref}`;

package/dist/predict/stackTargetRef.d.ts

@@ -0,0 +1,14 @@
+import type { Octokit } from "@octokit/rest";
+import type { StackNode } from "../types.js";
+/**
+ * The branch this PR's stack ultimately targets, or null for a plain PR.
+ *
+ * GitHub's stacked-PR machinery (server-side, per-repo rollout — engaged on
+ * dirsql, not on willrun-probe, so it cannot be inferred from PR structure)
+ * builds a child PR's test merge on the parent PR's test merge and evaluates
+ * `branches:` against the stack's terminal target (#30). The mode is read off
+ * `merge_commit_sha`: its first parent is the base tip in normal mode and the
+ * parent PR's own merge sha in stacked mode. Anything undecidable ends the
+ * walk at the last proven hop; never throws.
+ */
+export declare function stackTargetRef(octokit: Octokit, owner: string, repo: string, pr: StackNode): Promise<string | null>;

package/dist/predict/stackTargetRef.js

@@ -0,0 +1,58 @@
+/** Past this the walk stops at the last proven hop, which only narrows reach. */
+const MAX_STACK_DEPTH = 10;
+/**
+ * The branch this PR's stack ultimately targets, or null for a plain PR.
+ *
+ * GitHub's stacked-PR machinery (server-side, per-repo rollout — engaged on
+ * dirsql, not on willrun-probe, so it cannot be inferred from PR structure)
+ * builds a child PR's test merge on the parent PR's test merge and evaluates
+ * `branches:` against the stack's terminal target (#30). The mode is read off
+ * `merge_commit_sha`: its first parent is the base tip in normal mode and the
+ * parent PR's own merge sha in stacked mode. Anything undecidable ends the
+ * walk at the last proven hop; never throws.
+ */
+export async function stackTargetRef(octokit, owner, repo, pr) {
+    let target = null;
+    let cur = pr;
+    try {
+        for (let hop = 0; hop < MAX_STACK_DEPTH; hop++) {
+            const mergeSha = cur.merge_commit_sha;
+            if (mergeSha == null)
+                break;
+            const { data: preview } = await octokit.rest.repos.getCommit({
+                owner,
+                repo,
+                ref: mergeSha,
+            });
+            const previewParent = preview.parents[0]?.sha;
+            if (previewParent == null)
+                break;
+            const { data: baseTip } = await octokit.rest.repos.getCommit({
+                owner,
+                repo,
+                ref: cur.base.ref,
+            });
+            // Built on the base branch tip: normal mode, the walk is done.
+            if (previewParent === baseTip.sha)
+                break;
+            // Otherwise only an exact match against an open PR whose head is the
+            // base branch proves stacked mode; a stale preview matches nothing.
+            const { data: candidates } = await octokit.rest.pulls.list({
+                owner,
+                repo,
+                state: "open",
+                head: `${owner}:${cur.base.ref}`,
+                per_page: 100,
+            });
+            const parent = candidates.find((p) => p.merge_commit_sha === previewParent);
+            if (parent == null)
+                break;
+            target = parent.base.ref;
+            cur = parent;
+        }
+    }
+    catch {
+        // Rate limit, permissions, network: stop at the last proven hop.
+    }
+    return target;
+}

package/dist/triggers/getPrTrigger.d.ts

@@ -0,0 +1,3 @@
+import type { Workflow } from "../types.js";
+export declare const MISSING: unique symbol;
+export declare function getPrTrigger(wf: Workflow): Record<string, any> | typeof MISSING;

package/dist/triggers/getPrTrigger.js

@@ -0,0 +1,18 @@
+export const MISSING = Symbol("missing");
+export function getPrTrigger(wf) {
+    // YAML 1.1 parsers read `on` as boolean true; the `yaml` package (1.2)
+    // keeps it a string key. Handle both.
+    const on = wf["on"] ?? wf["true"];
+    if (on == null)
+        return MISSING;
+    if (typeof on === "string")
+        return on === "pull_request" ? {} : MISSING;
+    if (Array.isArray(on))
+        return on.includes("pull_request") ? {} : MISSING;
+    if (typeof on === "object") {
+        if ("pull_request" in on)
+            return on["pull_request"] ?? {};
+        return MISSING;
+    }
+    return MISSING;
+}

package/dist/triggers/index.d.ts

@@ -0,0 +1,2 @@
+export { getPrTrigger, MISSING } from "./getPrTrigger.js";
+export { workflowDispatches } from "./workflowDispatches.js";

package/dist/triggers/index.js

@@ -0,0 +1,2 @@
+export { getPrTrigger, MISSING } from "./getPrTrigger.js";
+export { workflowDispatches } from "./workflowDispatches.js";

package/dist/triggers/workflowDispatches.d.ts

@@ -0,0 +1,2 @@
+import type { Ctx, Workflow } from "../types.js";
+export declare function workflowDispatches(wf: Workflow, ctx: Ctx): [dispatches: boolean, reason: string];

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,8 +1,5 @@
-#!/usr/bin/env node
-import { Octokit } from "@octokit/rest";
-import { type ExecutionGrant, type JobExecutor } from "./execute.js";
-import { type Scope } from "./expr.js";
-interface EntryBase {
+import type { ExecutionGrant } from "./execute.js";
+export interface EntryBase {
     workflow: string;
     reason: string;
 }
@@ -14,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.
@@ -63,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[];
     /**
@@ -86,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.
  *
@@ -127,21 +131,49 @@ export interface PredictOptions {
 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, scope?: Scope): 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, and any job
- * outputs the caller knows. Without it a reusable workflow's guards are all
- * unknown, because every one of them is written against `inputs.*` or
- * `needs.*`.
+ * 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`.
@@ -212,31 +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.
- *
- * `scope` seeds what this workflow's own `${{ }}` resolve against — notably
- * `needs`, the outputs of jobs that have not run. Nothing here works out what
- * those are; a caller that knows hands them in, and a caller that does not
- * leaves them out and gets `unknown` where they would have been used.
- */
-export declare function expandWorkflowJobs(wf: Workflow, ctx: Ctx, reader: WorkflowReader, source: WorkflowSource, scope?: Scope, executor?: JobExecutor): 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 };