@rmartz/merge-safety 0.6.0

package/README.md

@@ -0,0 +1,122 @@
+# @rmartz/merge-safety
+
+The **pre-auto-merge safety verdict** for a pull request, packaged so a repo can
+use GitHub's native auto-merge safely. merge-safety gathers base-currency,
+breaking-change, and conflict facts for a PR, posts them as the `merge-safety`
+check-run, and re-holds every open PR when the base branch moves — so a PR only
+auto-merges once it is genuinely safe against the current base.
+
+It is distributed the same way [`@rmartz/repo-hygiene`](https://github.com/rmartz/repo-hygiene)
+is:
+
+1. **Updates propagate automatically.** Consuming repos pin one reusable workflow
+   by SHA; Dependabot's `github-actions` ecosystem opens PRs to bump that pin.
+2. **The check-run name is a fleet contract.** Every consumer requires a status
+   check named exactly `merge-safety`; see
+   [docs/check-run-contract.md](docs/check-run-contract.md).
+
+> **Status: released.** `v0.1.0` ships the full `evaluate` / `invalidate`
+> implementation and the `ai-merge-safety` CLI — the package is functional and
+> ready to adopt. It was split out of `@rmartz/pr-review` per
+> [ai-tools#247](https://github.com/rmartz/ai-tools/issues/247); see
+> [docs/migration.md](docs/migration.md) for the record of how it was extracted.
+
+## Using it in a consuming repo
+
+Add one caller workflow (this is what Dependabot keeps current). Unlike a
+read-only hygiene check, this caller carries the triggers, grants write scopes,
+and passes secrets through — because a reusable workflow can't declare its own
+triggers and runs with the intersection of granted and declared permissions:
+
+```yaml
+# .github/workflows/merge-safety.yml
+name: merge-safety
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, edited, labeled, unlabeled]
+  push:
+    branches: [main]
+  workflow_dispatch:
+    inputs:
+      pr:
+        description: PR number to evaluate
+        required: true
+permissions:
+  checks: write
+  pull-requests: write
+  contents: read
+  actions: write
+  packages: read
+jobs:
+  merge-safety:
+    uses: rmartz/merge-safety/.github/workflows/merge-safety.yml@<sha> # vX.Y.Z
+    with:
+      pr: ${{ inputs.pr }}
+    secrets: inherit
+```
+
+Then require the `merge-safety` status check on the default branch. Both the
+caller and the Dependabot entry are seeded once by
+[`@rmartz/bootstrap`](https://github.com/rmartz/ai-tools)
+(`ai-ensure-project-config`); after that Dependabot maintains the pin. The public
+`@rmartz/merge-safety` package on GitHub Packages is readable with the built-in
+`GITHUB_TOKEN`, so no consumer PAT is required.
+
+> For the full walkthrough — the caller's permissions, why it isn't trigger-free,
+> and how to verify the setup — see the
+> [consumer setup guide](docs/consuming.md).
+
+## Requirements
+
+- Node.js >= 20.11
+- pnpm 9 (pinned via `packageManager`)
+
+Consuming repos need neither — the reusable workflow runs the published CLI on a
+GitHub-hosted runner.
+
+## Local development
+
+```bash
+pnpm install
+pnpm run build        # tsup → dist (ESM + d.ts)
+pnpm run typecheck
+pnpm run lint
+pnpm run format:check
+pnpm run test         # vitest
+```
+
+## Releases
+
+Fully automatic via [`semantic-release`](https://semantic-release.gitbook.io) — no
+manual `pnpm version` step. Every push to `main` runs
+[`release.yml`](.github/workflows/release.yml): it analyzes the conventional-commit
+subjects since the last `vX.Y.Z` tag (the squash-merged **PR title** is that subject),
+computes the next version, builds and publishes the package to GitHub Packages
+(public), and creates the git tag + GitHub Release with generated notes — using only
+the built-in `GITHUB_TOKEN`, no release-please and no PAT. There is deliberately **no
+`@semantic-release/git`**: `package.json`'s `version` is a frozen `0.0.0` placeholder
+and is never committed back. The version installed by the reusable workflow is
+resolved at runtime from the **release tag at its own pinned commit**, so it lives
+only in the git tag. Config: [`.releaserc.json`](.releaserc.json).
+
+**Version mapping (v0):** `feat:` → minor; `fix:`/`perf:` → patch. Pre-1.0, a
+breaking change (`!`) is **capped at minor** so it can't auto-jump to `1.0.0`;
+leaving v0 (cutting `1.0.0`) is a deliberate manual act. Dependabot uses the
+split-prefix convention (rmartz/ai#82): a **production** bump arrives as
+`fix(deps):` → patch (it ships to users); **dev** (`chore(deps):`) and
+**github-actions** (`chore(github-actions):`) bumps are release-less — as a
+zero-runtime-dependency package, all Dependabot bumps are dev-only in practice.
+
+Three guards back the automatic flow: [`pr-title-lint.yml`](.github/workflows/pr-title-lint.yml)
+(pre-merge title format), [`commit-convention.yml`](.github/workflows/commit-convention.yml)
+(post-merge tripwire for a non-conventional subject that would make semantic-release
+silently skip), and, in [`ci.yml`](.github/workflows/ci.yml), the `Release notes render`
+job (renders the notes through the real changelog toolchain so an incompatible
+preset/writer pairing fails the PR) and the `Package`
+job (packs exactly what `pnpm publish` would upload and fails if the tarball is
+malformed or missing an `exports`/`bin` entry point) — so both a broken release config
+and a broken packaging manifest are caught before merge, not on the real release run.
+
+---
+
+🤖 Created by Claude Opus 4.8

package/dist/bin/merge-safety.d.ts

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+import { MergeSafetyCommand } from '../index.js';
+
+/** The open PR that heads a branch, reduced to what the barrier needs. */
+interface BasePr {
+    number: number;
+    /** The PR's label names, matched case-insensitively against the exempt set. */
+    labels: readonly string[];
+}
+
+/**
+ * Base-health classification — "is the base branch's own CI failing?", the
+ * PR-independent axis of the merge-safety verdict.
+ *
+ * Extracted from `merge-safety.ts` when the self-derived breaking-change signal
+ * (#53) pushed that file past its 480-line cap. It is a genuinely separate
+ * concern: every other clause of the verdict reads *this PR* against *its base*,
+ * while these functions read only the base tip's check-runs and know nothing
+ * about any PR. Pure — the network boundary stays in the bin's probes.
+ */
+/**
+ * A base-tip check-run reduced to what base-health classification needs: its name
+ * (matched against the base branch's required status checks), its conclusion, and
+ * the slug of the producing GitHub App (used by the fallback heuristic to tell a
+ * GitHub Actions CI run from an external deploy integration).
+ */
+interface BaseCheckRun {
+    /** The check-run name (e.g. the workflow / job name), matched to a required context. */
+    name: string;
+    /** The check-run conclusion, or `null` while still in progress. */
+    conclusion: string | null;
+    /** The producing GitHub App's slug (e.g. `github-actions`, `vercel`), or `null`. */
+    appSlug: string | null;
+}
+
+/**
+ * Fetches the base branch tip's check-runs (deduped to the latest per name) so
+ * base-health can be judged. Injected like {@link GitRunner} so the assembly logic
+ * stays testable with a fake and the network boundary lives in the bin. Soft-fails
+ * to `[]` (an unreadable base is treated as *not* failing) so a transient `gh`
+ * error never wedges the whole merge queue on a base-health false positive.
+ */
+type BaseChecksProbe = (baseSha: string) => Promise<readonly BaseCheckRun[]>;
+/**
+ * Fetches the base branch's **required status check** contexts — the set base-health
+ * scopes failures to (#40). Returns `null` when protection can't be read (transient
+ * `gh` error, no ruleset, missing scope); a `null` or empty set means base-health
+ * reports no failure, so a probe hiccup never wedges the merge queue. Injected like
+ * {@link BaseChecksProbe}, with the network boundary in the bin.
+ */
+type RequiredChecksProbe = (baseBranch: string) => Promise<readonly string[] | null>;
+/**
+ * Fetches the open PR whose **head** is a given branch — this PR's stacked parent
+ * (#54) — or `null` when no open PR heads it. A failed probe also yields `null`,
+ * which deliberately reads as "not stacked": an unreadable lookup must not hold a
+ * PR that may not be stacked at all, the same never-wedge posture as the check
+ * probes above. Injected like {@link BaseChecksProbe}.
+ */
+type BasePrProbe = (baseBranch: string) => Promise<BasePr | null>;
+
+interface Args {
+    mode: MergeSafetyCommand;
+    pr?: number;
+    exclude?: number;
+    repo?: string;
+    baseRef: string;
+    /**
+     * The consumer's caller workflow filename that `invalidate` re-dispatches per PR
+     * (issue #247's dispatch-target wrinkle: a reusable workflow's fan-out targets
+     * the *caller* file, not this reusable file). Defaults to the conventional name.
+     */
+    workflow: string;
+    cwd?: string;
+    /**
+     * The repository default branch, used by the stacked-PR barrier (#54). Absent →
+     * resolved from `gh repo view`; unresolvable → the barrier is disabled rather
+     * than holding every PR.
+     */
+    defaultBranch?: string;
+    /** Labels on a base PR that exempt its children from the barrier (#54). */
+    exemptBaseLabels: readonly string[];
+    /** Decision-only: print the verdict as JSON and perform no side effects. */
+    json: boolean;
+}
+/**
+ * A real base-checks probe: fetch the base tip's check-runs from the GitHub Checks
+ * API (deduped to the latest run per name via `?filter=latest`) and reduce each to
+ * the {@link BaseCheckRun} shape base-health classifies. `--jq` streams the array
+ * as JSONL so `--paginate` can concatenate pages for a base with many checks.
+ * Soft-fails to `[]` on any read error, so a transient `gh` failure never becomes
+ * a base-health false positive that wedges the merge queue.
+ */
+declare function makeBaseChecksProbe(repo: string, cwd?: string): BaseChecksProbe;
+/**
+ * A real required-checks probe: fetch the base branch's **required status check**
+ * contexts from the repository rulesets that apply to it (`/rules/branches/{branch}`,
+ * the endpoint that surfaces ruleset-declared rules the way this fleet configures
+ * them). `--jq` streams each `required_status_checks` rule's contexts as lines,
+ * deduped here. Soft-fails to `null` on any read error (no ruleset, missing scope,
+ * transient `gh` failure) so base-health degrades to "nothing gates" rather than
+ * wedging the queue on an unreadable protection config (#40).
+ */
+declare function makeRequiredChecksProbe(repo: string, cwd?: string): RequiredChecksProbe;
+/**
+ * A real base-PR probe: the open PR whose **head** is `baseBranch`, i.e. this PR's
+ * stacked parent (#54). Soft-fails to `null` (not stacked) on any read error or
+ * malformed payload, so a transient `gh` failure never holds a PR that may not be
+ * stacked at all. `--limit 1` suffices: a branch heads at most one open PR.
+ */
+declare function makeBasePrProbe(repo: string, cwd?: string): BasePrProbe;
+declare function runEvaluate(repo: string, pr: number, args: Args): Promise<void>;
+declare function runInvalidate(repo: string, args: Args): Promise<void>;
+
+export { type Args, makeBaseChecksProbe, makeBasePrProbe, makeRequiredChecksProbe, runEvaluate, runInvalidate };

package/dist/bin/merge-safety.js

@@ -0,0 +1,892 @@
+#!/usr/bin/env node
+import {
+  MERGE_SAFETY_CHECK_NAME,
+  isMergeSafetyCommand
+} from "../chunk-ITPKHZGC.js";
+
+// src/bin/merge-safety.ts
+import { realpathSync } from "fs";
+import { fileURLToPath } from "url";
+
+// src/lib/bounded-subprocess.ts
+import { spawn } from "child_process";
+function boundedRun(command, args, options) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd: options.cwd,
+      env: options.env,
+      detached: true
+      // new process group, so we can kill the whole tree
+    });
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      try {
+        process.kill(-child.pid, "SIGKILL");
+      } catch {
+      }
+    }, options.timeoutMs);
+    if (options.input !== void 0 && child.stdin) {
+      child.stdin.on("error", () => {
+      });
+      child.stdin.write(options.input);
+      child.stdin.end();
+    }
+    child.stdout.on("data", (chunk) => stdout += chunk.toString());
+    child.stderr.on("data", (chunk) => stderr += chunk.toString());
+    child.on("error", (err) => {
+      clearTimeout(timer);
+      reject(err);
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      resolve({ stdout, stderr, code, timedOut });
+    });
+  });
+}
+
+// src/lib/github.ts
+var GH_API_TIMEOUT_MS = 3e4;
+var MAX_RETRIES = 2;
+var BACKOFF_BASE_MS = 1e3;
+var BACKOFF_CAP_MS = 8e3;
+var realSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function isRateLimited(text) {
+  const t = (text ?? "").toLowerCase();
+  return t.includes("rate limit") || t.includes("rate-limit");
+}
+async function runTransport({ argv, stdin }, cwd) {
+  const [command, ...args] = argv;
+  if (command === void 0) return { stdout: null, stderr: "empty argv" };
+  try {
+    const r = await boundedRun(command, args, { timeoutMs: GH_API_TIMEOUT_MS, cwd, input: stdin });
+    if (r.code === 0) return { stdout: r.stdout, stderr: "" };
+    return { stdout: null, stderr: r.stderr || "" };
+  } catch (err) {
+    return { stdout: null, stderr: err instanceof Error ? err.message : String(err) };
+  }
+}
+async function ghCall(primary, fallback, opts = {}) {
+  const sleep = opts.sleep ?? realSleep;
+  for (const transport of [primary, fallback]) {
+    if (!transport) continue;
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+      const { stdout, stderr } = await runTransport(transport, opts.cwd);
+      if (stdout !== null) return stdout;
+      if (isRateLimited(stderr)) break;
+      if (attempt < MAX_RETRIES) {
+        await sleep(Math.min(BACKOFF_BASE_MS * 2 ** attempt, BACKOFF_CAP_MS));
+      }
+    }
+  }
+  return null;
+}
+function parseSlugFromRemoteUrl(url) {
+  const trimmed = url.trim();
+  const match = trimmed.match(/[/:]([^/:]+)\/([^/]+?)(?:\.git)?\/?$/);
+  if (match) return `${match[1]}/${match[2]}`;
+  const bare = trimmed.match(/^([^/:\s]+)\/([^/:\s]+?)(?:\.git)?$/);
+  return bare ? `${bare[1]}/${bare[2]}` : null;
+}
+async function currentRepo(opts = {}) {
+  const out = await ghCall(
+    { argv: ["gh", "repo", "view", "--json", "nameWithOwner", "--jq", ".nameWithOwner"] },
+    null,
+    opts
+  );
+  if (out && out.trim()) return out.trim();
+  const remote = await boundedRun("git", ["remote", "get-url", "origin"], {
+    timeoutMs: GH_API_TIMEOUT_MS,
+    cwd: opts.cwd
+  });
+  return remote.code === 0 ? parseSlugFromRemoteUrl(remote.stdout) : null;
+}
+async function resolveRepoTarget(opts = {}) {
+  const explicit = opts.repo?.trim();
+  if (explicit) return explicit;
+  const ghRepo = (opts.env ?? process.env).GH_REPO?.trim();
+  if (ghRepo) return ghRepo;
+  return currentRepo(opts);
+}
+function issueNumber(ref) {
+  const s = String(ref);
+  if (/^\d+$/.test(s)) return s;
+  const m = s.match(/\/(?:issues|pull)\/(\d+)/);
+  return m?.[1] ?? null;
+}
+async function addLabels(repo, issue, labels, call = {}) {
+  const number = issueNumber(issue);
+  if (number === null || !labels.length) return null;
+  const rest = {
+    argv: ["gh", "api", "-X", "POST", `repos/${repo}/issues/${number}/labels`, "--input", "-"],
+    stdin: JSON.stringify({ labels })
+  };
+  const fb = {
+    argv: ["gh", "issue", "edit", number, "--repo", repo, "--add-label", labels.join(",")]
+  };
+  const out = await ghCall(rest, fb, call);
+  return out !== null ? out.trim() : null;
+}
+async function removeLabel(repo, issue, label, call = {}) {
+  const number = issueNumber(issue);
+  if (number === null) return null;
+  const rest = {
+    argv: [
+      "gh",
+      "api",
+      "-X",
+      "DELETE",
+      `repos/${repo}/issues/${number}/labels/${encodeURIComponent(label)}`
+    ]
+  };
+  const fb = {
+    argv: ["gh", "issue", "edit", number, "--repo", repo, "--remove-label", label]
+  };
+  const out = await ghCall(rest, fb, call);
+  return out !== null ? out.trim() : null;
+}
+
+// src/lib/check-run.ts
+async function openCheckRunIds(repo, headSha, cwd) {
+  const out = await ghCall(
+    {
+      argv: [
+        "gh",
+        "api",
+        "--paginate",
+        `repos/${repo}/commits/${headSha}/check-runs?check_name=${encodeURIComponent(MERGE_SAFETY_CHECK_NAME)}&filter=all`,
+        "--jq",
+        '.check_runs[] | select(.status != "completed") | .id'
+      ]
+    },
+    null,
+    { cwd }
+  );
+  if (out === null) return null;
+  return out.split("\n").map((l) => Number(l.trim())).filter((id) => Number.isInteger(id) && id > 0);
+}
+async function postCheck(repo, headSha, output, conclusion, cwd) {
+  const state = conclusion === "pending" ? { status: "in_progress", output } : { status: "completed", conclusion, completed_at: (/* @__PURE__ */ new Date()).toISOString(), output };
+  let updated = false;
+  for (const id of await openCheckRunIds(repo, headSha, cwd) ?? []) {
+    const out = await ghCall(
+      {
+        argv: ["gh", "api", "-X", "PATCH", `repos/${repo}/check-runs/${id}`, "--input", "-"],
+        stdin: JSON.stringify(state)
+      },
+      null,
+      { cwd }
+    );
+    if (out !== null) updated = true;
+  }
+  if (updated) return;
+  await ghCall(
+    {
+      argv: ["gh", "api", "-X", "POST", `repos/${repo}/check-runs`, "--input", "-"],
+      stdin: JSON.stringify({
+        // The fleet-contract check-run name (src/index.ts). Never a local literal —
+        // every consumer's required status check matches exactly this name.
+        name: MERGE_SAFETY_CHECK_NAME,
+        head_sha: headSha,
+        ...state
+      })
+    },
+    null,
+    { cwd }
+  );
+}
+
+// src/conventional-commits.ts
+var BREAKING_SUBJECT_RE = /^[a-z]+(?:!(?:\([^)]*\))?|(?:\([^)]*\))?!):/;
+var BREAKING_FOOTER_RE = /^BREAKING[ -]CHANGE:/m;
+var CI_SUBJECT_RE = /^ci(\([^)]*\))?!?:/;
+var FUNCTIONAL_TYPES = /* @__PURE__ */ new Set(["feat", "fix", "perf", "revert"]);
+var CONVENTIONAL_TYPE_RE = /^([a-z]+)(?:!|\([^)]*\))*:/;
+function firstLine(message) {
+  return message.split("\n", 1)[0] ?? "";
+}
+function isBreakingCommitMessage(message) {
+  return BREAKING_SUBJECT_RE.test(firstLine(message)) || BREAKING_FOOTER_RE.test(message);
+}
+function isCiCommitMessage(message) {
+  return CI_SUBJECT_RE.test(firstLine(message));
+}
+function isBreakingTitle(title) {
+  return BREAKING_SUBJECT_RE.test(title.trim());
+}
+function isCiTitle(title) {
+  return CI_SUBJECT_RE.test(title.trim());
+}
+function mayCarryBreakingMarker(title) {
+  const type = CONVENTIONAL_TYPE_RE.exec(title.trim())?.[1];
+  return type !== void 0 && FUNCTIONAL_TYPES.has(type);
+}
+
+// src/stacked-base.ts
+var DEFAULT_EXEMPT_BASE_LABELS = ["release", "epic"];
+function isExemptBasePr(basePr, exemptLabels) {
+  const exempt = new Set(exemptLabels.map((l) => l.trim().toLowerCase()));
+  return basePr.labels.some((l) => exempt.has(l.trim().toLowerCase()));
+}
+function stackedParentPr({
+  baseBranch,
+  defaultBranch,
+  basePr,
+  exemptLabels
+}) {
+  if (!defaultBranch) return null;
+  if (!baseBranch || baseBranch === defaultBranch) return null;
+  if (!basePr) return null;
+  if (isExemptBasePr(basePr, exemptLabels)) return null;
+  return basePr.number;
+}
+function stackedBaseReason(baseBranch, parentPr) {
+  return `This PR targets \`${baseBranch}\`, the head of open PR #${parentPr} \u2014 it is stacked and must not merge until that PR does. Once #${parentPr} merges, GitHub retargets this PR to the default branch and it merges normally. Review and fixes proceed meanwhile; only the merge is held.`;
+}
+
+// src/reasons.ts
+var BREAKING_DIFF_REASONS = {
+  "major-version-bump": "dependency major bump",
+  "sensitive-package-bump": "CI-sensitive package version change",
+  "material-test-changes": "existing test file modified"
+};
+function nestedBullets(items) {
+  return items.map((item) => `  - ${item}`).join("\n");
+}
+function formatBaseCommit(commit) {
+  return `${commit.sha.slice(0, 7)} ${commit.subject}`;
+}
+function withDetail(sentence, detail) {
+  return detail.length ? `${sentence}
+${nestedBullets(detail)}` : sentence;
+}
+function breakingSignalDetail(signals) {
+  return signals.flatMap((s) => s.detail.map((d) => `${BREAKING_DIFF_REASONS[s.kind]}: ${d}`));
+}
+
+// src/breaking-diff.ts
+var CI_SENSITIVE_PACKAGES = /* @__PURE__ */ new Set(["eslint", "black", "pylint", "ruff", "prettier"]);
+var NON_DEPENDENCY_NPM_KEYS = /* @__PURE__ */ new Set(["version"]);
+var NPM_DEP_RE = /"([^"]+)"\s*:\s*"[\^~]?(\d+)\.(\d+)\.(\d+)/;
+var PIP_DEP_RE = /^\s*([A-Za-z0-9][A-Za-z0-9._-]*)\s*(?:==|~=|>=|<=|!=|<|>)\s*(\d+)(?:\.(\d+))?(?:\.(\d+))?/;
+var TEST_FILE_RE = /(\.test\.tsx?|\.spec\.tsx?|test_[^/]*\.py|[^/]*_test\.py)$/;
+var DIFF_HEADER_PATH_RE = / b\/(.+)$/;
+function normalizePackageName(name) {
+  return name.trim().toLowerCase().replace(/[-_.]+/g, "-");
+}
+function dependencyFileKind(diffGitLine) {
+  if (diffGitLine.includes("package.json")) return "npm";
+  if (/requirements[\w./-]*\.txt/.test(diffGitLine)) return "pip";
+  return null;
+}
+function isFileHeader(line) {
+  return line.startsWith("---") || line.startsWith("+++");
+}
+function dependencyChanges(diffText) {
+  const changes = [];
+  let kind = null;
+  for (const line of diffText.split("\n")) {
+    if (line.startsWith("diff --git")) {
+      kind = dependencyFileKind(line);
+      continue;
+    }
+    if (kind === null) continue;
+    if (isFileHeader(line)) continue;
+    if (!line.startsWith("-") && !line.startsWith("+")) continue;
+    const sign = line[0] === "-" ? "-" : "+";
+    const match = (kind === "npm" ? NPM_DEP_RE : PIP_DEP_RE).exec(line.slice(1));
+    if (!match) continue;
+    const name = match[1] ?? "";
+    if (kind === "npm" && NON_DEPENDENCY_NPM_KEYS.has(name.trim().toLowerCase())) continue;
+    const major = Number(match[2] ?? 0);
+    const minor = Number(match[3] ?? 0);
+    const patch = Number(match[4] ?? 0);
+    changes.push({ kind, sign, name, major, version: `${major}.${minor}.${patch}` });
+  }
+  return changes;
+}
+function indexChanges(changes) {
+  const removed = /* @__PURE__ */ new Map();
+  const added = /* @__PURE__ */ new Map();
+  for (const change of changes) {
+    const key = `${change.kind}:${normalizePackageName(change.name)}`;
+    (change.sign === "-" ? removed : added).set(key, change);
+  }
+  return { removed, added };
+}
+function majorVersionBumps(diffText) {
+  const { removed, added } = indexChanges(dependencyChanges(diffText));
+  const bumps = [];
+  for (const [key, addedChange] of added) {
+    const removedChange = removed.get(key);
+    if (removedChange && addedChange.major > removedChange.major) {
+      bumps.push(`${addedChange.name} ${removedChange.version} \u2192 ${addedChange.version}`);
+    }
+  }
+  return bumps;
+}
+function sensitivePackageBumps(diffText) {
+  const { removed, added } = indexChanges(dependencyChanges(diffText));
+  const bumps = [];
+  for (const [key, addedChange] of added) {
+    if (!CI_SENSITIVE_PACKAGES.has(normalizePackageName(addedChange.name))) continue;
+    const removedChange = removed.get(key);
+    if (removedChange && removedChange.version !== addedChange.version) {
+      bumps.push(`${addedChange.name} ${removedChange.version} \u2192 ${addedChange.version}`);
+    }
+  }
+  return bumps;
+}
+function materialTestChanges(diffText) {
+  const changed = [];
+  let file = null;
+  let hasAdds = false;
+  let hasRemoves = false;
+  const flush = () => {
+    if (file && hasAdds && hasRemoves && TEST_FILE_RE.test(file)) changed.push(file);
+  };
+  for (const line of diffText.split("\n")) {
+    if (line.startsWith("diff --git")) {
+      flush();
+      file = DIFF_HEADER_PATH_RE.exec(line)?.[1] ?? null;
+      hasAdds = false;
+      hasRemoves = false;
+      continue;
+    }
+    if (isFileHeader(line)) continue;
+    if (line.startsWith("+")) hasAdds = true;
+    else if (line.startsWith("-")) hasRemoves = true;
+  }
+  flush();
+  return changed;
+}
+function breakingDiffSignals(diffText) {
+  const signals = [];
+  const major = majorVersionBumps(diffText);
+  if (major.length) signals.push({ kind: "major-version-bump", detail: major });
+  const sensitive = sensitivePackageBumps(diffText);
+  if (sensitive.length) signals.push({ kind: "sensitive-package-bump", detail: sensitive });
+  const tests = materialTestChanges(diffText);
+  if (tests.length) signals.push({ kind: "material-test-changes", detail: tests });
+  return signals;
+}
+function hasSignal(signals, kind) {
+  return signals.some((s) => s.kind === kind);
+}
+function signalDetail(signals, kind) {
+  return signals.find((s) => s.kind === kind)?.detail ?? [];
+}
+
+// src/base-health.ts
+var FAILING_CI_CONCLUSIONS = ["failure", "timed_out", "startup_failure"];
+var GITHUB_ACTIONS_APP_SLUG = "github-actions";
+var NON_BUILD_PLATFORM_CHECKS = /* @__PURE__ */ new Set(["dependabot", "dependabot updates"]);
+function isGitHubActionsCheck(check) {
+  return check.appSlug === GITHUB_ACTIONS_APP_SLUG;
+}
+function isNonBuildPlatformCheck(name) {
+  return NON_BUILD_PLATFORM_CHECKS.has(name.trim().toLowerCase());
+}
+function isFailingCiConclusion(conclusion) {
+  return conclusion !== null && FAILING_CI_CONCLUSIONS.includes(conclusion);
+}
+function failingRequiredBaseChecks(checks, requiredContexts) {
+  if (!requiredContexts || requiredContexts.length === 0) return [];
+  const required = new Set(requiredContexts);
+  return checks.filter((c) => required.has(c.name) && isFailingCiConclusion(c.conclusion)).map((c) => c.name);
+}
+function failingFallbackBaseChecks(checks) {
+  return checks.filter(
+    (c) => isGitHubActionsCheck(c) && isFailingCiConclusion(c.conclusion) && !isNonBuildPlatformCheck(c.name)
+  ).map((c) => c.name);
+}
+
+// src/merge-safety.ts
+var MERGE_SAFETY_LABELS = ["update required", "merge conflict"];
+function isEvaluablePrState(state) {
+  return state === "OPEN";
+}
+var HOTFIX_LABEL = "hotfix";
+var BREAKING_LABEL = "breaking change";
+function overlappingFiles(prFiles, baseFiles) {
+  if (!prFiles.length || !baseFiles.length) return [];
+  const base = new Set(baseFiles);
+  return prFiles.filter((f) => base.has(f));
+}
+function evaluateMergeSafety(facts) {
+  const reasons = [];
+  if (facts.hasConflict) {
+    reasons.push("Git reports a merge conflict against the base \u2014 resolve it before merging.");
+  }
+  const stackedOnPr = facts.stackedOnPr;
+  const stackedBarred = stackedOnPr !== null;
+  if (stackedOnPr !== null) reasons.push(stackedBaseReason(facts.baseBranch, stackedOnPr));
+  const baseUnhealthy = facts.baseCiFailing && !facts.prIsHotfix;
+  if (baseUnhealthy) {
+    reasons.push(
+      withDetail(
+        "The base branch's CI is failing \u2014 only hotfix PRs may merge until it is green (label this PR `hotfix` to override):",
+        facts.failingBaseChecks
+      )
+    );
+  }
+  const stale = !facts.isCurrent;
+  if (stale && facts.baseBreakingSinceMergeBase) {
+    reasons.push(
+      withDetail(
+        "A breaking change landed on the base since merge-base \u2014 rebase and re-run CI:",
+        facts.baseBreakingCommits.map(formatBaseCommit)
+      )
+    );
+  }
+  if (stale && facts.prIsBreaking) {
+    reasons.push(
+      withDetail(
+        "This PR is a breaking change \u2014 it must be current with the base before merge.",
+        breakingSignalDetail(facts.prBreakingDiffSignals)
+      )
+    );
+  }
+  if (stale && facts.prIsCi && !facts.prIsHotfix) {
+    reasons.push(
+      "This PR is a CI change \u2014 it must be current with the base before merge, so it is re-tested against the latest base and cannot green a guard against a pattern that has since regressed."
+    );
+  }
+  if (stale && facts.baseCiSinceMergeBase) {
+    reasons.push(
+      withDetail(
+        "A CI change landed on the base since merge-base \u2014 rebase to re-test under it:",
+        facts.baseCiCommits.map(formatBaseCommit)
+      )
+    );
+  }
+  if (stale && facts.fileOverlap) {
+    reasons.push(
+      withDetail(
+        "This PR changes files the base also changed since merge-base \u2014 sync with base and re-run CI before merging to ensure the changes are compatible:",
+        facts.overlappingFiles
+      )
+    );
+  }
+  const needsCiRetitle = hasSignal(facts.prBreakingDiffSignals, "sensitive-package-bump") ? !facts.prIsCi : false;
+  const needsUpdate = stale && (facts.baseBreakingSinceMergeBase || facts.baseCiSinceMergeBase || facts.prIsBreaking || facts.prIsCi && !facts.prIsHotfix || facts.fileOverlap);
+  if (needsCiRetitle) {
+    reasons.push(
+      withDetail(
+        "This PR changes a CI-sensitive package version, which can redden the format/lint gate on PRs that never touched the bumped file. Retitle it with the `ci` type (e.g. `ci(deps): \u2026`) so merged siblings are forced to re-test under it \u2014 a `breaking change` label cannot carry this signal on a non-functional type:",
+        signalDetail(facts.prBreakingDiffSignals, "sensitive-package-bump")
+      )
+    );
+  }
+  const needsAction = facts.hasConflict || baseUnhealthy || needsCiRetitle || stackedBarred;
+  const conclusion = needsAction ? "failure" : needsUpdate ? "pending" : "success";
+  const summary = conclusion === "success" ? "No update required: current, or no breaking/overlapping changes on the base, no conflict, and the base CI is green." : firstLine(reasons[0] ?? "Not safe to merge as-is.");
+  const title = facts.hasConflict ? "Merge conflict" : stackedBarred ? "Base PR not merged" : baseUnhealthy ? "Base CI failing" : needsUpdate ? "Update required" : needsCiRetitle ? "Retitle as a CI change" : "No update required";
+  const add = [];
+  if (needsUpdate) add.push("update required");
+  if (facts.hasConflict) add.push("merge conflict");
+  const remove = MERGE_SAFETY_LABELS.filter((l) => !add.includes(l));
+  const addOnly = [];
+  if (hasSignal(facts.prBreakingDiffSignals, "major-version-bump") && facts.prMayCarryBreakingMarker)
+    addOnly.push(BREAKING_LABEL);
+  return {
+    conclusion,
+    needsUpdate,
+    hasConflict: facts.hasConflict,
+    baseUnhealthy,
+    needsCiRetitle,
+    stackedBarred,
+    title,
+    reasons,
+    summary,
+    labels: { add, remove, addOnly }
+  };
+}
+function errorMergeSafetyDecision(message) {
+  return {
+    conclusion: "failure",
+    needsUpdate: false,
+    hasConflict: false,
+    baseUnhealthy: false,
+    needsCiRetitle: false,
+    stackedBarred: false,
+    title: "Could not evaluate",
+    reasons: [message],
+    summary: `Could not evaluate merge safety: ${message}`,
+    labels: { add: [], remove: [], addOnly: [] }
+  };
+}
+
+// src/merge-safety-facts.ts
+var GIT_TIMEOUT_MS = 3e4;
+function baseBranchName(baseRef) {
+  return baseRef.replace(/^refs\/heads\//, "").replace(/^origin\//, "");
+}
+function makeGitRunner(cwd) {
+  return async (args) => {
+    const r = await boundedRun("git", args, { timeoutMs: GIT_TIMEOUT_MS, cwd });
+    return r.code === 0 ? r.stdout : null;
+  };
+}
+function splitLines(out) {
+  return (out ?? "").split("\n").map((l) => l.trim()).filter(Boolean);
+}
+function parseBaseCommits(logOut) {
+  return logOut.split("\0").map((record) => record.replace(/^\n+/, "")).filter((record) => record.trim().length > 0).map((record) => {
+    const newline = record.indexOf("\n");
+    const sha = (newline === -1 ? record : record.slice(0, newline)).trim();
+    const message = newline === -1 ? "" : record.slice(newline + 1).trim();
+    return { sha, message };
+  });
+}
+function selectCommits(commits, predicate) {
+  return commits.filter((c) => predicate(c.message)).map((c) => ({ sha: c.sha, subject: c.message.split("\n", 1)[0] ?? "" }));
+}
+async function gatherMergeSafetyFacts(meta, {
+  baseRef = "origin/main",
+  git,
+  baseChecks,
+  requiredChecks,
+  basePr = async () => null,
+  defaultBranch = null,
+  exemptBaseLabels = DEFAULT_EXEMPT_BASE_LABELS
+}) {
+  const mergeBase = (await git(["merge-base", meta.headSha, baseRef]))?.trim();
+  const baseTip = (await git(["rev-parse", baseRef]))?.trim();
+  if (!mergeBase || !baseTip) {
+    throw new Error(`could not resolve merge-base/base tip for ${meta.headSha}..${baseRef}`);
+  }
+  const isCurrent = mergeBase === baseTip;
+  const baseBranch = baseBranchName(baseRef);
+  const checks = await baseChecks(baseTip);
+  const required = await requiredChecks(baseBranch);
+  const failingBaseChecks = required && required.length > 0 ? failingRequiredBaseChecks(checks, required) : failingFallbackBaseChecks(checks);
+  const logOut = await git(["log", "-z", "--format=%H%n%B", `${mergeBase}..${baseRef}`]);
+  if (logOut === null) throw new Error(`git log failed for ${mergeBase}..${baseRef}`);
+  const commits = parseBaseCommits(logOut);
+  const baseBreakingCommits = selectCommits(commits, isBreakingCommitMessage);
+  const baseCiCommits = selectCommits(commits, isCiCommitMessage);
+  const baseFilesOut = await git(["diff", "--name-only", mergeBase, baseRef]);
+  if (baseFilesOut === null) throw new Error(`git diff failed for ${mergeBase}..${baseRef}`);
+  const baseFiles = splitLines(baseFilesOut);
+  const prFilesOut = await git(["diff", "--name-only", mergeBase, meta.headSha]);
+  if (prFilesOut === null) throw new Error(`git diff failed for ${mergeBase}..${meta.headSha}`);
+  const prFiles = splitLines(prFilesOut);
+  const overlaps = overlappingFiles(prFiles, baseFiles);
+  const prDiff = await git(["diff", "--unified=0", mergeBase, meta.headSha]);
+  if (prDiff === null) throw new Error(`git diff failed for ${mergeBase}..${meta.headSha}`);
+  const diffSignals = breakingDiffSignals(prDiff);
+  const parentPr = defaultBranch && baseBranch !== defaultBranch ? await basePr(baseBranch) : null;
+  const stackedOnPr = stackedParentPr({
+    baseBranch,
+    defaultBranch,
+    basePr: parentPr,
+    exemptLabels: exemptBaseLabels
+  });
+  const labels = meta.labels.map((l) => l.toLowerCase());
+  return {
+    isCurrent,
+    // Each boolean is derived from its detail list — one computation, two views.
+    baseBreakingSinceMergeBase: baseBreakingCommits.length > 0,
+    baseCiSinceMergeBase: baseCiCommits.length > 0,
+    // Additive by construction: the title marker and the label remain inputs, and
+    // the diff can only ever add a reason to treat the PR as breaking (#53).
+    prIsBreaking: isBreakingTitle(meta.title) || labels.includes(BREAKING_LABEL) || diffSignals.length > 0,
+    prIsCi: isCiTitle(meta.title),
+    fileOverlap: overlaps.length > 0,
+    hasConflict: meta.mergeable.toUpperCase() === "CONFLICTING",
+    baseCiFailing: failingBaseChecks.length > 0,
+    prIsHotfix: labels.includes(HOTFIX_LABEL),
+    baseBreakingCommits,
+    baseCiCommits,
+    overlappingFiles: overlaps,
+    failingBaseChecks,
+    prBreakingDiffSignals: diffSignals,
+    prMayCarryBreakingMarker: mayCarryBreakingMarker(meta.title),
+    baseBranch,
+    stackedOnPr
+  };
+}
+
+// src/bin/merge-safety.ts
+var DEFAULT_CALLER_WORKFLOW = "merge-safety.yml";
+function usage() {
+  console.error(
+    "usage: ai-merge-safety evaluate --pr <n> [--json] [--repo <o/r>] [--base <ref>] [--cwd <path>]\n                                 [--default-branch <name>] [--exempt-base-labels <csv>]\n       ai-merge-safety invalidate [--workflow <file>] [--exclude <n>] [--repo <o/r>] [--cwd <path>]"
+  );
+  process.exit(2);
+}
+function parse(argv) {
+  const mode = argv[0];
+  if (!isMergeSafetyCommand(mode)) usage();
+  const args = {
+    mode,
+    baseRef: "origin/main",
+    workflow: DEFAULT_CALLER_WORKFLOW,
+    exemptBaseLabels: DEFAULT_EXEMPT_BASE_LABELS,
+    json: false
+  };
+  for (let i = 1; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--pr") args.pr = Number(argv[++i]);
+    else if (a === "--exclude") args.exclude = Number(argv[++i]);
+    else if (a === "--repo") args.repo = argv[++i];
+    else if (a === "--base") args.baseRef = argv[++i] ?? args.baseRef;
+    else if (a === "--workflow") args.workflow = argv[++i] ?? args.workflow;
+    else if (a === "--cwd") args.cwd = argv[++i];
+    else if (a === "--default-branch") args.defaultBranch = argv[++i];
+    else if (a === "--exempt-base-labels")
+      args.exemptBaseLabels = (argv[++i] ?? "").split(",").map((l) => l.trim()).filter(Boolean);
+    else if (a === "--json" || a === "--dry-run") args.json = true;
+    else usage();
+  }
+  if (mode === "evaluate" && !args.pr) usage();
+  if (args.json && mode !== "evaluate") usage();
+  return args;
+}
+async function ghJson(argv, cwd) {
+  const out = await ghCall({ argv }, null, { cwd });
+  if (out === null) return null;
+  try {
+    return JSON.parse(out);
+  } catch {
+    return null;
+  }
+}
+function makeBaseChecksProbe(repo, cwd) {
+  return async (baseSha) => {
+    const out = await ghCall(
+      {
+        argv: [
+          "gh",
+          "api",
+          "--paginate",
+          `repos/${repo}/commits/${baseSha}/check-runs?filter=latest`,
+          "--jq",
+          ".check_runs[] | {name: .name, conclusion: .conclusion, appSlug: .app.slug}"
+        ]
+      },
+      null,
+      { cwd }
+    );
+    if (!out) return [];
+    const checks = [];
+    for (const line of out.split("\n")) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      try {
+        const c = JSON.parse(trimmed);
+        checks.push({ name: c.name, conclusion: c.conclusion, appSlug: c.appSlug });
+      } catch {
+      }
+    }
+    return checks;
+  };
+}
+function makeRequiredChecksProbe(repo, cwd) {
+  return async (baseBranch) => {
+    const out = await ghCall(
+      {
+        argv: [
+          "gh",
+          "api",
+          "--paginate",
+          `repos/${repo}/rules/branches/${encodeURIComponent(baseBranch)}`,
+          "--jq",
+          '.[] | select(.type == "required_status_checks") | .parameters.required_status_checks[].context'
+        ]
+      },
+      null,
+      { cwd }
+    );
+    if (out === null) return null;
+    const contexts = out.split("\n").map((l) => l.trim()).filter(Boolean);
+    return [...new Set(contexts)];
+  };
+}
+function makeBasePrProbe(repo, cwd) {
+  return async (baseBranch) => {
+    const prs = await ghJson(
+      [
+        "gh",
+        "pr",
+        "list",
+        "--repo",
+        repo,
+        "--state",
+        "open",
+        "--head",
+        baseBranch,
+        "--limit",
+        "1",
+        "--json",
+        "number,labels"
+      ],
+      cwd
+    );
+    const pr = prs?.[0];
+    if (!pr) return null;
+    return { number: pr.number, labels: (pr.labels ?? []).map((l) => l.name) };
+  };
+}
+async function resolveDefaultBranch(repo, override, cwd) {
+  if (override) return override;
+  const view = await ghJson(
+    ["gh", "repo", "view", repo, "--json", "defaultBranchRef"],
+    cwd
+  );
+  return view?.defaultBranchRef?.name ?? null;
+}
+async function fetchPrView(repo, pr, cwd) {
+  const fields = "number,headRefOid,title,labels,mergeable,state";
+  for (let attempt = 0; attempt < 3; attempt++) {
+    const view = await ghJson(
+      ["gh", "pr", "view", String(pr), "--repo", repo, "--json", fields],
+      cwd
+    );
+    if (!view) return null;
+    if (view.mergeable !== "UNKNOWN" || attempt === 2) return view;
+    await new Promise((r) => setTimeout(r, 2e3));
+  }
+  return null;
+}
+async function reconcileLabels(repo, pr, add, remove, cwd) {
+  if (add.length) await addLabels(repo, pr, [...add], { cwd });
+  for (const label of remove) await removeLabel(repo, pr, label, { cwd });
+}
+async function runEvaluate(repo, pr, args) {
+  const view = await fetchPrView(repo, pr, args.cwd);
+  if (!view) {
+    const msg = `could not read PR #${pr}`;
+    if (args.json) return emitDecisionJson(errorMergeSafetyDecision(msg), true);
+    throw new Error(msg);
+  }
+  if (!isEvaluablePrState(view.state)) {
+    console.log(`#${pr}: ${view.state.toLowerCase()} \u2014 skipping merge-safety evaluate`);
+    return;
+  }
+  const meta = {
+    headSha: view.headRefOid,
+    title: view.title,
+    labels: view.labels.map((l) => l.name),
+    mergeable: view.mergeable
+  };
+  let decision;
+  try {
+    const facts = await gatherMergeSafetyFacts(meta, {
+      baseRef: args.baseRef,
+      git: makeGitRunner(args.cwd),
+      baseChecks: makeBaseChecksProbe(repo, args.cwd),
+      requiredChecks: makeRequiredChecksProbe(repo, args.cwd),
+      basePr: makeBasePrProbe(repo, args.cwd),
+      defaultBranch: await resolveDefaultBranch(repo, args.defaultBranch, args.cwd),
+      exemptBaseLabels: args.exemptBaseLabels
+    });
+    decision = evaluateMergeSafety(facts);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    const failed = errorMergeSafetyDecision(msg);
+    if (args.json) return emitDecisionJson(failed, true);
+    await postCheck(
+      repo,
+      meta.headSha,
+      { title: failed.title, summary: failed.summary },
+      "failure",
+      args.cwd
+    );
+    console.error(`#${pr}: failure \u2014 could not evaluate: ${msg}`);
+    process.exitCode = 1;
+    return;
+  }
+  if (args.json) return emitDecisionJson(decision, false);
+  const detail = decision.reasons.length ? decision.reasons.map((r) => `- ${r}`).join("\n") : decision.summary;
+  await postCheck(
+    repo,
+    meta.headSha,
+    { title: decision.title, summary: `${decision.summary}
+
+${detail}` },
+    decision.conclusion,
+    args.cwd
+  );
+  await reconcileLabels(
+    repo,
+    pr,
+    [...decision.labels.add, ...decision.labels.addOnly],
+    decision.labels.remove,
+    args.cwd
+  );
+  console.log(`#${pr}: ${decision.conclusion} \u2014 ${decision.summary}`);
+}
+function emitDecisionJson(decision, isError) {
+  console.log(JSON.stringify(decision, null, 2));
+  if (isError) process.exitCode = 1;
+}
+async function runInvalidate(repo, args) {
+  const prs = await ghJson(
+    [
+      "gh",
+      "pr",
+      "list",
+      "--repo",
+      repo,
+      "--state",
+      "open",
+      "--base",
+      "main",
+      "--limit",
+      "1000",
+      "--json",
+      "number,headRefOid"
+    ],
+    args.cwd
+  );
+  if (!prs) throw new Error("could not list open PRs");
+  for (const pr of prs) {
+    if (pr.number === args.exclude) continue;
+    await postCheck(
+      repo,
+      pr.headRefOid,
+      { title: "Re-evaluating", summary: "Re-evaluating against the updated base\u2026" },
+      "pending",
+      args.cwd
+    );
+    await ghCall(
+      {
+        argv: ["gh", "workflow", "run", args.workflow, "--repo", repo, "-f", `pr=${pr.number}`]
+      },
+      null,
+      { cwd: args.cwd }
+    );
+    console.log(`#${pr.number}: invalidated (pending) + evaluate dispatched`);
+  }
+}
+async function main() {
+  const args = parse(process.argv.slice(2));
+  const repo = await resolveRepoTarget({ repo: args.repo, cwd: args.cwd });
+  if (!repo) {
+    console.error("error: could not resolve target repo (pass --repo <owner/repo>)");
+    process.exit(2);
+  }
+  if (args.mode === "evaluate") await runEvaluate(repo, args.pr, args);
+  else await runInvalidate(repo, args);
+}
+function isDirectRun() {
+  const entry = process.argv[1];
+  if (!entry) return false;
+  try {
+    return realpathSync(entry) === fileURLToPath(import.meta.url);
+  } catch {
+    return false;
+  }
+}
+if (isDirectRun()) void main();
+export {
+  makeBaseChecksProbe,
+  makeBasePrProbe,
+  makeRequiredChecksProbe,
+  runEvaluate,
+  runInvalidate
+};

