@pmelab/gtd 65.0.0 → 66.0.0

package/src/platform/Workspace.test.ts

@@ -1,4 +1,5 @@
 import {
+  chmodSync,
   mkdirSync,
   mkdtempSync,
   readFileSync,
@@ -38,6 +39,7 @@ interface WorkspaceTier {
   readonly root: string
   readonly writeWorking: (path: string, content: string) => void
   readonly commit: (path: string, content: string) => void
+  readonly chmod: (path: string, executable: boolean) => void
   readonly provide: <A>(eff: Effect.Effect<A, Error, Workspace>) => Promise<A>
   readonly dispose: () => void
 }
@@ -70,6 +72,7 @@ const makeLiveTier = (): WorkspaceTier => {
       gitExecIn(root, "add", "-A")
       gitExecIn(root, "commit", "-m", `commit ${path}`)
     },
+    chmod: (path, executable) => chmodSync(join(root, path), executable ? 0o755 : 0o644),
     provide: (eff) => Effect.runPromise(eff.pipe(Effect.provide(workspaceLayer))),
     dispose: () => rmSync(root, { recursive: true, force: true }),
   }
@@ -86,6 +89,7 @@ const makeInMemTier = (): WorkspaceTier => {
       repo.writeFile(path, content)
       repo.seedCommit(`commit ${path}`)
     },
+    chmod: (path, executable) => repo.setExecutable(path, executable),
     provide: (eff) =>
       Effect.runPromise(eff.pipe(Effect.provide(Layer.succeed(Workspace, workspaceOps)))),
     dispose: () => {},
@@ -232,6 +236,39 @@ for (const { name, make } of tiers) {
       await expect(attempt).rejects.toThrow(/repo-relative paths only/)
     })
 
