@rmartz/merge-safety 0.14.0 → 0.16.0

package/dist/index.d.ts

@@ -1,11 +1,367 @@
+/**
+ * Breaking-change detection over a PR's **own** unified diff (#53).
+ *
+ * Until now `prIsBreaking` was read entirely from the PR title's `!` marker or a
+ * `breaking change` label an LLM turn applies (`/review` Step 5 in the coordinator,
+ * which shells to `breaking-change.py check-diff`). That made a *required,
+ * merge-gating* check depend on a non-deterministic producer, and it failed in the
+ * **permissive** direction: no `/review` run, or a reviewer who misread the diff,
+ * and the PR was evaluated as non-breaking. These detectors are pure functions over
+ * a diff, so the check derives the fact itself; the title `!` marker is the only
+ * declared input alongside it — the label is never read.
+ *
+ * Ported from `claude/scripts/breaking_change.py` in `rmartz/dotfiles`
+ * (`has_major_version_bump` / `has_sensitive_package_bump` /
+ * `has_material_test_changes`). Each returns the *specific* packages or files that
+ * tripped it rather than a bare boolean, so the check-run can name them — the same
+ * "one computation, two views" shape the base-commit and file-overlap facts use.
+ *
+ * Deliberately NOT ported: `add_breaking_marker` / `remove_breaking_marker` /
+ * `reconcile_breaking_title`, which rewrite the PR *title* inside the squash-merge
+ * transaction (with the release-please exemption). Detection moves here; stamping
+ * stays in `merge-pr.py`, at a moment a PR-event action cannot reach.
+ */
+/** The kinds of breaking signal a PR's own diff can carry. */
+declare const BREAKING_DIFF_KINDS: readonly ["major-version-bump", "sensitive-package-bump", "material-test-changes"];
+type BreakingDiffKind = (typeof BREAKING_DIFF_KINDS)[number];
+/** One fired detector, with the packages / files that tripped it. */
+interface BreakingDiffSignal {
+    kind: BreakingDiffKind;
+    /** The specific package names or file paths, surfaced in the check-run reason. */
+    detail: string[];
+}
+
+/**
+ * Reason presentation for the merge-safety check-run — how a verdict's facts are
+ * rendered as the human-readable lines the check-run output carries.
+ *
+ * Split from `merge-safety.ts` (the verdict *logic*) so each stays under its
+ * `max-lines` cap as axes accumulate (#53 added the diff-derived breaking
+ * signals). Presentation is a genuinely separate concern —
+ * nothing here decides anything, it only formats.
+ */
+
+/** A base commit surfaced in a reason so the report names *which* commit triggered it. */
+interface BaseCommit {
+    /** The full commit SHA (rendered abbreviated in the report). */
+    sha: string;
+    /** The commit subject (first line of its message). */
+    subject: 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;
+}
+
+/**
+ * Merge-safety predicate — "is this PR safe to merge *as it stands*, or must it
+ * first be brought current against its base branch and re-run through CI?"
+ *
+ * This is the coordinator's `_pr_needs_branch_update` decision, lifted into a
+ * pure, side-effect-free function so it can be shared by two callers: PR Shepherd
+ * (which merges) and the `merge-safety` GitHub check (which *surfaces* the
+ * verdict as a required status so it's visible on the PR and can gate auto-merge).
+ * It knows nothing about posting, check-runs, or PR Shepherd's gate labels — it
+ * maps gathered *facts* to a verdict, and the caller owns the emission channel.
+ *
+ * The rule (a PR **must be brought current** when it is not already current AND):
+ *   1. a **breaking** commit landed on the base since the PR's merge-base **and the
+ *      PR is not a (non-breaking) `docs` PR**, OR
+ *   2. a **CI** commit landed on the base since merge-base — `ci`-typed, or one
+ *      that changed `.github/workflows/**` / `.github/actions/**` (#67) — (the
+ *      coordinator rebases in-flight PRs past CI changes, by prefix or path), OR
+ *   3. the PR is **itself** a breaking change **and the base has moved by more than
+ *      `docs` commits alone**, OR
+ *   4. the PR is **itself** a CI change (`ci`-typed, or its diff touches those
+ *      paths) **and is not a hotfix** — a CI
+ *      guard is only as good as the base it last ran against, so a CI PR that was
+ *      clean when it was opened must be re-tested against the current base to
+ *      catch a pattern the guard protects against that has regressed on the base
+ *      since (the symmetric partner to clause 2's base-side detection). The
+ *      `hotfix` label exempts *this* clause — a CI fix for a base whose own CI is
+ *      red can be caught in a bind (base health blocks it unless it is a hotfix,
+ *      and being forced current may itself be impossible or pointless while the
+ *      base is broken), so `hotfix` frees it here just as it frees the base-health
+ *      axis. The exemption is deliberately *this-PR-is-itself-CI*-only: it does
+ *      not touch clause 3 (`prIsBreaking`) or the base-side clauses (1, 2, 5),
+ *      which guard against real incompatibilities a hotfix must still rebase past,
+ *      OR
+ *   5. the PR's changed files **intersect** the files changed on the base since
+ *      merge-base.
+ *
+ * The `docs` carve-outs on clauses 1 and 3 (a breaking and a docs change interact
+ * only through a shared file; CI changes get no such carve-out) are explained in
+ * `staleness.ts`, which evaluates clauses 1–5.
+ *
+ * Clause 5 is a *narrowing* guard, not a widening one: it only ever forces more
+ * PRs current. Git can merge two disjoint-looking diffs cleanly and still produce
+ * invalid code (an earlier PR deletes a symbol this PR still references), so any
+ * file-level overlap forces a rebase + re-CI to catch the semantic conflict a
+ * clean textual merge hides.
+ *
+ * A hard git **conflict** is a separate axis from staleness — GitHub blocks such
+ * a merge regardless — but the verdict folds it in so a single check answers "is
+ * it safe to merge right now?", with a distinct label for visibility.
+ *
+ * **Base health** is a third, PR-independent axis: when the base branch's own CI
+ * is failing, merging anything but a fix onto it only compounds a broken base, so
+ * a PR is held **unless it is a hotfix** (the `hotfix` label is the escape hatch
+ * that lets the fix for broken main through). "Failing CI" is read expansively —
+ * any failing GitHub Actions run on the base counts — but a failing *deploy* does
+ * not: a red deploy under green Actions is likelier an external/environmental
+ * fault no code change can fix, so it must not wedge the whole merge queue.
+ *
+ * **The breaking verdict reads the title and the diff, never a label** (#82).
+ * `prIsBreaking` is the PR title's `!` marker or a breaking signal in the PR's own
+ * diff (`breaking-diff.ts`, #53). Whether a PR *should* carry `!` — the
+ * `breaking change` label, a dependency major bump, a linter bump's `ci` type — is
+ * title policy, enforced by pr-policy's title check; this check only consumes the
+ * resulting title and never reads or writes a label for it.
+ */
+
+/** Labels the check drives on a PR. Structural (`as const`) per repo convention. */
+declare const MERGE_SAFETY_LABELS: readonly ["update required", "merge conflict"];
+type MergeSafetyLabel = (typeof MERGE_SAFETY_LABELS)[number];
+/**
+ * The gathered facts a merge-safety verdict is computed from. The `*SinceMergeBase`
+ * / `fileOverlap` booleans drive the verdict; the parallel `baseBreakingCommits` /
+ * `baseCiCommits` / `overlappingFiles` detail lists name *which* base commits and
+ * files triggered each, so the report can surface the specifics. Each boolean is
+ * exactly `list.length > 0` — the gatherer derives it from the list.
+ */
+interface MergeSafetyFacts {
+    /** The PR's merge-base is the current base-branch tip — nothing is stale. */
+    isCurrent: boolean;
+    /** A breaking commit landed on the base since the PR's merge-base. */
+    baseBreakingSinceMergeBase: boolean;
+    /** A CI commit (`ci`-typed, or touching a CI path) landed on the base since merge-base. */
+    baseCiSinceMergeBase: boolean;
+    /** The PR is itself a breaking change: its title's `!` marker or a diff-derived signal. */
+    prIsBreaking: boolean;
+    /**
+     * The PR title is a `docs:` / `docs(scope):` conventional commit. A non-breaking
+     * docs PR is exempt from the base-breaking clause (a breaking base change only
+     * forces it current through a shared file, via `fileOverlap`).
+     */
+    prIsDocs: boolean;
+    /**
+     * The base moved since merge-base, and **every** commit it moved by is
+     * `docs`-typed. Exempts the `prIsBreaking` clause: a breaking PR behind only docs
+     * commits need not be brought current unless the files overlap.
+     */
+    baseOnlyDocsSinceMergeBase: boolean;
+    /**
+     * The PR is itself a CI change: title `ci:` / `ci(scope):`, or its own diff
+     * changes `.github/workflows/**` / `.github/actions/**` (#67).
+     */
+    prIsCi: boolean;
+    /** The PR's changed files intersect the base's changed files since merge-base. */
+    fileOverlap: boolean;
+    /** Git reports the PR as conflicting (`mergeable === 'CONFLICTING'`). */
+    hasConflict: boolean;
+    /** The base branch tip has at least one failing GitHub Actions CI check. */
+    baseCiFailing: boolean;
+    /**
+     * The PR carries the `hotfix` label, exempting it from the base-CI-failing axis
+     * *and* from the `prIsCi` update-required clause (a hotfix CI fix for a red base
+     * is not forced current). It does not exempt `prIsBreaking` or the base-side
+     * clauses.
+     */
+    prIsHotfix: boolean;
+    /** The base commits since merge-base whose message marks a breaking change. */
+    baseBreakingCommits: readonly BaseCommit[];
+    /** The CI base commits (`ci`-typed, or touching a CI path) since merge-base. */
+    baseCiCommits: readonly BaseCommit[];
+    /** The PR's changed files that also changed on the base since merge-base. */
+    overlappingFiles: readonly string[];
+    /** The names of the failing base CI checks, surfaced in the base-health reason. */
+    failingBaseChecks: readonly string[];
+    /**
+     * The breaking signals the PR's **own diff** carries (#53) — a dependency major
+     * bump, a CI-sensitive linter/formatter version change, or material changes to
+     * existing tests. These feed `prIsBreaking` alongside the title marker, so a PR
+     * that changes something risky is re-tested against a moved base even when its
+     * title is unmarked.
+     */
+    prBreakingDiffSignals: readonly BreakingDiffSignal[];
+}
+/**
+ * `pending` is posted as an incomplete (`in_progress`) check-run: it blocks the
+ * merge like `failure` but renders as a yellow dot, not a red ✗ (#58).
+ */
+type MergeSafetyConclusion = 'success' | 'failure' | 'pending';
+interface MergeSafetyDecision {
+    /**
+     * The check-run conclusion: `success` iff safe to merge as-is; `pending` when the
+     * only problem is staleness, which a branch update clears; otherwise `failure`.
+     */
+    conclusion: MergeSafetyConclusion;
+    /** The PR must be brought current before merge (the staleness axis). */
+    needsUpdate: boolean;
+    /** The PR has a hard git conflict (the mergeability axis). */
+    hasConflict: boolean;
+    /** Blocked because the base's CI is failing and this PR is not a hotfix (the base-health axis). */
+    baseUnhealthy: boolean;
+    /**
+     * Short state phrase for the check-run title — the verdict at a glance. One of
+     * `No update required` / `Update required` / `Merge conflict` / `Base CI
+     * failing` / `Could not evaluate`. The check-run
+     * *name* stays the stable `merge-safety` (so branch
+     * protection can match it); this varies with the outcome instead.
+     */
+    title: string;
+    /** Ordered most→least severe, human-readable — the check-run output detail. */
+    reasons: string[];
+    /** One-line check-run summary. */
+    summary: string;
+    /**
+     * Labels the check drives.
+     *
+     * `add` / `remove` are **reconciled**: the check owns `update required` and
+     * `merge conflict` outright, adding the ones that apply and removing the rest.
+     */
+    labels: {
+        add: MergeSafetyLabel[];
+        remove: MergeSafetyLabel[];
+    };
+}
+/**
+ * Map gathered {@link MergeSafetyFacts} to a {@link MergeSafetyDecision}. Pure:
+ * the same facts always yield the same verdict. A PR that is already current is
+ * always safe on the staleness axis — a stale trigger can only matter when the
+ * PR is behind — so the update clauses are gated on `!isCurrent`.
+ */
+declare function evaluateMergeSafety(facts: MergeSafetyFacts): MergeSafetyDecision;
+/**
+ * The verdict for a PR whose facts could not be gathered (bad merge-base, a git
+ * command that failed, an unreadable PR). Fail-safe: `failure`, so a consumer
+ * that trusts the verdict treats an ungatherable PR as unsafe rather than green.
+ * `needsUpdate` / `hasConflict` stay `false` because they are genuinely unknown —
+ * the `failure` conclusion is what carries the safety, not a fabricated axis. No
+ * labels are proposed: an ungatherable state is not evidence for adding or
+ * removing either label.
+ */
+declare function errorMergeSafetyDecision(message: string): MergeSafetyDecision;
+
+/** Runs a `git` argv and yields stdout, or `null` on non-zero exit / failure. */
+type GitRunner = (args: string[]) => Promise<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>;
+/** The real `git` runner, bounded and rooted at `cwd`. */
+declare function makeGitRunner(cwd?: string): GitRunner;
+/** PR metadata the gatherer needs beyond what git derives (from `gh pr view --json`). */
+interface PrMergeMeta {
+    headSha: string;
+    title: string;
+    labels: readonly string[];
+    /** `gh`'s `mergeable`: `MERGEABLE` | `CONFLICTING` | `UNKNOWN`. */
+    mergeable: string;
+}
+interface GatherOptions {
+    /** Base branch ref to compare against (default `origin/main`). */
+    baseRef?: string;
+    git: GitRunner;
+    /** Probe for the base tip's check-runs, used to judge base health. */
+    baseChecks: BaseChecksProbe;
+    /** Probe for the base branch's required status checks, scoping base health (#40). */
+    requiredChecks: RequiredChecksProbe;
+}
+/**
+ * Assemble {@link MergeSafetyFacts} for one PR. Throws when the merge-base or base
+ * tip can't be resolved — the caller must treat an ungatherable PR as unsafe
+ * (fail the check) rather than let a stale green through.
+ */
+declare function gatherMergeSafetyFacts(meta: PrMergeMeta, { baseRef, git, baseChecks, requiredChecks }: GatherOptions): Promise<MergeSafetyFacts>;
+
+/**
+ * The API-backed fact source: a {@link GitRunner} that answers the `git` queries
+ * {@link gatherMergeSafetyFacts} makes from the GitHub REST API instead of a local
+ * checkout, so merge-safety can run where there is no `git` binary (a hosted
+ * GitHub App's serverless function). The git-backed runner stays the default; this
+ * one is opt-in through the same `git` injection point.
+ *
+ * Every query maps onto two compares and, for CI-path detection, one commit read
+ * per base commit:
+ * - `compare/{head}...{tip}` — the merge base, the base commits since it, and the
+ *   base-side changed files;
+ * - `compare/{tip}...{head}` — the PR-side changed files and their patches;
+ * - `commits/{sha}` — each base commit's own files, for the CI-path signal.
+ *
+ * The compare API truncates silently (250 commits, 300 files) and omits `patch`
+ * for oversized files. Each of those **fails closed** by throwing, so the caller
+ * reports `Could not evaluate` rather than a verdict built on partial data.
+ */
+
+/**
+ * A GitHub REST `GET` for a path relative to the API root (e.g.
+ * `repos/o/r/compare/a...b`), yielding the parsed JSON body, or `null` when the
+ * read fails. A caller that wants a transient error to abort the run (rather than
+ * fail the check) may throw instead; the error propagates unchanged.
+ */
+type GitHubApiGet = (path: string) => Promise<unknown>;
+interface ApiGitRunnerOptions {
+    /** `owner/repo` the PR and its base live in. */
+    repo: string;
+    api: GitHubApiGet;
+    /** Concurrent `commits/{sha}` reads during CI-path detection (default 8). */
+    concurrency?: number;
+}
+/** The compare API's caps: past these its lists are silently truncated. */
+declare const COMPARE_MAX_COMMITS = 250;
+declare const COMPARE_MAX_FILES = 300;
+/** A commit read lists at most this many files without pagination. */
+declare const COMMIT_MAX_FILES = 300;
+/**
+ * A {@link GitRunner} backed by the GitHub REST API rather than a checkout. It
+ * answers exactly the queries {@link gatherMergeSafetyFacts} makes and throws on
+ * any other, so a new git query added there fails closed until it is mapped here.
+ * Comparisons are cached for the runner's lifetime, so create one per evaluation.
+ */
+declare function makeApiGitRunner({ repo, api, concurrency }: ApiGitRunnerOptions): GitRunner;
+
 /**
  * @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 `merge-safety` bin)
- * lives alongside it; this module is intentionally the narrow, frozen surface
- * consumers and the reusable workflow depend on.
+ * lives alongside it. The check-run name and command surface below are frozen;
+ * the re-exported library surface lets a consumer run the verdict in-process.
  */
 /**
  * The name of the check-run merge-safety posts for each PR.
@@ -18,6 +374,7 @@
  * docs/check-run-contract.md.
  */
 declare const MERGE_SAFETY_CHECK_NAME = "merge-safety";