package/dist/chunk-ITPKHZGC.js

@@ -0,0 +1,12 @@
+// src/index.ts
+var MERGE_SAFETY_CHECK_NAME = "merge-safety";
+var MERGE_SAFETY_COMMANDS = ["evaluate", "invalidate"];
+function isMergeSafetyCommand(value) {
+  return value !== void 0 && MERGE_SAFETY_COMMANDS.includes(value);
+}
+
+export {
+  MERGE_SAFETY_CHECK_NAME,
+  MERGE_SAFETY_COMMANDS,
+  isMergeSafetyCommand
+};

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @rmartz/merge-safety — public entry point.
+ *
+ * Encodes the package's stable public contract: the `merge-safety` check-run
+ * name and the CLI command surface. The evaluate/invalidate implementation
+ * (`merge-safety.ts` + `merge-safety-facts.ts` and the `ai-merge-safety` bin)
+ * lives alongside it; this module is intentionally the narrow, frozen surface
+ * consumers and the reusable workflow depend on.
+ */
+/**
+ * The name of the check-run merge-safety posts for each PR.
+ *
+ * This is a **fleet contract**, not an internal label: every consumer repo
+ * configures a *required status check* of exactly this name, and the auto-merge
+ * gate (`goldenGateChecks`) keys off it. Renaming it is a coordinated fleet
+ * migration (every consumer's required-check config + the auto-merge verifier +
+ * the gate floor, all at once), never a local edit. See
+ * docs/check-run-contract.md.
+ */
+declare const MERGE_SAFETY_CHECK_NAME = "merge-safety";
+/**
+ * The two operations the `ai-merge-safety` CLI dispatches:
+ * - `evaluate` — gather base-currency + breaking-change + conflict facts for one
+ *   PR, post the `merge-safety` check-run, and reconcile the update-required /
+ *   merge-conflict labels.
+ * - `invalidate` — on a push to the base branch, flip every *other* open PR's
+ *   check to pending and re-dispatch its `evaluate`, so a moved base holds native
+ *   auto-merge until each PR re-clears.
+ */
+declare const MERGE_SAFETY_COMMANDS: readonly ["evaluate", "invalidate"];
+type MergeSafetyCommand = (typeof MERGE_SAFETY_COMMANDS)[number];
+/** Type guard for the CLI command surface. */
+declare function isMergeSafetyCommand(value: string | undefined): value is MergeSafetyCommand;
+
+export { MERGE_SAFETY_CHECK_NAME, MERGE_SAFETY_COMMANDS, type MergeSafetyCommand, isMergeSafetyCommand };

