willfire 0.1.11 → 0.1.12

package/dist/matrix/expandMatrixDetailed.js

@@ -0,0 +1,74 @@
+import { evaluateValue } from "../expr.js";
+/**
+ * The values of one matrix axis, or null when they cannot be known.
+ *
+ * A plain list is itself. An axis written as an expression —
+ * `language: ${{ fromJSON(needs.detect.outputs.coverage_languages) }}` — is
+ * the values another job computed, and is knowable exactly when the scope
+ * carries that job's outputs. Anything else stays null, which is what makes
+ * the whole job `unknown` rather than a guess at how many checks it creates.
+ */
+function axisValues(v, scope) {
+    if (Array.isArray(v))
+        return v;
+    if (typeof v !== "string")
+        return null;
+    const val = evaluateValue(v, scope);
+    if (val.kind !== "json" || !Array.isArray(val.v))
+        return null;
+    return val.v;
+}
+export function expandMatrixDetailed(strategy, scope = {}) {
+    const matrix = strategy?.matrix;
+    if (matrix == null)
+        return [null];
+    // `matrix: ${{ ... }}` — the whole matrix as one expression, rather than the
+    // per-axis form below. It yields include-style entries, not axes, so it is a
+    // separate expansion and is not modelled.
+    if (typeof matrix === "string")
+        return null;
+    const include = matrix.include ?? [];
+    const exclude = matrix.exclude ?? [];
+    if (typeof include === "string" || typeof exclude === "string")
+        return null;
+    const axes = {};
+    for (const [k, v] of Object.entries(matrix)) {
+        if (k === "include" || k === "exclude")
+            continue;
+        const vals = axisValues(v, scope);
+        if (vals == null)
+            return null;
+        axes[k] = vals;
+    }
+    const axisKeys = Object.keys(axes);
+    let combos = [{ values: {}, displayKeys: axisKeys }];
+    for (const [k, vals] of Object.entries(axes)) {
+        combos = combos.flatMap((c) => vals.map((v) => ({ values: { ...c.values, [k]: v }, displayKeys: axisKeys })));
+    }
+    if (axisKeys.length === 0)
+        combos = [];
+    combos = combos.filter((c) => !exclude.some((ex) => Object.entries(ex).every(([k, v]) => c.values[k] === v)));
+    const extra = [];
+    for (const inc of include) {
+        const overlapping = Object.fromEntries(Object.entries(inc).filter(([k]) => k in axes));
+        const targets = combos.filter((c) => Object.entries(overlapping).every(([k, v]) => c.values[k] === v));
+        if (axisKeys.length > 0 && targets.length > 0) {
+            // Merge into the matching combinations. With no overlapping keys this
+            // matches every combination, per the docs ("added to each of the matrix
+            // combinations if none of the key:value pairs overwrite any of the
+            // original matrix values").
+            for (const c of targets)
+                Object.assign(c.values, inc);
+        }
+        else {
+            // No combination to attach to: the include entry becomes a combination
+            // of its own, and every one of its keys shows in the name.
+            extra.push({ values: { ...inc }, displayKeys: Object.keys(inc) });
+        }
+    }
+    combos.push(...extra);
+    // 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;
+}

package/dist/matrix/formatMatrixValue.d.ts

@@ -0,0 +1,8 @@
+/**
+ * How a single matrix value is rendered inside a check name.
+ *
+ * Probe-verified: object values are flattened to their own values, so
+ * `cfg: {os: linux, arch: x64}` renders as `linux, x64` — the check is
+ * `m-object (linux, x64)`.
+ */
+export declare function formatMatrixValue(v: unknown): string;

package/dist/matrix/formatMatrixValue.js

@@ -0,0 +1,16 @@
+/**
+ * How a single matrix value is rendered inside a check name.
+ *
+ * Probe-verified: object values are flattened to their own values, so
+ * `cfg: {os: linux, arch: x64}` renders as `linux, x64` — the check is
+ * `m-object (linux, x64)`.
+ */
+export function formatMatrixValue(v) {
+    if (v == null)
+        return "";
+    if (Array.isArray(v))
+        return v.map(formatMatrixValue).join(", ");
+    if (typeof v === "object")
+        return Object.values(v).map(formatMatrixValue).join(", ");
+    return String(v);
+}

package/dist/matrix/index.d.ts

@@ -0,0 +1,4 @@
+export { expandMatrixDetailed } from "./expandMatrixDetailed.js";
+export { expandMatrix } from "./expandMatrix.js";
+export { formatMatrixValue } from "./formatMatrixValue.js";
+export { matrixSuffix } from "./matrixSuffix.js";

package/dist/matrix/index.js

