@pmelab/gtd 48.0.0 → 50.0.0

package/src/workflows/shared/review.ts

@@ -5,6 +5,7 @@ import {
   judge,
   numeric,
   read,
+  refuse,
   requireRevert,
   restoreScript,
   run,
@@ -15,7 +16,7 @@ import {
   type Judgment,
   type ScopeAccess,
 } from "../../flows/index.js"
-import type { ReviewNote } from "../../steering/index.js"
+import { reviewChunks, reviewRisks, type ReviewNote } from "../../steering/index.js"
 import * as kit from "../../workflow-kit/index.js"
 import { guarded, healthy, type EscalationCount } from "./health.js"
 import { NO_FINDINGS, type LensReport } from "./lenses.js"
@@ -28,10 +29,11 @@ import {
   fixRisks,
   REQUIREMENTS,
   REVIEW,
+  reviewing,
   reviewMissing,
 } from "./steps.js"
 import { learnStandards, settlesStandard, standardsAddedSince, standardsPending } from "./learn.js"
-import { parseStandards, STANDARDS } from "./standards.js"
+import { isConflictTitle, parseStandards, STANDARDS } from "./standards.js"
 import { closeReview, isOptionalObject, tail, type TailOptions } from "./tail.js"
 import * as t from "./text.js"
 
@@ -68,10 +70,15 @@ interface Severity {
   readonly reason: string
   /** Capture order: 0 one-way door, 1 new concept, 2 everything else. */
   readonly rank: 0 | 1 | 2
+  readonly security?: true
 }
 
 /** Anything unanswered, unrecognised, cut or below `minP` is `critical`, never `could`. */
-export const severityOf = (note: ReviewNote, judgment: Judgment, minP: number): Severity => {
+export const severityOf = (
+  note: { readonly id: string; readonly forced?: boolean | undefined },
+  judgment: Judgment,
+  minP: number,
+): Severity => {
   const ans = (q: string) => judgment.answers[`${note.id}.${q}`]
   const a = (q: string): string | undefined => ans(q)?.answer
   const rank = (): 0 | 1 | 2 =>
@@ -88,7 +95,12 @@ export const severityOf = (note: ReviewNote, judgment: Judgment, minP: number):
     ...(a("reversibility") === "one-way" ? ["one-way door"] : []),
   ]
   if (critical.length > 0)
-    return { tier: "critical", reason: `critical: ${critical.join(", ")}`, rank: rank() }
+    return {
+      tier: "critical",
+      reason: `critical: ${critical.join(", ")}`,
+      rank: rank(),
+      ...(a("security") === "yes" ? { security: true as const } : {}),
+    }
   const should = [
     ...(a("blastRadius") === "contract" ? ["contract"] : []),
     ...(a("newConcept") === "yes" ? ["new concept"] : []),
@@ -98,31 +110,32 @@ export const severityOf = (note: ReviewNote, judgment: Judgment, minP: number):
   return { tier: "could", reason: "could", rank: 2 }
 }
 
-const severityQuestions = (note: ReviewNote): JudgeQuestion[] => [
+/** `asks` names the change in full, `change` refers back to it. */
+const severityQuestions = (id: string, asks: string, change: string): JudgeQuestion[] => [
   {
-    id: `${note.id}.security`,
+    id: `${id}.security`,
     primitive: "noul",
-    instructions: `Does the change the human asks for in note "${note.id}" (on "${note.anchor}") touch security — authentication, authorisation, secrets, untrusted input or data exposure?`,
+    instructions: `Does ${asks} touch security — authentication, authorisation, secrets, untrusted input or data exposure?`,
     criteria: "yes: it changes or could weaken a security property. no: it does not.",
   },
   {
-    id: `${note.id}.reversibility`,
+    id: `${id}.reversibility`,
     primitive: "choice",
-    instructions: `Once the change in note "${note.id}" ships, can it be undone without breaking anyone who already depends on it?`,
+    instructions: `Once ${change} ships, can it be undone without breaking anyone who already depends on it?`,
     criteria:
       "one-way: a published API, file format, persisted data, protocol or other contract that cannot be taken back. two-way: can be reverted freely.",
   },
   {
-    id: `${note.id}.blastRadius`,
+    id: `${id}.blastRadius`,
     primitive: "choice",
-    instructions: `How far does the change in note "${note.id}" reach?`,
+    instructions: `How far does ${change} reach?`,
     criteria:
       "local: one function or file. module: a whole module or several files. contract: a public interface other code or users depend on.",
   },
   {
-    id: `${note.id}.newConcept`,
+    id: `${id}.newConcept`,
     primitive: "noul",
-    instructions: `Does the change in note "${note.id}" introduce a concept new to this codebase — a new abstraction, entity or term? Judge from the evidence, never a glossary; reusing or extending an existing concept is not new.`,
+    instructions: `Does ${change} introduce a concept new to this codebase — a new abstraction, entity or term? Judge from the evidence, never a glossary; reusing or extending an existing concept is not new.`,
     criteria: "yes: a genuinely new concept. no: reuses or extends an existing one.",
   },
 ]
@@ -142,7 +155,14 @@ const triage =
       asked.length === 0
         ? { answers: {}, truncated: [] }
         : await judge("review.triage", {
-            questions: asked.flatMap((n) => [verdictQuestion(n), ...severityQuestions(n)]),
+            questions: asked.flatMap((n) => [
+              verdictQuestion(n),
+              ...severityQuestions(
+                n.id,
+                `the change the human asks for in note "${n.id}" (on "${n.anchor}")`,
+                `the change in note "${n.id}"`,
+              ),
+            ]),
             evidence: Object.fromEntries(
               asked.map((n) => [
                 n.id,
@@ -168,8 +188,108 @@ const triage =
     )
   }
 
+/** Review order: security, one-way doors, the judge unsure, then should, then could. */
+const chunkKey = (s: Severity): number =>
+  s.tier === "could" ? 4 : s.tier === "should" ? 3 : s.security === true ? 0 : s.rank === 0 ? 1 : 2
+
+type Pointer = ReturnType<typeof reviewChunks>[number]["files"][number]
+
+/** A chunk's text, then the code each of its pointers covers: a bare path the whole file. */
+const chunkEvidence = (text: string, files: readonly Pointer[]): string =>
+  [
+    text,
+    ...files.map(({ path, line, rangeEnd }) => {
+      const where = `${path}${line === undefined ? "" : `#${line}${rangeEnd === undefined ? "" : `-${rangeEnd}`}`}`
+      const lines = read(path.replace(/^\.\//, ""))?.split("\n")
+      if (lines === undefined) return `${where}: no longer exists`
+      const code = line === undefined ? lines : lines.slice(line - 1, rangeEnd ?? line)
+      return `${where}:\n${code.join("\n")}`
+    }),
+  ].join("\n\n")
+
+const bytes = (text: string): number => new TextEncoder().encode(text).length
+
+/** Fills each batch while the budget's even share still holds its widest evidence, so nothing is cut that fits alone. */
+const batched = <T extends { readonly evidence: string }>(
+  items: readonly T[],
+  budget: number,
+): T[][] => {
+  const batches: T[][] = []
+  let batch: T[] = []
+  let widest = 0
+  for (const item of items) {
+    const size = bytes(item.evidence)
+    if (batch.length > 0 && Math.floor(budget / (batch.length + 1)) < Math.max(widest, size)) {
+      batches.push(batch)
+      batch = []
+      widest = 0
+    }
+    batch.push(item)
+    widest = Math.max(widest, size)
+  }
+  return batch.length === 0 ? batches : [...batches, batch]
+}
+
+/**
+ * Rates every chunk the reviewer wrote — a walkthrough chunk or a carried
+ * finding — and sorts \`full\` by it, each chunk led by its tier and reason.
+ * gtd's summary chunks are not rated and stay last.
+ */
+const ranked = async (review: string, full: string): Promise<string> => {
+  const texts = t.chunkTexts(full)
+  const chunks = reviewChunks(review).map((c, i) => ({
+    id: `C${i + 1}`,
+    title: c.title,
+    evidence: chunkEvidence(texts.get(c.title) ?? "", c.files),
+  }))
+  if (chunks.length === 0) return full
+  const minP = numeric(vars.reviewSeverityMinP, Infinity)
+  const batches = batched(chunks, numeric(vars.judgeBudgetBytes, 32768))
+  const severities = new Map<string, Severity>()
+  for (const [i, batch] of batches.entries()) {
+    const judgment = await judge("review.ranking", {
+      questions: batch.flatMap((c) =>
+        severityQuestions(
+          c.id,
+          `the change review chunk "${c.id}" ("${c.title}") walks through`,
+          `the change in review chunk "${c.id}"`,
+        ),
+      ),
+      evidence: Object.fromEntries(batch.map((c) => [c.id, c.evidence])),
+      message: t.reviewRankingMessage(),
+      label:
+        batches.length === 1
+          ? "Ranking the review"
+          : `Ranking the review (${i + 1}/${batches.length})`,
+    })
+    for (const c of batch) severities.set(c.id, severityOf(c, judgment, minP))
+  }
+  return t.rankedReview(
+    full,
+    chunks
+      .map((c, i) => ({ c, i, s: severities.get(c.id)! }))
+      .sort((x, y) => chunkKey(x.s) - chunkKey(y.s) || x.i - y.i)
+      .map(({ c, s }) => ({ title: c.title, label: s.reason })),
+  )
+}
+
 export const isCode = (path: string): boolean => path !== ".gtd" && !path.startsWith(".gtd/")
 
+const composedOf = (
+  base: string,
+  report: LensReport,
+  nitFix: string | undefined,
+  answered: ReadonlySet<string>,
+): t.ComposedReview => ({
+  ...report,
+  nitFix,
+  answered,
+  standards: {
+    added: standardsAddedSince(base),
+    undecided: parseStandards(read(STANDARDS) ?? "").undecided,
+  },
+})
+
 /**
  * gtd writes `.gtd/REVIEW.md` from the quality lap's `report` — no reviewer
  * turn. A re-review
@@ -189,20 +309,84 @@ const composing = (
       ? writeScript(
           REVIEW,
           t.composedReview(base, {
-            ...report,
+            ...composedOf(base, report, nitFix, answered),
             weakened: kit.removedAssertions(changesSince(base)),
-            nitFix,
-            answered,
-            standards: {
-              added: standardsAddedSince(base),
-              undecided: parseStandards(read(STANDARDS) ?? "").undecided,
-            },
           }),
         )
       : showScript(carry, REVIEW, REVIEW),
     { label: "Composing the review", file: REVIEW, base },
   )
 
+/**
+ * Refuses a review with a chunk pointing at no code, or a lap note without a
+ * chunk of its own. A range with no code change has nothing to point at, so
+ * there only a note's chunk needs a pointer.
+ */
+const requirePointers = (
+  review: string,
+  notes: readonly { title: string }[],
+  codeChanged: boolean,
+): void => {
+  const chunks = reviewChunks(review)
+  const titles = new Set(chunks.map((c) => c.title))
+  const noted = new Set(notes.map((n) => n.title))
+  const problems = [
+    ...chunks
+      .filter((c) => c.pointers === 0 && (codeChanged || noted.has(c.title)))
+      .map((c) => `  - ${REVIEW}:${c.line + 1}: ${c.title} — points at no code`),
+    ...chunks
+      .filter((c) => isConflictTitle(c.title))
+      .map((c) => `  - ${REVIEW}:${c.line + 1}: ${c.title} — gtd writes conflicts; leave it out`),
+    ...notes.filter((n) => !titles.has(n.title)).map((n) => `  - ${n.title} — no chunk of its own`),
+    // Notes and answers are matched to their chunk by title.
+    ...chunks
+      .filter((c, i) => chunks.findIndex((d) => d.title === c.title) !== i)
+      .map((c) => `  - ${REVIEW}:${c.line + 1}: ${c.title} — a second chunk with this title`),
+    // A risk is fixed before the human sees it; a note is the human's to decide.
+    ...reviewRisks(review)
+      .filter((r) => [...noted].some((title) => r.anchor.startsWith(`${title} ./`)))
+      .map((r) => `  - ${r.anchor} — no \`Risk:\` in a quality finding's chunk`),
+  ]
+  if (problems.length === 0) return
+  refuse(
+    `gtd land: review-pointers: ${problems.length} problem(s) in ${REVIEW} — every chunk needs a pointer to its code, and every quality finding its own chunk, headed exactly as the prompt gave it:\n${problems.join("\n")}`,
+  )
+}
+
+/**
+ * A reviewer walks the human through everything since `base`, every chunk
+ * pointing at its code and each of the lap's notes a chunk of its own; gtd
+ * then adds each note's text and answer boxes, and the summary chunks.
+ */
+const walkthrough = async (
+  base: string,
+  report: t.ComposedReview,
+  lap: t.ReviewRange,
+  carry: string | undefined,
+): Promise<void> => {
+  const notes = t.titledNotes(report)
+  await reviewing(base, carry, lap, t.walkthroughBlock(notes, report.nitFix))
+  const written = read(REVIEW)
+  // A review the reviewer did not write is the round's own refusal or rest.
+  if (written === undefined) return
+  const review = t.unranked(written)
+  // Against the file as written, so a refusal's line numbers match it.
+  requirePointers(
+    written,
+    notes,
+    changesSince(base).some((c) => isCode(c.path)),
+  )
+  // Ranked even when it marks risks: the review written after their fix reaches the human with its own.
+  const full = await ranked(review, t.withWalkthrough(review, report))
+  if (full !== written) {
+    await run("review.carrying", writeScript(REVIEW, full), {
+      label: "Ordering the review and adding the quality lap's findings",
+      file: REVIEW,
+      base,
+    })
+  }
+}
+
 /**
  * The quality lap's notes reach a human over everything since `base`, who
  * answers each one — fix as suggested, won't fix, or their own answer — and
@@ -234,12 +418,27 @@ export const humanReview = (
     isCode,
     reviewing: (b, carry) => {
       const fixedAt = nitFix
-      nitFix = undefined
-      return composing(b, options.report ?? NO_FINDINGS, carry, fixedAt, answered)
+      const report = options.report ?? NO_FINDINGS
+      return options.walkthrough === true
+        ? guarded(
+            () =>
+              walkthrough(
+                b,
+                composedOf(b, report, fixedAt, answered),
+                options.lap ?? "first",
+                carry,
+              ),
+            guard,
+          )()
+        : composing(b, report, carry, fixedAt, answered)
     },
     fixRisks: guarded((notes) => fixRisks(notes, fixAccess, rules), guard),
     keepGreen: () => healthy(() => fixCheck(rules), { escalations, guard, guardRests, rules }),
-    awaitReview,
+    // Kept until the human sees a review, so a re-review after a risk fix still names it.
+    awaitReview: (b) => {
+      nitFix = undefined
+      return awaitReview(b)
+    },
     reviewMissing,
     collecting: feedback.collecting,
     triage: triage(severities),
@@ -297,8 +496,10 @@ export interface BuildTailOptions extends TailOptions {
   readonly feedback?: FeedbackTarget | undefined
   /** Write access for the nit and risk fix turns; absent: the bundled `access` export decides. */
   readonly fixAccess?: ScopeAccess | undefined
-  /** @deprecated No reviewer turn reads it since the review is composed. */
+  /** Which round a `walkthrough` reviewer writes; absent: `first`. */
   readonly lap?: t.ReviewRange | undefined
+  /** A reviewer turn writes the review as a walkthrough of the code, the lap's notes among its chunks; absent: gtd composes it from the notes alone. */
+  readonly walkthrough?: boolean | undefined
   /** What the triaged quality lap left for the review; absent: nothing. */
   readonly report?: LensReport | undefined
 }

package/src/workflows/shared/steps.ts

@@ -94,15 +94,16 @@ export const fixQuality = (rules?: string): Promise<void> =>
     allowEmpty: true,
   })
 
-/** Write `.gtd/REVIEW.md` over everything since `base`, carrying the answers of commit `carry` when given. */
+/** Write `.gtd/REVIEW.md` over everything since `base`, carrying the answers of commit `carry` when given; `extra` joins the prompt. */
 export const reviewing = (
   base: string,
   carry?: string,
   lap: t.ReviewRange = "first",
+  extra = "",
 ): Promise<void> =>
   t.agentWithSkills(
     "review.reviewing",
-    t.buildReviewReviewingPrompt(base, lap, carry, removedAssertions(changesSince(base))),
+    t.buildReviewReviewingPrompt(base, lap, carry, removedAssertions(changesSince(base)), extra),
     {
       label: "Reviewing",
       file: REVIEW,

package/src/workflows/shared/text.test.ts

@@ -30,6 +30,11 @@ import {
   summaryPrompt,
   withSkills,
   composedReview,
+  titledNotes,
+  walkthroughBlock,
+  withWalkthrough,
+  rankedReview,
+  unranked,
 } from "./text.js"
 import { reviewDecisions, steeringFormatFor, unansweredNotes } from "../../steering/index.js"
 import { captureStep, renderText } from "./text.fixture.js"
@@ -1391,3 +1396,214 @@ describe("composedReview", () => {
     expect(doc).toContain("## a (2)\n\n2")
   })
 })
+
+describe("walkthrough", () => {
+  const empty = { notes: [], fixed: [], noise: [] }
+  const review = [
+    "# Review: abc1234",
+    "",
+    "<!-- base: abc1234 -->",
+    "",
+    "## Subtract",
+    "",
+    "- [ ] ./src/calc.ts#2-2 — subtract(a, b)",
+    "",
+    "## Fixed automatically",
+    "",
+    "- [ ] ./src/calc.ts#2-2 — the reviewer's own chunk",
+    "",
+  ].join("\n")
+
+  it("titles notes uniquely, never a summary's, and leaves out answered ones", () => {
+    const notes = [
+      { title: "Fixed automatically", body: "a" },
+      { title: "x", body: "b" },
+      { title: "x", body: "c" },
+    ]
+    expect(titledNotes({ ...empty, notes }).map((n) => n.title)).toEqual([
+      "Fixed automatically (2)",
+      "x",
+      "x (2)",
+    ])
+    expect(titledNotes({ ...empty, notes, answered: new Set(["x"]) }).map((n) => n.title)).toEqual([
+      "Fixed automatically (2)",
+      "x (2)",
+    ])
+  })
+
+  it("lists each note with its exact heading, origin and quoted body", () => {
+    const block = walkthroughBlock([
+      { title: "No test", body: "Add one.\n\n- [ ] a box", slice: "2", lens: "tests" },
+    ])
+    expect(block).toContain(
+      "- `## No test` (slice 2, lens tests):\n\n  > Add one.\n  >\n  > - a box",
+    )
+    expect(block).toContain("its heading exactly as given")
+  })
+
+  it("names the nit fix's commit, and says nothing with nothing to tell", () => {
+    expect(walkthroughBlock([], "0123456789")).toContain(
+      "Commit `0123456` worked on the human's nits",
+    )
+    expect(walkthroughBlock([])).toBe("")
+  })
+
+  it("puts a note's text under its heading and its boxes after the reviewer's pointers", () => {
+    const out = withWalkthrough(review, {
+      ...empty,
+      notes: [{ title: "Subtract", body: "It may overflow.", unresolved: true }],
+    })
+    expect(out).toContain(
+      [
+        "## Subtract",
+        "",
+        "_The fixer left this unresolved._",
+        "",
+        "It may overflow.",
+        "",
+        "In the code:",
+        "",
+        "- [ ] ./src/calc.ts#2-2 — subtract(a, b)",
+        "",
+        "Tick exactly one:",
+        "",
+        "- [ ] fix as suggested",
+        "- [ ] won't fix",
+        "- [ ] _your answer_",
+        "",
+        "## Fixed automatically",
+      ].join("\n"),
+    )
+  })
+
+  it("appends the fixes and noise, numbered past a title the reviewer took", () => {
+    const out = withWalkthrough(review, {
+      ...empty,
+      fixed: [{ title: "a", commit: "0123456789", slice: "1" }],
+      noise: [{ title: "b", p: 0.9 }],
+    })
+    expect(
+      out.endsWith(
+        "## Fixed automatically (2)\n\n- a (0123456, slice 1)\n\n## Dropped as noise\n\n- b (p=0.9)\n",
+      ),
+    ).toBe(true)
+  })
+
+  it("leaves a review with nothing to add byte for byte, trailing newlines and all", () => {
+    expect(withWalkthrough(review, empty)).toBe(review)
+    expect(withWalkthrough(review.trimEnd(), empty)).toBe(review.trimEnd())
+    expect(withWalkthrough(review, { ...empty, notes: [{ title: "absent", body: "x" }] })).toBe(
+      review,
+    )
+  })
+
+  it("keeps a note ending in a list apart from the pointers, so its answer carries the list", () => {
+    const out = withWalkthrough(review, {
+      ...empty,
+      notes: [{ title: "Subtract", body: "Do this:\n\n- step one\n- step two" }],
+    }).replace("- [ ] fix as suggested", "- [x] fix as suggested")
+    const [decision] = reviewDecisions("", out)
+    expect(decision?.body).toContain("step two")
+    expect(decision?.body).not.toContain("./src/calc.ts")
+  })
+
+  it("shows a title holding backticks as one unbroken code span", () => {
+    expect(walkthroughBlock([{ title: "`sub` drifts", body: "x" }])).toContain(
+      "- `` ## `sub` drifts ``:",
+    )
+  })
+
+  it("keeps Risk: out of a finding's chunk", () => {
+    expect(walkthroughBlock([{ title: "x", body: "y" }])).toContain(
+      "never open a note in a finding's chunk with `Risk:`",
+    )
+  })
+})
+
+describe("rankedReview", () => {
+  const review = [
+    "# Review: abc1234",
+    "",
+    "<!-- base: abc1234 -->",
+    "",
+    "## Rename",
+    "",
+    "- [ ] ./a.ts#1-1",
+    "",
+    "## Token",
+    "",
+    "_could_",
+    "",
+    "Reads the token.",
+    "",
+    "- [ ] ./a.ts#2-2",
+    "",
+    "## Fixed automatically",
+    "",
+    "- x (abc1234)",
+    "",
+  ].join("\n")
+
+  it("puts the ranked chunks first, each led by its tier, and leaves the rest in place", () => {
+    expect(
+      rankedReview(unranked(review), [
+        { title: "Token", label: "critical: security" },
+        { title: "Rename", label: "could" },
+      ]),
+    ).toBe(
+      [
+        "# Review: abc1234",
+        "",
+        "<!-- base: abc1234 -->",
+        "",
+        "## Token",
+        "",
+        "_critical: security_",
+        "",
+        "Reads the token.",
+        "",
+        "- [ ] ./a.ts#2-2",
+        "",
+        "## Rename",
+        "",
+        "_could_",
+        "",
+        "- [ ] ./a.ts#1-1",
+        "",
+        "## Fixed automatically",
+        "",
+        "- x (abc1234)",
+        "",
+      ].join("\n"),
+    )
+  })
+
+  it("keeps a setext heading whole", () => {
+    expect(
+      rankedReview("# Review: a\n\nToken\n-----\n\n- [ ] ./a.ts#1\n", [
+        { title: "Token", label: "could" },
+      ]),
+    ).toBe("# Review: a\n\nToken\n-----\n\n_could_\n\n- [ ] ./a.ts#1\n")
+  })
+
+  it("keeps a chunk's leading indented code block indented", () => {
+    const code = "# Review: abc1234\n\n## Code\n\n    const x = 1\n\n- [ ] ./a.ts#1-1\n"
+    expect(rankedReview(code, [{ title: "Code", label: "could" }])).toContain(
+      "_could_\n\n    const x = 1",
+    )
+  })
+
+  it("drops a stale tier with no blank line under the heading, never a longer paragraph", () => {
+    expect(unranked("## A\n_could_\n\nbody\n")).toBe("## A\nbody\n")
+    expect(unranked("## A\n\n_could_\n- [ ] ./a.ts#1\n")).toBe("## A\n\n- [ ] ./a.ts#1\n")
+    const code = "## A\n\n    _could_\n"
+    expect(unranked(code)).toBe(code)
+    const prose = "## A\n\n_should: x_\nruns on\n"
+    expect(unranked(prose)).toBe(prose)
+  })
+
+  it("drops a stale tier, so a re-review is ranked afresh", () => {
+    expect(unranked(review)).not.toContain("_could_")
+    expect(unranked(unranked(review))).toBe(unranked(review))
+  })
+})