@rmartz/merge-safety 0.12.0 → 0.14.0

package/README.md

@@ -6,11 +6,13 @@ 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:
+Consuming repos adopt it through the composite action
+[**`rmartz/merge-safety-action`**](https://github.com/rmartz/merge-safety-action),
+distributed the same way as the fleet's other `-action` repos:
 
-1. **Updates propagate automatically.** Consuming repos pin one reusable workflow
-   by SHA; Dependabot's `github-actions` ecosystem opens PRs to bump that pin.
+1. **Updates propagate automatically.** Consuming repos pin the action by SHA;
+   Dependabot's `github-actions` ecosystem opens PRs to bump that pin, and each
+   action release pins a specific version of this CLI.
 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).
@@ -20,60 +22,22 @@ is:
 
 ## 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_target:
-    types: [opened, synchronize, reopened, edited, labeled, unlabeled]
-  push:
-    branches: [main]
-  check_suite:
-    types: [completed]
-  workflow_dispatch:
-    inputs:
-      pr:
-        description: PR number to evaluate
-        required: true
-permissions:
-  checks: write
-  statuses: 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
-`@rmartz/merge-safety` CLI is public on npmjs, so installing it needs no token.
-(Pins at v0.6.0 or earlier install from GitHub Packages instead, which is what the
-`packages: read` permission above is for; it can be dropped once your pin is past
-v0.6.0.)
+Add the caller workflow from the action's
+[consumer guide](https://github.com/rmartz/merge-safety-action/blob/main/docs/consuming.md),
+create the labels merge-safety manages, and require the `merge-safety` status
+check on the default branch. See [docs/consuming.md](docs/consuming.md) for what
+the verdict expects of a repo and how it behaves.
 
-> 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).
+> **The reusable workflow in this repo is deprecated.** Repos pinned to
+> `rmartz/merge-safety/.github/workflows/merge-safety.yml` keep working and see a
+> deprecation warning on each run; migrate them to the action.
 
 ## Requirements
 
 - Node.js >= 20.11
 - pnpm 9 (pinned via `packageManager`)
 
-Consuming repos need neither — the reusable workflow runs the published CLI on a
+Consuming repos need neither — the action runs the published CLI on a
 GitHub-hosted runner.
 
 ## Local development
@@ -98,9 +62,9 @@ OIDC trusted publishing with provenance — no npm token), and creates the git t
 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).
+and is never committed back. The version installed by the deprecated reusable
+workflow is resolved at runtime from the **release tag at its own pinned commit**,
+so it lives only in the git tag; the action pins the version in its own lockfile. 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`;

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
   };
 }
 
@@ -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/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@rmartz/merge-safety",
-  "version": "0.12.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.",
+  "version": "0.14.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",
     "merge-safety",
     "auto-merge",
     "github-actions",
-    "reusable-workflow",
+    "composite-action",
     "check-run"
   ],
   "homepage": "https://github.com/rmartz/merge-safety#readme",