@@ -0,0 +1,4 @@
+export { expandMatrixDetailed } from "./expandMatrixDetailed.js";
+export { expandMatrix } from "./expandMatrix.js";
+export { formatMatrixValue } from "./formatMatrixValue.js";
+export { matrixSuffix } from "./matrixSuffix.js";

package/dist/matrix/matrixSuffix.d.ts

@@ -0,0 +1,3 @@
+import type { DetailedCombo } from "../types.js";
+/** The ` (v1, v2)` suffix GitHub appends for a matrix combination. */
+export declare function matrixSuffix(combo: DetailedCombo): string;

package/dist/matrix/matrixSuffix.js

@@ -0,0 +1,8 @@
+import { formatMatrixValue } from "./formatMatrixValue.js";
+/** The ` (v1, v2)` suffix GitHub appends for a matrix combination. */
+export function matrixSuffix(combo) {
+    const keys = combo.displayKeys.filter((k) => k in combo.values);
+    if (keys.length === 0)
+        return "";
+    return ` (${keys.map((k) => formatMatrixValue(combo.values[k])).join(", ")})`;
+}

package/dist/names/index.d.ts

@@ -0,0 +1,4 @@
+export { lookupPath } from "./lookupPath.js";
+export { renderName } from "./renderName.js";
+export { jobDisplayName, EXPRESSION_RE } from "./jobDisplayName.js";
+export { skippedDisplayName } from "./skippedDisplayName.js";

package/dist/names/index.js

@@ -0,0 +1,4 @@
+export { lookupPath } from "./lookupPath.js";
+export { renderName } from "./renderName.js";
+export { jobDisplayName, EXPRESSION_RE } from "./jobDisplayName.js";
+export { skippedDisplayName } from "./skippedDisplayName.js";

package/dist/names/jobDisplayName.d.ts

@@ -0,0 +1,16 @@
+import type { DetailedCombo, DisplayName, Workflow } from "../types.js";
+/**
+ * A `name:` that contains any `${{ }}` expression suppresses the matrix
+ * parenthetical; a literal one does not.
+ *
+ * Probe-verified three ways over `a: [x, y]`: `name: Static Label` yields
+ * `Static Label (x)` / `Static Label (y)`, `name: ev ${{ github.event_name }}`
+ * yields two checks both called `ev pull_request`, and
+ * `name: p ${{ matrix.a }}` over `a: [x], b: ["1", "2"]` yields two checks
+ * both called `p x`. So the trigger is the presence of an expression, not
+ * whether the expression happens to read the matrix — and duplicate check
+ * names are a real outcome GitHub allows.
+ */
+export declare const EXPRESSION_RE: RegExp;
+/** The check name for one job/combination. */
+export declare function jobDisplayName(jobId: string, job: Workflow, combo: DetailedCombo | null): DisplayName;

package/dist/names/jobDisplayName.js