package/dist/index.js

@@ -0,0 +1,10 @@
+import {
+  MERGE_SAFETY_CHECK_NAME,
+  MERGE_SAFETY_COMMANDS,
+  isMergeSafetyCommand
+} from "./chunk-ITPKHZGC.js";
+export {
+  MERGE_SAFETY_CHECK_NAME,
+  MERGE_SAFETY_COMMANDS,
+  isMergeSafetyCommand
+};

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@rmartz/merge-safety",
+  "version": "0.6.0",
+  "description": "The pre-auto-merge safety verdict for a PR (base-currency, breaking-change, and conflict facts), posted as the `merge-safety` check-run and distributed via a reusable workflow kept current by Dependabot.",
+  "keywords": [
+    "ci",
+    "merge-safety",
+    "auto-merge",
+    "github-actions",
+    "reusable-workflow",
+    "check-run"
+  ],
+  "homepage": "https://github.com/rmartz/merge-safety#readme",
+  "bugs": {
+    "url": "https://github.com/rmartz/merge-safety/issues"
+  },
+  "type": "module",
+  "packageManager": "pnpm@9.12.0",
+  "engines": {
+    "node": ">=20.11.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "ai-merge-safety": "./dist/bin/merge-safety.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "@rmartz:registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rmartz/merge-safety.git"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "verify:release-notes": "node scripts/verify-changelog-render.mjs"
+  },
+  "devDependencies": {
+    "@semantic-release/release-notes-generator": "^14.1.1",
+    "@types/node": "^26.6.2",
+    "@typescript-eslint/eslint-plugin": "^8.70.0",
+    "@typescript-eslint/parser": "^8.70.0",
+    "@vitest/coverage-v8": "^5.0.1",
+    "conventional-changelog-conventionalcommits": "^9.3.1",
+    "eslint": "^10.11.0",
+    "eslint-import-resolver-typescript": "^4.4.5",
+    "eslint-plugin-import": "^2.32.0",
+    "prettier": "^3.9.8",
+    "semantic-release": "^25.0.9",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "vite": "^8.3.0",
+    "vitest": "^5.0.1"
+  },
+  "pnpm": {
+    "overrides": {
+      "esbuild": ">=0.28.1"
+    }
+  }
+}