@rmartz/merge-safety 0.15.0 → 0.16.0

package/README.md

@@ -32,6 +32,13 @@ the verdict expects of a repo and how it behaves.
 > `rmartz/merge-safety/.github/workflows/merge-safety.yml` keep working and see a
 > deprecation warning on each run; migrate them to the action.
 
+## Using it as a library
+
+The package also exports the verdict for in-process use, e.g. from a hosted
+GitHub App with no checkout: `gatherMergeSafetyFacts` with the API-backed
+`makeApiGitRunner` fact source, then `evaluateMergeSafety`. See
+[docs/fact-sources.md](docs/fact-sources.md).
+
 ## Requirements
 
 - Node.js >= 20.11
@@ -74,8 +81,8 @@ split-prefix convention (rmartz/ai#82): a **production** bump arrives as
 **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)
+Three guards back the automatic flow: pr-policy's `title` check, part of the
+`pr-policy` check run by [`pr-policy.yml`](.github/workflows/pr-policy.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), the shared [`release-check.yml`](.github/workflows/release-check.yml)
 (renders the notes through the shared

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

@@ -1,47 +1,5 @@
 #!/usr/bin/env node
-import { MergeSafetyCommand } from '../index.js';
-
-/**
- * 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>;
+import { MergeSafetyCommand, BaseChecksProbe, RequiredChecksProbe } from '../index.js';
 
 interface Args {
     mode: MergeSafetyCommand;

package/dist/bin/merge-safety.js

@@ -1,52 +1,19 @@
 #!/usr/bin/env node
 import {
   MERGE_SAFETY_CHECK_NAME,
-  isMergeSafetyCommand
-} from "../chunk-ITPKHZGC.js";
+  boundedRun,
+  errorMergeSafetyDecision,
+  evaluateMergeSafety,
+  gatherMergeSafetyFacts,
+  isEvaluablePrState,
+  isMergeSafetyCommand,
+  makeGitRunner
+} from "../chunk-2QWRQ4Q5.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;
@@ -283,391 +250,6 @@ async function abandonRunAsCancelled(err, opts = {}) {
   await wait(CANCEL_GRACE_MS);
 }
 
-// src/conventional-commits.ts
-var BREAKING_SUBJECT_RE = /^[a-z]+(?:!(?:\([^)]*\))?|(?:\([^)]*\))?!):/;
-var BREAKING_FOOTER_RE = /^BREAKING[ -]CHANGE:/m;
-var CI_SUBJECT_RE = /^ci(\([^)]*\))?!?:/;
-var DOCS_SUBJECT_RE = /^docs(\([^)]*\))?!?:/;
-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 isDocsCommitMessage(message) {
-  return DOCS_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 isDocsTitle(title) {
-  return DOCS_SUBJECT_RE.test(title.trim());
-}
-
-// 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/staleness.ts
-function evaluateStaleness(facts) {
-  const reasons = [];
-  if (facts.isCurrent) return { needsUpdate: false, reasons };
-  const baseBreaking = facts.baseBreakingSinceMergeBase && !(facts.prIsDocs && !facts.prIsBreaking);
-  const prBreaking = facts.prIsBreaking && !facts.baseOnlyDocsSinceMergeBase;
-  const prCi = facts.prIsCi && !facts.prIsHotfix;
-  if (baseBreaking) {
-    reasons.push(
-      withDetail(
-        "A breaking change landed on the base since merge-base \u2014 rebase and re-run CI:",
-        facts.baseBreakingCommits.map(formatBaseCommit)
-      )
-    );
-  }
-  if (prBreaking) {
-    reasons.push(
-      withDetail(
-        "This PR is a breaking change \u2014 it must be current with the base before merge.",
-        breakingSignalDetail(facts.prBreakingDiffSignals)
-      )
-    );
-  }
-  if (prCi) {
-    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 (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 (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 needsUpdate = baseBreaking || facts.baseCiSinceMergeBase || prBreaking || prCi || facts.fileOverlap;
-  return { needsUpdate, reasons };
-}
-
-// 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";
-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 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 { needsUpdate, reasons: stalenessReasons } = evaluateStaleness(facts);
-  reasons.push(...stalenessReasons);
-  const needsAction = facts.hasConflict || baseUnhealthy;
-  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" : baseUnhealthy ? "Base CI failing" : needsUpdate ? "Update required" : "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));
-  return {
-    conclusion,
-    needsUpdate,
-    hasConflict: facts.hasConflict,
-    baseUnhealthy,
-    title,
-    reasons,
-    summary,
-    labels: { add, remove }
-  };
-}
-function errorMergeSafetyDecision(message) {
-  return {
-    conclusion: "failure",
-    needsUpdate: false,
-    hasConflict: false,
-    baseUnhealthy: false,
-    title: "Could not evaluate",
-    reasons: [message],
-    summary: `Could not evaluate merge safety: ${message}`,
-    labels: { add: [], remove: [] }
-  };
-}
-
-// 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;
-}
-
-// 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 };
-  });
-}
-var CI_PATH_RE = /^\.github\/(?:workflows|actions)\//;
-function isCiPath(path) {
-  return CI_PATH_RE.test(path);
-}
-function parseCiPathShas(logOut) {
-  const shas = /* @__PURE__ */ new Set();
-  for (const record of logOut.split("\0")) {
-    const [sha, ...files] = splitLines(record);
-    if (sha && files.some(isCiPath)) shas.add(sha);
-  }
-  return shas;
-}
-function selectCommits(commits, predicate) {
-  return commits.filter(predicate).map((c) => ({ sha: c.sha, subject: c.message.split("\n", 1)[0] ?? "" }));
-}
-async function gatherMergeSafetyFacts(meta, { baseRef = "origin/main", git, baseChecks, requiredChecks }) {
-  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, (c) => isBreakingCommitMessage(c.message));
-  const fileLogOut = await git([
-    "log",
-    "--format=%x00%H",
-    "--name-only",
-    `${mergeBase}..${baseRef}`
-  ]);
-  if (fileLogOut === null) throw new Error(`git log failed for ${mergeBase}..${baseRef}`);
-  const ciPathShas = parseCiPathShas(fileLogOut);
-  const baseCiCommits = selectCommits(
-    commits,
-    (c) => isCiCommitMessage(c.message) || ciPathShas.has(c.sha)
-  );
-  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 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,
-    // The title's `!` is the only declared input (#82) — pr-policy's title check
-    // keeps it in step with the `breaking change` label. The diff can only add a
-    // reason to re-test the PR against a moved base (#53).
-    prIsBreaking: isBreakingTitle(meta.title) || diffSignals.length > 0,
-    prIsDocs: isDocsTitle(meta.title),
-    baseOnlyDocsSinceMergeBase: commits.length > 0 && commits.every((c) => isDocsCommitMessage(c.message)),
-    // Title or path (#67): a release-typed PR that changes CI is still re-tested.
-    prIsCi: isCiTitle(meta.title) || prFiles.some(isCiPath),
-    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
-  };
-}
-
 // src/bin/merge-safety.ts
 var DEFAULT_CALLER_WORKFLOW = "merge-safety.yml";
 function usage() {