@@ -0,0 +1,25 @@
+import { matrixSuffix } from "../matrix/matrixSuffix.js";
+import { renderName } from "./renderName.js";
+/**
+ * A `name:` that contains any `${{ }}` expression suppresses the matrix
+ * parenthetical; a literal one does not.
+ *
+ * Probe-verified three ways over `a: [x, y]`: `name: Static Label` yields
+ * `Static Label (x)` / `Static Label (y)`, `name: ev ${{ github.event_name }}`
+ * yields two checks both called `ev pull_request`, and
+ * `name: p ${{ matrix.a }}` over `a: [x], b: ["1", "2"]` yields two checks
+ * both called `p x`. So the trigger is the presence of an expression, not
+ * whether the expression happens to read the matrix — and duplicate check
+ * names are a real outcome GitHub allows.
+ */
+export const EXPRESSION_RE = /\$\{\{/;
+/** The check name for one job/combination. */
+export function jobDisplayName(jobId, job, combo) {
+    const raw = job != null && job.name != null ? String(job.name) : null;
+    if (raw === null) {
+        return { name: jobId + (combo ? matrixSuffix(combo) : ""), resolved: true };
+    }
+    const { text, resolved } = renderName(raw, combo?.values ?? null);
+    const suffix = combo && !EXPRESSION_RE.test(raw) ? matrixSuffix(combo) : "";
+    return { name: text + suffix, resolved };
+}

package/dist/names/lookupPath.d.ts

@@ -0,0 +1 @@
+export declare function lookupPath(obj: any, path: string): unknown;

package/dist/names/lookupPath.js

@@ -0,0 +1,9 @@
+export function lookupPath(obj, path) {
+    let cur = obj;
+    for (const seg of path.split(".")) {
+        if (cur == null || typeof cur !== "object" || !(seg in cur))
+            return undefined;
+        cur = cur[seg];
+    }
+    return cur;
+}

package/dist/names/renderName.d.ts

@@ -0,0 +1,2 @@
+import type { Combo, Rendered } from "../types.js";
+export declare function renderName(template: string, combo: Combo): Rendered;

package/dist/names/renderName.js

@@ -0,0 +1,26 @@
+import { formatMatrixValue } from "../matrix/formatMatrixValue.js";
+import { lookupPath } from "./lookupPath.js";
+export function renderName(template, combo) {
+    let resolved = true;
+    const text = template.replace(/\$\{\{(.*?)\}\}/g, (whole, inner) => {
+        const expr = String(inner).trim();
+        if (expr.startsWith("matrix.")) {
+            if (!combo) {
+                resolved = false;
+                return whole;
+            }
+            const val = lookupPath(combo, expr.slice("matrix.".length));
+            if (val === undefined) {
+                resolved = false;
+                return whole;
+            }
+            return formatMatrixValue(val);
+        }
+        // We only predict pull_request dispatch, so this one is knowable.
+        if (expr === "github.event_name")
+            return "pull_request";
+        resolved = false;
+        return whole;
+    });
+    return { text, resolved };
+}

package/dist/names/skippedDisplayName.d.ts

@@ -0,0 +1,14 @@
+import type { DisplayName, Workflow } from "../types.js";
+/**
+ * The check name a job gets when it is skipped.
+ *
+ * A skipped job is never set up, so nothing about it is evaluated: the matrix
+ * does not expand and `name:` is not interpolated. Probe-verified twice over:
+ * `if: false` with `a: [x, y]` produces the single check `m-skipped`, not
+ * `m-skipped (x)` / `m-skipped (y)`; and `name: sk ${{ github.event_name }}`
+ * with `if: false` produces a check literally called
+ * `sk ${{ github.event_name }}`, expression text and all. The same collapse
+ * applies to a skipped reusable-workflow call: one check named after the
+ * caller, with no `/ <callee job>` entries.
+ */
+export declare function skippedDisplayName(jobId: string, job: Workflow): DisplayName;

package/dist/names/skippedDisplayName.js

@@ -0,0 +1,16 @@
+/**
+ * The check name a job gets when it is skipped.
+ *
+ * A skipped job is never set up, so nothing about it is evaluated: the matrix
+ * does not expand and `name:` is not interpolated. Probe-verified twice over:
+ * `if: false` with `a: [x, y]` produces the single check `m-skipped`, not
+ * `m-skipped (x)` / `m-skipped (y)`; and `name: sk ${{ github.event_name }}`
+ * with `if: false` produces a check literally called
+ * `sk ${{ github.event_name }}`, expression text and all. The same collapse
+ * applies to a skipped reusable-workflow call: one check named after the
+ * caller, with no `/ <callee job>` entries.
+ */
+export function skippedDisplayName(jobId, job) {
+    const raw = job != null && job.name != null ? String(job.name) : null;
+    return { name: raw ?? jobId, resolved: true };
+}

package/dist/predict/finalizePrediction.d.ts

@@ -0,0 +1,2 @@
+import type { DraftEntry, Prediction, WorkflowSource } from "../types.js";
+export declare function finalizePrediction(entries: DraftEntry[], skip: string | null, sources: Map<string, WorkflowSource>): Prediction;

package/dist/predict/finalizePrediction.js

@@ -0,0 +1,19 @@
+import { sourceKey } from "./sourceKey.js";
+const isWorkflowDraft = (e) => e.job === "*";
+const finalize = (e) => isWorkflowDraft(e)
+    ? { ...e, checkName: null }
+    : { ...e, checkName: e.checkName ?? null };
+export function finalizePrediction(entries, skip, sources) {
+    const final = entries.map(finalize);
+    const names = new Set();
+    for (const e of final) {
+        if (e.status === "run" && e.checkName != null)
+            names.add(e.checkName);
+    }
+    return {
+        entries: final,
+        checkNames: [...names].sort(),
+        skip,
+        sources: [...sources.values()].sort((a, b) => sourceKey(a).localeCompare(sourceKey(b))),
+    };
+}

package/dist/predict/index.d.ts

@@ -0,0 +1,5 @@
+export { makeOctokit } from "./makeOctokit.js";
+export { sourceKey } from "./sourceKey.js";
+export { stackTargetRef } from "./stackTargetRef.js";
+export { finalizePrediction } from "./finalizePrediction.js";
+export { predict } from "./predict.js";

package/dist/predict/index.js

@@ -0,0 +1,5 @@
+export { makeOctokit } from "./makeOctokit.js";
+export { sourceKey } from "./sourceKey.js";
+export { stackTargetRef } from "./stackTargetRef.js";
+export { finalizePrediction } from "./finalizePrediction.js";
+export { predict } from "./predict.js";

package/dist/predict/makeOctokit.d.ts

@@ -0,0 +1,2 @@
+import { Octokit } from "@octokit/rest";
+export declare function makeOctokit(): Octokit;

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];