@pmelab/gtd 23.2.0 → 24.1.0

package/src/steering/Footnotes.test.ts

@@ -0,0 +1,977 @@
+import { describe, expect, it } from "vitest"
+import fc from "fast-check"
+import {
+  footnoteAdditionEdits,
+  footnoteAttachEdits,
+  footnotePointerAt,
+  isOnExistingFootnote,
+  nextFootnoteName,
+  parseFootnotes,
+  openThreadFindings,
+  parseThreads,
+  threadReplyActions,
+} from "./Footnotes.js"
+
+/** Applies a list of `SteeringEdit`s to `content`, last-to-first so earlier offsets stay valid — used only by tests to assert the resulting document, never by production code (which always splices via LSP tooling). */
+const applyEdits = (
+  content: string,
+  edits: readonly {
+    range: { start: { line: number; character: number }; end: { line: number; character: number } }
+    newText: string
+  }[],
+): string => {
+  const lines = content.split("\n")
+  const toOffset = (pos: { line: number; character: number }): number => {
+    let offset = 0
+    for (let i = 0; i < pos.line; i += 1) offset += (lines[i]?.length ?? 0) + 1
+    return offset + pos.character
+  }
+  const sorted = [...edits].sort((a, b) => toOffset(b.range.start) - toOffset(a.range.start))
+  let result = content
+  for (const edit of sorted) {
+    const start = toOffset(edit.range.start)
+    const end = toOffset(edit.range.end)
+    result = result.slice(0, start) + edit.newText + result.slice(end)
+  }
+  return result
+}
+
+describe("parseFootnotes", () => {
+  it("is total on an empty string", () => {
+    expect(() => parseFootnotes("")).not.toThrow()
+    expect(parseFootnotes("")).toEqual({ markers: [], definitions: [], findings: [] })
+  })
+
+  it("never throws on arbitrary input", () => {
+    fc.assert(
+      fc.property(fc.string(), (content) => {
+        expect(() => parseFootnotes(content)).not.toThrow()
+      }),
+    )
+  })
+
+  it("is total on a document of only backticks", () => {
+    expect(() => parseFootnotes("```````````")).not.toThrow()
+  })
+
+  it("yields the exact 0-based column of a marker mid-sentence", () => {
+    const content = "Some prose, a claim[^fn1], continues.\n\n[^fn1]: the reason\n"
+    const { markers } = parseFootnotes(content)
+    expect(markers).toEqual([{ name: "fn1", line: 0, character: 19, endCharacter: 25 }])
+  })
+
+  it("parses a single-line definition with endLine === line and its body", () => {
+    const content = "text[^fn1]\n\n[^fn1]: a short reason\n"
+    const { definitions } = parseFootnotes(content)
+    expect(definitions).toEqual([{ name: "fn1", line: 2, endLine: 2, body: "a short reason" }])
+  })
+
+  it("joins four-space-indented continuation lines and tracks endLine", () => {
+    const content = ["text[^fn1]", "", "[^fn1]:", "    first line of body", "    second line"].join(
+      "\n",
+    )
+    const { definitions } = parseFootnotes(content)
+    expect(definitions).toEqual([
+      { name: "fn1", line: 2, endLine: 4, body: "first line of body second line" },
+    ])
+  })
+
+  it("does not treat a two-space indent as a continuation — GFM requires four spaces, unlike the old hand-rolled walker", () => {
+    const content = ["text[^fn1]", "", "[^fn1]:", "  first", "  second"].join("\n")
+    const { definitions } = parseFootnotes(content)
+    expect(definitions).toEqual([{ name: "fn1", line: 2, endLine: 2, body: "" }])
+  })
+
+  it("raises the indent finding (not the empty-body one) for a definition whose continuation is indented under 4 spaces, even though a human wrote real words there — the indent, not the words, decides membership", () => {
+    const content = ["text[^fn1]", "", "[^fn1]:", " a human wrote this comment here"].join("\n")
+    const { definitions, findings } = parseFootnotes(content)
+    expect(definitions).toEqual([{ name: "fn1", line: 2, endLine: 2, body: "" }])
+    expect(findings).toContainEqual({
+      message:
+        'Footnote definition "[^fn1]": the text below it is indented too little to belong to it — indent continuation lines by 4 spaces',
+      line: 2,
+      range: { start: { line: 2, character: 0 }, end: { line: 3, character: 32 } },
+    })
+    expect(findings.some((f) => f.message.includes("has an empty body"))).toBe(false)
+  })
+
+  it("raises the indent message and never the empty-body one, and exactly one finding, for a definition followed by words indented 1-3 spaces", () => {
+    const content = ["text[^fn1]", "", "[^fn1]:", "   stranded words here"].join("\n")
+    const { findings } = parseFootnotes(content)
+    expect(findings).toHaveLength(1)
+    expect(findings[0]!.message).toBe(
+      'Footnote definition "[^fn1]": the text below it is indented too little to belong to it — indent continuation lines by 4 spaces',
+    )
+  })
+
+  it("spans the indent finding's range through the stranded paragraph's own last line when it wraps several lines", () => {
+    const content = [
+      "text[^fn1]",
+      "",
+      "[^fn1]:",
+      " first stranded line",
+      " second stranded line",
+    ].join("\n")
+    const { findings } = parseFootnotes(content)
+    expect(findings).toHaveLength(1)
+    expect(findings[0]!.range).toEqual({
+      start: { line: 2, character: 0 },
+      end: { line: 4, character: " second stranded line".length },
+    })
+  })
+
+  it("still raises has an empty body for a definition followed by a non-blank line at 0 indent", () => {
+    const content = ["text[^fn1]", "", "[^fn1]:", "not indented at all"].join("\n")
+    const { findings } = parseFootnotes(content)
+    expect(findings).toHaveLength(1)
+    expect(findings[0]!.message).toBe('Footnote definition "[^fn1]" has an empty body')
+  })
+
+  it("raises has an empty body for [^a] (never the indent message) when the indented next line is actually [^b]'s own definition", () => {
+    const content = ["text[^fn1] text[^fn2]", "", "[^fn1]:", " [^fn2]: text"].join("\n")
+    const { findings } = parseFootnotes(content)
+    const fn1Findings = findings.filter((f) => f.message.includes('"[^fn1]"'))
+    expect(fn1Findings).toEqual([
+      {
+        message: 'Footnote definition "[^fn1]" has an empty body',
+        line: 2,
+        range: { start: { line: 2, character: 0 }, end: { line: 2, character: 7 } },
+      },
+    ])
+  })
+
+  it("raises neither finding for a definition followed by a tab-indented line — GFM joins it to the body", () => {
+    const content = ["text[^fn1]", "", "[^fn1]:", "\tstranded but joined by the tab"].join("\n")
+    const { definitions, findings } = parseFootnotes(content)
+    expect(definitions[0]!.body).toBe("stranded but joined by the tab")
+    expect(findings).toHaveLength(0)
+  })
+
+  it("ends a definition at a blank line", () => {
+    const content = ["text[^fn1]", "", "[^fn1]:", "    first", "", "not part of it"].join("\n")
+    const { definitions } = parseFootnotes(content)
+    expect(definitions[0]!.endLine).toBe(3)
+    expect(definitions[0]!.body).toBe("first")
+  })
+
+  it("keeps an unindented line as a LAZY continuation of the body paragraph, per real GFM paragraph continuation rules", () => {
+    const content = ["text[^fn1]", "", "[^fn1]:", "    first", "not indented, not part of it"].join(
+      "\n",
+    )
+    const { definitions } = parseFootnotes(content)
+    expect(definitions[0]!.endLine).toBe(4)
+    expect(definitions[0]!.body).toBe("first not indented, not part of it")
+  })
+
+  it("produces no marker for [^x] inside a fenced code block", () => {
+    const content = ["```", "[^x]", "```", "", "[^y] real marker[^y]"].join("\n")
+    const { markers } = parseFootnotes(content)
+    expect(markers.map((m) => m.name)).toEqual(["y", "y"])
+  })
+
+  it("produces no marker for [^x] inside an inline-code span", () => {
+    const content = "prose `[^x]` and [^y] real one"
+    const { markers } = parseFootnotes(content)
+    expect(markers.map((m) => m.name)).toEqual(["y"])
+  })
+
+  it("still finds an orphan [^y] written inside another definition's body — GFM applies the same reference-vs-text rule everywhere, no special-cased skip for a body's own prose", () => {
+    const content = ["text[^fn1]", "", "[^fn1]:", "    see also [^y] here"].join("\n")
+    const { markers } = parseFootnotes(content)
+    expect(markers.map((m) => m.name)).toEqual(["fn1", "y"])
+  })
+
+  it("produces no finding for two markers of the same name with one definition", () => {
+    const content = ["a[^fn1] b[^fn1]", "", "[^fn1]: reason"].join("\n")
+    const { findings } = parseFootnotes(content)
+    expect(findings).toEqual([])
+  })
+
+  it("reports a marker with no definition at the marker's line", () => {
+    const content = "orphan marker[^fn1] here"
+    const { findings } = parseFootnotes(content)
+    expect(findings).toEqual([
+      {
+        message: 'Footnote marker "[^fn1]" has no matching definition',
+        line: 0,
+        range: { start: { line: 0, character: 13 }, end: { line: 0, character: 19 } },
+      },
+    ])
+  })
+
+  it("reports a definition no marker references at the definition's line", () => {
+    const content = "no markers here\n\n[^fn1]: orphan definition"
+    const { findings } = parseFootnotes(content)
+    expect(findings).toEqual([
+      {
+        message: 'Footnote definition "[^fn1]" has no marker referencing it',
+        line: 2,
+        range: { start: { line: 2, character: 0 }, end: { line: 2, character: 25 } },
+      },
+    ])
+  })
+
+  it("reports a duplicate definition name at the second definition's line", () => {
+    const content = ["a[^fn1]", "", "[^fn1]: first", "[^fn1]: second"].join("\n")
+    const { findings } = parseFootnotes(content)
+    expect(findings).toContainEqual({
+      message: 'Duplicate footnote definition "[^fn1]"',
+      line: 3,
+      range: { start: { line: 3, character: 0 }, end: { line: 3, character: 14 } },
+    })
+  })
+
+  it("parses a body-less definition as a real footnoteDefinition, matched to its marker, not an orphan", () => {
+    const content = "a[^fn1]\n\n[^fn1]:\n"
+    const { definitions, markers, findings } = parseFootnotes(content)
+    expect(definitions).toEqual([{ name: "fn1", line: 2, endLine: 2, body: "" }])
+    expect(markers).toEqual([{ name: "fn1", line: 0, character: 1, endCharacter: 7 }])
+    expect(findings.some((f) => f.message.includes("has no matching definition"))).toBe(false)
+  })
+
+  it("reports a definition whose body is empty as unfilled", () => {
+    const content = ["a[^fn1]", "", "[^fn1]:"].join("\n")
+    const { findings } = parseFootnotes(content)
+    expect(findings).toContainEqual({
+      message: 'Footnote definition "[^fn1]" has an empty body',
+      line: 2,
+      range: { start: { line: 2, character: 0 }, end: { line: 2, character: 7 } },
+    })
+  })
+
+  it("reports no finding for a definition holding the ordinary human text 'your comment' — it is no longer a placeholder", () => {
+    const content = ["a[^fn1]", "", "[^fn1]: your comment"].join("\n")
+    const { findings } = parseFootnotes(content)
+    expect(findings.some((f) => f.message.includes("has an empty body"))).toBe(false)
+  })
+
+  it("reports no finding of any kind for placement — a far-away definition is valid", () => {
+    const content = [
+      "a[^fn1] paragraph one",
+      "",
+      "paragraph two, unrelated",
+      "",
+      "paragraph three",
+      "",
+      "[^fn1]: the definition, far below",
+    ].join("\n")
+    const { findings } = parseFootnotes(content)
+    expect(findings).toEqual([])
+  })
+
+  it("does not recognize a definition below a fence opened above the slice it's handed — the tree sees the whole document, so a fence opened earlier still hides it", () => {
+    const content = ["```", "[^fn1]: not a real definition, still fenced", "```"].join("\n")
+    const { definitions, markers } = parseFootnotes(content)
+    expect(definitions).toEqual([])
+    expect(markers).toEqual([])
+  })
+
+  it("produces no marker for [^x] inside a four-space indented code block", () => {
+    const content = ["    [^x] indented code", "", "real [^y]", "", "[^y]: d"].join("\n")
+    const { markers } = parseFootnotes(content)
+    expect(markers.map((m) => m.name)).toEqual(["y"])
+  })
+
+  it("produces no marker for [^x] inside a ~~~ fence", () => {
+    const content = ["~~~", "[^x]", "~~~", "", "real [^y]", "", "[^y]: d"].join("\n")
+    const { markers } = parseFootnotes(content)
+    expect(markers.map((m) => m.name)).toEqual(["y"])
+  })
+
+  it("produces no marker for [^x] inside a double-backtick span", () => {
+    const content = "prose ``[^x]`` and [^y] real\n\n[^y]: d"
+    const { markers } = parseFootnotes(content)
+    expect(markers.map((m) => m.name)).toEqual(["y"])
+  })
+
+  it("does not recognize a [^name]: definition written inside an inline-code span", () => {
+    const content = "no ref here\n\n`[^fn1]: not a def`"
+    const { definitions } = parseFootnotes(content)
+    expect(definitions).toEqual([])
+  })
+
+  it("carries all of a multi-paragraph definition's paragraphs in body", () => {
+    const content = ["text[^fn1]", "", "[^fn1]: first paragraph", "", "    second paragraph"].join(
+      "\n",
+    )
+    const { definitions } = parseFootnotes(content)
+    expect(definitions).toEqual([
+      { name: "fn1", line: 2, endLine: 4, body: "first paragraph second paragraph" },
+    ])
+  })
+
+  describe("orphan markers", () => {
+    it("reports 'has no matching definition' for a marker with no definition anywhere", () => {
+      const content = "Some text[^fn1] here."
+      const { findings, markers } = parseFootnotes(content)
+      expect(markers).toEqual([{ name: "fn1", line: 0, character: 9, endCharacter: 15 }])
+      expect(findings).toEqual([
+        {
+          message: 'Footnote marker "[^fn1]" has no matching definition',
+          line: 0,
+          range: { start: { line: 0, character: 9 }, end: { line: 0, character: 15 } },
+        },
+      ])
+    })
+
+    it("reports the TRUE column of an orphan marker preceded on the same line by an entity reference, not node.value's shorter length", () => {
+      const content = "&amp;[^fn1] after"
+      const { markers } = parseFootnotes(content)
+      // Source column is after the literal "&amp;" (5 chars), not the decoded "&" (1 char).
+      expect(markers).toEqual([{ name: "fn1", line: 0, character: 5, endCharacter: 11 }])
+    })
+
+    it("reports line two, not the text node's start line, for an orphan on the second line of a lazy list-item wrap", () => {
+      const content = ["- some text", "  continues[^fn1] here"].join("\n")
+      const { markers } = parseFootnotes(content)
+      expect(markers).toEqual([{ name: "fn1", line: 1, character: 11, endCharacter: 17 }])
+    })
+
+    it("reports nothing for an orphan inside a fence, an indented code block, or an inline-code span", () => {
+      const content = ["```", "[^a]", "```", "", "    [^b] indented", "", "prose `[^c]` span"].join(
+        "\n",
+      )
+      const { markers } = parseFootnotes(content)
+      expect(markers).toEqual([])
+    })
+  })
+})
+
+describe("nextFootnoteName", () => {
+  it("is fn1 for a document with no footnotes at all", () => {
+    expect(nextFootnoteName("just prose")).toBe("fn1")
+  })
+
+  it("skips names already used by a marker or a definition, whichever is higher", () => {
+    expect(nextFootnoteName("a[^fn1] b[^fn3]\n\n[^fn2]: reason")).toBe("fn4")
+  })
+
+  it("is idempotent across two applications: fn1 then fn2, never a collision", () => {
+    const first = nextFootnoteName("prose")
+    expect(first).toBe("fn1")
+    const withFirst = `prose[^${first}]\n\n[^${first}]:\n`
+    expect(nextFootnoteName(withFirst)).toBe("fn2")
+  })
+
+  it("counts an orphan marker (written but never given a definition) so it's never reused", () => {
+    // fn1 has no definition anywhere — it's an orphan, not a footnoteReference node.
+    expect(nextFootnoteName("prose[^fn1] more")).toBe("fn2")
+  })
+})
+
+describe("footnoteAdditionEdits", () => {
+  it("inserts the marker at exactly the cursor position — no scan, no +1 — and a seeded-empty definition anchored one line PAST blockEndLine, separated by blank lines", () => {
+    const content = ["Option A here", "", "next paragraph"].join("\n")
+    const edits = footnoteAdditionEdits(content, { line: 0, character: 7 }, 0)
+    expect(edits).toHaveLength(2)
+    expect(edits[0]).toEqual({
+      range: { start: { line: 0, character: 7 }, end: { line: 0, character: 7 } },
+      newText: "[^fn1]",
+    })
+    expect(edits[1]!.newText).toBe("\n[^fn1]:\n\n")
+    expect(edits[1]!.range.start).toEqual({ line: 1, character: 0 })
+    expect(edits[1]!.range.end).toEqual({ line: 2, character: 0 })
+  })
+
+  it("plants the marker mid-word when the cursor sits inside one — the old word-end scan is gone", () => {
+    const content = "new add function"
+    const edits = footnoteAdditionEdits(content, { line: 0, character: 1 }, 0) // cursor on "e" of "new"
+    expect(edits[0]).toEqual({
+      range: { start: { line: 0, character: 1 }, end: { line: 0, character: 1 } },
+      newText: "[^fn1]",
+    })
+  })
+
+  it("leaves the marker exactly where the cursor already sits just past a word", () => {
+    const content = "new add function"
+    const edits = footnoteAdditionEdits(content, { line: 0, character: 3 }, 0) // right after "new", before the space
+    expect(edits[0]!.range.start).toEqual({ line: 0, character: 3 })
+  })
+
+  it("at end of file, seeds the definition with a single trailing newline, no extra blank line after", () => {
+    const content = "Option A here"
+    const edits = footnoteAdditionEdits(content, { line: 0, character: 7 }, 0)
+    expect(edits[1]!.newText).toBe("\n[^fn1]:\n")
+    expect(edits[1]!.range.start).toEqual({ line: 1, character: 0 })
+    expect(edits[1]!.range.end).toEqual({ line: 1, character: 0 })
+  })
+
+  it("generates the next unused name, never colliding with an existing footnote", () => {
+    const content = ["a[^fn1]", "", "[^fn1]: reason"].join("\n")
+    const edits = footnoteAdditionEdits(content, { line: 0, character: 1 }, 0)
+    expect(edits[0]!.newText).toBe("[^fn2]")
+  })
+
+  it("never shares a start position between the two edits, even when the cursor sits at the very end of blockEndLine itself — the collision that corrupted the marker (regression)", () => {
+    const content = ["some trailing prose", "", "next paragraph"].join("\n")
+    const cursorCharacter = "some trailing prose".length // end of blockEndLine's own line
+    const edits = footnoteAdditionEdits(content, { line: 0, character: cursorCharacter }, 0)
+    const [markerEdit, definitionEdit] = edits
+    // Same line as the marker would be a collision; one line later never is.
+    expect(definitionEdit!.range.start.line).toBeGreaterThan(markerEdit!.range.start.line)
+    expect(
+      definitionEdit!.range.start.line === markerEdit!.range.end.line &&
+        definitionEdit!.range.start.character === markerEdit!.range.end.character,
+    ).toBe(false)
+  })
+
+  it("applying both edits raises exactly one finding — the empty-body one — for the definition it just seeded", () => {
+    const content = ["Option A here", "", "next paragraph"].join("\n")
+    const edits = footnoteAdditionEdits(content, { line: 0, character: 7 }, 0)
+    const applied = applyEdits(content, edits)
+    const { findings } = parseFootnotes(applied)
+    expect(findings).toHaveLength(1)
+    expect(findings[0]!.message).toBe('Footnote definition "[^fn1]" has an empty body')
+  })
+})
+
+describe("footnoteAttachEdits", () => {
+  it("produces exactly two edits and every byte outside their ranges is unchanged", () => {
+    const content = ["Some chunk text here", "", "next paragraph"].join("\n")
+    const result = footnoteAttachEdits(
+      content,
+      {
+        line: 0,
+        endCharacter: "Some chunk text here".length,
+        blockEndLine: 0,
+        key: "chunk:0",
+      },
+      "the human's own typed note",
+    )
+    expect(result.ok).toBe(true)
+    if (!result.ok) return
+    expect(result.edits).toHaveLength(2)
+    const applied = applyEdits(content, result.edits)
+    expect(applied).toBe(
+      `Some chunk text here[^${result.id}]\n\n[^${result.id}]:\n    - H: the human's own typed note\n\nnext paragraph`,
+    )
+  })
+
+  it("lands the marker at the end of the anchor's own text, not on a new line", () => {
+    const content = "Option A here"
+    const result = footnoteAttachEdits(
+      content,
+      {
+        line: 0,
+        endCharacter: 9,
+        blockEndLine: 0,
+        key: "opt:a",
+      },
+      "a note",
+    )
+    expect(result.ok).toBe(true)
+    if (!result.ok) return
+    expect(result.edits[0]!.range).toEqual({
+      start: { line: 0, character: 9 },
+      end: { line: 0, character: 9 },
+    })
+  })
+
+  it("two attaches at two different anchors in one document produce two distinct ids", () => {
+    const content = ["Chunk A", "", "Chunk B"].join("\n")
+    const first = footnoteAttachEdits(
+      content,
+      {
+        line: 0,
+        endCharacter: 7,
+        blockEndLine: 0,
+        key: "chunk:a",
+      },
+      "note a",
+    )
+    const second = footnoteAttachEdits(
+      content,
+      {
+        line: 2,
+        endCharacter: 7,
+        blockEndLine: 2,
+        key: "chunk:b",
+      },
+      "note b",
+    )
+    expect(first.ok && second.ok).toBe(true)
+    if (!first.ok || !second.ok) return
+    expect(first.id).not.toBe(second.id)
+  })
+
+  it("a second attach at the SAME anchor EDITS the existing note in place, rather than rejecting it (T6: 'offers editing it, not a second note')", () => {
+    const content = "Chunk A"
+    const first = footnoteAttachEdits(
+      content,
+      {
+        line: 0,
+        endCharacter: 7,
+        blockEndLine: 0,
+        key: "chunk:a",
+      },
+      "note a",
+    )
+    expect(first.ok).toBe(true)
+    if (!first.ok) return
+    const applied = applyEdits(content, first.edits)
+    const second = footnoteAttachEdits(
+      applied,
+      {
+        line: 0,
+        endCharacter: 7,
+        blockEndLine: 0,
+        key: "chunk:a",
+      },
+      "note a, again",
+    )
+    expect(second.ok).toBe(true)
+    if (!second.ok) return
+    // Same id, single replace edit — no second marker, no second definition.
+    expect(second.id).toBe(first.id)
+    expect(second.edits).toHaveLength(1)
+    const reapplied = applyEdits(applied, second.edits)
+    expect(reapplied).toContain(`[^${first.id}]:\n    - H: note a, again`)
+    expect(reapplied).not.toContain("note a, again, again")
+    expect((reapplied.match(new RegExp(`\\[\\^${first.id}\\]`, "g")) ?? []).length).toBe(2) // one marker, one definition
+    expect(parseFootnotes(reapplied).definitions).toHaveLength(1)
+  })
+
+  it("an id colliding with a definition NOT already attached at THIS anchor's own line is still rejected", () => {
+    const key = "chunk:a"
+    const generated = footnoteAttachEdits(
+      "x",
+      { line: 0, endCharacter: 1, blockEndLine: 0, key },
+      "note",
+    )
+    expect(generated.ok).toBe(true)
+    if (!generated.ok) return
+    const upperId = generated.id.toUpperCase()
+    // The existing marker/definition sit on line 5 — a different line than
+    // where THIS anchor's own attach would land (line 0) — so this reads as
+    // a genuine collision with unrelated content, never a re-attach at the
+    // same spot.
+    const content = `text\n\n\n\n\nelsewhere[^${upperId}]\n\n[^${upperId}]: existing reason\n`
+    const result = footnoteAttachEdits(
+      content,
+      {
+        line: 0,
+        endCharacter: 4,
+        blockEndLine: 0,
+        key,
+      },
+      "note",
+    )
+    expect(result).toEqual({ ok: false, reason: "id-collision" })
+  })
+
+  it("keeps CRLF line endings", () => {
+    const content = ["Chunk A", "", "next"].join("\r\n")
+    const result = footnoteAttachEdits(
+      content,
+      {
+        line: 0,
+        endCharacter: 7,
+        blockEndLine: 0,
+        key: "chunk:a",
+      },
+      "note",
+    )
+    expect(result.ok).toBe(true)
+    if (!result.ok) return
+    const applied = applyEdits(content, result.edits)
+    expect(applied).not.toContain("\n\n\n")
+    expect(applied.includes("\r\n")).toBe(true)
+  })
+
+  it("seeds the new definition with the given text verbatim, never empty — the resulting document never trips the empty-body finding", () => {
+    const content = "Some chunk text here"
+    const result = footnoteAttachEdits(
+      content,
+      { line: 0, endCharacter: content.length, blockEndLine: 0, key: "chunk:0" },
+      "a real reason a human actually typed",
+    )
+    expect(result.ok).toBe(true)
+    if (!result.ok) return
+    const applied = applyEdits(content, result.edits)
+    const { findings } = parseFootnotes(applied)
+    expect(findings.some((f) => f.message.includes("has an empty body"))).toBe(false)
+  })
+})
+
+describe("footnotePointerAt", () => {
+  const doc = ["a[^fn1] b", "", "[^fn1]: the reason", ""].join("\n")
+
+  it("jumps from within a marker's span to its definition's line", () => {
+    const character = doc.split("\n")[0]!.indexOf("[^fn1]") + 2 // inside the name
+    expect(footnotePointerAt(doc, { line: 0, character })?.pointer).toEqual({ line: 2 })
+  })
+
+  it("jumps from a definition line to its first marker's line AND exact column", () => {
+    const markerCol = doc.split("\n")[0]!.indexOf("[^fn1]")
+    expect(footnotePointerAt(doc, { line: 2, character: 0 })?.pointer).toEqual({
+      line: 0,
+      character: markerCol,
+    })
+  })
+
+  it("resolves an orphan marker to 'handled, but no pointer' rather than falling through", () => {
+    const orphan = "orphan[^missing]"
+    const character = orphan.indexOf("[^missing]") + 2
+    const result = footnotePointerAt(orphan, { line: 0, character })
+    expect(result).toEqual({ pointer: undefined })
+  })
+
+  it("resolves an orphan definition to 'handled, but no pointer'", () => {
+    const orphan = "[^missing]: nobody points here"
+    expect(footnotePointerAt(orphan, { line: 0, character: 0 })).toEqual({ pointer: undefined })
+  })
+
+  it("returns undefined (not applicable) for a position that is neither a marker nor a definition", () => {
+    expect(footnotePointerAt(doc, { line: 0, character: 8 })).toBeUndefined() // "b", not the marker
+  })
+
+  it("returns undefined — not 'resolved, no pointer' — for a two-space-indented line that LOOKS like a continuation but isn't one per real GFM (regression: a since-deleted line-based helper used to dead-end here on its own looser 'any indent continues' rule)", () => {
+    const content = ["text[^fn1]", "", "[^fn1]:", "  the reason"].join("\n")
+    // The tree's real GFM continuation span ends at line 2 (four spaces are
+    // required; this is indented only two) — line 3 is NOT part of the
+    // definition, so the caller must be free to fall through instead of
+    // getting stuck on "handled, but no pointer".
+    expect(footnotePointerAt(content, { line: 3, character: 2 })).toBeUndefined()
+  })
+})
+
+describe("isOnExistingFootnote", () => {
+  const doc = ["a[^fn1] b", "", "[^fn1]: the reason", ""].join("\n")
+
+  it("is true inside an existing marker's [^name] span", () => {
+    const character = doc.split("\n")[0]!.indexOf("[^fn1]") + 2 // inside the name
+    expect(isOnExistingFootnote(doc, { line: 0, character })).toBe(true)
+  })
+
+  it("is true on a definition's own label line", () => {
+    expect(isOnExistingFootnote(doc, { line: 2, character: 3 })).toBe(true)
+  })
+
+  it("is true on a definition's indented continuation line", () => {
+    const content = ["a[^fn1]", "", "[^fn1]:", "    continued body"].join("\n")
+    expect(isOnExistingFootnote(content, { line: 3, character: 4 })).toBe(true)
+  })
+
+  it("is false for ordinary text, even right next to a marker", () => {
+    expect(isOnExistingFootnote(doc, { line: 0, character: 8 })).toBe(false) // "b"
+  })
+
+  it("is false for a document with no footnotes at all", () => {
+    expect(isOnExistingFootnote("just prose", { line: 0, character: 0 })).toBe(false)
+  })
+
+  it("refuses inside an orphan marker's span too — planting a name there would still corrupt existing `[^` syntax", () => {
+    const content = "orphan[^missing] text"
+    const character = content.indexOf("[^missing]") + 2
+    expect(isOnExistingFootnote(content, { line: 0, character })).toBe(true)
+  })
+})
+
+describe("case-insensitive definition matching", () => {
+  it("resolves [^FN1] against a [^fn1]: definition with zero findings", () => {
+    const content = "claim[^FN1]\n\n[^fn1]: the reason\n"
+    const { findings } = parseFootnotes(content)
+    expect(findings).toEqual([])
+  })
+
+  it("jumps between a differently-cased marker and its definition in both directions", () => {
+    const content = "claim[^FN1]\n\n[^fn1]: the reason\n"
+    const markerChar = content.indexOf("[^FN1]") + 2
+    expect(footnotePointerAt(content, { line: 0, character: markerChar })?.pointer).toEqual({
+      line: 2,
+    })
+    expect(footnotePointerAt(content, { line: 2, character: 0 })?.pointer).toEqual({
+      line: 0,
+      character: content.indexOf("[^FN1]"),
+    })
+  })
+
+  it("renders a finding's message with the author's own casing (label), not the normalized identifier", () => {
+    const content = "no marker for this one\n\n[^FN1]: orphan definition"
+    const { findings } = parseFootnotes(content)
+    expect(findings).toContainEqual({
+      message: 'Footnote definition "[^FN1]" has no marker referencing it',
+      line: 2,
+      range: { start: { line: 2, character: 0 }, end: { line: 2, character: 25 } },
+    })
+  })
+})
+
+import { freeFormFormat, getParseCount, steeringFormatFor } from "./index.js"
+
+const qaDescriptor = steeringFormatFor("qa")!
+const reviewDescriptor = steeringFormatFor("review")!
+
+const CACHE = [
+  "We cache the result per request.[^cache]",
+  "",
+  "[^cache]:",
+  "    - H: why do we do that this way?",
+  "    - A: because ...",
+  "    - H: would this ... work instead?",
+  "    - A: no, because ...",
+  "    - H: and this ...?",
+  "    - A: yes, that would work",
+  "    - H: then do it this way",
+  "",
+].join("\n")
+
+describe("parseThreads", () => {
+  it("parses the requirement example into 7 alternating entries waiting on the agent", () => {
+    const [t] = parseThreads(CACHE)
+    expect(t!.name).toBe("cache")
+    expect(t!.entries).toHaveLength(7)
+    expect(t!.entries.map((e) => e.author)).toEqual([
+      "me",
+      "agent",
+      "me",
+      "agent",
+      "me",
+      "agent",
+      "me",
+    ])
+    expect(t!.entries[0]).toEqual({
+      author: "me",
+      text: "why do we do that this way?",
+      line: 3,
+      endLine: 3,
+      column: 4,
+    })
+    expect(t!.waitingOn).toBe("agent")
+    expect(t!.markers).toHaveLength(1)
+  })
+
+  it("parses identically when a long entry is wrapped with a 6-space continuation", () => {
+    const wrapped = CACHE.replace(
+      "    - H: why do we do that this way?",
+      "    - H: why do we do that\n      this way?",
+    )
+    expect(parseThreads(wrapped)[0]!.entries.map((e) => e.text)).toEqual(
+      parseThreads(CACHE)[0]!.entries.map((e) => e.text),
+    )
+  })
+
+  it("is open when the last entry is the agent's", () => {
+    const open = CACHE.replace("    - H: then do it this way\n", "")
+    expect(parseThreads(open)[0]!.waitingOn).toBe("human")
+  })
+
+  it("is not a thread for a plain paragraph body or an unprefixed first list item", () => {
+    expect(parseThreads("a.[^x]\n\n[^x]: just a note\n")).toEqual([])
+    expect(parseThreads("a.[^x]\n\n[^x]:\n    - item one\n    - H: hi\n")).toEqual([])
+  })
+
+  it("parses a definition whose list starts on the next line at 4 spaces' indent", () => {
+    expect(parseThreads("a.[^x]\n\n[^x]:\n    - H: hi\n")).toHaveLength(1)
+  })
+
+  it("a list opening with the retired `- Me:` prefix is a one-shot footnote, not a thread", () => {
+    expect(parseThreads("a.[^x]\n\n[^x]:\n    - Me: hi\n")).toEqual([])
+  })
+
+  it("costs one parseMarkdown parse for two calls on the same document", () => {
+    const doc = `${CACHE}\nunique ${Math.random()}\n`
+    const before = getParseCount()
+    parseThreads(doc)
+    parseThreads(doc)
+    expect(getParseCount() - before).toBe(1)
+  })
+})
+
+describe("thread syntax findings", () => {
+  const wrap = (body: string) => `a.[^x]\n\n[^x]:\n${body}\n`
+  const cases: [string, string, RegExp][] = [
+    ["unprefixed item", "    - H: hi\n    - A: yo\n    - stray", /must start with/],
+    ["agent starts", "    - A: hi\n    - H: yo", /never starts/],
+    ["same author twice", "    - H: hi\n    - H: again", /consecutive/],
+    ["empty entry", "    - H:", /write your own words/],
+    ["stray paragraph", "    - H: hi\n\n    stray paragraph", /only one list/],
+  ]
+  for (const [name, body, re] of cases) {
+    for (const [fmtName, fmt] of [
+      ["qa", qaDescriptor],
+      ["review", reviewDescriptor],
+      ["freeform", freeFormFormat],
+    ] as const) {
+      it(`${fmtName}: ${name} is a finding`, () => {
+        const messages = fmt.validate(wrap(body)).map((f) => f.message)
+        expect(messages.some((m) => re.test(m))).toBe(true)
+        expect(parseFootnotes(wrap(body)).findings.some((f) => re.test(f.message))).toBe(true)
+      })
+    }
+  }
+
+  it("an open thread produces no finding", () => {
+    const body = "    - H: hi\n    - A: yo"
+    expect(parseFootnotes(wrap(body)).findings).toEqual([])
+    expect(freeFormFormat.validate(wrap(body))).toEqual([])
+  })
+
+  it("openThreads lists open threads in every format", () => {
+    const doc = wrap("    - H: hi\n    - A: yo")
+    for (const fmt of [qaDescriptor, reviewDescriptor, freeFormFormat]) {
+      expect(fmt.openThreads!(doc)).toEqual([{ name: "x", line: 2, firstMe: "hi" }])
+    }
+  })
+})
+
+const QA = steeringFormatFor("qa")!
+
+const QA_DOC = (agentLast: boolean): string =>
+  [
+    "## Open Questions",
+    "",
+    "### Which one?",
+    "",
+    "- [ ] A [^t1]",
+    "- [ ] B",
+    "",
+    "[^t1]:",
+    "    - H: why A?",
+    ...(agentLast ? ["    - A: because", "      wrapped on two lines"] : []),
+    "",
+    "[^once]: one-shot note",
+    "",
+  ].join("\n")
+
+const cursor = (line: number, character = 0) => ({
+  start: { line, character },
+  end: { line, character },
+})
+
+describe("open-thread findings", () => {
+  it("one finding on the last entry's full span", () => {
+    const f = openThreadFindings(QA_DOC(true))
+    expect(f).toHaveLength(1)
+    expect(f[0]!.range).toEqual({
+      start: { line: 9, character: 0 },
+      end: { line: 10, character: 26 },
+    })
+  })
+  it("none while waiting on the agent", () => {
+    expect(openThreadFindings(QA_DOC(false))).toEqual([])
+  })
+})
+
+describe("threadReplyActions", () => {
+  it("offered on the marker and anywhere in the definition", () => {
+    const doc = QA_DOC(true)
+    for (const [line, ch] of [
+      [4, 12],
+      [7, 0],
+      [9, 5],
+      [10, 3],
+    ] as const) {
+      expect(threadReplyActions(doc, { line, character: ch }).map((a) => a.title)).toEqual([
+        "gtd: reply",
+      ])
+    }
+  })
+
+  it("not offered while waiting on the agent, nor on a one-shot footnote", () => {
+    expect(threadReplyActions(QA_DOC(false), { line: 7, character: 0 })).toEqual([])
+    expect(threadReplyActions(QA_DOC(true), { line: 12, character: 0 })).toEqual([])
+  })
+
+  it("inserts after a wrapped last entry at the list indent", () => {
+    const [a] = threadReplyActions(QA_DOC(true), { line: 7, character: 0 })
+    expect(a!.edits).toEqual([
+      {
+        range: { start: { line: 10, character: 26 }, end: { line: 10, character: 26 } },
+        newText: "\n    - H: ",
+      },
+    ])
+  })
+
+  it("preserves CRLF", () => {
+    const doc = QA_DOC(true).replace(/\n/g, "\r\n")
+    const [a] = threadReplyActions(doc, { line: 7, character: 0 })
+    expect(a!.edits[0]!.newText).toBe("\r\n    - H: ")
+    expect(a!.edits[0]!.range.start).toEqual({ line: 10, character: 26 })
+  })
+
+  it("qa/review actions keep add-a-footnote away from threads", () => {
+    const titles = QA.actions(QA_DOC(true), cursor(7)).map((a) => a.title)
+    expect(titles).toContain("gtd: reply")
+    expect(titles).not.toContain("gtd: add a footnote")
+  })
+})
+
+describe("footnoteAttachEdits — threads", () => {
+  const anchor = { line: 0, endCharacter: 7, blockEndLine: 0, key: "chunk:a" }
+  const id = (() => {
+    const r = footnoteAttachEdits("Chunk A", anchor, "x")
+    if (!r.ok) throw new Error("setup")
+    return r.id
+  })()
+
+  it("no footnote → a single-entry `- H:` thread", () => {
+    const content = "Chunk A\n\nnext"
+    const result = footnoteAttachEdits(content, anchor, "do it")
+    expect(result.ok).toBe(true)
+    if (!result.ok) return
+    expect(applyEdits(content, result.edits)).toBe(
+      `Chunk A[^${id}]\n\n[^${id}]:\n    - H: do it\n\nnext`,
+    )
+  })
+
+  it("no footnote, CRLF → the thread uses the document's own EOL", () => {
+    const content = "Chunk A\r\n\r\nnext"
+    const result = footnoteAttachEdits(content, anchor, "do it")
+    expect(result.ok).toBe(true)
+    if (!result.ok) return
+    const applied = applyEdits(content, result.edits)
+    expect(applied).toContain(`[^${id}]:\r\n    - H: do it\r\n`)
+    expect(applied.replace(/\r\n/g, "")).not.toMatch(/[\r\n]/)
+  })
+
+  it("an open thread → appends a `- H:` entry", () => {
+    const content = `Chunk A[^${id}]\n\n[^${id}]:\n    - H: first\n    - A: question?\n`
+    const result = footnoteAttachEdits(content, anchor, "answer")
+    expect(result.ok).toBe(true)
+    if (!result.ok) return
+    const applied = applyEdits(content, result.edits)
+    expect(applied).toBe(
+      `Chunk A[^${id}]\n\n[^${id}]:\n    - H: first\n    - A: question?\n    - H: answer\n`,
+    )
+    const thread = parseThreads(applied)[0]!
+    expect(thread.waitingOn).toBe("agent")
+    expect(thread.entries.map((e) => e.text)).toEqual(["first", "question?", "answer"])
+  })
+
+  it("a thread waiting on the agent → replaces its last `- H:` entry", () => {
+    const content = `Chunk A[^${id}]\n\n[^${id}]:\n    - H: first\n    - A: q?\n    - H: old\n`
+    const result = footnoteAttachEdits(content, anchor, "new")
+    expect(result.ok).toBe(true)
+    if (!result.ok) return
+    expect(applyEdits(content, result.edits)).toBe(
+      `Chunk A[^${id}]\n\n[^${id}]:\n    - H: first\n    - A: q?\n    - H: new\n`,
+    )
+  })
+
+  it("a one-shot footnote → replaces its body", () => {
+    const content = `Chunk A[^${id}]\n\n[^${id}]: old\n`
+    const result = footnoteAttachEdits(content, anchor, "new")
+    expect(result.ok).toBe(true)
+    if (!result.ok) return
+    expect(applyEdits(content, result.edits)).toBe(`Chunk A[^${id}]\n\n[^${id}]: new\n`)
+  })
+
+  it("multi-line text keeps continuation lines inside the entry", () => {
+    const content = "Chunk A"
+    const result = footnoteAttachEdits(content, anchor, "a\nb")
+    expect(result.ok).toBe(true)
+    if (!result.ok) return
+    const thread = parseThreads(applyEdits(content, result.edits))[0]!
+    expect(thread.entries).toHaveLength(1)
+    expect(thread.entries[0]!.text).toBe("a b")
+  })
+
+  it("a taken id with no marker at the anchor still refuses", () => {
+    const content = `x\n\nelse[^${id}]\n\n[^${id}]:\n    - H: a\n`
+    expect(footnoteAttachEdits(content, anchor, "n")).toEqual({
+      ok: false,
+      reason: "id-collision",
+    })
+  })
+})