@rmartz/pr-lifecycle 9.0.0 → 9.1.0

package/dist/bin/pr-lifecycle.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   runCli
-} from "../chunk-K5K64YZP.js";
+} from "../chunk-4GTGNP35.js";
 
 // src/bin/pr-lifecycle.ts
 process.exitCode = await runCli(

package/dist/{chunk-K5K64YZP.js → chunk-4GTGNP35.js}

@@ -184,7 +184,8 @@ function parseReconcile(args) {
       case "--pr":
       case "--trusted-authors":
       case "--hold-checks":
-      case "--ignore-checks": {
+      case "--ignore-checks":
+      case "--prose-paths": {
         const value = args[index + 1];
         if (value === void 0 || value.startsWith("--")) {
           return usageError(`${arg} requires a value`);
@@ -212,6 +213,7 @@ function parseReconcile(args) {
   }
   const holdChecks = listOption(values["--hold-checks"]);
   const ignoredChecks = listOption(values["--ignore-checks"]);
+  const prosePatterns = listOption(values["--prose-paths"]);
   return {
     command: "reconcile",
     owner: repoMatch[1],
@@ -227,7 +229,8 @@ function parseReconcile(args) {
     },
     dryRun,
     json,
-    tokenAdvisory
+    tokenAdvisory,
+    ...prosePatterns === void 0 ? {} : { prosePatterns }
   };
 }
 function listOption(value) {
@@ -909,6 +912,25 @@ async function updateBranch(release, target) {
   }
 }
 
+// src/lineage/prose.ts
+var DEFAULT_PROSE_PATTERNS = ["*.md", "!index.md"];
+function compile(pattern) {
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replaceAll("*", ".*");
+  return new RegExp(`^${escaped}$`);
+}
+function proseMatcher(patterns) {
+  const include = patterns.filter((pattern) => !pattern.startsWith("!")).map(compile);
+  const exclude = patterns.filter((pattern) => pattern.startsWith("!")).map((pattern) => compile(pattern.slice(1)));
+  return (path) => {
+    const basename2 = path.slice(path.lastIndexOf("/") + 1);
+    return include.some((regex) => regex.test(basename2)) && !exclude.some((regex) => regex.test(basename2));
+  };
+}
+function overlappingProse(ours, theirs, isProse) {
+  const theirSet = new Set(theirs);
+  return ours.filter((path) => theirSet.has(path) && isProse(path)).sort();
+}
+
 // src/lineage/git.ts
 import { execFile } from "child_process";
 var TIMEOUT_MS = 12e4;
@@ -1020,6 +1042,23 @@ async function createMergeVerifier(git, source) {
       ]);
       return merged.code === 0 && merged.stdout.split("\n")[0]?.trim() === step.tree;
     },
+    async changedPaths(from, to) {
+      if (!OBJECT_ID.test(from) || !OBJECT_ID.test(to)) {
+        return void 0;
+      }
+      const diff = await git.run([
+        "--git-dir",
+        gitDir,
+        "diff-tree",
+        "-r",
+        "-z",
+        "--name-only",
+        "--no-renames",
+        from,
+        to
+      ]);
+      return diff.code === 0 ? diff.stdout.split("\0").filter((path) => path !== "") : void 0;
+    },
     async dispose() {
       await rm(gitDir, { recursive: true, force: true });
     }
@@ -1039,11 +1078,22 @@ async function onBaseBranch(client, commit, baseHeadSha) {
   const { status } = await client.compareCommits(commit, baseHeadSha);
   return status === "identical" || status === "ahead";
 }
+async function proseOverlapReason(verifier, step, isProse) {
+  const ours = await verifier.changedPaths(step.mergeBase, step.first);
+  const theirs = await verifier.changedPaths(step.mergeBase, step.second);
+  if (ours === void 0 || theirs === void 0) {
+    return "could not list the files each side changed";
+  }
+  const overlap = overlappingProse(ours, theirs, isProse);
+  return overlap.length === 0 ? void 0 : `both sides edited the same prose (${overlap.join(", ")})`;
+}
 async function walk(client, git, input, wanted) {
   const verifier = await createMergeVerifier(git, input.source);
   if (verifier === void 0) {
     return { cleanAncestors: [], stoppedBecause: "git unavailable or older than 2.40" };
   }
+  const patterns = input.prosePatterns ?? DEFAULT_PROSE_PATTERNS;
+  const isProse = patterns.length === 0 ? void 0 : proseMatcher(patterns);
   const cleanAncestors = [];
   try {
     let current = input.headSha;
@@ -1057,15 +1107,14 @@ async function walk(client, git, input, wanted) {
         return { cleanAncestors, stoppedBecause: `${current} merges a commit not on the base` };
       }
       const { mergeBaseSha } = await client.compareCommits(first, second);
-      const clean = await verifier.verify({
-        mergeBase: mergeBaseSha,
-        first,
-        second,
-        tree: commit.treeSha
-      });
-      if (!clean) {
+      const mergeStep = { mergeBase: mergeBaseSha, first, second, tree: commit.treeSha };
+      if (!await verifier.verify(mergeStep)) {
         return { cleanAncestors, stoppedBecause: `${current} is not the clean automatic merge` };
       }
+      const overlap = isProse === void 0 ? void 0 : await proseOverlapReason(verifier, mergeStep, isProse);
+      if (overlap !== void 0) {
+        return { cleanAncestors, stoppedBecause: `${current}: ${overlap}` };
+      }
       cleanAncestors.push(first);
       current = first;
       if ([...wanted].every((sha) => cleanAncestors.includes(sha))) {
@@ -1262,7 +1311,8 @@ async function gatherLineageFor(client, pull, reviews, options) {
         url: pull.cloneUrl,
         ...options.lineage.token === void 0 ? {} : { token: options.lineage.token }
       },
-      reviews
+      reviews,
+      ...options.lineage.prosePatterns === void 0 ? {} : { prosePatterns: options.lineage.prosePatterns }
     });
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
@@ -1423,6 +1473,8 @@ reconcile options:
   --skip-copilot-review     Don't wait for requested bot reviewers (deprecated)
   --hold-checks <a,b>       Required checks whose pending is a hold (default: pr-policy)
   --ignore-checks <a,b>     Required checks CI never counts (default: merge-safety)
+  --prose-paths <a,b>       Basename patterns whose overlapping edits in a base merge
+                            need a new review (default: *.md,!index.md)
   --dry-run                 Compute the plan without writing anything
   --json                    Print one JSON object (schemaVersion 1) on stdout
   --no-token-advisory       Don't comment on the PR when arming lacks a release token
@@ -1466,7 +1518,11 @@ async function runCli(argv, io, deps) {
   try {
     const result2 = await reconcilePullRequest(client, args.pr, args.policy, {
       dryRun: args.dryRun,
-      lineage: { git: deps.git ?? createGitRunner(), token },
+      lineage: {
+        git: deps.git ?? createGitRunner(),
+        token,
+        ...args.prosePatterns === void 0 ? {} : { prosePatterns: args.prosePatterns }
+      },
       // Only arming, merging, and updating use the release token (never reads).
       // Without one they are skipped, not done with GITHUB_TOKEN; see docs/cli.md.
       release: hasReleaseToken ? clientFor(releaseToken) : "unavailable"
@@ -1546,6 +1602,9 @@ export {
   isRebasePending,
   OWNED_LABEL_DEFINITIONS,
   executePlan,
+  DEFAULT_PROSE_PATTERNS,
+  proseMatcher,
+  overlappingProse,
   createGitRunner,
   parseGitVersion,
   createMergeVerifier,

package/dist/index.d.ts

@@ -420,7 +420,7 @@ interface CliDeps {
     /** Runs git for approval carry-over; tests inject one. Defaults to the real binary. */
     git?: GitRunner;
 }
-declare const USAGE = "Usage: ai-pr-lifecycle <command> [options]\n\nCommands:\n  reconcile   Recompute a PR's lifecycle state and converge its labels\n  help        Show this message\n\nreconcile options:\n  --repo <owner/repo>       Repository (required)\n  --pr <number>             Pull request number (required)\n  --arm-auto-merge          Arm/disarm native auto-merge from the state\n  --auto-update             Update approved PRs merge-safety flags 'update required'\n                            (Dependabot PRs are asked to rebase, never updated)\n  --trusted-authors <a,b>   Only these logins (with write access) may cast verdicts\n  --skip-copilot-review     Don't wait for requested bot reviewers (deprecated)\n  --hold-checks <a,b>       Required checks whose pending is a hold (default: pr-policy)\n  --ignore-checks <a,b>     Required checks CI never counts (default: merge-safety)\n  --dry-run                 Compute the plan without writing anything\n  --json                    Print one JSON object (schemaVersion 1) on stdout\n  --no-token-advisory       Don't comment on the PR when arming lacks a release token\n\nEnvironment:\n  GITHUB_TOKEN              Token for reads and writes (required)\n  PR_LIFECYCLE_TOKEN\n                            Real-actor token for arming, merging, and updating;\n                            without it, labels are kept but those are skipped\n  GITHUB_API_URL            API base URL (GitHub Enterprise Server)";
+declare const USAGE = "Usage: ai-pr-lifecycle <command> [options]\n\nCommands:\n  reconcile   Recompute a PR's lifecycle state and converge its labels\n  help        Show this message\n\nreconcile options:\n  --repo <owner/repo>       Repository (required)\n  --pr <number>             Pull request number (required)\n  --arm-auto-merge          Arm/disarm native auto-merge from the state\n  --auto-update             Update approved PRs merge-safety flags 'update required'\n                            (Dependabot PRs are asked to rebase, never updated)\n  --trusted-authors <a,b>   Only these logins (with write access) may cast verdicts\n  --skip-copilot-review     Don't wait for requested bot reviewers (deprecated)\n  --hold-checks <a,b>       Required checks whose pending is a hold (default: pr-policy)\n  --ignore-checks <a,b>     Required checks CI never counts (default: merge-safety)\n  --prose-paths <a,b>       Basename patterns whose overlapping edits in a base merge\n                            need a new review (default: *.md,!index.md)\n  --dry-run                 Compute the plan without writing anything\n  --json                    Print one JSON object (schemaVersion 1) on stdout\n  --no-token-advisory       Don't comment on the PR when arming lacks a release token\n\nEnvironment:\n  GITHUB_TOKEN              Token for reads and writes (required)\n  PR_LIFECYCLE_TOKEN\n                            Real-actor token for arming, merging, and updating;\n                            without it, labels are kept but those are skipped\n  GITHUB_API_URL            API base URL (GitHub Enterprise Server)";
 declare function runCli(argv: readonly string[], io: CliIo, deps: CliDeps): Promise<number>;
 
 /**
@@ -438,6 +438,8 @@ interface ReconcileArgs {
     json: boolean;
     /** Comment on the PR when arming is skipped for want of a release token. */
     tokenAdvisory: boolean;
+    /** Prose basename patterns for carry-over; absent means the default. */
+    prosePatterns?: string[];
 }
 type ParsedArgs = ReconcileArgs | {
     command: 'help';
@@ -515,6 +517,11 @@ interface RepoSource {
 interface MergeVerifier {
     /** True only when the step is a verified clean merge; false on any doubt. */
     verify(step: MergeStep): Promise<boolean>;
+    /**
+     * Paths that differ between two commits a `verify` call already fetched;
+     * undefined on any error, so the caller can fail closed.
+     */
+    changedPaths(from: string, to: string): Promise<string[] | undefined>;
     dispose(): Promise<void>;
 }
 /**
@@ -528,7 +535,9 @@ declare function createMergeVerifier(git: GitRunner, source: RepoSource): Promis
  * Finds the head's clean ancestors: commits reached by walking back from the head
  * through a chain of **verified clean base merges**, so reviews bound to them
  * still describe the change being merged (docs/reconciler-design.md §Approval
- * carry-over). Fails closed: any doubt or error ends the chain, and the cost is
+ * carry-over). A clean merge in which both sides edited the same prose file also
+ * ends the chain: nothing automatic checks that the merged page still reads
+ * correctly. Fails closed: any doubt or error ends the chain, and the cost is
  * an extra review, never a false approval.
  */
 /** A longer chain of base merges than this is unusual enough to review again. */
@@ -540,6 +549,11 @@ interface LineageInput {
     baseHeadSha: string;
     source: RepoSource;
     reviews: readonly ReviewData[];
+    /**
+     * Basename patterns for prose files (see src/lineage/prose.ts); default
+     * `DEFAULT_PROSE_PATTERNS`. Empty turns the prose-overlap check off.
+     */
+    prosePatterns?: readonly string[];
 }
 interface Lineage {
     cleanAncestors: string[];
@@ -573,6 +587,7 @@ interface GatherOptions {
     lineage?: {
         git: GitRunner;
         token?: string;
+        prosePatterns?: readonly string[];
     };
 }
 declare function gatherFacts(client: GitHubClient, pr: number, policy?: ReconcilePolicy, options?: GatherOptions): Promise<GatheredPullRequest>;
@@ -748,6 +763,22 @@ declare function buildTokenAdvisoryBody(skipped: 'arm' | 'merge'): string;
  */
 declare function postTokenAdvisory(client: GitHubClient, pr: number, skipped: 'arm' | 'merge'): Promise<boolean>;
 
+/**
+ * Which files are prose for approval carry-over: a clean base merge in which both
+ * sides edited the same prose file doesn't carry an approval over, because no CI
+ * check can tell whether two concurrent edits to a page still read correctly
+ * together (docs/reconciler-design.md §Approval carry-over).
+ *
+ * Patterns match a file's **basename** with `*` as the only wildcard; a leading
+ * `!` excludes. A file is prose when it matches some pattern and no exclusion.
+ */
+/** Every Markdown file except index pages, which take routine concurrent appends. */
+declare const DEFAULT_PROSE_PATTERNS: readonly string[];
+type ProseMatcher = (path: string) => boolean;
+declare function proseMatcher(patterns: readonly string[]): ProseMatcher;
+/** Prose paths changed on both sides of a merge, sorted. */
+declare function overlappingProse(ours: readonly string[], theirs: readonly string[], isProse: ProseMatcher): string[];
+
 /**
  * Verdict parsing and trust. A review is a verdict when it carries a /review
  * `skill-meta` marker with a verdict outcome, or (with no marker) a native
@@ -768,4 +799,4 @@ declare function isTrustedAuthor(author: ReviewAuthor, policy: ReconcilePolicy):
 /** The latest verdict that counts for the PR's current head, if any. */
 declare function currentVerdict(facts: PullRequestFacts, policy: ReconcilePolicy): Verdict | undefined;
 
-export { ACTOR_TYPES, AUTO_MERGE_LABEL, type ActorType, type AutoMergeAction, BRANCH_UPDATERS, type BotEligibility, type BotPrCommit, type BotPrFacts, type BotPrType, type BranchUpdater, type ChangedFile, type CliDeps, type CliIo, type CollaboratorPermission, type CommitData, DEFAULT_SETTLE_MS, DEPENDABOT_LOGIN, DEPENDABOT_REBASE_COMMAND, DEPENDABOT_REBASING_LABEL, DEPENDABOT_REBASING_NOTICE, DEPENDABOT_RECREATING_NOTICE, DEPENDABOT_UPDATE_TYPES, type DependabotUpdateType, type GatherOptions, type GatheredPullRequest, GitHubApiError, type GitHubClient, type GitResult, type GitRunner, type HttpClientOptions, LIFECYCLE_LABELS, LIFECYCLE_STATES, type LabelDefinition, type LifecycleLabel, type LifecycleState, type Lineage, type LineageInput, MAX_CHAIN_STEPS, type MergeStep, type MergeVerifier, OWNED_LABEL_DEFINITIONS, PR_STATUSES, type ParsedArgs, type ParsedVerdict, type PlanTarget, type PullRequestData, type PullRequestFacts, type PullRequestStatus, RELEASE_PLEASE_BRANCH_PREFIX, RELEASE_TOKEN_DOCS_URL, REPO_PERMISSIONS, REVIEW_STATES, type ReconcileArgs, type ReconcileJson, type ReconcileOptions, type ReconcilePlan, type ReconcilePolicy, type ReconcileResult, type ReconcileTarget, type ReleaseActions, type ReleaseDiffVerdict, type RepoPermission, type RepoSource, type ReviewAuthor, type ReviewData, type ReviewFact, type ReviewState, SCHEMA_VERSION, type SettleOptions, TOKEN_ADVISORY_MARKER, UPDATE_REQUIRED_LABEL, USAGE, type UpdateAction, VERDICTS, type Verdict, buildRebaseRequestBody, buildTokenAdvisoryBody, classifyBotPr, classifyReleaseDiff, computeState, createGitRunner, createHttpClient, createMergeVerifier, currentVerdict, executePlan, formatSummary, gatherFacts, gatherLineage, isApiStatus, isDependabotRebasing, isRebasePending, isTrustedAuthor, isVersionOnlyPatch, parseArgs, parseDependabotUpdateType, parseGitVersion, parseVerdict, planReconcile, postTokenAdvisory, rebaseRequestMarker, reconcilePullRequest, runCli, toReconcileJson, withoutReleaseActions };
+export { ACTOR_TYPES, AUTO_MERGE_LABEL, type ActorType, type AutoMergeAction, BRANCH_UPDATERS, type BotEligibility, type BotPrCommit, type BotPrFacts, type BotPrType, type BranchUpdater, type ChangedFile, type CliDeps, type CliIo, type CollaboratorPermission, type CommitData, DEFAULT_PROSE_PATTERNS, DEFAULT_SETTLE_MS, DEPENDABOT_LOGIN, DEPENDABOT_REBASE_COMMAND, DEPENDABOT_REBASING_LABEL, DEPENDABOT_REBASING_NOTICE, DEPENDABOT_RECREATING_NOTICE, DEPENDABOT_UPDATE_TYPES, type DependabotUpdateType, type GatherOptions, type GatheredPullRequest, GitHubApiError, type GitHubClient, type GitResult, type GitRunner, type HttpClientOptions, LIFECYCLE_LABELS, LIFECYCLE_STATES, type LabelDefinition, type LifecycleLabel, type LifecycleState, type Lineage, type LineageInput, MAX_CHAIN_STEPS, type MergeStep, type MergeVerifier, OWNED_LABEL_DEFINITIONS, PR_STATUSES, type ParsedArgs, type ParsedVerdict, type PlanTarget, type ProseMatcher, type PullRequestData, type PullRequestFacts, type PullRequestStatus, RELEASE_PLEASE_BRANCH_PREFIX, RELEASE_TOKEN_DOCS_URL, REPO_PERMISSIONS, REVIEW_STATES, type ReconcileArgs, type ReconcileJson, type ReconcileOptions, type ReconcilePlan, type ReconcilePolicy, type ReconcileResult, type ReconcileTarget, type ReleaseActions, type ReleaseDiffVerdict, type RepoPermission, type RepoSource, type ReviewAuthor, type ReviewData, type ReviewFact, type ReviewState, SCHEMA_VERSION, type SettleOptions, TOKEN_ADVISORY_MARKER, UPDATE_REQUIRED_LABEL, USAGE, type UpdateAction, VERDICTS, type Verdict, buildRebaseRequestBody, buildTokenAdvisoryBody, classifyBotPr, classifyReleaseDiff, computeState, createGitRunner, createHttpClient, createMergeVerifier, currentVerdict, executePlan, formatSummary, gatherFacts, gatherLineage, isApiStatus, isDependabotRebasing, isRebasePending, isTrustedAuthor, isVersionOnlyPatch, overlappingProse, parseArgs, parseDependabotUpdateType, parseGitVersion, parseVerdict, planReconcile, postTokenAdvisory, proseMatcher, rebaseRequestMarker, reconcilePullRequest, runCli, toReconcileJson, withoutReleaseActions };

package/dist/index.js

@@ -2,6 +2,7 @@ import {
   ACTOR_TYPES,
   AUTO_MERGE_LABEL,
   BRANCH_UPDATERS,
+  DEFAULT_PROSE_PATTERNS,
   DEFAULT_SETTLE_MS,
   DEPENDABOT_LOGIN,
   DEPENDABOT_REBASE_COMMAND,
@@ -42,22 +43,25 @@ import {
   isRebasePending,
   isTrustedAuthor,
   isVersionOnlyPatch,
+  overlappingProse,
   parseArgs,
   parseDependabotUpdateType,
   parseGitVersion,
   parseVerdict,
   planReconcile,
   postTokenAdvisory,
+  proseMatcher,
   rebaseRequestMarker,
   reconcilePullRequest,
   runCli,
   toReconcileJson,
   withoutReleaseActions
-} from "./chunk-K5K64YZP.js";
+} from "./chunk-4GTGNP35.js";
 export {
   ACTOR_TYPES,
   AUTO_MERGE_LABEL,
   BRANCH_UPDATERS,
+  DEFAULT_PROSE_PATTERNS,
   DEFAULT_SETTLE_MS,
   DEPENDABOT_LOGIN,
   DEPENDABOT_REBASE_COMMAND,
@@ -98,12 +102,14 @@ export {
   isRebasePending,
   isTrustedAuthor,
   isVersionOnlyPatch,
+  overlappingProse,
   parseArgs,
   parseDependabotUpdateType,
   parseGitVersion,
   parseVerdict,
   planReconcile,
   postTokenAdvisory,
+  proseMatcher,
   rebaseRequestMarker,
   reconcilePullRequest,
   runCli,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rmartz/pr-lifecycle",
-  "version": "9.0.0",
+  "version": "9.1.0",
   "description": "Event-driven PR lifecycle reconciler: recomputes a pull request's lifecycle labels from its current facts on every GitHub event and arms native auto-merge on approval.",
   "keywords": [
     "ci",