@llm4ts/flow 2.25.0 → 2.27.0

package/src/Review.ts

@@ -1,3 +1,4 @@
+import { join } from "node:path"
 import * as Clock from "effect/Clock"
 import * as Effect from "effect/Effect"
 import * as Schema from "effect/Schema"
@@ -9,6 +10,8 @@ import { Capabilities } from "@llm4ts/core/Capability"
 import { guarded } from "./CapabilityGuard.ts"
 import type { Chat } from "./Chat.ts"
 import { FlowLlmError, ProcessError, describeFlowError, type FlowError } from "./FlowError.ts"
+import type { PlainFileStoreShape } from "./Persistence.ts"
+import { cachedReview, fingerprintOf } from "./ReviewCache.ts"
 import {
   Info,
   JudgmentObserved,
@@ -217,12 +220,21 @@ export const llmDriven = (picker: LlmServiceShape): ReviewerSelector => ({
   }
 })
 
+/** A lens name as a file name. */
+const fileSlug = (name: string): string =>
+  name
+    .toLowerCase()
+    .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
@@ -320,6 +332,23 @@ export interface ReviewAndFixOptions {
    * act mode skips lenses. Omit to disable the judgment entirely.
    */
   readonly prescreen?: ReviewPrescreen
+  /**
+   * Where each lens's answer is kept beside a fingerprint of the lens, the
+   * task and the diff: a rerun over an unchanged diff reuses it instead of
+   * asking again. One file per lens under `dir`.
+   */
+  readonly cache?: ReviewCacheLocation
+  /** Told after every round's findings are published, settled or not. */
+  readonly onRound?: (
+    round: number,
+    result: ReviewResult,
+    settled: boolean
+  ) => Effect.Effect<void, FlowError>
+}
+
+export interface ReviewCacheLocation {
+  readonly files: PlainFileStoreShape
+  readonly dir: string
 }
 
 export interface ReviewPrescreen {
@@ -476,10 +505,17 @@ export const reviewAndFixLoop = Effect.fn("@llm4ts/flow/Review.reviewAndFixLoop"
           ? { reviewers: selected, observations: [] }
           : yield* prescreenReviewers(options.prescreen, options.events, diff, selected)
       const chosen = screened.reviewers
-      const run = (lens: Reviewer) =>
-        reviewWith(options.reviewerService, options.events, lens, options.taskTitle, diff).pipe(
-          Effect.map((result) => ({ lens, result }))
-        )
+      const cache = options.cache
+      const review = (lens: Reviewer): Effect.Effect<ReviewResult, FlowError> =>
+        cache === undefined
+          ? reviewWith(options.reviewerService, options.events, lens, options.taskTitle, diff)
+          : cachedReview(
+              cache.files,
+              join(cache.dir, `${fileSlug(lens.name)}.json`),
+              fingerprintOf([lens.name, lens.systemPrompt, options.taskTitle, diff]),
+              reviewWith(options.reviewerService, options.events, lens, options.taskTitle, diff)
+            )
+      const run = (lens: Reviewer) => Effect.map(review(lens), (result) => ({ lens, result }))
       const parallelism = options.parallelism ?? 0
       const results =
         parallelism > 0
@@ -537,6 +573,9 @@ export const reviewAndFixLoop = Effect.fn("@llm4ts/flow/Review.reviewAndFixLoop"
           )
         })
       )
+      if (options.onRound !== undefined) {
+        yield* options.onRound(round, result, settled)
+      }
       if (settled) {
         return result
       }

package/src/ReviewCache.ts

@@ -1,45 +1,84 @@
+import { createHash } from "node:crypto"
 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"
 
-class ReviewCacheEntry extends Schema.Class<ReviewCacheEntry>("ReviewCacheEntry")({
-  fingerprint: Schema.String,
-  result: ReviewResult
-}) {}
+/** A stable key over parts, length-prefixed so a split never collides with another. */
+export const fingerprintOf = (parts: ReadonlyArray<string>): string => {
+  const hash = createHash("sha256")
+  for (const part of parts) {
+    hash.update(`${part.length}:`)
+    hash.update(part)
+  }
+  return hash.digest("hex")
+}
 
-const decodeEntry = (contents: string): Effect.Effect<ReviewCacheEntry | undefined> =>
-  Schema.decodeUnknownEffect(Schema.fromJsonString(ReviewCacheEntry))(contents).pipe(
-    Effect.option,
-    Effect.map((option) => (option._tag === "Some" ? option.value : undefined))
-  )
+export interface CachedValue<A> {
+  readonly value: A
+  /** True when the answer came from disk, for an unchanged fingerprint. */
+  readonly reused: boolean
+}
+
+export interface CachedValueOptions {
+  /** False evaluates regardless and only stores the answer (default true). */
+  readonly reuse?: boolean
+}
 
