@llm4ts/flow 2.50.0 → 2.52.0

package/src/Review.ts

@@ -34,6 +34,16 @@ import {
   parseUnifiedDiff,
   passedCountIn
 } from "./OracleGuard.ts"
+import { ReviewMemory } from "./Recheck.ts"
+import {
+  type Candidate,
+  diffChunks,
+  planRound,
+  recheckLead,
+  remember,
+  standing,
+  touchedFiles
+} from "./Recheck.ts"
 import { cachedReview, fingerprintOf } from "./ReviewCache.ts"
 import { withCallPurpose } from "./Timing.ts"
 import {
@@ -61,46 +71,8 @@ import {
   type JudgmentPolicy
 } from "./Judgment.ts"
 
-export const Severity = Schema.Literals(["Critical", "Warning", "Info"])
-export type Severity = typeof Severity.Type
-
-export class ReviewIssue extends Schema.Class<ReviewIssue>("ReviewIssue")({
-  severity: Severity,
-  title: Schema.String,
-  description: Schema.String.pipe(
-    Schema.withConstructorDefault(Effect.succeed("")),
-    Schema.withDecodingDefaultKey(Effect.succeed(""))
-  ),
-  file: Schema.optionalKey(Schema.String),
-  line: Schema.optionalKey(Schema.Int),
-  suggestion: Schema.optionalKey(Schema.String),
-  confidence: Schema.Number.pipe(
-    Schema.withConstructorDefault(Effect.succeed(1)),
-    Schema.withDecodingDefaultKey(Effect.succeed(1))
-  ),
-  /** A gate failure's triage against the base (ADR 0027); absent for review findings. */
-  origin: Schema.optionalKey(Schema.Literals(["new", "base", "flaky"])),
-  /** How a gate ended: a red exit, killed at the timeout, or a signal exit. */
-  gateClass: Schema.optionalKey(Schema.Literals(["red", "hang", "crash"])),
-  /** Why a test gate's output could not stand for green: no tests ran, or test files failed to load. */
-  gateReason: Schema.optionalKey(Schema.Literals(["zero-tests", "load-failure"])),
-  /** Where the gate's full output was written, when the caller asked for a log. */
-  logPath: Schema.optionalKey(Schema.String)
-}) {}
-
-export class ReviewResult extends Schema.Class<ReviewResult>("ReviewResult")({
-  issues: Schema.Array(ReviewIssue),
-  summary: Schema.String.pipe(
-    Schema.withConstructorDefault(Effect.succeed("")),
-    Schema.withDecodingDefaultKey(Effect.succeed(""))
-  ),
-  /** A test gate's passed-test count, when its output had a summary the oracle guard reads (ADR 0027). */
-  passed: Schema.optionalKey(Schema.Int)
-}) {
-  get isClean(): boolean {
-    return this.issues.length === 0
-  }
-}
+export { ReviewIssue, ReviewResult, Severity, reviewPrompt } from "./ReviewModel.ts"
+import { ReviewIssue, ReviewResult, reviewPrompt } from "./ReviewModel.ts"
 
 export const reviewJsonSchema: JsonSchema = {
   type: "object",
@@ -300,19 +272,6 @@ const fileSlug = (name: string): string =>
     .replace(/[^a-z0-9]+/g, "-")
     .replace(/^-+|-+$/g, "") || "lens"
 
-export const reviewPrompt = (task: string, diff: string): string =>
-  [
-    `Review the change below for task "${task}". Report problems as JSON:`,
-    '{"issues":[{"severity":"Critical|Warning|Info","title":"...",',
-    '"description":"..."}],"summary":"..."}.',
-    'An empty "issues" array means the change is acceptable. Respond with JSON only.',
-    "The diff below is the whole subject: judge what it shows. Do not explore the",
-    "repository, read other files, or run anything; answer from the diff.",
-    "",
-    "Diff:",
-    diff
-  ].join("\n")
-
 export interface FixPromptOptions {
   /** Characters of a gate's output kept in the prompt, from the end. Default 4000. */
   readonly tailChars?: number
@@ -460,6 +419,17 @@ export const applyTriage = Effect.fn("@llm4ts/flow/Review.applyTriage")(function
   return triaged.blocking
 })
 
+/** Names `lens` as the source of every finding in `result` that names none yet (ADR 0044). */
+export const tagLens = (lens: string, result: ReviewResult): ReviewResult =>
+  result.issues.every((issue) => issue.lens !== undefined)
+    ? result
+    : ReviewResult.make({
+        ...result,
+        issues: result.issues.map((issue) =>
+          issue.lens === undefined ? ReviewIssue.make({ ...issue, lens }) : issue
+        )
+      })
+
 export const mergeReviewResults = (results: ReadonlyArray<ReviewResult>): ReviewResult => {
   const counts = results.flatMap((result) => (result.passed === undefined ? [] : [result.passed]))
   return ReviewResult.make({
@@ -755,6 +725,32 @@ export interface ReviewAndFixOptions {
    * non-blocking. A red gate is always blocking.
    */
   readonly settle?: SettleRule
+  /**
+   * Incremental re-review (ADR 0044): each reviewer's findings are kept
+   * across rounds, a later round asks only the reviewers with findings (a
+   * re-check of them) or with files they have not seen, and the result is
+   * every finding still standing. Absent, every lens reviews every round.
+   */
+  readonly recheck?: RecheckOptions
+}
+
+/** A reviewer beside the lenses, such as the story judge (ADR 0044). */
+export interface ExtraReview {
+  readonly name: string
+  /** `prior`: its own standing findings when this run is a re-check; undefined for a full review. */
+  readonly review: (
+    diff: string,
+    prior: ReadonlyArray<ReviewIssue> | undefined
+  ) => Effect.Effect<ReviewResult, FlowError>
+}
+
+export interface RecheckOptions {
+  readonly extra?: ReadonlyArray<ExtraReview>
+  /** Where the reviewers' memory is kept, so a restart resumes at the next round. */
+  readonly memory?: {
+    readonly load: Effect.Effect<ReviewMemory | undefined, FlowError>
+    readonly save: (memory: ReviewMemory) => Effect.Effect<void, FlowError>
+  }
 }
 
 /** When a review round stops sending findings back to the coder (ADR 0031). */
@@ -865,9 +861,13 @@ export const reviewWith = (
   events: FlowEventsShape,
   lens: Reviewer,
   taskTitle: string,
-  diff: string
+  diff: string,
+  /** A re-check (ADR 0044): the files the fix touched and the lens's own earlier findings. */
+  recheck?: { readonly touched: ReadonlyArray<string>; readonly prior: ReadonlyArray<ReviewIssue> }
 ): Effect.Effect<ReviewResult, FlowLlmError> => {
-  const prompt = `${lensPrompt(lens)}\n\n${reviewPrompt(taskTitle, diff)}`
+  const lead =
+    recheck === undefined ? "" : `${recheckLead(taskTitle, recheck.touched, recheck.prior)}\n\n`
+  const prompt = `${lensPrompt(lens)}\n\n${lead}${reviewPrompt(taskTitle, diff)}`
   // Usage is published per attempt — a schema retry costs real tokens too.
   const attempt = (text: string): Effect.Effect<ReviewResult, LlmError> =>
     service.executeStructuredWithUsage(text, ReviewResult, reviewJsonSchema).pipe(
@@ -915,6 +915,104 @@ export const reviewAndFixLoop = Effect.fn("@llm4ts/flow/Review.reviewAndFixLoop"
   // A red gate is never settled early, whatever its findings' severities.
   const gateRed = yield* Ref.make(false)
 
+  const recheck = options.recheck
+  const loaded = recheck?.memory === undefined ? undefined : yield* recheck.memory.load
+  const memory = yield* Ref.make<ReviewMemory | undefined>(loaded)
+
+  /** One round of incremental re-review (ADR 0044): returns what still stands. */
+  const recheckRound = (
+    settings: RecheckOptions,
+    round: number,
+    diff: string,
+    files: ReadonlyArray<string>
+  ): Effect.Effect<ReviewResult, FlowError> =>
+    Effect.gen(function* () {
+      const before = yield* Ref.get(memory)
+      const chunks = diffChunks(diff)
+      const shown = files.length > 0 ? files : Object.keys(chunks)
+      const touched = before === undefined ? [] : touchedFiles(before.chunks, chunks)
+      const extras = settings.extra ?? []
+      const candidates: ReadonlyArray<Candidate> = [
+        ...options.reviewers.map((lens) => ({
+          name: lens.name,
+          matches: (changed: ReadonlyArray<string>) => lens.matches(changed)
+        })),
+        ...extras.map((extra) => ({ name: extra.name, matches: () => true, onlyWhenDirty: true }))
+      ]
+      const plan = planRound(candidates, before, shown, touched)
+      const priorOf = (name: string): ReadonlyArray<ReviewIssue> =>
+        before?.reviewers.find((entry) => entry.name === name)?.findings ?? []
+      const asked = [...plan.full, ...plan.recheck]
+      if (asked.length > 0) {
+        yield* options.events.publish(
+          Info.make({
+            message: `review round ${round} of "${options.taskTitle}": ${asked
+              .map((name) => (plan.recheck.includes(name) ? `${name} (re-check)` : name))
+              .join(", ")}`
+          })
+        )
+      }
+      const cache = options.cache
+      const ask = (
+        name: string
+      ): Effect.Effect<{ readonly name: string; readonly result: ReviewResult }, FlowError> => {
+        const again = plan.recheck.includes(name)
+        const prior = priorOf(name)
+        const lens = options.reviewers.find((candidate) => candidate.name === name)
+        const extra = extras.find((candidate) => candidate.name === name)
+        const lensAnswer = (lens: Reviewer): Effect.Effect<ReviewResult, FlowError> => {
+          const call = withCallPurpose(
+            `${name} lens${again ? " · re-check" : ""}`,
+            reviewWith(
+              options.reviewerService,
+              options.events,
+              lens,
+              options.taskTitle,
+              diff,
+              again ? { touched, prior } : undefined
+            )
+          )
+          const answered =
+            cache === undefined
+              ? call
+              : cachedReview(
+                  cache.files,
+                  join(cache.dir, `${fileSlug(name)}.json`),
+                  fingerprintOf([
+                    name,
+                    lensPrompt(lens),
+                    "0",
+                    options.taskTitle,
+                    diff,
+                    ...(again ? ["recheck", ...prior.map((issue) => issue.title)] : [])
+                  ]),
+                  call
+                )
+          return Effect.flatMap(answered, (result) =>
+            demoteUnplaced(lens, result, files, options.events)
+          )
+        }
+        const answer: Effect.Effect<ReviewResult, FlowError> =
+          lens !== undefined
+            ? lensAnswer(lens)
+            : extra !== undefined
+              ? extra.review(diff, again ? prior : undefined)
+              : Effect.succeed(ReviewResult.make({ issues: [] }))
+        return Effect.map(answer, (result) => ({ name, result: tagLens(name, result) }))
+      }
+      const parallelism = options.parallelism ?? 0
+      const ran =
+        parallelism > 0
+          ? yield* Effect.forEach(asked, ask, { concurrency: parallelism })
+          : yield* Effect.forEach(asked, ask, { concurrency: "unbounded" })
+      const next = remember(before, round, chunks, ran, shown)
+      yield* Ref.set(memory, next)
+      if (settings.memory !== undefined) {
+        yield* settings.memory.save(next)
+      }
+      return standing(next)
+    })
+
   const reviewOnce = (
     round: number,
     previous: ReviewResult | undefined
@@ -933,6 +1031,9 @@ export const reviewAndFixLoop = Effect.fn("@llm4ts/flow/Review.reviewAndFixLoop"
       }
       const diff = yield* options.currentDiff
       const files = yield* changedFiles
+      if (recheck !== undefined) {
+        return yield* recheckRound(recheck, round, diff, files)
+      }
       const selected = yield* selector.select(options.reviewers, files, round, previous)
       const screened =
         options.prescreen === undefined
@@ -974,7 +1075,7 @@ export const reviewAndFixLoop = Effect.fn("@llm4ts/flow/Review.reviewAndFixLoop"
         Effect.flatMap(review(lens), (result) =>
           Effect.map(demoteUnplaced(lens, result, files, options.events), (placed) => ({
             lens,
-            result: placed
+            result: tagLens(lens.name, placed)
           }))
         )
       const parallelism = options.parallelism ?? 0
@@ -1056,10 +1157,12 @@ export const reviewAndFixLoop = Effect.fn("@llm4ts/flow/Review.reviewAndFixLoop"
         result.isClean ||
         round >= maxRounds ||
         (settle === "blocking" && !(yield* Ref.get(gateRed)) && !result.issues.some(isBlocking))
+      const reviewed = !(yield* Ref.get(gateRed)) && diffNow.length > 0
       yield* options.events.publish(
         ReviewFindings.make({
           round,
           settled,
+          ...(reviewed ? { diffLines: diffNow.split("\n").length } : {}),
           issues: result.issues.map((issue) =>
             ReviewFinding.make({
               severity: issue.severity,
@@ -1076,10 +1179,27 @@ export const reviewAndFixLoop = Effect.fn("@llm4ts/flow/Review.reviewAndFixLoop"
       if (settled) {
         return result
       }
+      yield* applyFix(result)
+      return yield* loop(round + 1, result)
+    })
+
+  /** Sends the findings to the fixer; in recheck mode, records that the fix landed (ADR 0044). */
+  const applyFix = (result: ReviewResult): Effect.Effect<void, FlowError> =>
+    Effect.gen(function* () {
       const fix = fixPrompt(result, options.fix)
       yield* options.fixWith === undefined ? options.coder.ask(fix) : options.fixWith(fix)
-      return yield* loop(round + 1, result)
+      const remembered = yield* Ref.get(memory)
+      if (recheck?.memory !== undefined && remembered !== undefined) {
+        const fixed = ReviewMemory.make({ ...remembered, fixed: true })
+        yield* Ref.set(memory, fixed)
+        yield* recheck.memory.save(fixed)
+      }
     })
 
-  return yield* loop(1, undefined)
+  // A restart resumes after the last round its reviewers answered (ADR 0044),
+  // first applying that round's fix when it never landed.
+  if (loaded !== undefined && loaded.fixed !== true && !standing(loaded).isClean) {
+    yield* applyFix(standing(loaded))
+  }
+  return yield* loop(loaded === undefined ? 1 : Math.min(loaded.round + 1, maxRounds), undefined)
 })

package/src/ReviewCache.ts

@@ -3,7 +3,7 @@ import * as Effect from "effect/Effect"
 import * as Schema from "effect/Schema"
 import { PersistenceError, type FlowError } from "./FlowError.ts"
 import type { PlainFileStoreShape } from "./Persistence.ts"
-import { ReviewResult } from "./Review.ts"
+import { ReviewResult } from "./ReviewModel.ts"
 
 /** A stable key over parts, length-prefixed so a split never collides with another. */
 export const fingerprintOf = (parts: ReadonlyArray<string>): string => {

package/src/ReviewModel.ts

@@ -0,0 +1,63 @@
+/**
+ * What a review answers: findings and their result. Kept apart from
+ * `Review.ts` so modules that `Review.ts` imports can build schemas over them
+ * at load time without an import cycle (ADR 0044).
+ */
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+
+export const Severity = Schema.Literals(["Critical", "Warning", "Info"])
+export type Severity = typeof Severity.Type
+
+export class ReviewIssue extends Schema.Class<ReviewIssue>("ReviewIssue")({
+  severity: Severity,
+  title: Schema.String,
+  description: Schema.String.pipe(
+    Schema.withConstructorDefault(Effect.succeed("")),
+    Schema.withDecodingDefaultKey(Effect.succeed(""))
+  ),
+  file: Schema.optionalKey(Schema.String),
+  line: Schema.optionalKey(Schema.Int),
+  suggestion: Schema.optionalKey(Schema.String),
+  confidence: Schema.Number.pipe(
+    Schema.withConstructorDefault(Effect.succeed(1)),
+    Schema.withDecodingDefaultKey(Effect.succeed(1))
+  ),
+  /** A gate failure's triage against the base (ADR 0027); absent for review findings. */
+  origin: Schema.optionalKey(Schema.Literals(["new", "base", "flaky"])),
+  /** How a gate ended: a red exit, killed at the timeout, or a signal exit. */
+  gateClass: Schema.optionalKey(Schema.Literals(["red", "hang", "crash"])),
+  /** Why a test gate's output could not stand for green: no tests ran, or test files failed to load. */
+  gateReason: Schema.optionalKey(Schema.Literals(["zero-tests", "load-failure"])),
+  /** Where the gate's full output was written, when the caller asked for a log. */
+  logPath: Schema.optionalKey(Schema.String),
+  /** The reviewer that raised it (ADR 0044): a lens name, or "judge"; absent for gate findings. */
+  lens: Schema.optionalKey(Schema.String)
+}) {}
+
+export class ReviewResult extends Schema.Class<ReviewResult>("ReviewResult")({
+  issues: Schema.Array(ReviewIssue),
+  summary: Schema.String.pipe(
+    Schema.withConstructorDefault(Effect.succeed("")),
+    Schema.withDecodingDefaultKey(Effect.succeed(""))
+  ),
+  /** A test gate's passed-test count, when its output had a summary the oracle guard reads (ADR 0027). */
+  passed: Schema.optionalKey(Schema.Int)
+}) {
+  get isClean(): boolean {
+    return this.issues.length === 0
+  }
+}
+
+export const reviewPrompt = (task: string, diff: string): string =>
+  [
+    `Review the change below for task "${task}". Report problems as JSON:`,
+    '{"issues":[{"severity":"Critical|Warning|Info","title":"...",',
+    '"description":"..."}],"summary":"..."}.',
+    'An empty "issues" array means the change is acceptable. Respond with JSON only.',
+    "The diff below is the whole subject: judge what it shows. Do not explore the",
+    "repository, read other files, or run anything; answer from the diff.",
+    "",
+    "Diff:",
+    diff
+  ].join("\n")