@effect-agent/pr-review 0.1.0-beta.23 → 0.1.0-beta.25

package/src/action.ts

@@ -3,6 +3,8 @@ import { Config, Console, Effect, FileSystem, Layer, Option, Redacted, Schema }
 import { BudgetExceeded, UsageBudgetLimits } from "effect-agent";
 import { FetchHttpClient } from "effect/unstable/http";
 
+import { collectReviewAdjudications } from "./internal/adjudication.ts";
+import { splitCarriedScope } from "./internal/coverage.ts";
 import type { ChangedFile } from "./internal/diff.ts";
 import { InvalidEffortInput, parseEffortPosition, type EffortPosition } from "./internal/effort.ts";
 import { PrReview, type RunReviewOptions } from "./internal/factory.ts";
@@ -21,9 +23,14 @@ import {
 } from "./internal/providers.ts";
 import { retireStaleReviews } from "./internal/retirement.ts";
 import {
+  adjudicationIdentity,
+  concernIdentity,
+  findingIdentity,
+  fullReviewSelection,
   ReviewExecutionContext,
   ReviewHeadComparison,
   ReviewStateAuthenticator,
+  isLineageAncestor,
   type ReviewMode,
   type ReviewState,
   selectReviewRange,
@@ -259,8 +266,6 @@ const outcomeOutputs = (
   ["verdict", outcome.review.verdict],
   ["input-coverage", outcome.inputCoverage.status],
   ["review-assurance", outcome.assurance.status],
-  // Compatibility output: the precise outputs above own new integrations.
-  ["coverage", outcome.coverage.status],
   ["review-mode", outcome.reviewMode ?? "full"],
   ["review-reason", outcome.reviewReason ?? "direct full review"],
   ["inline-comments", String(outcome.plan.comments.length)],
@@ -280,26 +285,34 @@ const outcomeSummary = (
   outcome: ReviewRunOutcome,
   modelLabel: string | undefined,
   conclusion: ReviewCheckConclusion,
-): ReadonlyArray<string> => [
-  "### Pull-request review",
-  `- Check conclusion: **${conclusion}**`,
-  `- Verdict: **${outcome.review.verdict}**`,
-  `- Input coverage: **${outcome.inputCoverage.status}** · scope: ${outcome.reviewMode ?? "full"}`,
-  `- Review assurance: **${outcome.assurance.status}** · general discovery ${outcome.assurance.completedGeneralDiscoveryPasses}/${outcome.assurance.requiredGeneralDiscoveryPasses} · specialist ${outcome.assurance.completedSpecialistPasses}/${outcome.assurance.requiredSpecialistPasses} · verification ${outcome.assurance.completedVerificationPasses}/${outcome.assurance.requiredVerificationPasses}`,
-  `- Inline comments: ${outcome.plan.comments.length} · demoted findings: ${outcome.plan.demoted.length} · concerns: ${outcome.review.concerns?.length ?? 0}`,
-  ...(outcome.unreviewedPaths.length === 0
-    ? []
-    : [
-        `- Carried forward: ${outcome.unreviewedPaths.length} unreviewed path(s) retried automatically on the next run (reviewer-side gap, not a code defect)`,
-      ]),
-  ...(modelLabel === undefined ? [] : [`- Model: \`${modelLabel}\``]),
-  ...(outcome.usage === undefined
-    ? []
-    : [`- Tokens: ${outcome.usage.inputTokens} in / ${outcome.usage.outputTokens} out`]),
-  ...(outcome.published === undefined
-    ? ["- Dry run: nothing posted"]
-    : [`- Posted: ${outcome.published.url}`]),
-];
+): ReadonlyArray<string> => {
+  const scope = splitCarriedScope(outcome);
+  return [
+    "### Pull-request review",
+    `- Check conclusion: **${conclusion}**`,
+    `- Verdict: **${outcome.review.verdict}**`,
+    `- Input coverage: **${outcome.inputCoverage.status}** · scope: ${outcome.reviewMode ?? "full"}`,
+    `- Review assurance: **${outcome.assurance.status}** · general discovery ${outcome.assurance.completedGeneralDiscoveryPasses}/${outcome.assurance.requiredGeneralDiscoveryPasses} · specialist ${outcome.assurance.completedSpecialistPasses}/${outcome.assurance.requiredSpecialistPasses} · verification ${outcome.assurance.completedVerificationPasses}/${outcome.assurance.requiredVerificationPasses}`,
+    `- Inline comments: ${outcome.plan.comments.length} · demoted findings: ${outcome.plan.demoted.length} · concerns: ${outcome.review.concerns?.length ?? 0}`,
+    ...(scope.retryablePaths.length === 0
+      ? []
+      : [
+          `- Carried forward: ${scope.retryablePaths.length} unreviewed path(s) retried automatically on the next run (reviewer-side gap, not a code defect)`,
+        ]),
+    ...(scope.undiffablePaths.length === 0
+      ? []
+      : [
+          `- Unreviewable: ${scope.undiffablePaths.length} path(s) with no reviewable diff (binary or oversized) — remove them from the pull request or exclude them with ignore globs`,
+        ]),
+    ...(modelLabel === undefined ? [] : [`- Model: \`${modelLabel}\``]),
+    ...(outcome.usage === undefined
+      ? []
+      : [`- Tokens: ${outcome.usage.inputTokens} in / ${outcome.usage.outputTokens} out`]),
+    ...(outcome.published === undefined
+      ? ["- Dry run: nothing posted"]
+      : [`- Posted: ${outcome.published.url}`]),
+  ];
+};
 
 /** The result of one action invocation: a typed skip or a settled review. */
 export type ReviewActionResult =
@@ -332,30 +345,41 @@ const resolveRunUrl = Effect.fn("resolveRunUrl")(function* () {
  * The reviewer surface the action harness drives. `PrReview.make` and
  * `PrReview.makeFanOut` provide the state-selection effects. A fingerprint is
  * skip authority only when a profile fingerprint and authenticated review
- * state bind it to settled assurance; a fingerprint-only custom harness
- * remains source-compatible but deliberately runs instead of claiming green
- * assurance from unauthenticated prior-review text.
+ * state bind it to settled assurance.
  */
-export interface HarnessedReviewer<E, R, FingerprintE, FingerprintR> {
-  readonly run: (runOptions?: RunReviewOptions) => Effect.Effect<ReviewRunOutcome, E, R>;
-  /** Current effective changeset fingerprint; not standalone skip authority. */
-  readonly fingerprint?: Effect.Effect<string, FingerprintE, FingerprintR> | undefined;
-  readonly profileFingerprint?: Effect.Effect<string, FingerprintE, FingerprintR> | undefined;
-  readonly snapshot?:
-    | Effect.Effect<
-        {
-          readonly metadata: PullRequestMetadata;
-          readonly files: ReadonlyArray<ChangedFile>;
-        },
-        FingerprintE,
-        FingerprintR
-      >
-    | undefined;
-  readonly filterFiles?:
-    | ((files: ReadonlyArray<ChangedFile>) => ReadonlyArray<ChangedFile>)
-    | undefined;
+interface HarnessedReviewerBase<E, R> {
+  /** The action composition root always supplies the selected run context. */
+  readonly run: (
+    runOptions?: RunReviewOptions,
+  ) => Effect.Effect<ReviewRunOutcome, E, R | ReviewExecutionContext>;
 }
 
+export type HarnessedReviewer<E, R, FingerprintE, FingerprintR> = HarnessedReviewerBase<E, R> &
+  (
+    | {
+        readonly fingerprint?: undefined;
+        readonly profileFingerprint?: undefined;
+        readonly snapshot?: undefined;
+        readonly filterFiles?: undefined;
+      }
+    | {
+        /** Current effective changeset fingerprint; not standalone skip authority. */
+        readonly fingerprint: Effect.Effect<string, FingerprintE, FingerprintR>;
+        readonly profileFingerprint: Effect.Effect<string, FingerprintE, FingerprintR>;
+        readonly snapshot: Effect.Effect<
+          {
+            readonly metadata: PullRequestMetadata;
+            readonly files: ReadonlyArray<ChangedFile>;
+          },
+          FingerprintE,
+          FingerprintR
+        >;
+        readonly filterFiles?:
+          | ((files: ReadonlyArray<ChangedFile>) => ReadonlyArray<ChangedFile>)
+          | undefined;
+      }
+  );
+
 const blockingReasons = (input: {
   readonly findings: ReadonlyArray<{ readonly severity: string; readonly title: string }>;
   readonly concerns: ReadonlyArray<{ readonly severity: string; readonly title: string }>;
@@ -372,10 +396,13 @@ const blockingReasons = (input: {
  * Host-derived check conclusion; model verdict prose cannot weaken it.
  *
  * Blocking code findings outrank machinery gaps — they are the actionable
- * signal. A machinery gap (incomplete input, unsettled passes) concludes
- * `incomplete` with reasons that explicitly say the failure is reviewer-side
- * uncertainty carried forward for retry, never an invitation to change code.
- * The flat reviewer's constant `unverified` assurance is not a gap.
+ * signal. A retryable machinery gap (failed passes, capacity overflow)
+ * concludes `incomplete` with reasons that explicitly say the failure is
+ * reviewer-side uncertainty carried forward for retry, never an invitation to
+ * change code. Undiffable files are the deliberate exception: no retry can
+ * settle them, so their reason instructs removal or ignore globs instead of
+ * promising an automatic retry. The flat reviewer's constant `unverified`
+ * assurance is not a gap.
  */
 export const concludeReviewOutcome = (
   outcome: ReviewRunOutcome,
@@ -385,11 +412,19 @@ export const concludeReviewOutcome = (
 } => {
   const machinery: Array<string> = [];
   if (outcome.inputCoverage.status === "incomplete" || outcome.assurance.status === "incomplete") {
-    machinery.push(
-      outcome.unreviewedPaths.length > 0
-        ? `review infrastructure did not settle — a reviewer-side gap, not a code defect; ${outcome.unreviewedPaths.length} path(s) are carried forward and retried automatically on the next run`
-        : "review infrastructure did not settle — a reviewer-side gap, not a code defect",
-    );
+    const scope = splitCarriedScope(outcome);
+    if (scope.retryableGap) {
+      machinery.push(
+        scope.retryablePaths.length > 0
+          ? `review infrastructure did not settle — a reviewer-side gap, not a code defect; ${scope.retryablePaths.length} path(s) are carried forward and retried automatically on the next run`
+          : "review infrastructure did not settle — a reviewer-side gap, not a code defect",
+      );
+    }
+    if (scope.undiffablePaths.length > 0) {
+      machinery.push(
+        `${scope.undiffablePaths.length} path(s) have no reviewable diff (binary or oversized) and no retry can settle them — remove them from the pull request or exclude them with ignore globs`,
+      );
+    }
     if (outcome.inputCoverage.status === "incomplete") {
       machinery.push(...outcome.inputCoverage.reasons);
     }
@@ -408,10 +443,14 @@ export const concludeReviewOutcome = (
   return { conclusion: "success", reasons: [] };
 };
 
-const concludeReviewState = (state: ReviewState) => {
+const concludeReviewState = (state: ReviewState, adjudicated: ReadonlySet<string>) => {
   const reasons = blockingReasons({
-    findings: state.unresolvedFindings,
-    concerns: state.unresolvedConcerns,
+    findings: state.unresolvedFindings.filter(
+      (finding) => !adjudicated.has(findingIdentity(finding)),
+    ),
+    concerns: state.unresolvedConcerns.filter(
+      (concern) => !adjudicated.has(concernIdentity(concern)),
+    ),
   });
   return reasons.length > 0
     ? ({ conclusion: "blocking", reasons } as const)
@@ -423,20 +462,21 @@ const skipCoveredReview = Effect.fn("skipCoveredReview")(function* (input: {
   readonly pullRequestNumber: number;
   readonly reason: string;
   readonly state: ReviewState;
-  readonly fingerprint?: string | undefined;
 }) {
-  const result = concludeReviewState(input.state);
+  // A maintainer adjudication must lift a preserved blocking conclusion
+  // without a code push, so the skip path re-reads adjudications (fail-open;
+  // stored ones survive a listing fault) before enforcing the stored state.
+  const adjudications = yield* collectReviewAdjudications(input.state.adjudications ?? []);
+  const result = concludeReviewState(input.state, new Set(adjudications.map(adjudicationIdentity)));
   yield* Console.log(
     `Skipping review of ${input.repository}#${input.pullRequestNumber}: ${input.reason}.`,
   );
   yield* writeActionOutputs([
     ["skipped", "true"],
     ["skip-reason", input.reason],
-    ...(input.fingerprint === undefined ? [] : ([["fingerprint", input.fingerprint]] as const)),
     ["conclusion", result.conclusion],
     ["input-coverage", "complete"],
     ["review-assurance", "settled"],
-    ["coverage", "complete"],
     ["review-mode", "incremental"],
   ]);
   yield* writeStepSummary([
@@ -501,16 +541,13 @@ export const runReviewAction = <E, R, FingerprintE = never, FingerprintR = never
     return yield* Effect.gen(function* () {
       let selection: ReturnType<typeof selectReviewRange> | undefined;
       if (reviewer.profileFingerprint !== undefined) {
-        const source = yield* PullRequestSource;
         const [snapshot, profileFingerprint, currentFingerprint] = yield* Effect.all([
-          reviewer.snapshot ?? Effect.all({ metadata: source.metadata, files: source.anchorFiles }),
+          reviewer.snapshot,
           reviewer.profileFingerprint,
-          reviewer.fingerprint === undefined
-            ? Effect.succeed(undefined)
-            : reviewer.fingerprint.pipe(
-                Effect.map((fingerprint): string | undefined => fingerprint),
-                Effect.orElseSucceed(() => undefined),
-              ),
+          reviewer.fingerprint.pipe(
+            Effect.map((fingerprint): string | undefined => fingerprint),
+            Effect.orElseSucceed(() => undefined),
+          ),
         ]);
         const { metadata, files: fullFiles } = snapshot;
         const history = options.priorReviews ?? (yield* PriorReviews);
@@ -541,7 +578,7 @@ export const runReviewAction = <E, R, FingerprintE = never, FingerprintR = never
           recovered.state.settled &&
           currentFingerprint !== undefined &&
           validateReviewState(recovered.state, metadata, profileFingerprint) === undefined &&
-          recovered.state.acceptedScopeFingerprint === currentFingerprint
+          recovered.state.settledScopeFingerprint === currentFingerprint
             ? recovered.state
             : undefined;
         if (equivalentPatchState !== undefined) {
@@ -553,11 +590,11 @@ export const runReviewAction = <E, R, FingerprintE = never, FingerprintR = never
                 ? "the current head already has settled stored review assurance"
                 : "the effective pull-request patch is unchanged since the last settled review",
             state: equivalentPatchState,
-            fingerprint: currentFingerprint,
           });
         }
         let comparison: ReviewHeadComparison | undefined;
         let baseComparison: ReviewHeadComparison | undefined;
+        let contentComparison: ReviewHeadComparison | undefined;
         if (
           (options.reviewMode ?? "incremental") === "incremental" &&
           recovered.state !== undefined
@@ -593,6 +630,21 @@ export const runReviewAction = <E, R, FingerprintE = never, FingerprintR = never
               });
             }
           }
+          if (
+            recovered.state.reviewedHeadSha !== metadata.headSha &&
+            (comparison === undefined ||
+              !isLineageAncestor(comparison, recovered.state, metadata.headSha))
+          ) {
+            contentComparison = yield* history
+              .compareTrees(recovered.state.reviewedHeadSha, metadata.headSha)
+              .pipe(Effect.orElseSucceed(() => undefined));
+            if (contentComparison !== undefined && reviewer.filterFiles !== undefined) {
+              contentComparison = ReviewHeadComparison.make({
+                ...contentComparison,
+                files: reviewer.filterFiles(contentComparison.files),
+              });
+            }
+          }
         }
         selection = {
           ...selectReviewRange({
@@ -603,6 +655,7 @@ export const runReviewAction = <E, R, FingerprintE = never, FingerprintR = never
             priorState: recovered.state,
             comparison,
             baseComparison,
+            contentComparison,
             lookupFailure: recovered.failure,
           }),
           stateAuthenticator,
@@ -623,6 +676,17 @@ export const runReviewAction = <E, R, FingerprintE = never, FingerprintR = never
           });
         }
       }
+      const executionContext =
+        selection ??
+        (yield* Effect.gen(function* () {
+          const source = yield* PullRequestSource;
+          const [metadata, files] = yield* Effect.all([source.metadata, source.changedFiles]);
+          return fullReviewSelection({
+            reason: "explicit custom-reviewer full review without continuity selection",
+            files,
+            totalFiles: metadata.totalChangedFiles,
+          });
+        }));
       yield* Console.log(
         `Reviewing ${target.repository}#${target.number} (${options.post === false ? "dry run" : "posting"})...`,
       );
@@ -639,9 +703,9 @@ export const runReviewAction = <E, R, FingerprintE = never, FingerprintR = never
         const headMetadata = yield* source.metadata.pipe(Effect.orElseSucceed(() => undefined));
         yield* progress.value.begin({
           headSha: headMetadata?.headSha,
-          reviewMode: selection?.mode,
-          reviewReason: selection?.reason,
-          filesInScope: selection?.files.length,
+          reviewMode: executionContext.mode,
+          reviewReason: executionContext.reason,
+          filesInScope: executionContext.files.length,
           modelLabel: options.modelLabel,
           runUrl,
         });
@@ -658,12 +722,11 @@ export const runReviewAction = <E, R, FingerprintE = never, FingerprintR = never
             ),
           )
         : runReview;
-      const outcome = yield* selection === undefined
-        ? reviewEffect
-        : reviewEffect.pipe(
-            Effect.provide(selectedPullRequestSourceLayer(selection)),
-            Effect.provideService(ReviewExecutionContext, selection),
-          );
+      const executionLayer = Layer.merge(
+        Layer.succeed(ReviewExecutionContext)(executionContext),
+        selectedPullRequestSourceLayer(executionContext),
+      );
+      const outcome = yield* reviewEffect.pipe(Effect.provide(executionLayer));
       yield* Console.log(
         `Review finished in ${outcome.turns} turn(s): verdict ${outcome.review.verdict}, ` +
           `${outcome.plan.comments.length} inline comment(s), ${outcome.plan.demoted.length} demoted finding(s).`,

package/src/cli.ts

@@ -19,6 +19,7 @@ import {
   type ReviewProvider,
 } from "./internal/providers.ts";
 import { ReviewPublicationPlan } from "./internal/render.ts";
+import { fullReviewExecutionContextLayer } from "./internal/review-state.ts";
 import type { ReviewRunOutcome } from "./internal/run.ts";
 
 // ---------------------------------------------------------------------------
@@ -158,7 +159,11 @@ const command = CliCommand.make(
               return Option.none<ReviewRunOutcome>();
             }
           }
-          return Option.some(yield* reviewer.run({ post: flags.post }));
+          return Option.some(
+            yield* reviewer
+              .run({ post: flags.post })
+              .pipe(Effect.provide(fullReviewExecutionContextLayer("explicit CLI full review"))),
+          );
         });
 
       let result: Option.Option<ReviewRunOutcome>;

package/src/index.ts

@@ -1,6 +1,7 @@
 // The @effect-agent/pr-review public surface. Platform-free: host entrypoints
 // live behind the "./action" and "./cli" subpaths, deterministic test helpers
 // behind "./testing".
+export * from "./internal/adjudication.ts";
 export * from "./internal/anchors.ts";
 export * from "./internal/diff.ts";
 export * from "./internal/coverage.ts";