@pmelab/gtd 51.0.1 → 52.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "51.0.1",
+  "version": "52.0.0",
   "private": false,
   "description": "Git-aware CLI that emits the next prompt for an autonomous coding agent based on the current repository state",
   "bin": {

package/src/steering/FORMATS.md

@@ -14,7 +14,10 @@ read them.
   `<!-- base: <sha> -->` comment, then `##` chunks with prose and `- [ ]` hunk
   pointers (`./path`, `./path#start-end`), each optionally followed by
   `— <note>`. A pointer note starting `Risk:` is a reviewer's risk. A ticked
-  pointer is a hunk the human has read.
+  pointer is a hunk the human has read. A chunk's `Tick exactly one:` list is
+  its decision. A `## Findings` or `## Walkthrough` heading groups the `###`
+  chunks under it; a walkthrough chunk takes no decision. Any other `##` is a
+  chunk of its own.
 - **Free-form**: any markdown, for a file with no mode or an unknown one. Only
   its threads are validated.
 - **Threads**, shared by all three: a footnote whose definition is a list of

package/src/steering/SteeringFormat.ts

@@ -64,6 +64,8 @@ export interface SteeringLink {
  * format-agnostic: `review`'s chunk/hunk and `qa`'s question/option are the
  * same two things here (a container and one of its numbered children), plus
  * `paragraph`, which a client resolves from its cursor rather than the view.
+ * A `review` finding's answer boxes are `option`s too, `questionIndex` being
+ * the chunk's index.
  */
 export type SteeringAnchor =
   | { readonly kind: "chunk"; readonly index: number }
@@ -110,7 +112,7 @@ export interface SteeringViewNode {
   readonly detail?: string
   /** A free-form status label, when the format has one (`qa`'s `"open"`/`"answered"`). */
   readonly status?: string
-  /** `true` when this node's own condition is fully satisfied (`qa`'s answered-question flag) — distinct from `checked`, which is a per-item tick. */
+  /** `true` when this node's own condition is fully satisfied (`qa`'s answered question, `review`'s decided finding) — distinct from `checked`, which is a per-item tick. */
   readonly answered?: boolean
   /** This node's own checkbox state, when it has one (a hunk's tick, an option's tick). */
   readonly checked?: boolean
@@ -138,6 +140,10 @@ export interface SteeringViewNode {
   readonly endLine?: number
   /** Where `annotate` attaches a NEW note to this node. */
   readonly anchor: SteeringAnchor
+  /** The section a top-level node sits in, when the format groups them (`review`'s `Findings` / `Walkthrough`). */
+  readonly group?: string
+  /** A `review` finding's answer boxes, in order — fix as suggested, won't fix, and the free-text slot, whose `title` is the human's text (`""` while unfilled). Kept out of `children`, which are its hunks. */
+  readonly decision?: readonly SteeringViewNode[]
   readonly children?: readonly SteeringViewNode[]
   /**
    * A node's body, a SIBLING of `children` and never a reuse of it: a `qa`

package/src/steering/contract.test.ts

@@ -97,7 +97,8 @@ describe.each(FORMATS)("the %s format", (dir, format, ticks) => {
 
     if (ticks)
       it("round-trips every tick: writing back what was read leaves the bytes unchanged", () => {
-        for (const node of nodesOf(format.view(content).nodes)) {
+        const nodes = nodesOf(format.view(content).nodes)
+        for (const node of [...nodes, ...nodes.flatMap((n) => n.decision ?? [])]) {
           if (node.checked === undefined || node.anchor.kind === "chunk") continue
           const anchor: SteeringAnchor = node.anchor
           const same = write(

package/src/steering/fixtures/review/sectioned.md

@@ -0,0 +1,31 @@
+# Review: 1a2b3c4
+
+<!-- base: 1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b -->
+
+## Findings
+
+### A lone CR is kept
+
+_should: contract_
+
+The parser keeps a lone `\r` as content.
+
+In the code:
+
+- [x] ./src/parse.ts#30-31 — where it is kept
+
+Tick exactly one:
+
+- [ ] fix as suggested
+- [x] won't fix
+- [ ] _your answer_
+
+## Walkthrough
+
+### Parser accepts CRLF
+
+- [ ] ./src/parse.ts#10-14 — normalizes `\r\n` first
+
+## Fixed automatically
+
+- a test name typo (0123456)

package/src/steering/fixtures/review/sectioned.read.json

@@ -0,0 +1,119 @@
+{
+  "header": "1a2b3c4",
+  "nodes": [
+    {
+      "title": "A lone CR is kept",
+      "detail": "The parser keeps a lone `\\r` as content. In the code:",
+      "body": [
+        {
+          "title": "The parser keeps a lone `\\r` as content.",
+          "anchor": {
+            "kind": "paragraph",
+            "line": 10
+          }
+        },
+        {
+          "title": "In the code:",
+          "anchor": {
+            "kind": "paragraph",
+            "line": 12
+          }
+        }
+      ],
+      "status": "should: contract",
+      "anchor": {
+        "kind": "chunk",
+        "index": 0
+      },
+      "group": "Findings",
+      "answered": true,
+      "decision": [
+        {
+          "title": "fix as suggested",
+          "checked": false,
+          "anchor": {
+            "kind": "option",
+            "questionIndex": 0,
+            "index": 0
+          }
+        },
+        {
+          "title": "won't fix",
+          "checked": true,
+          "anchor": {
+            "kind": "option",
+            "questionIndex": 0,
+            "index": 1
+          }
+        },
+        {
+          "title": "",
+          "checked": false,
+          "anchor": {
+            "kind": "option",
+            "questionIndex": 0,
+            "index": 2
+          }
+        }
+      ],
+      "children": [
+        {
+          "title": "./src/parse.ts#30-31",
+          "path": "./src/parse.ts",
+          "line": 30,
+          "endLine": 31,
+          "checked": true,
+          "detail": "where it is kept",
+          "anchor": {
+            "kind": "hunk",
+            "chunkIndex": 0,
+            "index": 0
+          }
+        }
+      ]
+    },
+    {
+      "title": "Parser accepts CRLF",
+      "detail": "",
+      "body": [],
+      "anchor": {
+        "kind": "chunk",
+        "index": 1
+      },
+      "group": "Walkthrough",
+      "children": [
+        {
+          "title": "./src/parse.ts#10-14",
+          "path": "./src/parse.ts",
+          "line": 10,
+          "endLine": 14,
+          "checked": false,
+          "detail": "normalizes `\\r\\n` first",
+          "anchor": {
+            "kind": "hunk",
+            "chunkIndex": 1,
+            "index": 0
+          }
+        }
+      ]
+    },
+    {
+      "title": "Fixed automatically",
+      "detail": "- a test name typo (0123456)",
+      "body": [
+        {
+          "title": "a test name typo (0123456)",
+          "anchor": {
+            "kind": "paragraph",
+            "line": 30
+          }
+        }
+      ],
+      "anchor": {
+        "kind": "chunk",
+        "index": 2
+      },
+      "children": []
+    }
+  ]
+}

package/src/steering/index.ts

@@ -16,11 +16,15 @@ export {
   reviewDecisions,
   reviewNotes,
   reviewRisks,
+  reviewSections,
+  REVIEW_SECTIONS,
+  sectionedReview,
   severityLine,
   unansweredNotes,
   type ReviewChoice,
   type ReviewDecision,
   type ReviewNote,
+  type ReviewSection,
 } from "./review.js"
 export { applySteeringEdits } from "./Edits.js"
 

package/src/steering/qa.ts

@@ -830,7 +830,7 @@ const replaceOptionTextEdit = (
  * offset for, breaking this anchor's `apply` forever. The placeholder reads
  * back as `""`, so an erase still reads as unanswered.
  */
-const normalizeFreeTextAnswer = (text: string): string => {
+export const normalizeFreeTextAnswer = (text: string): string => {
   const normalized = text.replace(/\s+/g, " ").trim()
   return normalized.length === 0 ? FREE_TEXT_PLACEHOLDER : normalized
 }

package/src/steering/review.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest"
 import { FOOTNOTE_ACTION_TITLE, steeringFormatFor, viewOf } from "./index.js"
-import { parseReviewDoc } from "./review.js"
+import { parseReviewDoc, unansweredNotes } from "./review.js"
 import { getParseCount } from "./index.js"
 
 describe("parseReviewDoc", () => {
@@ -1532,13 +1532,90 @@ describe("review.apply", () => {
     ).toEqual({ ok: false, reason: "anchor-not-found" })
   })
 
-  it("a question/option anchor — not this format's own kind — refuses anchor-not-found", () => {
+  it("a question anchor — not this format's own kind — refuses anchor-not-found", () => {
     expect(review.apply(NESTED_CONTENT, { kind: "question", index: 0 }, { checked: true })).toEqual(
       { ok: false, reason: "anchor-not-found" },
     )
   })
 })
 
+describe("review decisions — a finding's answer boxes", () => {
+  const FINDINGS = [
+    "# Review: abc1234",
+    "",
+    "<!-- base: abc1234def5678901234567890123456789abcd -->",
+    "",
+    "## Findings",
+    "",
+    "### Token check",
+    "",
+    "- [ ] ./src/auth.ts#1-2",
+    "",
+    "Tick exactly one:",
+    "",
+    "- [ ] fix as suggested",
+    "- [x] won't fix",
+    "- [ ] _your answer_",
+    "",
+    "## Walkthrough",
+    "",
+    "### Rename",
+    "",
+    "- [ ] ./src/calc.ts#1-1",
+    "",
+  ].join("\n")
+  const option = (index: number) => ({ kind: "option" as const, questionIndex: 0, index })
+  const write = (content: string, index: number, opts: { checked?: boolean; text?: string }) => {
+    const result = review.apply(content, option(index), opts)
+    if (!result.ok) throw new Error(result.reason)
+    return applyEdits(content, result.edits)
+  }
+
+  it("views a finding's boxes as its decision, apart from its hunks", () => {
+    const [finding, walkthrough] = review.view(FINDINGS).nodes
+    expect(finding!.answered).toBe(true)
+    expect(finding!.decision!.map((o) => [o.title, o.checked])).toEqual([
+      ["fix as suggested", false],
+      ["won't fix", true],
+      ["", false],
+    ])
+    expect(finding!.children!.map((c) => c.anchor.kind)).toEqual(["hunk"])
+    expect(walkthrough!.decision).toBeUndefined()
+    expect(walkthrough!.answered).toBeUndefined()
+  })
+
+  it("ticking a box unticks the others", () => {
+    const after = write(FINDINGS, 0, { checked: true })
+    expect(after).toContain("- [x] fix as suggested\n- [ ] won't fix\n- [ ] _your answer_")
+    expect(unansweredNotes(after)).toEqual([])
+  })
+
+  it("an answer ticks the free-text slot and writes its text in one edit set", () => {
+    const after = write(FINDINGS, 2, { checked: true, text: "Only for\n admin tokens " })
+    expect(after).toContain("- [ ] won't fix\n- [x] Only for admin tokens\n")
+    expect(review.view(after).nodes[0]!.decision![2]!.title).toBe("Only for admin tokens")
+    expect(unansweredNotes(after)).toEqual([])
+    expect(review.validate(after)).toEqual([])
+  })
+
+  it("clearing the answer unticks the slot and restores its placeholder", () => {
+    const answered = write(FINDINGS, 2, { checked: true, text: "Later" })
+    const cleared = write(answered, 2, { checked: false, text: "" })
+    expect(cleared).toContain("- [ ] won't fix\n- [ ] _your answer_\n")
+    expect(review.view(cleared).nodes[0]!.answered).toBe(false)
+  })
+
+  it("a walkthrough chunk or a missing box refuses anchor-not-found", () => {
+    expect(
+      review.apply(FINDINGS, { kind: "option", questionIndex: 1, index: 0 }, { checked: true }),
+    ).toEqual({ ok: false, reason: "anchor-not-found" })
+    expect(review.apply(FINDINGS, option(3), { checked: true })).toEqual({
+      ok: false,
+      reason: "anchor-not-found",
+    })
+  })
+})
+
 describe("review.view — chunk-level footnote projection", () => {
   it("projects a footnote marker on the chunk's own heading line as that chunk node's own `note`, distinct from a hunk's own note", () => {
     // review.sample carries exactly this shape: `## Sample chunk[^naduiqc4]`
@@ -1899,7 +1976,7 @@ describe("reviewChunks", async () => {
       "",
       "<!-- base: abc1234def5678901234567890123456789abcd -->",
       "",
-      "## Walkthrough",
+      "## Changes",
       "",
       "- [ ] ./src/a.ts#1-3 — first",
       "- [ ] ./src/b.ts#4-6 — second",
@@ -1914,7 +1991,7 @@ describe("reviewChunks", async () => {
     ].join("\n")
     expect(reviewChunks(content)).toEqual([
       {
-        title: "Walkthrough",
+        title: "Changes",
         line: 4,
         pointers: 2,
         files: [
@@ -2039,3 +2116,192 @@ describe("answer boxes", async () => {
     ])
   })
 })
+
+describe("review — sectioned layout", async () => {
+  const { reviewChunks, reviewDecisions, reviewSections, sectionedReview, unansweredNotes } =
+    await import("./review.js")
+  const boxes = (ticked?: 0 | 1 | 2): string[] => [
+    "Tick exactly one:",
+    "",
+    `- [${ticked === 0 ? "x" : " "}] fix as suggested`,
+    `- [${ticked === 1 ? "x" : " "}] won't fix`,
+    `- [${ticked === 2 ? "x" : " "}] _your answer_`,
+  ]
+  const head = [
+    "# Review: abc1234",
+    "",
+    "<!-- base: abc1234def5678901234567890123456789abcd -->",
+    "",
+  ]
+  const sectioned = (ticked?: 0 | 1 | 2): string =>
+    [
+      ...head,
+      "## Findings",
+      "",
+      "### A finding",
+      "",
+      "_critical: security_",
+      "",
+      "Leaks a token.",
+      "",
+      "- [ ] ./src/a.ts#1-2 — here",
+      "",
+      ...boxes(ticked),
+      "",
+      "## Walkthrough",
+      "",
+      "### Wiring",
+      "",
+      "- [x] ./src/b.ts#3-4 — wires it",
+      "",
+      "## Fixed automatically",
+      "",
+      "- f (fedcba9)",
+      "",
+    ].join("\n")
+
+  it("reads `###` chunks under the sections and other `## ` chunks on their own", () => {
+    expect(review.validate(sectioned())).toEqual([])
+    expect(reviewChunks(sectioned())).toEqual([
+      expect.objectContaining({ title: "A finding", line: 6, pointers: 1, section: "findings" }),
+      expect.objectContaining({ title: "Wiring", line: 22, pointers: 1, section: "walkthrough" }),
+      { title: "Fixed automatically", line: 26, pointers: 0, files: [] },
+    ])
+    expect(reviewSections(sectioned())).toEqual([
+      { section: "findings", line: 4 },
+      { section: "walkthrough", line: 20 },
+    ])
+  })
+
+  it("reads a decision from a finding", () => {
+    expect(unansweredNotes(sectioned())).toEqual([
+      { title: "A finding", line: 7, reason: "tick exactly one box" },
+    ])
+    expect(reviewDecisions(sectioned(), sectioned(1))).toEqual([
+      expect.objectContaining({ anchor: "A finding", choice: "wontfix" }),
+    ])
+  })
+
+  it("reads no decision in the walkthrough: boxes there are a chunk gone wrong", () => {
+    const content = sectioned(0).replace(
+      "- [x] ./src/b.ts#3-4 — wires it\n",
+      ["- [x] ./src/b.ts#3-4 — wires it", "", ...boxes(1), ""].join("\n"),
+    )
+    expect(unansweredNotes(content)).toEqual([])
+    expect(reviewDecisions(sectioned(), content)).toEqual([
+      expect.objectContaining({ anchor: "A finding", choice: "fix" }),
+    ])
+  })
+
+  it("still reads the flat layout, every `## ` a chunk and its boxes a decision", () => {
+    const flat = [...head, "## A finding", "", "Leaks a token.", "", ...boxes(), ""].join("\n")
+    expect(review.validate(flat)).toEqual([])
+    expect(reviewChunks(flat)).toEqual([{ title: "A finding", line: 4, pointers: 0, files: [] }])
+    expect(unansweredNotes(flat)).toHaveLength(1)
+  })
+
+  it("outlines the sections as containers, each finding's decision a node of its own", () => {
+    const outline = viewOf(review, sectioned()).outline
+    expect(outline.map((n) => n.name)).toEqual(["Findings", "Walkthrough", "Fixed automatically"])
+    expect(outline[0]!.children!.map((n) => n.name)).toEqual(["A finding (0/1)"])
+    expect(outline[0]!.children![0]!.children!.map((n) => n.name)).toEqual(["Decision: open"])
+    expect(outline[0]!.children![0]!.children![0]!.selectionRange.start.line).toBe(14)
+    // A fully ticked walkthrough chunk is reviewed: its section is left empty.
+    expect(outline[1]!.children).toEqual([])
+  })
+
+  it("names the ticked decision, and keeps a decided finding while a hunk is unticked", () => {
+    const outline = viewOf(review, sectioned(1)).outline
+    expect(outline[0]!.children![0]!.children!.map((n) => n.name)).toEqual(["Decision: won't fix"])
+  })
+
+  it("groups the view's chunks by section, anchors unchanged", () => {
+    const { nodes } = review.view(sectioned())
+    expect(nodes.map((n) => [n.title, n.group, n.anchor])).toEqual([
+      ["A finding", "Findings", { kind: "chunk", index: 0 }],
+      ["Wiring", "Walkthrough", { kind: "chunk", index: 1 }],
+      ["Fixed automatically", undefined, { kind: "chunk", index: 2 }],
+    ])
+  })
+
+  it("offers a chunk's toggle only within its own span, never on the next section's heading", () => {
+    const titles = viewOf(review, sectioned())
+      .actionsAt({ start: { line: 20, character: 0 }, end: { line: 20, character: 0 } })
+      .map((a) => a.title)
+    expect(titles.some((t) => t.includes("A finding"))).toBe(false)
+  })
+
+  describe("sectionedReview", () => {
+    const flat = [
+      ...head,
+      "## Weakened scenarios",
+      "",
+      "- a.feature — s — Then x",
+      "",
+      "## A finding",
+      "",
+      "_should: contract_",
+      "",
+      "Leaks a token.",
+      "",
+      ...boxes(),
+      "",
+      "Wiring",
+      "------",
+      "",
+      "### Detail",
+      "",
+      "- [ ] ./src/b.ts#3-4 — wires it",
+      "",
+      "## Fixed automatically",
+      "",
+      "- f (fedcba9)",
+      "",
+    ].join("\n")
+
+    it("moves boxed chunks under Findings and the named ones under Walkthrough, a level deeper", () => {
+      expect(sectionedReview(flat, new Set(["Wiring"]))).toBe(
+        [
+          ...head,
+          "## Weakened scenarios",
+          "",
+          "- a.feature — s — Then x",
+          "",
+          "## Findings",
+          "",
+          "### A finding",
+          "",
+          "_should: contract_",
+          "",
+          "Leaks a token.",
+          "",
+          ...boxes(),
+          "",
+          "## Walkthrough",
+          "",
+          "### Wiring",
+          "",
+          "#### Detail",
+          "",
+          "- [ ] ./src/b.ts#3-4 — wires it",
+          "",
+          "## Fixed automatically",
+          "",
+          "- f (fedcba9)",
+          "",
+        ].join("\n"),
+      )
+    })
+
+    it("is valid and stable once sectioned", () => {
+      const once = sectionedReview(flat, new Set(["Wiring"]))
+      expect(review.validate(once)).toEqual([])
+      expect(sectionedReview(once, new Set(["Wiring"]))).toBe(once)
+    })
+
+    it("leaves a review with nothing to group byte for byte", () => {
+      const plain = [...head, "## Nothing to note", "", "Review the diff yourself.", ""].join("\n")
+      expect(sectionedReview(plain, new Set())).toBe(plain)
+    })
+  })
+})