@effect-agent/pr-review 0.1.0-beta.22 → 0.1.0-beta.24

package/src/internal/review-state.ts

@@ -46,16 +46,37 @@ export class StoredReviewConcern extends Schema.Class<StoredReviewConcern>(
   body: StoredText,
 }) {}
 
+/** The carried-scope bound; a run that cannot fit its leftovers publishes no state. */
+export const MAX_STORED_UNREVIEWED_PATHS = 100;
+
+/** Failed-pass records stored beside the leftover paths; one per unit stage. */
+export const MAX_STORED_UNREVIEWED_PASSES = 24;
+
+/** Stages a leftover path may need retried without a second general discovery. */
+export const UnreviewedStage = Schema.Literals(["discovery", "specialist", "verification"]);
+export type UnreviewedStage = typeof UnreviewedStage.Type;
+
+/** One failed fan-out pass whose paths should be retried, not rediscovered. */
+export class StoredUnreviewedPass extends Schema.Class<StoredUnreviewedPass>(
+  "@effect-agent/pr-review/StoredUnreviewedPass",
+)({
+  stage: UnreviewedStage,
+  paths: Schema.Array(ChangedPath).check(Schema.isMinLength(1)).check(Schema.isMaxLength(12)),
+}) {}
+
 /**
- * Versioned state embedded only after complete input assignment and settled
- * configured review assurance. The head plus full-scope fingerprint forms an
- * incremental baseline; an absent unresolved item never means the path is
- * defect-free. The `acceptedScopeFingerprint` name is retained for wire
- * compatibility. Storing hundreds of path strings separately would not fit
- * GitHub's bounded review body in the worst case.
+ * Versioned state embedded after EVERY completed run that can be signed. The
+ * head plus full-scope fingerprint forms an incremental baseline; an absent
+ * unresolved item never means the path is defect-free. `unreviewedPaths`
+ * carries retryable review gaps (failed passes) forward so the next
+ * incremental run re-reviews exactly them plus the new delta — the baseline
+ * advances monotonically instead of freezing on one flaky pass and reopening
+ * the whole post-baseline scope. The `acceptedScopeFingerprint` name is
+ * retained for wire compatibility. Storing hundreds of path strings
+ * separately would not fit GitHub's bounded review body in the worst case.
  */
 export class ReviewState extends Schema.Class<ReviewState>("@effect-agent/pr-review/ReviewState")({
-  version: Schema.Literal(1),
+  version: Schema.Literal(2),
   repository: Schema.NonEmptyString.check(Schema.isMaxLength(200)),
   pullRequestNumber: Schema.Int.check(Schema.isGreaterThan(0)),
   baseRef: Schema.NonEmptyString.check(Schema.isMaxLength(300)),
@@ -67,6 +88,22 @@ export class ReviewState extends Schema.Class<ReviewState>("@effect-agent/pr-rev
   reviewedPathCount: Schema.Int.check(Schema.isBetween({ minimum: 0, maximum: 300 })),
   unresolvedFindings: Schema.Array(StoredReviewFinding).check(Schema.isMaxLength(20)),
   unresolvedConcerns: Schema.Array(StoredReviewConcern).check(Schema.isMaxLength(10)),
+  /** Retryable review gaps carried into the next incremental run's scope. */
+  unreviewedPaths: Schema.Array(ChangedPath).check(Schema.isMaxLength(MAX_STORED_UNREVIEWED_PATHS)),
+  /**
+   * Which failed pass produced those leftovers. Absent on state-v2 markers
+   * written before this field existed; those leftovers still re-enter scope
+   * but cannot skip rediscovery. Present (including empty) on new markers.
+   */
+  unreviewedPasses: Schema.optionalKey(
+    Schema.Array(StoredUnreviewedPass).check(Schema.isMaxLength(MAX_STORED_UNREVIEWED_PASSES)),
+  ),
+  /**
+   * True only when the producing run had complete input coverage, no
+   * unsettled pass, and nothing carried. Skip-unchanged authority: an
+   * unchanged patch may skip re-review only over a settled state.
+   */
+  settled: Schema.Boolean,
   lastReviewMode: ReviewScopeMode,
 }) {}
 
@@ -100,15 +137,15 @@ export const toStoredConcern = (concern: ReviewConcern): StoredReviewConcern =>
 export const fromStoredConcern = (concern: StoredReviewConcern): ReviewConcern =>
   ReviewConcern.make({ severity: concern.severity, title: concern.title, body: concern.body });
 
-const STATE_MARKER_PREFIX = "<!-- effect-agent-pr-review state-v1:";
+const STATE_MARKER_PREFIX = "<!-- effect-agent-pr-review state-v2:";
 const STATE_MARKER_SUFFIX = " -->";
 const STATE_MARKER_PATTERN =
-  /(?:^|\n)<!-- effect-agent-pr-review state-v1:([A-Za-z0-9+/]+={0,2})\.([0-9a-f]{64}) -->$/;
-const STATE_SIGNATURE_DOMAIN = "effect-agent-pr-review/state-v1\u0000";
+  /(?:^|\n)<!-- effect-agent-pr-review state-v2:([A-Za-z0-9+/]+={0,2})\.([0-9a-f]{64}) -->$/;
+const STATE_SIGNATURE_DOMAIN = "effect-agent-pr-review/state-v2\u0000";
 export const MAX_REVIEW_STATE_MARKER_CHARS = 24_000;
 export const ReviewStateMarker = Schema.NonEmptyString.check(
   Schema.isMaxLength(MAX_REVIEW_STATE_MARKER_CHARS),
-  Schema.isPattern(/^<!-- effect-agent-pr-review state-v1:[A-Za-z0-9+/]+={0,2}\.[0-9a-f]{64} -->$/),
+  Schema.isPattern(/^<!-- effect-agent-pr-review state-v2:[A-Za-z0-9+/]+={0,2}\.[0-9a-f]{64} -->$/),
 ).pipe(Schema.brand("@effect-agent/pr-review/ReviewStateMarker"));
 export type ReviewStateMarker = typeof ReviewStateMarker.Type;
 
@@ -278,6 +315,12 @@ export interface ReviewSelection {
   readonly files: ReadonlyArray<ChangedFile>;
   /** Paths whose changes invalidate prior findings, including paths reverted out of the PR. */
   readonly affectedPaths: ReadonlyArray<string>;
+  /**
+   * Leftover paths whose contents did not change. Fan-out retries only the
+   * recorded failed stages on these paths and keeps their stored findings.
+   */
+  readonly retryPaths: ReadonlyArray<string>;
+  readonly retryStages: ReadonlyArray<UnreviewedStage>;
   readonly totalFiles: number;
   readonly baselineSha: string | undefined;
   readonly priorState: ReviewState | undefined;
@@ -298,12 +341,26 @@ const fullSelection = (input: {
   affectedPaths: input.files.flatMap((file) =>
     file.previousPath === undefined ? [file.path] : [file.path, file.previousPath],
   ),
+  retryPaths: [],
+  retryStages: [],
   totalFiles: input.totalFiles,
   baselineSha: undefined,
   priorState: undefined,
   profileFingerprint: input.profileFingerprint,
 });
 
+/** Three-dot lineage from the reviewed head to the current head is usable. */
+export const isLineageAncestor = (
+  comparison: ReviewHeadComparison,
+  priorState: ReviewState,
+  currentHeadSha: string,
+): boolean =>
+  comparison.baseSha === priorState.reviewedHeadSha &&
+  comparison.headSha === currentHeadSha &&
+  comparison.mergeBaseSha === priorState.reviewedHeadSha &&
+  !comparison.truncated &&
+  (comparison.status === "ahead" || comparison.status === "identical");
+
 /**
  * Validate that persisted state belongs to this exact PR/base lineage and the
  * same review profile. A mismatch is a full-review reason, never an error that
@@ -326,6 +383,96 @@ export const validateReviewState = (
   return undefined;
 };
 
+const filePaths = (file: ChangedFile): ReadonlyArray<string> =>
+  file.previousPath === undefined ? [file.path] : [file.path, file.previousPath];
+
+const incrementalFromDelta = (input: {
+  readonly current: PullRequestMetadata;
+  readonly fullFiles: ReadonlyArray<ChangedFile>;
+  readonly profileFingerprint: string;
+  readonly priorState: ReviewState;
+  readonly deltaFiles: ReadonlyArray<ChangedFile>;
+  readonly extraAffectedPaths?: ReadonlyArray<string> | undefined;
+  readonly reason: string;
+}): ReviewSelection => {
+  const currentPaths = new Set(input.fullFiles.flatMap(filePaths));
+  const affectedPaths = new Set([
+    ...input.deltaFiles.flatMap(filePaths),
+    ...(input.extraAffectedPaths ?? []),
+  ]);
+  const selectedByPath = new Map<string, ChangedFile>();
+  for (const file of input.deltaFiles) {
+    if (
+      currentPaths.has(file.path) ||
+      (file.previousPath !== undefined && currentPaths.has(file.previousPath))
+    ) {
+      selectedByPath.set(file.path, file);
+    }
+  }
+  const carriedPaths = input.priorState.unreviewedPaths.filter((path) => currentPaths.has(path));
+  const surgical = input.priorState.unreviewedPasses !== undefined;
+  const retryOnly = new Set<string>();
+  const retryStages = new Set<UnreviewedStage>();
+  for (const path of carriedPaths) {
+    if (affectedPaths.has(path)) continue;
+    retryOnly.add(path);
+    if (surgical) {
+      for (const pass of input.priorState.unreviewedPasses ?? []) {
+        if (pass.paths.includes(path)) retryStages.add(pass.stage);
+      }
+    } else {
+      affectedPaths.add(path);
+    }
+  }
+  if (
+    surgical &&
+    retryStages.has("verification") &&
+    !retryStages.has("discovery") &&
+    !retryStages.has("specialist")
+  ) {
+    retryStages.add("discovery");
+    retryStages.add("specialist");
+  }
+  if (surgical && retryOnly.size > 0 && retryStages.size === 0) {
+    for (const path of retryOnly) affectedPaths.add(path);
+    retryStages.add("discovery");
+    retryStages.add("specialist");
+    retryStages.add("verification");
+  }
+  if (carriedPaths.length > 0 || (input.extraAffectedPaths?.length ?? 0) > 0) {
+    for (const file of input.fullFiles) {
+      const needed =
+        affectedPaths.has(file.path) ||
+        (file.previousPath !== undefined && affectedPaths.has(file.previousPath)) ||
+        retryOnly.has(file.path) ||
+        (file.previousPath !== undefined && retryOnly.has(file.previousPath));
+      if (needed) selectedByPath.set(file.path, file);
+    }
+  }
+  const selectedFiles = [...selectedByPath.values()].sort((left, right) =>
+    left.path < right.path ? -1 : left.path > right.path ? 1 : 0,
+  );
+  const leftoverCount = [...retryOnly].filter((path) => !affectedPaths.has(path)).length;
+  const carriedReason =
+    leftoverCount > 0 && surgical
+      ? `; retrying ${leftoverCount} unchanged leftover path(s) without rediscovery`
+      : carriedPaths.length > 0
+        ? `; retrying ${carriedPaths.length} carried unreviewed path(s)`
+        : "";
+  return {
+    mode: "incremental",
+    reason: `${input.reason}${carriedReason}`,
+    files: selectedFiles,
+    affectedPaths: [...affectedPaths].sort(),
+    retryPaths: [...retryOnly].filter((path) => !affectedPaths.has(path)).sort(),
+    retryStages: [...retryStages].sort(),
+    totalFiles: selectedFiles.length,
+    baselineSha: input.priorState.reviewedHeadSha,
+    priorState: input.priorState,
+    profileFingerprint: input.profileFingerprint,
+  };
+};
+
 /** Pure, deterministic range selection with conservative full-review fallbacks. */
 export const selectReviewRange = (input: {
   readonly requestedMode: ReviewMode;
@@ -335,6 +482,12 @@ export const selectReviewRange = (input: {
   readonly priorState: ReviewState | undefined;
   readonly comparison: ReviewHeadComparison | undefined;
   readonly baseComparison?: ReviewHeadComparison | undefined;
+  /**
+   * Two-dot tree comparison used when the reviewed head is not a git ancestor
+   * (rebase, amend, force-push). Intersected with the current PR path set so
+   * main-drift outside the pull request never re-enters scope.
+   */
+  readonly contentComparison?: ReviewHeadComparison | undefined;
   readonly lookupFailure?: string | undefined;
 }): ReviewSelection => {
   const full = (reason: string) =>
@@ -352,79 +505,53 @@ export const selectReviewRange = (input: {
   const invalid = validateReviewState(input.priorState, input.current, input.profileFingerprint);
   if (invalid !== undefined) return full(invalid);
   const comparison = input.comparison;
-  if (comparison === undefined) return full("the incremental head comparison was unavailable");
   if (
-    comparison.baseSha !== input.priorState.reviewedHeadSha ||
-    comparison.headSha !== input.current.headSha ||
-    comparison.mergeBaseSha !== input.priorState.reviewedHeadSha ||
-    (comparison.status !== "ahead" && comparison.status !== "identical")
+    comparison !== undefined &&
+    isLineageAncestor(comparison, input.priorState, input.current.headSha)
   ) {
-    return full("the prior reviewed head is not an ancestor of the current head");
-  }
-  if (comparison.truncated) return full("the incremental comparison exceeded GitHub's file bound");
-  const affectedPaths = new Set(
-    comparison.files.flatMap((file) =>
-      file.previousPath === undefined ? [file.path] : [file.path, file.previousPath],
-    ),
-  );
-  let baseReason = "";
-  if (input.priorState.baseSha !== input.current.baseSha) {
-    const baseComparison = input.baseComparison;
-    if (baseComparison === undefined) {
-      return full("the pull request base changed and its lineage comparison was unavailable");
-    }
-    if (
-      baseComparison.baseSha !== input.priorState.baseSha ||
-      baseComparison.headSha !== input.current.baseSha ||
-      baseComparison.mergeBaseSha !== input.priorState.baseSha ||
-      (baseComparison.status !== "ahead" && baseComparison.status !== "identical") ||
-      baseComparison.truncated
-    ) {
-      return full("the pull request base changed materially or exceeded the comparison bound");
-    }
-    for (const file of baseComparison.files) {
-      affectedPaths.add(file.path);
-      if (file.previousPath !== undefined) affectedPaths.add(file.previousPath);
-    }
-    baseReason = `; base advanced from ${input.priorState.baseSha.slice(0, 7)} and overlapping PR paths were included`;
-  }
-  const currentPaths = new Set(
-    input.fullFiles.flatMap((file) =>
-      file.previousPath === undefined ? [file.path] : [file.path, file.previousPath],
-    ),
-  );
-  const selectedByPath = new Map<string, ChangedFile>();
-  for (const file of comparison.files) {
-    if (
-      currentPaths.has(file.path) ||
-      (file.previousPath !== undefined && currentPaths.has(file.previousPath))
-    ) {
-      selectedByPath.set(file.path, file);
-    }
-  }
-  if (input.priorState.baseSha !== input.current.baseSha) {
-    for (const file of input.fullFiles) {
+    const extraAffected: Array<string> = [];
+    let baseReason = "";
+    if (input.priorState.baseSha !== input.current.baseSha) {
+      const baseComparison = input.baseComparison;
+      if (baseComparison === undefined) {
+        return full("the pull request base changed and its lineage comparison was unavailable");
+      }
       if (
-        affectedPaths.has(file.path) ||
-        (file.previousPath !== undefined && affectedPaths.has(file.previousPath))
+        baseComparison.baseSha !== input.priorState.baseSha ||
+        baseComparison.headSha !== input.current.baseSha ||
+        baseComparison.mergeBaseSha !== input.priorState.baseSha ||
+        (baseComparison.status !== "ahead" && baseComparison.status !== "identical") ||
+        baseComparison.truncated
       ) {
-        selectedByPath.set(file.path, file);
+        return full("the pull request base changed materially or exceeded the comparison bound");
       }
+      for (const file of baseComparison.files) extraAffected.push(...filePaths(file));
+      baseReason = `; base advanced from ${input.priorState.baseSha.slice(0, 7)} and overlapping PR paths were included`;
     }
+    return incrementalFromDelta({
+      current: input.current,
+      fullFiles: input.fullFiles,
+      profileFingerprint: input.profileFingerprint,
+      priorState: input.priorState,
+      deltaFiles: comparison.files,
+      extraAffectedPaths: extraAffected,
+      reason: `changes since reviewed head ${input.priorState.reviewedHeadSha.slice(0, 7)}${baseReason}`,
+    });
   }
-  const selectedFiles = [...selectedByPath.values()].sort((left, right) =>
-    left.path < right.path ? -1 : left.path > right.path ? 1 : 0,
-  );
-  return {
-    mode: "incremental",
-    reason: `changes since settled review head ${input.priorState.reviewedHeadSha.slice(0, 7)}${baseReason}`,
-    files: selectedFiles,
-    affectedPaths: [...affectedPaths].sort(),
-    totalFiles: selectedFiles.length,
-    baselineSha: input.priorState.reviewedHeadSha,
-    priorState: input.priorState,
-    profileFingerprint: input.profileFingerprint,
-  };
+  const contentComparison = input.contentComparison;
+  if (contentComparison !== undefined && !contentComparison.truncated) {
+    return incrementalFromDelta({
+      current: input.current,
+      fullFiles: input.fullFiles,
+      profileFingerprint: input.profileFingerprint,
+      priorState: input.priorState,
+      deltaFiles: contentComparison.files,
+      reason: `rewritten history; contents changed since reviewed head ${input.priorState.reviewedHeadSha.slice(0, 7)}`,
+    });
+  }
+  if (comparison === undefined) return full("the incremental head comparison was unavailable");
+  if (comparison.truncated) return full("the incremental comparison exceeded GitHub's file bound");
+  return full("the prior reviewed head is not an ancestor of the current head");
 };
 
 /** Per-run context consumed by orchestration and publication, not by the model. */
@@ -482,18 +609,6 @@ export const selectedPullRequestSourceLayer = (
     }),
   );
 
-/** Profile fingerprints are SHA-256 over configuration-only signatures. */
-export const computeProfileFingerprint = (signature: string): Effect.Effect<string> =>
-  Effect.promise(async () => {
-    const digest = await globalThis.crypto.subtle.digest(
-      "SHA-256",
-      new TextEncoder().encode(signature),
-    );
-    return Array.from(new Uint8Array(digest))
-      .map((byte) => byte.toString(16).padStart(2, "0"))
-      .join("");
-  });
-
 /** Build the full-surface mission used only to resolve profile guidance. */
 export const buildProfileMission = (
   metadata: PullRequestMetadata,

package/src/internal/review-units.ts

@@ -6,6 +6,7 @@ import {
   fileReviewEvidenceChunks,
   type FindingSeverity,
   MAX_PATCH_CHARS,
+  type ReviewConcern,
   type ReviewFinding,
 } from "./review-agent.ts";
 
@@ -465,3 +466,27 @@ export const rankAndDedupeFindings = (
     })
     .slice(0, MAX_MERGED_FINDINGS);
 };
+
+/**
+ * The concern analogue of `rankAndDedupeFindings`: dedupe by exact content
+ * keeping the most severe duplicate, rank by severity, and cap at the
+ * `CodeReview` concerns bound.
+ */
+export const rankAndDedupeConcerns = (
+  concerns: ReadonlyArray<ReviewConcern>,
+): ReadonlyArray<ReviewConcern> => {
+  const byContent = new Map<string, ReviewConcern>();
+  for (const concern of concerns) {
+    const key = `${concern.title}\u0000${concern.body}`;
+    const previous = byContent.get(key);
+    if (
+      previous === undefined ||
+      severityRank[concern.severity] < severityRank[previous.severity]
+    ) {
+      byContent.set(key, concern);
+    }
+  }
+  return [...byContent.values()]
+    .sort((left, right) => severityRank[left.severity] - severityRank[right.severity])
+    .slice(0, 10);
+};