willfire 0.1.11 → 0.1.12

package/dist/cli/index.d.ts

@@ -0,0 +1 @@
+export { parseArgs } from "./parseArgs.js";

package/dist/cli/index.js

@@ -0,0 +1 @@
+export { parseArgs } from "./parseArgs.js";

package/dist/cli/parseArgs.d.ts

@@ -0,0 +1,9 @@
+import { type ExecutionGrant } from "../execute.js";
+import type { PrEventAction } from "../types.js";
+export declare function parseArgs(argv: string[]): {
+    repo: string;
+    pr: number;
+    json: boolean;
+    action?: PrEventAction;
+    execute: ExecutionGrant[];
+};

package/dist/cli/parseArgs.js

@@ -0,0 +1,42 @@
+import { parseGrant } from "../execute.js";
+const USAGE = "usage: predict --repo owner/name --pr N [--action opened|synchronize|reopened]" +
+    " [--execute owner/repo:job1,job2]... [--json]";
+const isPrEventAction = (v) => v === "opened" || v === "synchronize" || v === "reopened";
+export function parseArgs(argv) {
+    const get = (flag) => {
+        const i = argv.indexOf(flag);
+        return i >= 0 ? argv[i + 1] : undefined;
+    };
+    const repo = get("--repo");
+    const pr = get("--pr");
+    if (!repo || !pr) {
+        console.error(USAGE);
+        process.exit(2);
+    }
+    // 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);
+    }
+    // Repeatable, one grant per flag. A malformed grant is refused for the same
+    // reason a bad --action is: silently dropping it would predict without the
+    // execution the caller thought they asked for.
+    const execute = [];
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] !== "--execute")
+            continue;
+        const spec = argv[i + 1];
+        const grant = spec == null ? null : parseGrant(spec);
+        if (grant == null) {
+            console.error(`bad --execute: ${spec}`);
+            console.error(USAGE);
+            process.exit(2);
+        }
+        execute.push(grant);
+    }
+    return { repo, pr: Number(pr), json: argv.includes("--json"), action, execute };
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+// Usage: pnpm predict --repo owner/name --pr N [--json]
+//
+// Auth: GH_TOKEN or GITHUB_TOKEN env var (any token with
+// contents/actions/pull-requests read). Inside an action, pass the workflow's
+// GITHUB_TOKEN.
+import { parseArgs } from "./cli/parseArgs.js";
+import { isWorkflowEntry } from "./entries/isWorkflowEntry.js";
+import { makeOctokit } from "./predict/makeOctokit.js";
+import { predict } from "./predict/predict.js";
+const isMain = /cli\.(ts|js)$|\/willfire$/.test(process.argv[1] ?? "");
+if (isMain) {
+    const args = parseArgs(process.argv.slice(2));
+    const prediction = await predict(makeOctokit(), args.repo, args.pr, {
+        action: args.action,
+        execute: args.execute,
+    });
+    const { entries, skip, sources } = prediction;
+    if (args.json) {
+        console.log(JSON.stringify(prediction, null, 2));
+    }
+    else {
+        if (skip) {
+            console.log(`# ${skip} -> nothing dispatches`);
+        }
+        else {
+            for (const e of entries) {
+                if (isWorkflowEntry(e))
+                    console.log(`# ${e.workflow} :: ${e.status} (${e.reason})`);
+                else {
+                    const name = e.checkName ?? `${e.job} (name unresolved)`;
+                    console.log(`${e.workflow} :: ${name} :: ${e.status}`);
+                }
+            }
+        }
+        // Last, and on the skip path too, so a red gate's first question — which
+        // commits was this read from? — is answered wherever the reader lands.
+        for (const s of sources)
+            console.log(`# read ${s.owner}/${s.repo}@${s.ref} -> ${s.sha}`);
+    }
+}

package/dist/entries/index.d.ts

@@ -0,0 +1,3 @@
+export { jobName } from "./jobName.js";
+export { isWorkflowEntry } from "./isWorkflowEntry.js";
+export { isJobEntry } from "./isJobEntry.js";

