@rmartz/merge-safety 0.6.0 → 0.10.1

package/README.md

@@ -32,10 +32,12 @@ triggers and runs with the intersection of granted and declared permissions:
 # .github/workflows/merge-safety.yml
 name: merge-safety
 on:
-  pull_request:
+  pull_request_target:
     types: [opened, synchronize, reopened, edited, labeled, unlabeled]
   push:
     branches: [main]
+  check_suite:
+    types: [completed]
   workflow_dispatch:
     inputs:
       pr:
@@ -43,6 +45,7 @@ on:
         required: true
 permissions:
   checks: write
+  statuses: write
   pull-requests: write
   contents: read
   actions: write
@@ -58,9 +61,11 @@ jobs:
 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.
+(`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.)
 
 > For the full walkthrough — the caller's permissions, why it isn't trigger-free,
 > and how to verify the setup — see the
@@ -91,9 +96,10 @@ Fully automatic via [`semantic-release`](https://semantic-release.gitbook.io)
 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
+computes the next version, builds and publishes the package to npmjs (public, via
+OIDC trusted publishing with provenance — no npm token), 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

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

@@ -77,6 +77,12 @@ interface Args {
      * than holding every PR.
      */
     defaultBranch?: string;
+    /**
+     * `invalidate` only: the branch that moved, whose open PRs are fanned out over.
+     * Any branch, not just the default — a push to a stacked parent's branch must
+     * invalidate its children (#54). Absent → the resolved default branch.
+     */
+    baseBranch?: 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. */

package/dist/bin/merge-safety.js

@@ -167,7 +167,34 @@ async function openCheckRunIds(repo, headSha, cwd) {
   if (out === null) return null;
   return out.split("\n").map((l) => Number(l.trim())).filter((id) => Number.isInteger(id) && id > 0);
 }
+var STATUS_DESCRIPTION_MAX = 140;
+async function postStatus(repo, headSha, output, conclusion, cwd) {
+  const { GITHUB_SERVER_URL, GITHUB_REPOSITORY, GITHUB_RUN_ID } = process.env;
+  const runUrl = GITHUB_SERVER_URL && GITHUB_REPOSITORY && GITHUB_RUN_ID ? `${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}` : void 0;
+  const out = await ghCall(
+    {
+      argv: ["gh", "api", "-X", "POST", `repos/${repo}/statuses/${headSha}`, "--input", "-"],
+      stdin: JSON.stringify({
+        state: conclusion,
+        context: MERGE_SAFETY_CHECK_NAME,
+        description: output.title.slice(0, STATUS_DESCRIPTION_MAX),
+        ...runUrl ? { target_url: runUrl } : {}
+      })
+    },
+    null,
+    { cwd }
+  );
+  if (out === null) {
+    console.warn(
+      `::warning::could not set the ${MERGE_SAFETY_CHECK_NAME} commit status on ${headSha} \u2014 does the caller workflow grant \`statuses: write\`? (rmartz/merge-safety#73)`
+    );
+  }
+}
 async function postCheck(repo, headSha, output, conclusion, cwd) {
+  await postCheckRun(repo, headSha, output, conclusion, cwd);
+  await postStatus(repo, headSha, output, conclusion, cwd);
+}
+async function postCheckRun(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) ?? []) {
@@ -202,6 +229,7 @@ async function postCheck(repo, headSha, output, conclusion, cwd) {
 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) {
@@ -213,12 +241,18 @@ function isBreakingCommitMessage(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());
+}
 function mayCarryBreakingMarker(title) {
   const type = CONVENTIONAL_TYPE_RE.exec(title.trim())?.[1];
   return type !== void 0 && FUNCTIONAL_TYPES.has(type);
@@ -266,6 +300,54 @@ 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/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,46 +514,9 @@ function evaluateMergeSafety(facts) {
       )
     );
   }
-  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 { needsUpdate, reasons: stalenessReasons } = evaluateStaleness(facts);
+  reasons.push(...stalenessReasons);
   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(
@@ -541,8 +586,20 @@ function parseBaseCommits(logOut) {
     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((c) => predicate(c.message)).map((c) => ({ sha: c.sha, subject: c.message.split("\n", 1)[0] ?? "" }));
+  return commits.filter(predicate).map((c) => ({ sha: c.sha, subject: c.message.split("\n", 1)[0] ?? "" }));
 }
 async function gatherMergeSafetyFacts(meta, {
   baseRef = "origin/main",
@@ -566,8 +623,19 @@ async function gatherMergeSafetyFacts(meta, {
   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 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);
@@ -594,7 +662,10 @@ async function gatherMergeSafetyFacts(meta, {
     // 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),
+    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,
@@ -614,7 +685,7 @@ async function gatherMergeSafetyFacts(meta, {
 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>]"
+    "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 [--base-branch <name>] [--workflow <file>] [--exclude <n>]\n                                   [--repo <o/r>] [--cwd <path>]"
   );
   process.exit(2);
 }
@@ -637,6 +708,7 @@ function parse(argv) {
     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 === "--base-branch") args.baseBranch = 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;
@@ -825,6 +897,8 @@ function emitDecisionJson(decision, isError) {
   if (isError) process.exitCode = 1;
 }
 async function runInvalidate(repo, args) {
+  const baseBranch = await resolveDefaultBranch(repo, args.baseBranch, args.cwd);
+  if (!baseBranch) throw new Error("could not resolve the base branch to fan out over");
   const prs = await ghJson(
     [
       "gh",
@@ -835,7 +909,7 @@ async function runInvalidate(repo, args) {
       "--state",
       "open",
       "--base",
-      "main",
+      baseBranch,
       "--limit",
       "1000",
       "--json",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rmartz/merge-safety",
-  "version": "0.6.0",
+  "version": "0.10.1",
   "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",
@@ -51,6 +51,7 @@
     "verify:release-notes": "node scripts/verify-changelog-render.mjs"
   },
   "devDependencies": {
+    "@semantic-release/exec": "^7.1.0",
     "@semantic-release/release-notes-generator": "^14.1.1",
     "@types/node": "^26.6.2",
     "@typescript-eslint/eslint-plugin": "^8.70.0",