@rmartz/merge-safety 0.11.0 → 0.13.0

package/README.md

@@ -15,11 +15,8 @@ is:
    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.
+> **Status: released.** The package ships the full `evaluate` / `invalidate`
+> implementation as the `merge-safety` CLI and is ready to adopt.
 
 ## Using it in a consuming repo
 

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

@@ -51,8 +51,8 @@ interface Args {
     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.
+     * (a reusable workflow's fan-out must target the *caller* file, not this
+     * reusable file). Defaults to the conventional name.
      */
     workflow: string;
     cwd?: string;

package/dist/bin/merge-safety.js

@@ -230,8 +230,6 @@ var BREAKING_SUBJECT_RE = /^[a-z]+(?:!(?:\([^)]*\))?|(?:\([^)]*\))?!):/;
 var BREAKING_FOOTER_RE = /^BREAKING[ -]CHANGE:/m;
 var CI_SUBJECT_RE = /^ci(\([^)]*\))?!?:/;
 var DOCS_SUBJECT_RE = /^docs(\([^)]*\))?!?:/;
-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] ?? "";
 }
@@ -253,10 +251,6 @@ function isCiTitle(title) {
 function isDocsTitle(title) {
   return DOCS_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/reasons.ts
 var BREAKING_DIFF_REASONS = {
@@ -326,6 +320,89 @@ function evaluateStaleness(facts) {
   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"]);
@@ -432,110 +509,6 @@ function breakingDiffSignals(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 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 needsCiRetitle = hasSignal(facts.prBreakingDiffSignals, "sensitive-package-bump") ? !facts.prIsCi : false;
-  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;
-  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" : 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,
-    title,
-    reasons,
-    summary,
-    labels: { add, remove, addOnly }
-  };
-}
-function errorMergeSafetyDecision(message) {
-  return {
-    conclusion: "failure",
-    needsUpdate: false,
-    hasConflict: false,
-    baseUnhealthy: false,
-    needsCiRetitle: 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;
@@ -617,9 +590,10 @@ async function gatherMergeSafetyFacts(meta, { baseRef = "origin/main", git, base
     // 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,
+    // 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.
@@ -632,8 +606,7 @@ async function gatherMergeSafetyFacts(meta, { baseRef = "origin/main", git, base
     baseCiCommits,
     overlappingFiles: overlaps,
     failingBaseChecks,
-    prBreakingDiffSignals: diffSignals,
-    prMayCarryBreakingMarker: mayCarryBreakingMarker(meta.title)
+    prBreakingDiffSignals: diffSignals
   };
 }
 
@@ -641,7 +614,7 @@ async function gatherMergeSafetyFacts(meta, { baseRef = "origin/main", git, base
 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       ai-merge-safety invalidate [--base-branch <name>] [--workflow <file>] [--exclude <n>]\n                                   [--repo <o/r>] [--cwd <path>]"
+    "usage: merge-safety evaluate --pr <n> [--json] [--repo <o/r>] [--base <ref>] [--cwd <path>]\n       merge-safety invalidate [--base-branch <name>] [--workflow <file>] [--exclude <n>]\n                                   [--repo <o/r>] [--cwd <path>]"
   );
   process.exit(2);
 }
@@ -807,13 +780,7 @@ ${detail}` },
     decision.conclusion,
     args.cwd
   );
-  await reconcileLabels(
-    repo,
-    pr,
-    [...decision.labels.add, ...decision.labels.addOnly],
-    decision.labels.remove,
-    args.cwd
-  );
+  await reconcileLabels(repo, pr, decision.labels.add, decision.labels.remove, args.cwd);
   console.log(`#${pr}: ${decision.conclusion} \u2014 ${decision.summary}`);
 }
 function emitDecisionJson(decision, isError) {

package/dist/index.d.ts

@@ -3,7 +3,7 @@
  *
  * 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)
+ * (`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.
  */
@@ -19,7 +19,7 @@
  */
 declare const MERGE_SAFETY_CHECK_NAME = "merge-safety";
 /**
- * The two operations the `ai-merge-safety` CLI dispatches:
+ * The two operations the `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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rmartz/merge-safety",
-  "version": "0.11.0",
+  "version": "0.13.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",
@@ -26,7 +26,7 @@
     }
   },
   "bin": {
-    "ai-merge-safety": "./dist/bin/merge-safety.js"
+    "merge-safety": "./dist/bin/merge-safety.js"
   },
   "files": [
     "dist"