package/dist/entries/index.js

@@ -0,0 +1,3 @@
+export { jobName } from "./jobName.js";
+export { isWorkflowEntry } from "./isWorkflowEntry.js";
+export { isJobEntry } from "./isJobEntry.js";

package/dist/entries/isJobEntry.d.ts

@@ -0,0 +1,3 @@
+import type { Entry, JobEntry } from "../types.js";
+/** Narrow to the job-level variant without inspecting the sentinel. */
+export declare const isJobEntry: (e: Entry) => e is JobEntry;

package/dist/entries/isJobEntry.js

@@ -0,0 +1,2 @@
+/** Narrow to the job-level variant without inspecting the sentinel. */
+export const isJobEntry = (e) => e.job !== "*";

package/dist/entries/isWorkflowEntry.d.ts

@@ -0,0 +1,3 @@
+import type { Entry, WorkflowEntry } from "../types.js";
+/** Narrow to the workflow-level variant without inspecting the sentinel. */
+export declare const isWorkflowEntry: (e: Entry) => e is WorkflowEntry;

package/dist/entries/isWorkflowEntry.js

@@ -0,0 +1,2 @@
+/** Narrow to the workflow-level variant without inspecting the sentinel. */
+export const isWorkflowEntry = (e) => e.job === "*";

package/dist/entries/jobName.d.ts

@@ -0,0 +1,3 @@
+import type { JobName } from "../types.js";
+/** Tag a job display name. Rejects the workflow-level sentinel. */
+export declare const jobName: <S extends string>(name: S extends "*" ? never : S) => JobName;

package/dist/entries/jobName.js

@@ -0,0 +1,2 @@
+/** Tag a job display name. Rejects the workflow-level sentinel. */
+export const jobName = (name) => name;

package/dist/execute.d.ts

@@ -30,7 +30,7 @@
  * recorded as done; a checkout *with inputs* is not modelled and stops.
  */
 import { type Scope } from "./expr.js";
-import type { ResolveRef, WorkflowSource } from "./predict.js";
+import type { ResolveRef, WorkflowSource } from "./types.js";
 /**
  * Permission to execute named jobs from one repo's workflows.
  *

package/dist/filters/index.d.ts

@@ -0,0 +1,2 @@
+export { patternToRegex } from "./patternToRegex.js";
+export { matchFilters } from "./matchFilters.js";

package/dist/filters/index.js

@@ -0,0 +1,2 @@
+export { patternToRegex } from "./patternToRegex.js";
+export { matchFilters } from "./matchFilters.js";

package/dist/filters/matchFilters.d.ts

@@ -0,0 +1,2 @@
+/** Order-sensitive match: last matching pattern wins; ! negates. */
+export declare function matchFilters(value: string, patterns: string[]): boolean;

package/dist/filters/matchFilters.js

@@ -0,0 +1,12 @@
+import { patternToRegex } from "./patternToRegex.js";
+/** Order-sensitive match: last matching pattern wins; ! negates. */
+export function matchFilters(value, patterns) {
+    let matched = false;
+    for (const pat of patterns) {
+        const neg = pat.startsWith("!");
+        const p = neg ? pat.slice(1) : pat;
+        if (patternToRegex(p).test(value))
+            matched = !neg;
+    }
+    return matched;
+}

package/dist/filters/patternToRegex.d.ts

@@ -0,0 +1 @@
+export declare function patternToRegex(pat: string): RegExp;

package/dist/filters/patternToRegex.js