+
 /**
  * The two operations the `merge-safety` CLI dispatches:
  * - `evaluate` — gather base-currency + breaking-change + conflict facts for one
@@ -32,4 +389,4 @@ 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 };
+export { type ApiGitRunnerOptions, type BaseCheckRun, type BaseChecksProbe, COMMIT_MAX_FILES, COMPARE_MAX_COMMITS, COMPARE_MAX_FILES, type GatherOptions, type GitHubApiGet, type GitRunner, MERGE_SAFETY_CHECK_NAME, MERGE_SAFETY_COMMANDS, type MergeSafetyCommand, type MergeSafetyDecision, type MergeSafetyFacts, type PrMergeMeta, type RequiredChecksProbe, errorMergeSafetyDecision, evaluateMergeSafety, gatherMergeSafetyFacts, isMergeSafetyCommand, makeApiGitRunner, makeGitRunner };

package/dist/index.js

@@ -1,10 +1,26 @@
 import {
+  COMMIT_MAX_FILES,
+  COMPARE_MAX_COMMITS,
+  COMPARE_MAX_FILES,
   MERGE_SAFETY_CHECK_NAME,
   MERGE_SAFETY_COMMANDS,
-  isMergeSafetyCommand
-} from "./chunk-ITPKHZGC.js";
+  errorMergeSafetyDecision,
+  evaluateMergeSafety,
+  gatherMergeSafetyFacts,
+  isMergeSafetyCommand,
+  makeApiGitRunner,
+  makeGitRunner
+} from "./chunk-2QWRQ4Q5.js";
 export {
+  COMMIT_MAX_FILES,
+  COMPARE_MAX_COMMITS,
+  COMPARE_MAX_FILES,
   MERGE_SAFETY_CHECK_NAME,
   MERGE_SAFETY_COMMANDS,
-  isMergeSafetyCommand
+  errorMergeSafetyDecision,
+  evaluateMergeSafety,
+  gatherMergeSafetyFacts,
+  isMergeSafetyCommand,
+  makeApiGitRunner,
+  makeGitRunner
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rmartz/merge-safety",
-  "version": "0.14.0",
+  "version": "0.16.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 through the `rmartz/merge-safety-action` composite action kept current by Dependabot.",
   "keywords": [
     "ci",

package/dist/chunk-ITPKHZGC.js

@@ -1,12 +0,0 @@
-// 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
-};