-export const cachedReview = Effect.fn("@llm4ts/flow/ReviewCache.cached")(function* <R>(
+/**
+ * An answer persisted beside its fingerprint: a rerun re-evaluates only
+ * when the fingerprint changes, and says when it did not have to.
+ */
+export const cachedValue = Effect.fn("@llm4ts/flow/ReviewCache.cachedValue")(function* <
+  A,
+  E,
+  RD,
+  RE,
+  R
+>(
   files: PlainFileStoreShape,
   path: string,
+  schema: Schema.Codec<A, E, RD, RE>,
   fingerprint: string,
-  evaluate: Effect.Effect<ReviewResult, FlowError, R>
-): Effect.fn.Return<ReviewResult, FlowError, R> {
-  const contents = yield* files.read(path).pipe(Effect.catch(() => Effect.succeed(undefined)))
-  const entry = contents === undefined ? undefined : yield* decodeEntry(contents)
+  evaluate: Effect.Effect<A, FlowError, R>,
+  options: CachedValueOptions = {}
+): Effect.fn.Return<CachedValue<A>, FlowError, R | RD | RE> {
+  const Entry = Schema.fromJsonString(Schema.Struct({ fingerprint: Schema.String, result: schema }))
+  const contents =
+    options.reuse === false
+      ? undefined
+      : yield* files.read(path).pipe(Effect.catch(() => Effect.succeed(undefined)))
+  const entry =
+    contents === undefined
+      ? undefined
+      : yield* Schema.decodeUnknownEffect(Entry)(contents).pipe(
+          Effect.option,
+          Effect.map((option) => (option._tag === "Some" ? option.value : undefined))
+        )
   if (entry?.fingerprint === fingerprint) {
-    return entry.result
+    return { value: entry.result, reused: true }
   }
   const result = yield* evaluate
-  const encoded = yield* Schema.encodeEffect(Schema.fromJsonString(ReviewCacheEntry))(
-    ReviewCacheEntry.make({
-      fingerprint,
-      result
-    })
-  ).pipe(
+  const encoded = yield* Schema.encodeEffect(Entry)({ fingerprint, result }).pipe(
     Effect.mapError((error) =>
       PersistenceError.make({
-        message: `failed to encode review cache: ${String(error)}`,
+        message: `failed to encode cache entry: ${String(error)}`,
         cause: error
       })
     )
   )
   yield* files.writeAtomic(path, encoded)
-  return result
+  return { value: result, reused: false }
 })
+
+export const cachedReview = <R>(
+  files: PlainFileStoreShape,
+  path: string,
+  fingerprint: string,
+  evaluate: Effect.Effect<ReviewResult, FlowError, R>
+): Effect.Effect<ReviewResult, FlowError, R> =>
+  Effect.map(
+    cachedValue(files, path, ReviewResult, fingerprint, evaluate),
+    (cached) => cached.value
+  )

package/src/Stories.ts

@@ -58,6 +58,7 @@ import { Plan, Task } from "./Plan.ts"
 import { stage } from "./PlanExecution.ts"
 import { planFrom } from "./Planner.ts"
 import { ReviewIssue, ReviewResult } from "./Review.ts"
+import { cachedValue, fingerprintOf } from "./ReviewCache.ts"
 import type { Reviewer } from "./Reviewer.ts"
 import {
   dependentsOf,
@@ -85,6 +86,9 @@ export class StoryVerdict extends ReviewResult.extend<StoryVerdict>("StoryVerdic
   dimensions: Schema.Array(JudgedDimension)
 }) {}
 
+/** What a judge answers: a scored verdict, or a plain review result. */
+const Verdict = Schema.Union([StoryVerdict, ReviewResult])
+
 export interface StorySeats {
   readonly context: FlowContextShape
   /** Running usage of this story's seats — estimates where the backend reports none. */
@@ -668,6 +672,37 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
   const judgeRounds = Math.max(1, options.judgeRounds ?? 2)
   const statePath = (story: Story): string => join(options.stateDir, `stories/${story.id}.json`)
   const planPath = (story: Story): string => join(options.stateDir, `stories/${story.id}.plan.md`)
+  /** The judge's last verdict beside a fingerprint of what it judged. */
+  const judgePath = (story: Story): string =>
+    join(options.stateDir, `stories/${story.id}.judge.json`)
+  /** One file per review lens, beside a fingerprint of the task and diff. */
+  const reviewCacheDir = (story: Story): string =>
+    join(options.stateDir, `stories/${story.id}.review`)
+  /** What reviewers and the judge found, round by round, for people to read. */
+  const findingsPath = (story: Story): string =>
+    join(options.stateDir, `stories/${story.id}.findings.md`)
+  const findingLines = (result: ReviewResult): ReadonlyArray<string> =>
+    result.issues.map((issue) => {
+      const where =
+        issue.file === undefined
+          ? ""
+          : ` (${issue.file}${issue.line === undefined ? "" : `:${issue.line}`})`
+      const detail = issue.description.trim().length === 0 ? "" : `: ${issue.description.trim()}`
+      return `- [${issue.severity}] ${issue.title}${where}${detail}`
+    })
+  const appendFindings = (
+    story: Story,
+    heading: string,
+    result: ReviewResult
+  ): Effect.Effect<void, FlowError> =>
+    files.append(
+      findingsPath(story),
+      [
+        `## ${heading}`,
+        ...(result.issues.length === 0 ? ["- no issues"] : findingLines(result)),
+        ""
+      ].join("\n") + "\n"
+    )
   /** Git's empty tree: a diff against it is a path's whole current content. */
   const emptyTree = "4b825dc642cb6eb9a060e54bf8d69288fbee4904"
   const revisionTitle = /^Revision \d+: /u
@@ -1099,6 +1134,18 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
       // satisfied — without saying the exact sentinel — must not sink the
       // story: the option exists for pipelines shaped like this one.
       noopTaskPolicy: "complete",
+      // A lens's answer is kept beside the task and diff it answered, so a
+      // rerun over the same change asks nothing; every round is written to
+      // the story's findings log for people to read.
+      reviewCache: { files, dir: reviewCacheDir(story) },
+      onReview: (task, round, result, settled) =>
+        appendFindings(
+          story,
+          `review "${task.title}" round ${round} — ${
+            result.isClean ? "clean" : `${result.issues.length} issue(s)`
+          }${settled ? "" : ", fixing"}`,
+          result
+        ),
       ...(options.reviewers === undefined ? {} : { reviewers: options.reviewers }),
       ...(options.maxRounds === undefined ? {} : { maxRounds: options.maxRounds })
     })
@@ -1151,23 +1198,62 @@ export const implementStoriesFlow = Effect.fn("@llm4ts/flow/Stories.implement")(
         // code instead: the owned paths against the empty tree.
         const empty = diff.trim().length === 0
         const subject = empty ? yield* git.diffVsBaseScoped(emptyTree, story.owned, false) : diff
-        const verdict =
+        // The verdict is kept beside a fingerprint of what was judged: a
+        // rerun that finds the same diff gets the same answer without a
+        // model call, and the last verdict is on disk to read. Only the
+        // first round reuses it; a later round follows a revision and asks.
+        const judged =
           empty && subject.trim().length === 0
             ? // Nothing to judge is decided here, not asked of a model.
-              ReviewResult.make({
-                issues: [
-                  ReviewIssue.make({
-                    severity: "Critical",
-                    title: `nothing exists yet under ${story.owned.join(", ")}`,
-                    description: "The story's owned paths are empty on the epic branch."
-                  })
-                ],
-                summary: `judge:${story.id}`
-              })
-            : yield* withTimedRole(
-                "judge",
-                judge(story, subject, watchedSeats, empty ? "code" : "diff")
+              {
+                value: ReviewResult.make({
+                  issues: [
+                    ReviewIssue.make({
+                      severity: "Critical",
+                      title: `nothing exists yet under ${story.owned.join(", ")}`,
+                      description: "The story's owned paths are empty on the epic branch."
+                    })
+                  ],
+                  summary: `judge:${story.id}`
+                }),
+                reused: false
+              }
+            : yield* cachedValue(
+                files,
+                judgePath(story),
+                Verdict,
+                fingerprintOf([
+                  empty ? "code" : "diff",
+                  subject,
+                  story.id,
+                  story.title,
+                  story.description,
+                  story.provides.join("\n")
+                ]),
+                withTimedRole(
+                  "judge",
+                  judge(story, subject, watchedSeats, empty ? "code" : "diff")
+                ),
+                { reuse: round === 1 }
               )
+        const verdict = judged.value
+        if (judged.reused) {
+          yield* laneOf(story).publish(
+            Info.make({
+              lane: story.id,
+              message: `judge round ${round}: reused the verdict for an unchanged ${empty ? "code" : "diff"}`
+            })
+          )
+        }
+        yield* appendFindings(
+          story,
+          `judge round ${round} — ${verdict.isClean ? "cleared" : "not cleared"}${
+            verdict instanceof StoryVerdict
+              ? ` (${verdict.dimensions.map((d) => `${d.id} ${d.score}/${d.max}`).join(", ")})`
+              : ""
+          }${judged.reused ? ", reused" : ""}`,
+          verdict
+        )
         yield* laneOf(story).publish(
           StoryJudged.make({
             lane: story.id,