@@ -0,0 +1,35 @@
+// 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.
+const escapeRegex = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+export function patternToRegex(pat) {
+    let out = "";
+    for (let i = 0; i < pat.length; i++) {
+        const c = pat[i];
+        if (c === "*") {
+            if (pat[i + 1] === "*") {
+                out += ".*";
+                i++;
+            }
+            else {
+                out += "[^/]*";
+            }
+        }
+        else if (c === "?" || c === "+") {
+            out += c;
+        }
+        else if (c === "[") {
+            const j = pat.indexOf("]", i + 1);
+            out += pat.slice(i, j + 1);
+            i = j;
+        }
+        else if (c === "\\") {
+            i++;
+            out += escapeRegex(pat[i]);
+        }
+        else {
+            out += escapeRegex(c);
+        }
+    }
+    return new RegExp(`^${out}$`);
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { jobName, isWorkflowEntry, isJobEntry } from "./entries/index.js";
+export { patternToRegex, matchFilters } from "./filters/index.js";
+export { expandMatrix } from "./matrix/index.js";
+export { evalIf, expandWorkflowJobs } from "./jobs/index.js";
+export { parseUses } from "./uses/index.js";
+export { makeOctokit, predict } from "./predict/index.js";
+export type { JobName, WorkflowEntry, JobEntry, Entry, Prediction, PrEventAction, PredictOptions, Ctx, ExpandedJob, SourceRef, WorkflowSource, FetchWorkflow, ResolveRef, WorkflowReader, UsesTarget, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+export { jobName, isWorkflowEntry, isJobEntry } from "./entries/index.js";
+export { patternToRegex, matchFilters } from "./filters/index.js";
+export { expandMatrix } from "./matrix/index.js";
+export { evalIf, expandWorkflowJobs } from "./jobs/index.js";
+export { parseUses } from "./uses/index.js";
+export { makeOctokit, predict } from "./predict/index.js";

package/dist/jobs/evalIf.d.ts

@@ -0,0 +1,10 @@
+import { type Scope } from "../expr.js";
+/**
+ * Return run|skipped|unknown for a job-level `if:`.
+ *
+ * `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.*`.
+ */
+export declare function evalIf(cond: any, scope?: Scope): "run" | "skipped" | "unknown";

package/dist/jobs/evalIf.js

@@ -0,0 +1,18 @@
+import { evaluate } from "../expr.js";
+import { prScope } from "./prScope.js";
+/**
+ * Return run|skipped|unknown for a job-level `if:`.
+ *
+ * `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.*`.
+ */
+export function evalIf(cond, scope = {}) {
+    if (cond == null)
+        return "run";
+    const verdict = evaluate(String(cond), prScope(scope));
+    if (verdict === null)
+        return "unknown";
+    return verdict ? "run" : "skipped";
+}

package/dist/jobs/expandJobs.d.ts

@@ -0,0 +1,4 @@
+import { type Scope } from "../expr.js";
+import type { JobExecutor } from "../execute.js";
+import type { Ctx, ExpandedJob, Workflow, WorkflowReader, WorkflowSource } from "../types.js";
+export declare function expandJobs(wf: Workflow, ctx: Ctx, reader: WorkflowReader, source: WorkflowSource, depth?: number, prefix?: string, prefixResolved?: boolean, scope?: Scope, executor?: JobExecutor): Promise<ExpandedJob[]>;

package/dist/jobs/expandJobs.js

@@ -0,0 +1,247 @@
+import { parse as parseYaml } from "yaml";
+import { UNKNOWN } from "../expr.js";
+import { expandMatrixDetailed } from "../matrix/expandMatrixDetailed.js";
+import { jobDisplayName } from "../names/jobDisplayName.js";
+import { skippedDisplayName } from "../names/skippedDisplayName.js";
+import { parseUses } from "../uses/parseUses.js";
+import { evalIf } from "./evalIf.js";
+import { prScope } from "./prScope.js";
+/**
+ * A `with:` value as the callee will see it.
+ *
+ * A value carrying `${{ }}` is left unknown rather than evaluated. Resolving
+ * it would mean evaluating the caller's own expression context, and every
+ * caller in practice passes plain literals — so the reach that would buy is
+ * not worth the surface. Unknown here is the same unknown as before this
+ * existed; nothing regresses.
+ */
+function inputLiteral(raw) {
+    if (raw == null)
+        return { kind: "value", v: "" };
+    if (typeof raw === "boolean" || typeof raw === "number")
+        return { kind: "value", v: raw };
+    if (typeof raw === "string")
+        return raw.includes("${{") ? UNKNOWN : { kind: "value", v: raw };
+    return UNKNOWN;
+}
+/** The `on.workflow_call.inputs` block, tolerating the YAML 1.1 `on` -> true key. */
+function workflowCallInputs(wf) {
+    const on = wf?.["on"] ?? wf?.["true"];
+    if (on == null || typeof on !== "object")
+        return {};
+    const call = on["workflow_call"];
+    if (call == null || typeof call !== "object")
+        return {};
+    const inputs = call["inputs"];
+    return inputs != null && typeof inputs === "object" ? inputs : {};
+}
+/**
+ * What `inputs.*` resolves to inside a called workflow: what the caller passed,
+ * over the defaults the callee declares.
+ *
+ * A declared input the caller omits falls back to its `default`. A declared
+ * input with no default and no caller value is unknown rather than empty — the
+ * workflow would be invalid if it were required, and guessing empty would
+ * silently decide guards that are not decided.
+ */
+function calleeInputs(withBlock, subWf) {
+    const out = {};
+    for (const [name, decl] of Object.entries(workflowCallInputs(subWf))) {
+        out[name] =
+            decl != null && typeof decl === "object" && "default" in decl
+                ? inputLiteral(decl["default"])
+                : UNKNOWN;
+    }
+    if (withBlock != null && typeof withBlock === "object") {
+        for (const [name, raw] of Object.entries(withBlock)) {
+            out[name] = inputLiteral(raw);
+        }
+    }
+    return out;
+}
+/**
+ * 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;
+/** `ref` is already a commit id, so resolving it is a no-op. */
+const SHA_RE = /^[0-9a-f]{40}$/i;
+const isSha = (ref) => SHA_RE.test(ref);
+export async function expandJobs(wf, ctx, reader, source, depth = 0, prefix = "", prefixResolved = true, scope = {}, executor) {
+    const entries = [];
+    const jobs = wf.jobs ?? {};
+    const statuses = {};
+    // Execute what the caller granted, before anything reads `needs`. The
+    // grant names the repo the workflow *file* lives in, so a granted callee
+    // job fires here in the recursion, where `source` is that repo. The guard
+    // is the same `evalIf` the main loop applies — same scope, same verdict —
+    // so a job is executed exactly when it is predicted to run. A job that
+    // would not run is not executed; a job that fails to execute contributes
+    // nothing but its reason, which `execNote` threads into the entries that
+    // needed it.
+    let scoped = scope;
+    const execFailures = {};
+    if (executor != null) {
+        for (const [jobId, jobRaw] of Object.entries(jobs)) {
+            if (!executor.granted(source, jobId))
+                continue;
+            const job = jobRaw ?? {};
+            if (evalIf(job.if, scoped) !== "run")
+                continue;
+            const res = await executor.executeJob(jobId, job, wf, scoped);
+            if (res.ok) {
+                scoped = { ...scoped, needs: { ...scoped.needs, [jobId]: { outputs: res.outputs } } };
+            }
+            else {
+                execFailures[jobId] = res.reason;
+            }
+        }
+    }
+    const execNote = (needs) => {
+        const failed = needs.find((n) => n in execFailures);
+        return failed == null ? "" : `; executing '${failed}' failed: ${execFailures[failed]}`;
+    };
+    for (const [jobId, jobRaw] of Object.entries(jobs)) {
+        const job = jobRaw ?? {};
+        let status = evalIf(job.if, scoped);
+        let reason = job.if != null ? `if: ${JSON.stringify(job.if)}` : "";
+        let needs = job.needs ?? [];
+        if (typeof needs === "string")
+            needs = [needs];
+        const cond = String(job.if ?? "");
+        if (status !== "skipped" && !cond.includes("always()")) {
+            for (const n of needs) {
+                if (statuses[n] === "skipped") {
+                    status = "skipped";
+                    reason = `needs '${n}' which is skipped`;
+                }
+                else if (statuses[n] === "unknown" && status === "run") {
+                    status = "unknown";
+                    reason = `needs '${n}' whose status is unknown`;
+                }
+            }
+        }
+        statuses[jobId] = status;
+        // A skipped job never expands its matrix and never dispatches a called
+        // workflow: it collapses to a single check under the bare job name.
+        if (status === "skipped") {
+            const disp = skippedDisplayName(jobId, job);
+            const name = prefix + disp.name;
+            entries.push({
+                job: name,
+                checkName: prefixResolved && disp.resolved ? name : null,
+                status,
+                reason,
+            });
+            continue;
+        }
+        const combos = expandMatrixDetailed(job.strategy, prScope(scoped));
+        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 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({
+                    job: prefix + jobId,
+                    checkName: null,
+                    status: "unknown",
+                    reason: "dynamic matrix on reusable workflow call" + execNote(needs),
+                });
+                continue;
+            }
+            // Resolve the called workflow once, not once per matrix combination.
+            let subWf = null;
+            let failure = null;
+            // 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;
+            // What `inputs.*` means on the other side of the call.
+            let subScope = {};
+            const target = parseUses(uses);
+            if (depth + 1 > MAX_REUSABLE_DEPTH) {
+                failure = `reusable workflow nested deeper than ${MAX_REUSABLE_DEPTH} levels`;
+            }
+            else if (target == null) {
+                failure = `unresolvable reusable reference: ${uses}`;
+            }
+            else {
+                // A local `./` call stays on the caller's source, which is already
+                // pinned to a commit. A cross-repo one arrives as whatever the `uses:`
+                // string spelled — `@v0` — and has to be resolved before anything is
+                // read from it, so the file that gets read and the commit the
+                // prediction names are the same one.
+                let resolved = source;
+                if (target.source != null) {
+                    const { ref } = target.source;
+                    const sha = isSha(ref) ? ref : await reader.resolveRef(target.source);
+                    resolved = sha == null ? null : { ...target.source, sha };
+                }
+                if (resolved == null) {
+                    failure = `cannot resolve ref for ${uses}`;
+                }
+                else {
+                    subSource = resolved;
+                    const content = await reader.fetchWorkflow(target.path, subSource);
+                    if (content == null) {
+                        failure = `cannot fetch ${uses}`;
+                    }
+                    else {
+                        try {
+                            subWf = parseYaml(content);
+                            // `inputs.*` changes at the call boundary; `github.*` does not.
+                            // A callee's jobs run in the caller's repo, so the facts seeded
+                            // at the top of the prediction stay true all the way down.
+                            subScope = { inputs: calleeInputs(job.with, subWf ?? {}), github: scoped.github };
+                        }
+                        catch (e) {
+                            failure = `YAML parse error in ${uses}: ${e}`;
+                        }
+                    }
+                }
+            }
+            for (const combo of combos) {
+                const disp = jobDisplayName(jobId, job, combo);
+                const baseName = prefix + disp.name;
+                const nameResolved = prefixResolved && disp.resolved;
+                if (failure != null || subWf == null) {
+                    entries.push({
+                        job: baseName,
+                        checkName: null,
+                        status: "unknown",
+                        reason: failure ?? `cannot resolve ${uses}`,
+                    });
+                    continue;
+                }
+                entries.push(...(await expandJobs(subWf, ctx, reader, subSource, depth + 1, `${baseName} / `, nameResolved, subScope, executor)));
+            }
+            continue;
+        }
+        if (combos == null) {
+            entries.push({
+                job: prefix + jobId,
+                checkName: null,
+                status: "unknown",
+                reason: "dynamic matrix" + execNote(needs),
+            });
+            continue;
+        }
+        for (const combo of combos) {
+            const disp = jobDisplayName(jobId, job, combo);
+            const name = prefix + disp.name;
+            entries.push({
+                job: name,
+                checkName: prefixResolved && disp.resolved ? name : null,
+                status,
+                reason,
+            });
+        }
+    }
+    return entries;
+}

