@rmartz/pr-lifecycle 7.0.0 → 8.0.0

package/README.md

@@ -2,7 +2,7 @@
 
 An **event-driven pull-request lifecycle reconciler** for GitHub Actions. On every
 relevant GitHub event it recomputes a PR's lifecycle state from the PR's current
-facts — draft status, Copilot review of the head, the latest verdict from a
+facts — draft status, pending bot review requests, the latest verdict from a
 trusted author and the head SHA it reviewed — converges the PR's labels to match,
 and **arms GitHub-native auto-merge when the PR reaches `approved`**. The
 consumer's branch ruleset (required checks) then decides when the merge lands.

package/dist/bin/pr-lifecycle.js

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

package/dist/{chunk-PJOTYSEK.js → chunk-ENU2AAWK.js}

@@ -455,7 +455,9 @@ function createHttpClient(options) {
         isCrossRepository: pull.head.repo?.id !== pull.base.repo.id,
         mergeable: pull.mergeable ?? void 0,
         mergeState: pull.mergeable_state,
-        changedFileCount: pull.changed_files
+        changedFileCount: pull.changed_files,
+        createdAt: pull.created_at,
+        requestedBotReviewers: (pull.requested_reviewers ?? []).filter((reviewer) => reviewer.type === "Bot").map((reviewer) => reviewer.login)
       };
     },
     async getBranchHeadSha(branch) {
@@ -512,6 +514,10 @@ function createHttpClient(options) {
     async removeLabel(pr, name) {
       await request("DELETE", `${repoPath}/issues/${pr}/labels/${encodeURIComponent(name)}`);
     },
+    async getLastReadyForReviewAt(pr) {
+      const events = await paginate(`${repoPath}/issues/${pr}/events`);
+      return events.filter((event) => event.event === "ready_for_review").at(-1)?.created_at;
+    },
     async listIssueComments(pr) {
       const comments = await paginate(`${repoPath}/issues/${pr}/comments`);
       return comments.map((comment) => comment.body ?? "");
@@ -621,8 +627,8 @@ function currentVerdict(facts, policy) {
 // src/state.ts
 var LIFECYCLE_STATES = [
   "approved",
+  "awaiting-bot-review",
   "awaiting-ci",
-  "awaiting-copilot",
   "blocked-base-red",
   "changes-requested",
   "ci-failing",
@@ -632,7 +638,6 @@ var LIFECYCLE_STATES = [
   "fix-required",
   "review-requested"
 ];
-var COPILOT_REVIEWER_LOGIN = "copilot-pull-request-reviewer[bot]";
 var WIP_PATTERN = /\[wip\]/i;
 function computeState(facts, policy) {
   if (facts.status !== "open") {
@@ -657,14 +662,10 @@ function computeState(facts, policy) {
   if (facts.ciStatus === "pending") {
     return "awaiting-ci";
   }
-  if (policy.skipCopilotReview === true) {
-    return "review-requested";
+  if (facts.pendingBotReviewers.length > 0 && policy.skipCopilotReview !== true) {
+    return "awaiting-bot-review";
   }
-  const reviewedCommits = countingCommits(facts);
-  const copilotReviewedHead = facts.reviews.some(
-    (review) => review.author.login === COPILOT_REVIEWER_LOGIN && reviewedCommits.has(review.commitSha)
-  );
-  return copilotReviewedHead ? "review-requested" : "awaiting-copilot";
+  return "review-requested";
 }
 
 // src/plan.ts
@@ -692,8 +693,8 @@ function lifecycleLabels(state) {
       return ["fix required", "ci failing"];
     case "review-requested":
       return ["review requested"];
+    case "awaiting-bot-review":
     case "awaiting-ci":
-    case "awaiting-copilot":
     case "blocked-base-red":
     case "closed":
     case "draft":
@@ -1017,7 +1018,7 @@ var MAX_CHAIN_STEPS = 20;
 function reviewedAncestors(input) {
   return new Set(
     input.reviews.filter((review) => review.commitSha !== input.headSha).filter(
-      (review) => review.login === COPILOT_REVIEWER_LOGIN || review.state === "APPROVED" || review.state === "CHANGES_REQUESTED" || review.body.includes("skill-meta")
+      (review) => review.state === "APPROVED" || review.state === "CHANGES_REQUESTED" || review.body.includes("skill-meta")
     ).map((review) => review.commitSha)
   );
 }
@@ -1283,6 +1284,7 @@ async function gatherFacts(client, pr, policy = {}, options = {}) {
     nodeId: pull.nodeId,
     botEligibility,
     lineage,
+    createdAt: pull.createdAt,
     facts: {
       status: pull.merged ? "merged" : pull.state,
       isDraft: pull.draft,
@@ -1298,11 +1300,46 @@ async function gatherFacts(client, pr, policy = {}, options = {}) {
       cleanAncestors: lineage?.cleanAncestors ?? [],
       updater,
       rebasePending,
-      reviews: reviews.map((review) => toReviewFact(review, permissions))
+      reviews: reviews.map((review) => toReviewFact(review, permissions)),
+      pendingBotReviewers: pull.requestedBotReviewers
     }
   };
 }
 
+// src/github/settle.ts
+var DEFAULT_SETTLE_MS = 3e4;
+function realSleep(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+async function settleDelay(client, pr, gathered, policy, settleMs, now) {
+  const { facts } = gathered;
+  if (policy.skipCopilotReview === true || computeState(facts, policy) !== "review-requested") {
+    return 0;
+  }
+  if (facts.labels.includes("review requested")) {
+    return 0;
+  }
+  const readyAt = await client.getLastReadyForReviewAt(pr);
+  const reviewableSince = Math.max(
+    Date.parse(gathered.createdAt),
+    readyAt === void 0 ? 0 : Date.parse(readyAt)
+  );
+  const elapsed = now - reviewableSince;
+  if (!Number.isFinite(elapsed)) {
+    return settleMs;
+  }
+  return Math.min(settleMs, Math.max(0, settleMs - elapsed));
+}
+function resolveSettle(options = {}) {
+  return {
+    settleMs: options.settleMs ?? DEFAULT_SETTLE_MS,
+    now: options.now ?? Date.now,
+    sleep: options.sleep ?? realSleep
+  };
+}
+
 // src/github/reconcile.ts
 var REFUSE_RELEASE = {
   createIssueComment: () => Promise.reject(new Error("rebase requests need a release token")),
@@ -1311,7 +1348,14 @@ var REFUSE_RELEASE = {
   updateBranch: () => Promise.reject(new Error("updating needs a release token"))
 };
 async function reconcilePullRequest(client, pr, policy, options = {}) {
-  const { facts, nodeId, botEligibility, lineage } = await gatherFacts(client, pr, policy, options);
+  const settle = resolveSettle(options.settle);
+  let gathered = await gatherFacts(client, pr, policy, options);
+  const settledMs = await settleDelay(client, pr, gathered, policy, settle.settleMs, settle.now());
+  if (settledMs > 0) {
+    await settle.sleep(settledMs);
+    gathered = await gatherFacts(client, pr, policy, options);
+  }
+  const { facts, nodeId, botEligibility, lineage } = gathered;
   const planned = planReconcile(facts, policy);
   const unavailable = options.release === "unavailable";
   const plan = unavailable ? withoutReleaseActions(planned) : planned;
@@ -1322,7 +1366,7 @@ async function reconcilePullRequest(client, pr, policy, options = {}) {
   const wanted = planned.autoMerge;
   const skippedAutoMerge = unavailable && (wanted === "arm" || wanted === "merge") ? wanted : void 0;
   const skippedUpdate = unavailable && planned.update !== "none" ? planned.update : void 0;
-  return { plan, botEligibility, lineage, skippedAutoMerge, skippedUpdate };
+  return { plan, botEligibility, lineage, skippedAutoMerge, skippedUpdate, settledMs };
 }
 
 // src/github/token-advisory.ts
@@ -1362,7 +1406,7 @@ reconcile options:
   --auto-update             Update approved PRs merge-safety flags 'update required'
                             (Dependabot PRs are asked to rebase, never updated)
   --trusted-authors <a,b>   Only these logins (with write access) may cast verdicts
-  --skip-copilot-review     Don't wait for a Copilot review
+  --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)
   --dry-run                 Compute the plan without writing anything
@@ -1472,7 +1516,6 @@ export {
   isTrustedAuthor,
   currentVerdict,
   LIFECYCLE_STATES,
-  COPILOT_REVIEWER_LOGIN,
   computeState,
   LIFECYCLE_LABELS,
   AUTO_MERGE_LABEL,
@@ -1492,6 +1535,7 @@ export {
   MAX_CHAIN_STEPS,
   gatherLineage,
   gatherFacts,
+  DEFAULT_SETTLE_MS,
   reconcilePullRequest,
   TOKEN_ADVISORY_MARKER,
   RELEASE_TOKEN_DOCS_URL,

package/dist/index.d.ts

@@ -179,6 +179,11 @@ interface PullRequestFacts {
      */
     rebasePending: boolean;
     reviews: readonly ReviewFact[];
+    /**
+     * Logins of the bots (e.g. Copilot) whose review is requested and not yet
+     * submitted. Users and teams are left out: the lifecycle never waits on people.
+     */
+    pendingBotReviewers: readonly string[];
 }
 interface ReconcilePolicy {
     /**
@@ -196,8 +201,10 @@ interface ReconcilePolicy {
      */
     autoUpdate?: boolean;
     /**
-     * Don't wait for a Copilot review before `review-requested`, for repos without
-     * Copilot code review (where the wait would never end). Off by default.
+     * Don't wait for requested bot reviewers (e.g. Copilot) before
+     * `review-requested`. Rarely needed: a bot that won't review is never requested.
+     * Off by default. Deprecated: the wait now ends on its own; kept so existing
+     * callers keep working.
      */
     skipCopilotReview?: boolean;
     /**
@@ -243,6 +250,10 @@ interface PullRequestData {
     mergeState: string | undefined;
     /** How many files the PR changes (`changed_files`), to tell a full file list from a truncated one. */
     changedFileCount: number;
+    /** ISO-8601 time the PR was opened. */
+    createdAt: string;
+    /** Logins of requested reviewers that are bots (users and teams left out). */
+    requestedBotReviewers: string[];
 }
 /** A check-run on a commit (the latest run per name). */
 interface CheckRunData {
@@ -316,6 +327,8 @@ interface GitHubClient {
     addLabels(pr: number, names: readonly string[]): Promise<void>;
     /** Throws a GitHubApiError with status 404 when the label is not on the PR. */
     removeLabel(pr: number, name: string): Promise<void>;
+    /** When the PR was last marked ready for review (ISO-8601), if ever. */
+    getLastReadyForReviewAt(pr: number): Promise<string | undefined>;
     /** Bodies of the PR's conversation comments, oldest first. */
     listIssueComments(pr: number): Promise<string[]>;
     createIssueComment(pr: number, body: string): Promise<void>;
@@ -400,7 +413,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 a Copilot review\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  --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>;
 
 /**
@@ -431,9 +444,8 @@ declare function parseArgs(argv: readonly string[]): ParsedArgs;
  * Lifecycle state, computed from facts in a fixed priority order. See
  * docs/reconciler-design.md §State.
  */
-declare const LIFECYCLE_STATES: readonly ["approved", "awaiting-ci", "awaiting-copilot", "blocked-base-red", "changes-requested", "ci-failing", "closed", "draft", "escalation-needed", "fix-required", "review-requested"];
+declare const LIFECYCLE_STATES: readonly ["approved", "awaiting-bot-review", "awaiting-ci", "blocked-base-red", "changes-requested", "ci-failing", "closed", "draft", "escalation-needed", "fix-required", "review-requested"];
 type LifecycleState = (typeof LIFECYCLE_STATES)[number];
-declare const COPILOT_REVIEWER_LOGIN = "copilot-pull-request-reviewer[bot]";
 declare function computeState(facts: PullRequestFacts, policy: ReconcilePolicy): LifecycleState;
 
 /**
@@ -536,6 +548,8 @@ interface GatheredPullRequest {
     botEligibility: BotEligibility;
     /** How far approval carry-over verified, for reporting (absent when off). */
     lineage: Lineage | undefined;
+    /** When the PR was opened (ISO-8601), for the settle wait (settle.ts). */
+    createdAt: string;
 }
 interface GatherOptions {
     /**
@@ -550,7 +564,28 @@ interface GatherOptions {
 }
 declare function gatherFacts(client: GitHubClient, pr: number, policy?: ReconcilePolicy, options?: GatherOptions): Promise<GatheredPullRequest>;
 
+/**
+ * The settle wait: a PR that just became reviewable isn't moved to
+ * `review-requested` until bot reviewers have had time to be requested. Copilot's
+ * auto-review request lands a few seconds after the PR opens (observed: up to 5s),
+ * so a run that reads the PR sooner would see no request and skip the wait. The
+ * wait happens inside the run, never as "stay put and wait for the next event":
+ * when no bot is coming, no further event may ever fire. See
+ * docs/reconciler-design.md §Waiting for bot reviewers.
+ */
+/** Long enough to cover the observed request delay several times over. */
+declare const DEFAULT_SETTLE_MS = 30000;
+interface SettleOptions {
+    /** How long after a PR becomes reviewable to wait for bot requests. */
+    settleMs?: number;
+    /** Clock and timer, injectable for tests. */
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+}
+
 interface ReconcileOptions extends GatherOptions {
+    /** The settle wait for a PR that just became reviewable (settle.ts). */
+    settle?: SettleOptions;
     /** Compute and return the plan without writing anything. */
     dryRun?: boolean;
     /**
@@ -570,10 +605,12 @@ interface ReconcileResult {
     skippedAutoMerge: 'arm' | 'merge' | undefined;
     /** The branch update the plan wanted but skipped because `release` was unavailable. */
     skippedUpdate: Exclude<UpdateAction, 'none'> | undefined;
+    /** How long the run waited for bot review requests before gathering again (ms). */
+    settledMs: number;
 }
 /**
- * One full reconcile pass for a PR: gather its facts, plan, and (unless dry-run)
- * execute. Returns the plan, the bot-eligibility verdict, and the carry-over
+ * One full reconcile pass for a PR: gather its facts (waiting to settle first if it
+ * just became reviewable), plan, and (unless dry-run) execute. Returns the plan, the bot-eligibility verdict, and the carry-over
  * result so callers can report what changed and why.
  */
 declare function reconcilePullRequest(client: GitHubClient, pr: number, policy: ReconcilePolicy, options?: ReconcileOptions): Promise<ReconcileResult>;
@@ -707,6 +744,7 @@ interface ParsedVerdict {
 declare function parseVerdict(review: ReviewFact): ParsedVerdict | undefined;
 /** Whether an author may cast a counting verdict under the policy. */
 declare function isTrustedAuthor(author: ReviewAuthor, policy: ReconcilePolicy): boolean;
+/** 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, COPILOT_REVIEWER_LOGIN, type ChangedFile, type CliDeps, type CliIo, type CollaboratorPermission, type CommitData, DEPENDABOT_LOGIN, DEPENDABOT_REBASE_COMMAND, DEPENDABOT_REBASING_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, 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, 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_SETTLE_MS, DEPENDABOT_LOGIN, DEPENDABOT_REBASE_COMMAND, DEPENDABOT_REBASING_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, isRebasePending, isTrustedAuthor, isVersionOnlyPatch, parseArgs, parseDependabotUpdateType, parseGitVersion, parseVerdict, planReconcile, postTokenAdvisory, rebaseRequestMarker, reconcilePullRequest, runCli, toReconcileJson, withoutReleaseActions };

package/dist/index.js

@@ -2,7 +2,7 @@ import {
   ACTOR_TYPES,
   AUTO_MERGE_LABEL,
   BRANCH_UPDATERS,
-  COPILOT_REVIEWER_LOGIN,
+  DEFAULT_SETTLE_MS,
   DEPENDABOT_LOGIN,
   DEPENDABOT_REBASE_COMMAND,
   DEPENDABOT_REBASING_NOTICE,
@@ -50,12 +50,12 @@ import {
   runCli,
   toReconcileJson,
   withoutReleaseActions
-} from "./chunk-PJOTYSEK.js";
+} from "./chunk-ENU2AAWK.js";
 export {
   ACTOR_TYPES,
   AUTO_MERGE_LABEL,
   BRANCH_UPDATERS,
-  COPILOT_REVIEWER_LOGIN,
+  DEFAULT_SETTLE_MS,
   DEPENDABOT_LOGIN,
   DEPENDABOT_REBASE_COMMAND,
   DEPENDABOT_REBASING_NOTICE,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rmartz/pr-lifecycle",
-  "version": "7.0.0",
+  "version": "8.0.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",