+    it("modeSync reports committed and working-tree modes, kept across an overwrite", async () => {
+      t = make()
+      t.commit("a.sh", "echo\n")
+      t.chmod("a.sh", true)
+      const modes = await t.provide(
+        Effect.gen(function* () {
+          const workspace = yield* Workspace
+          const committed = workspace.modeSync("HEAD").get("a.sh")
+          const chmodded = workspace.modeSync(undefined).get("a.sh")
+          t.writeWorking("a.sh", "echo 2\n")
+          return [committed, chmodded, workspace.modeSync(undefined).get("a.sh")]
+        }),
+      )
+      expect(modes).toEqual(["100644", "100755", "100755"])
+    })
+
+    it.runIf(name === "Live")(
+      "modeSync reads only the owner execute bit, as git does",
+      async () => {
+        t = make()
+        t.commit("a.sh", "echo\n")
+        t.writeWorking("a.sh", "echo 2\n")
+        chmodSync(join(t.root, "a.sh"), 0o654)
+        const mode = await t.provide(
+          Effect.gen(function* () {
+            return (yield* Workspace).modeSync(undefined).get("a.sh")
+          }),
+        )
+        gitExecIn(t.root, "add", "a.sh")
+        expect(mode).toBe(gitExecIn(t.root, "ls-files", "-s", "a.sh").split(" ")[0])
+      },
+    )
+
     it("atPath reads an absolute path INSIDE root, the same content readSync's relative form sees", async () => {
       t = make()
       t.writeWorking("nested/a.txt", "inside\n")

package/src/platform/Workspace.ts

@@ -150,6 +150,16 @@ const applyRawDiff = (tree: Map<string, string>, entries: readonly RawDiffEntry[
   }
 }
 
+/** `git ls-tree -r -z --full-tree <ref>`'s output, parsed into `path → mode`. */
+const parseLsTreeModes = (out: string): Map<string, string> => {
+  const modes = new Map<string, string>()
+  for (const record of out.split("\0")) {
+    const tab = record.indexOf("\t")
+    if (tab !== -1) modes.set(record.slice(tab + 1), record.slice(0, tab).split(" ")[0]!)
+  }
+  return modes
+}
+
 /** `git ls-tree -r -z --full-tree <ref>`'s output, parsed into `path → blob id`. */
 const parseLsTree = (out: string): Map<string, string> => {
   const entries = new Map<string, string>()
@@ -227,6 +237,8 @@ export interface WorkspaceOps {
    * reader compares contents instead.
    */
   readonly worktreeSync: () => ReadonlyMap<string, string | undefined>
+  /** Every path's git file mode (`100644`, `100755`, …) at `ref`, or in the working tree as `git add -A` would store it when `ref` is `undefined`. */
+  readonly modeSync: (ref: string | undefined) => ReadonlyMap<string, string>
   /**
    * `hash → (path → blob id)` for `base` (when given) and every one of
    * `commits`, in ONE call regardless of how many commits that is: a single
@@ -528,6 +540,29 @@ const makeWorkspaceOps = (
     return new Map([...entries].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)))
   }
 
+  const modeSync = (ref: string | undefined): ReadonlyMap<string, string> => {
+    const modes = parseLsTreeModes(gitSync(["ls-tree", "-r", "-z", "--full-tree", ref ?? "HEAD"]))
+    if (ref !== undefined) return modes
+    const status = gitSync([
+      "status",
+      "--porcelain=v1",
+      "-z",
+      "--untracked-files=all",
+      "--no-renames",
+      "--ignore-submodules=none",
+    ])
+    for (const record of status.split("\0")) {
+      if (record.length < 4) continue
+      const path = record.slice(3).replace(/\/$/, "")
+      const stat = io.lstat(paths.join(root, path))
+      if (stat === undefined) modes.delete(path)
+      else if (stat.type === "symlink") modes.set(path, "120000")
+      else if (stat.type === "directory") modes.set(path, "160000")
+      else modes.set(path, stat.executable === true ? "100755" : "100644")
+    }
+    return modes
+  }
+
   /** A submodule's (or embedded repository's) checked-out commit — what `git add` records for it. */
   const gitlinkOf = (path: string): string | undefined => {
     try {
@@ -547,6 +582,7 @@ const makeWorkspaceOps = (
   return {
     treeSync,
     worktreeSync,
+    modeSync,
     episodeTrees,
     readSync,
     read: (path) => Effect.try({ try: () => readSync(path), catch: toError }),

package/src/replay/Replay.ts

@@ -322,13 +322,43 @@ const STEERING_OPTIONS = ["file", "mode", "label", "base"]
 // The option keys each step accepts. A gtd.config.ts is evaluated without a
 // type check, so a misspelt key would otherwise be silently ignored.
 const KNOWN_OPTIONS: Readonly<Record<StepKind, ReadonlySet<string>>> = {
-  agent: new Set([...STEERING_OPTIONS, "model", "system", "allowEmpty", "keep"]),
+  agent: new Set([
+    ...STEERING_OPTIONS,
+    "model",
+    "system",
+    "allowEmpty",
+    "keep",
+    "validate",
+    "cap",
+    "exhausted",
+    "correction",
+  ]),
   human: new Set([...STEERING_OPTIONS, "message", "acceptClean", "approve"]),
   run: new Set([...STEERING_OPTIONS, "onFail"]),
   ship: new Set(["label", "base"]),
   judge: new Set([...STEERING_OPTIONS, "message"]),
 }
 
+const validatorOptionFault = (
+  name: string,
+  options: Extract<StepRequest, { kind: "agent" }>["options"],
+): string | undefined => {
+  const { validate, cap, exhausted, correction } = options
+  const prefix = `gtd: step "${name}": `
+  const notFunction = Object.entries({ validate, exhausted, correction }).find(
+    ([, value]) => value !== undefined && typeof value !== "function",
+  )
+  if (notFunction !== undefined)
+    return `${prefix}${notFunction[0]} must be a function in agent() options`
+  if (cap !== undefined && !(Number.isInteger(cap) && cap > 0)) {
+    return `${prefix}cap must be a positive integer in agent() options`
+  }
+  if (validate !== undefined && options.keep === true) {
+    return `${prefix}validate cannot be combined with keep: true — a kept turn is set aside, so there is no landed result to validate`
+  }
+  return undefined
+}
+
 const restsOnFail = (step: ReachedStep): boolean =>
   step.request.kind === "run" && step.request.options.onFail === "rest"
 
@@ -775,6 +805,8 @@ export const replay = async (raw: ReplayInput): Promise<ReplayOutcome> => {
     }
     if (request.kind !== "agent") return bodyFault(request)
     const name = scoped(request.name)
+    const optionFault = validatorOptionFault(name, request.options)
+    if (optionFault !== undefined) return optionFault
     if (request.options.keep === true) {
       // A clean allowEmpty keep would land an ordinary commit with no Gtd-Kept: a silent skip.
       if ((request.options as { readonly allowEmpty?: unknown }).allowEmpty === true) {

package/src/replay/Trailers.ts

@@ -296,6 +296,8 @@ export interface CommitSpec {
   readonly anchor?: string
   readonly branch?: string
   readonly version?: string
+  /** Written after `Gtd-Format`: a landing recording a ship an earlier, hook-rejected attempt already made. */
+  readonly shipped?: string
 }
 
 const sortedEntries = (record: Readonly<Record<string, string>> = {}): [string, string][] =>
@@ -323,6 +325,7 @@ export const formatCommitMessage = (spec: CommitSpec): string => {
     ...trailer("Branch", spec.branch),
     ...trailer("Version", spec.version),
     `Gtd-Format: ${HISTORY_FORMAT}`,
+    ...trailer("Shipped", spec.shipped),
   ]
   const subject = formatSubject(spec.actor, spec.to, spec.from)
   return `${subject}\n\n${lines.join("\n")}`

package/src/replay/Tree.ts

@@ -8,6 +8,8 @@ export interface TreeView {
   readonly paths: () => readonly string[]
   readonly read: (path: string) => string | undefined
   readonly id?: (path: string) => string | undefined
+  /** Git file mode; when both sides give one, a differing mode is a modification even with equal content. */
+  readonly mode?: (path: string) => string | undefined
 }
 
 export const treeFromRecord = (files: Readonly<Record<string, string>>): TreeView => ({
@@ -24,6 +26,9 @@ export interface TreeDiff {
 export const diffTrees = (before: TreeView, after: TreeView): TreeDiff => {
   // Blob ids only compare against blob ids; otherwise fall back to contents.
   const same = (path: string): boolean => {
+    if (before.mode !== undefined && after.mode !== undefined) {
+      if (before.mode(path) !== after.mode(path)) return false
+    }
     const a = before.id?.(path)
     const b = after.id?.(path)
     return a !== undefined && b !== undefined ? a === b : before.read(path) === after.read(path)

package/src/steering/FORMATS.md

@@ -17,7 +17,9 @@ read them.
   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.
+  chunk of its own. Under `## Findings` a location is a plain list item
+  (`- ./path`, `- ./path#start-end`) with no checkbox; a `- [ ]`/`- [x]` pointer
+  there is an error.
 - **`findings`**: the finding gate's file. `## ` entries, those under a
   `# Dropped as noise` heading being the noise; each holds exactly one
   `- [ ] fix` box. A ticked box fixes the finding; text below the box is the

package/src/steering/SteeringFormat.ts

@@ -17,6 +17,11 @@ export interface SteeringEdit {
 export interface SteeringAction {
   readonly title: string
   readonly edits: readonly SteeringEdit[]
+  /** A range the editor selects once the edits apply; absent means no reveal. */
+  readonly select?: {
+    readonly start: { readonly line: number; readonly character: number }
+    readonly end: { readonly line: number; readonly character: number }
+  }
 }
 
 /** A go-to-definition target. `path` absent means "this same document" (a footnote jump); `character` defaults to 0. */
@@ -105,6 +110,12 @@ export interface SteeringViewThread {
   readonly waitingOn: "human" | "agent"
 }
 
+/** One labelled part of a node's drafted comment. */
+export interface SteeringViewSection {
+  readonly label: string
+  readonly body: readonly SteeringViewNode[]
+}
+
 /**
  * One node of a format's `view`: a generic container/item tree, the SAME
  * shape for every format. Deliberately never a closed per-format union — a
@@ -140,6 +151,8 @@ export interface SteeringViewNode {
    * (question); absent wherever `detail` itself is absent.
    */
   readonly detailInline?: readonly InlineNode[]
+  /** A review finding's drafted PR comment as labelled sections (What / Impact / Fix), when it has one. */
+  readonly comment?: readonly SteeringViewSection[]
   /** A file path this node points at, when it has one (a `review` hunk). */
   readonly path?: string
   /** A 1-based line in `path` this node points at, when it has one. */

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

@@ -12,7 +12,7 @@ The parser keeps a lone `\r` as content.
 
 In the code:
 
-- [x] ./src/parse.ts#30-31 — where it is kept
+- ./src/parse.ts#30-31 — where it is kept
 
 Tick exactly one:
 

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

@@ -62,7 +62,6 @@
           "path": "./src/parse.ts",
           "line": 30,
           "endLine": 31,
-          "checked": true,
           "detail": "where it is kept",
           "anchor": {
             "kind": "hunk",

package/src/steering/index.ts

@@ -47,6 +47,7 @@ export type {
   SteeringPointer,
   SteeringView,
   SteeringViewNode,
+  SteeringViewSection,
   SteeringViewThread,
 } from "./SteeringFormat.js"
 

package/src/steering/review.test.ts

@@ -27,6 +27,7 @@ describe("parseReviewDoc", () => {
           title: "Add calculator",
           headingLine: 4,
           description: "New add function for the calculator.",
+          detail: "New add function for the calculator.",
           descriptionInline: [{ kind: "text", value: "New add function for the calculator." }],
           descriptionNodes: [
             {
@@ -1557,6 +1558,23 @@ describe("review.apply", () => {
     ).toEqual({ ok: false, reason: "anchor-not-found" })
   })
 
+  it("a chunk anchor on a findings chunk refuses anchor-not-found", () => {
+    const doc = [
+      "# Review: abc1234",
+      "",
+      "## Findings",
+      "",
+      "### Token check",
+      "",
+      "- ./src/auth.ts#1-2",
+      "",
+    ].join("\n")
+    expect(review.apply(doc, { kind: "chunk", index: 0 }, { checked: true })).toEqual({
+      ok: false,
+      reason: "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" },
@@ -1574,7 +1592,7 @@ describe("review decisions — a finding's answer boxes", () => {
     "",
     "### Token check",
     "",
-    "- [ ] ./src/auth.ts#1-2",
+    "- ./src/auth.ts#1-2",
     "",
     "Tick exactly one:",
     "",
@@ -2169,7 +2187,7 @@ describe("review — sectioned layout", async () => {
       "",
       "Leaks a token.",
       "",
-      "- [ ] ./src/a.ts#1-2 — here",
+      "- ./src/a.ts#1-2 — here",
       "",
       ...boxes(ticked),
       "",
@@ -2228,16 +2246,16 @@ describe("review — sectioned layout", async () => {
   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!.map((n) => n.name)).toEqual(["A finding"])
     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", () => {
+  it("drops a decided finding from the outline: its location carries no read tick", () => {
     const outline = viewOf(review, sectioned(1)).outline
-    expect(outline[0]!.children![0]!.children!.map((n) => n.name)).toEqual(["Decision: won't fix"])
+    expect(outline[0]!.children).toEqual([])
   })
 
   it("groups the view's chunks by section, anchors unchanged", () => {
@@ -2256,3 +2274,161 @@ describe("review — sectioned layout", async () => {
     expect(titles.some((t) => t.includes("A finding"))).toBe(false)
   })
 })
+
+describe("review — finding locations and decision actions", () => {
+  const finding = (pointer: string, ticked?: 0 | 1 | 2): string =>
+    [
+      "# Review: abc1234",
+      "",
+      "<!-- base: abc1234def5678901234567890123456789abcd -->",
+      "",
+      "## Findings",
+      "",
+      "### A finding",
+      "",
+      pointer,
+      "",
+      "Tick exactly one:",
+      "",
+      `- [${ticked === 0 ? "x" : " "}] fix as suggested`,
+      `- [${ticked === 1 ? "x" : " "}] won't fix`,
+      `- [${ticked === 2 ? "x" : " "}] _your answer_`,
+      "",
+    ].join("\n")
+  const at = (content: string, line: number) =>
+    review.actions!(content, { start: { line, character: 0 }, end: { line, character: 0 } })
+
+  it("links a plain location and resolves go-to-definition to its line", () => {
+    const content = finding("- ./src/a.ts#5-6 — here")
+    expect(review.validate(content)).toEqual([])
+    expect(review.documentLinks!(content)).toEqual([
+      expect.objectContaining({ path: "./src/a.ts", line: 4 }),
+    ])
+    expect(review.pointerAt!(content, { line: 8, character: 3 })).toEqual({
+      path: "./src/a.ts",
+      line: 4,
+    })
+  })
+
+  it("refuses a checkbox pointer in a finding at its own line", () => {
+    for (const box of ["[ ]", "[x]"]) {
+      const found = review.validate(finding(`- ${box} ./src/a.ts#5-6`))
+      expect(found.some((f) => f.line === 8)).toBe(true)
+    }
+  })
+
+  it("offers no hunk tick and no read count for a finding location", () => {
+    const content = finding("- ./src/a.ts#5-6")
+    const titles = at(content, 8).map((a) => a.title)
+    expect(titles.some((t) => t.includes("hunk"))).toBe(false)
+    expect(viewOf(review, content).outline[0]!.children![0]!.name).toBe("A finding")
+    const hunk = review.view(content).nodes[0]!.children![0]!
+    expect(hunk.checked).toBeUndefined()
+    expect(review.apply(content, hunk.anchor, { checked: true }).ok).toBe(false)
+  })
+
+  it("accepts, rejects and answers from any line, leaving out the current tick's action", () => {
+    const content = finding("- ./src/a.ts#5-6")
+    for (const line of [6, 8, 12]) {
+      expect(at(content, line).map((a) => a.title)).toEqual(
+        expect.arrayContaining([
+          "gtd: accept finding",
+          "gtd: reject finding",
+          "gtd: answer finding",
+        ]),
+      )
+    }
+    const run = (title: string, text: string) =>
+      applySteeringEdits(text, at(text, 8).find((a) => a.title === title)!.edits)
+    const accepted = run("gtd: accept finding", finding("- ./src/a.ts#5-6", 1))
+    expect(accepted).toBe(finding("- ./src/a.ts#5-6", 0))
+    expect(at(accepted, 8).map((a) => a.title)).not.toContain("gtd: accept finding")
+    expect(run("gtd: reject finding", accepted)).toBe(finding("- ./src/a.ts#5-6", 1))
+    expect(run("gtd: answer finding", accepted)).toBe(finding("- ./src/a.ts#5-6", 2))
+  })
+
+  it("selects the whole free-text slot on answer", () => {
+    const content = finding("- ./src/a.ts#5-6")
+    const answer = at(content, 8).find((a) => a.title === "gtd: answer finding")!
+    expect(answer.select).toEqual({
+      start: { line: 14, character: 6 },
+      end: { line: 14, character: 19 },
+    })
+  })
+
+  it("offers no finding actions on a top-level comments chunk", () => {
+    const content = finding("- ./src/a.ts#5-6").replace(
+      "## Findings\n\n### A finding",
+      "## Your comments:",
+    )
+    expect(
+      at(content, 6)
+        .map((a) => a.title)
+        .join(),
+    ).not.toContain("finding")
+  })
+})
+
+describe("review view drafted comment", () => {
+  const doc = (pointer: string) => `# Review
+
+## Findings
+
+### Token check
+
+_correctness · judge: fix_
+
+${pointer}Draft PR comment:
+
+> nit: Uses \`==\`.
+> Impact: Timing leak.
+> Fix: Use \`timingSafeEqual\`.
+>
+> \`\`\`suggestion
+> return ok
+> \`\`\`
+
+Tick exactly one:
+
+- [ ] fix as suggested
+- [ ] won't fix
+- [ ] _your answer_
+`
+  for (const [name, pointer] of [
+    ["with a pointer", "- [ ] ./src/auth.ts#1-3\n\n"],
+    ["without a pointer", ""],
+  ] as const) {
+    it(`splits the comment into What, Impact and Fix ${name}`, () => {
+      const node = steeringFormatFor("review")!.view(doc(pointer)).nodes[0]!
+      expect(node.comment?.map((s) => s.label)).toEqual(["What", "Impact", "Fix"])
+      const fix = node.comment![2]!.body
+      expect(fix.some((n) => n.block?.kind === "code" && n.block.text === "return ok")).toBe(true)
+      expect(node.detail).not.toContain("Draft PR comment")
+    })
+  }
+
+  it("keeps an unlabelled comment as one What", () => {
+    const node = steeringFormatFor("review")!.view(
+      doc("")
+        .replace(/Impact:[^]*?```\n\nTick/, "Plain.\n\nTick")
+        .replace("> nit: Uses `==`.\n> ", "> nit: Uses."),
+    ).nodes[0]!
+    expect(node.comment?.map((s) => s.label)).toEqual(["What"])
+  })
+
+  it("keeps a Fix: line inside a suggestion fence in its code block", () => {
+    const node = steeringFormatFor("review")!.view(
+      doc("").replace("> return ok", "> Fix: inside\n> return ok"),
+    ).nodes[0]!
+    expect(node.comment?.map((s) => s.label)).toEqual(["What", "Impact", "Fix"])
+    const code = node.comment![2]!.body.find((n) => n.block?.kind === "code")
+    expect(code?.block?.text).toContain("Fix: inside")
+  })
+
+  it("leaves the comment in the body of a chunk with no answer list", () => {
+    const node = steeringFormatFor("review")!.view(doc("").replace(/Tick exactly one:[^]*$/, ""))
+      .nodes[0]!
+    expect(node.comment).toBeUndefined()
+    expect(node.detail).toContain("Draft PR comment")
+  })
+})