package/dist/jobs/expandWorkflowJobs.d.ts

@@ -0,0 +1,14 @@
+import type { Scope } from "../expr.js";
+import type { JobExecutor } from "../execute.js";
+import type { Ctx, ExpandedJob, Workflow, WorkflowReader, WorkflowSource } from "../types.js";
+/**
+ * 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[]>;

package/dist/jobs/expandWorkflowJobs.js

@@ -0,0 +1,14 @@
+import { expandJobs } from "./expandJobs.js";
+/**
+ * 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 function expandWorkflowJobs(wf, ctx, reader, source, scope = {}, executor) {
+    return expandJobs(wf, ctx, reader, source, 0, "", true, scope, executor);
+}

package/dist/jobs/index.d.ts

@@ -0,0 +1,4 @@
+export { prScope } from "./prScope.js";
+export { evalIf } from "./evalIf.js";
+export { expandJobs } from "./expandJobs.js";
+export { expandWorkflowJobs } from "./expandWorkflowJobs.js";

package/dist/jobs/index.js

@@ -0,0 +1,4 @@
+export { prScope } from "./prScope.js";
+export { evalIf } from "./evalIf.js";
+export { expandJobs } from "./expandJobs.js";
+export { expandWorkflowJobs } from "./expandWorkflowJobs.js";

package/dist/jobs/prScope.d.ts

@@ -0,0 +1,10 @@
+import type { Scope } from "../expr.js";
+/**
+ * A scope with the fixed pull-request facts filled in.
+ *
+ * Every `${{ }}` this module evaluates — a job `if:`, a matrix axis — is
+ * evaluated for the same event, so they all get the same `github.*`. Anything
+ * the caller states wins; there is nothing here worth overriding, but a scope
+ * that silently ignored what it was handed would be the wrong shape.
+ */
+export declare const prScope: (scope: Scope) => Scope;

package/dist/jobs/prScope.js

@@ -0,0 +1,19 @@
+/**
+ * The `github.*` values that are fixed for everything this module predicts.
+ * `predict` only ever answers for a pull request, so `event_name` is not a
+ * variable — which is what lets a `github.event_name == 'pull_request'` guard
+ * resolve instead of hanging the job on an unknown.
+ */
+const PR_GITHUB_CONTEXT = { event_name: "pull_request" };
+/**
+ * A scope with the fixed pull-request facts filled in.
+ *
+ * Every `${{ }}` this module evaluates — a job `if:`, a matrix axis — is
+ * evaluated for the same event, so they all get the same `github.*`. Anything
+ * the caller states wins; there is nothing here worth overriding, but a scope
+ * that silently ignored what it was handed would be the wrong shape.
+ */
+export const prScope = (scope) => ({
+    ...scope,
+    github: { ...PR_GITHUB_CONTEXT, ...scope.github },
+});

package/dist/matrix/expandMatrix.d.ts

@@ -0,0 +1,4 @@
+import type { Scope } from "../expr.js";
+import type { Combo } from "../types.js";
+/** Return list of matrix combination dicts, or null if dynamic. */
+export declare function expandMatrix(strategy: any, scope?: Scope): Combo[] | null;

package/dist/matrix/expandMatrix.js

@@ -0,0 +1,6 @@
+import { expandMatrixDetailed } from "./expandMatrixDetailed.js";
+/** Return list of matrix combination dicts, or null if dynamic. */
+export function expandMatrix(strategy, scope = {}) {
+    const detailed = expandMatrixDetailed(strategy, scope);
+    return detailed == null ? null : detailed.map((c) => (c == null ? null : c.values));
+}

package/dist/matrix/expandMatrixDetailed.d.ts

@@ -0,0 +1,3 @@
+import { type Scope } from "../expr.js";
+import type { DetailedCombos } from "../types.js";
+export declare function expandMatrixDetailed(strategy: any, scope?: Scope): DetailedCombos;