@pmelab/gtd 24.0.0 → 24.1.0

package/src/steering/Inline.test.ts

@@ -0,0 +1,227 @@
+import { describe, expect, it } from "vitest"
+import type { Paragraph } from "mdast"
+import { parseMarkdown } from "./Inline.fixture.js"
+import { collapseImages, definitionsOf, joinInlineRuns, projectInline } from "./Inline.js"
+
+const paragraphOf = (content: string): Paragraph => {
+  const tree = parseMarkdown(content)
+  return tree.children[0] as Paragraph
+}
+
+describe("projectInline", () => {
+  it("projects strong, emphasis, delete, code, link and image", () => {
+    const paragraph = paragraphOf(
+      "**bold** _em_ ~~gone~~ `code` [label](https://x.example/a) ![alt](https://x.example/b.png)\n",
+    )
+    expect(projectInline(paragraph.children)).toEqual([
+      { kind: "strong", children: [{ kind: "text", value: "bold" }] },
+      { kind: "text", value: " " },
+      { kind: "emphasis", children: [{ kind: "text", value: "em" }] },
+      { kind: "text", value: " " },
+      { kind: "delete", children: [{ kind: "text", value: "gone" }] },
+      { kind: "text", value: " " },
+      { kind: "code", value: "code" },
+      { kind: "text", value: " " },
+      {
+        kind: "link",
+        href: "https://x.example/a",
+        children: [{ kind: "text", value: "label" }],
+      },
+      { kind: "text", value: " " },
+      { kind: "image", src: "https://x.example/b.png", alt: "alt" },
+    ])
+  })
+
+  it("drops a footnote reference structurally", () => {
+    const paragraph = paragraphOf("See it[^note].\n\n[^note]: body\n")
+    const nodes = projectInline(paragraph.children)
+    expect(nodes).toEqual([
+      { kind: "text", value: "See it" },
+      { kind: "text", value: "." },
+    ])
+  })
+
+  it("projects a hard break as a single space", () => {
+    const paragraph = paragraphOf("one\\\ntwo\n")
+    expect(projectInline(paragraph.children)).toEqual([
+      { kind: "text", value: "one" },
+      { kind: "text", value: " " },
+      { kind: "text", value: "two" },
+    ])
+  })
+
+  it("pins 'markdown is never raw HTML': a real <script> tag projects as one text node holding the raw tag, and no inline kind can ever carry HTML", () => {
+    const paragraph = paragraphOf("before <script>window.__xss = true</script> after\n")
+    const nodes = projectInline(paragraph.children)
+    expect(nodes.every((n) => n.kind === "text")).toBe(true)
+    const joined = nodes.map((n) => ("value" in n ? n.value : "")).join("")
+    expect(joined).toBe("before <script>window.__xss = true</script> after")
+  })
+
+  it("projects inline HTML as inert text, never a carrying kind", () => {
+    const paragraph = paragraphOf("before <script>window.__xss = true</script> after\n")
+    const nodes = projectInline(paragraph.children)
+    expect(nodes.some((n) => n.kind !== "text")).toBe(false)
+    const joined = nodes.map((n) => ("value" in n ? n.value : "")).join("")
+    expect(joined).toContain("<script>window.__xss = true</script>")
+  })
+
+  it("rejects a javascript: link href, keeping the label's own styled children", () => {
+    const paragraph = paragraphOf("[click](javascript:alert(1))\n")
+    expect(projectInline(paragraph.children)).toEqual([{ kind: "text", value: "click" }])
+  })
+
+  it("rejects an entity-decoded javascript: link href too — mdast decodes link.url before this ever sees it", () => {
+    const paragraph = paragraphOf("[click](&#106;avascript:alert(1))\n")
+    const nodes = projectInline(paragraph.children)
+    expect(nodes.some((n) => n.kind === "link")).toBe(false)
+  })
+
+  it("degrades a rejected image to a text node carrying its alt", () => {
+    const paragraph = paragraphOf("![alt text](javascript:alert(1))\n")
+    expect(projectInline(paragraph.children)).toEqual([{ kind: "text", value: "alt text" }])
+  })
+
+  it("allows a scheme-less (relative) href/src, and mailto:", () => {
+    const paragraph = paragraphOf("[a](./src/x.ts#42) [b](mailto:x@example.com)\n")
+    const nodes = projectInline(paragraph.children)
+    expect(nodes.filter((n) => n.kind === "link")).toHaveLength(2)
+  })
+
+  // Spec feedback: the WHATWG URL parser strips every ASCII tab/CR/LF from
+  // the WHOLE input before it ever looks for a scheme, so a `javascript:`
+  // href broken up by one of those characters still executes on tap even
+  // though the raw string doesn't match `SCHEME_RE` at all.
+  it("rejects a javascript: href broken by an entity-decoded tab", () => {
+    const paragraph = paragraphOf("[a](java&#9;script:alert(1))\n")
+    expect(projectInline(paragraph.children).some((n) => n.kind === "link")).toBe(false)
+  })
+
+  it("rejects a javascript: href broken by a LEADING entity-decoded tab", () => {
+    const paragraph = paragraphOf("[a](&#9;javascript:alert(1))\n")
+    expect(projectInline(paragraph.children).some((n) => n.kind === "link")).toBe(false)
+  })
+
+  it("rejects a javascript: href broken by an entity-decoded newline", () => {
+    const paragraph = paragraphOf("[a](java&NewLine;script:alert(1))\n")
+    expect(projectInline(paragraph.children).some((n) => n.kind === "link")).toBe(false)
+  })
+
+  // Spec feedback: the WHATWG URL parser ALSO trims every leading (and
+  // trailing) C0 control or space off the whole input before it looks for a
+  // scheme — a second pass beyond the tab/CR/LF removal above. Missing it
+  // leaves a `javascript:` reachable via a leading space, a leading C0
+  // control other than tab/CR/LF, or an angle-bracket destination's own
+  // literal leading spaces.
+  it("rejects a javascript: href prefixed by an entity-decoded leading space", () => {
+    const paragraph = paragraphOf("[click](&#32;javascript:alert&#40;1&#41;)\n")
+    expect(projectInline(paragraph.children).some((n) => n.kind === "link")).toBe(false)
+  })
+
+  it("rejects a javascript: href prefixed by a literal C0 control (U+0001) inside an angle-bracket destination", () => {
+    // `&#1;` itself decodes to U+FFFD (the replacement character) in this
+    // parser, never surviving as literal U+0001 — a real C0 control reaches
+    // `link.url` intact only through an angle-bracket destination, which
+    // tolerates raw control bytes an entity reference here does not.
+    const paragraph = paragraphOf(`[click](<${String.fromCharCode(1)}javascript:alert(1)>)\n`)
+    expect(projectInline(paragraph.children).some((n) => n.kind === "link")).toBe(false)
+  })
+
+  it("rejects a javascript: href prefixed by an entity-decoded form feed (U+000C)", () => {
+    const paragraph = paragraphOf("[click](&#12;javascript:alert&#40;1&#41;)\n")
+    expect(projectInline(paragraph.children).some((n) => n.kind === "link")).toBe(false)
+  })
+
+  it("rejects a javascript: href prefixed by literal leading spaces inside an angle-bracket destination", () => {
+    const paragraph = paragraphOf("[click](<  javascript:alert(1)>)\n")
+    expect(projectInline(paragraph.children).some((n) => n.kind === "link")).toBe(false)
+  })
+
+  it("the same leading-space/C0 hole is closed on image src too — one allowlist, both attributes", () => {
+    const paragraph = paragraphOf("![alt](&#32;javascript:alert&#40;1&#41;)\n")
+    expect(projectInline(paragraph.children)).toEqual([{ kind: "text", value: "alt" }])
+  })
+
+  // Spec feedback: R1 scopes in links/images with no reference-style
+  // exclusion, and a rejected/unresolved reference must degrade (keep its
+  // own label/alt) exactly like a rejected inline link/image — never vanish.
+  it("resolves a linkReference through its own definition, exactly like a bare link", () => {
+    const content = "See [the docs][1] here.\n\n[1]: https://example.com\n"
+    const paragraph = paragraphOf(content)
+    const nodes = projectInline(paragraph.children, definitionsOf(content))
+    expect(nodes).toContainEqual({
+      kind: "link",
+      href: "https://example.com",
+      children: [{ kind: "text", value: "the docs" }],
+    })
+  })
+
+  it("degrades an UNRESOLVED linkReference (a real node whose identifier the given definitions map doesn't carry) to its own label text, never dropping it", () => {
+    const content = "See [the docs][1] here.\n\n[1]: https://example.com\n"
+    const paragraph = paragraphOf(content)
+    // No `definitions` argument at all — the default empty map, mirroring a
+    // caller that forgot to thread `definitionsOf` through.
+    const nodes = projectInline(paragraph.children)
+    const joined = nodes.map((n) => ("value" in n ? n.value : "")).join("")
+    expect(joined).toBe("See the docs here.")
+  })
+
+  it("resolves an imageReference through its own definition, exactly like a bare image", () => {
+    const content = "An ![pic][2] there.\n\n[2]: https://example.com/p.png\n"
+    const paragraph = paragraphOf(content)
+    const nodes = projectInline(paragraph.children, definitionsOf(content))
+    expect(nodes).toContainEqual({ kind: "image", src: "https://example.com/p.png", alt: "pic" })
+  })
+
+  it("degrades an UNRESOLVED imageReference (a real node whose identifier the given definitions map doesn't carry) to its own alt text, never dropping it", () => {
+    const content = "An ![pic][2] there.\n\n[2]: https://example.com/p.png\n"
+    const paragraph = paragraphOf(content)
+    const nodes = projectInline(paragraph.children)
+    const joined = nodes.map((n) => ("value" in n ? n.value : "")).join("")
+    expect(joined).toBe("An pic there.")
+  })
+
+  it("rejects a linkReference resolving to a javascript: url, degrading to its own label", () => {
+    const content = "See [click][x] here.\n\n[x]: javascript:alert(1)\n"
+    const paragraph = paragraphOf(content)
+    const nodes = projectInline(paragraph.children, definitionsOf(content))
+    expect(nodes.some((n) => n.kind === "link")).toBe(false)
+    expect(nodes.map((n) => ("value" in n ? n.value : "")).join("")).toBe("See click here.")
+  })
+
+  // Spec feedback: `stripMarkerText` (the string-flattening path's own
+  // regex) strips EVERY `[^name]`-shaped run, defined or not — a dangling
+  // marker with no matching definition never becomes a real
+  // `footnoteReference` node, so it must be stripped here too, or it leaks
+  // into `inline`/`detailInline` for the first time.
+  it("strips a DANGLING [^name] marker (no matching definition) from plain text, matching stripMarkerText's outcome", () => {
+    const paragraph = paragraphOf("Dangling marker[^n1] here.\n")
+    expect(projectInline(paragraph.children)).toEqual([
+      { kind: "text", value: "Dangling marker here." },
+    ])
+  })
+})
+
+describe("collapseImages", () => {
+  it("replaces an image, at any depth, with a text node carrying its alt", () => {
+    const nested = [
+      { kind: "strong" as const, children: [{ kind: "image" as const, src: "x", alt: "pic" }] },
+    ]
+    expect(collapseImages(nested)).toEqual([
+      { kind: "strong", children: [{ kind: "text", value: "pic" }] },
+    ])
+  })
+})
+
+describe("joinInlineRuns", () => {
+  it("joins non-empty runs with a single space text separator, dropping empty runs", () => {
+    const a = [{ kind: "text" as const, value: "a" }]
+    const b: readonly (typeof a)[number][] = []
+    const c = [{ kind: "text" as const, value: "c" }]
+    expect(joinInlineRuns([a, b, c])).toEqual([
+      { kind: "text", value: "a" },
+      { kind: "text", value: " " },
+      { kind: "text", value: "c" },
+    ])
+  })
+})

package/src/steering/Inline.ts

@@ -0,0 +1,195 @@
+import type { Definition, Node, PhrasingContent } from "mdast"
+import { parseMarkdown } from "./MarkdownTree.js"
+
+/**
+ * The server-side projection of a run of mdast inline (phrasing) content —
+ * the shape the client's shared renderer (`src/web/screens/InlineRun.tsx`)
+ * walks instead of a string. Deliberately closed to these seven kinds: a
+ * `footnoteReference` is dropped (see `projectInline`), a hard `break`
+ * collapses to a single space `text` node, and an inline `html` node
+ * projects as `text` carrying its raw source verbatim — no kind here can
+ * ever carry raw HTML, which is what pins "markdown is never raw HTML" at
+ * the type level as well as by test.
+ */
+export type InlineNode =
+  | { readonly kind: "text"; readonly value: string }
+  | { readonly kind: "strong"; readonly children: readonly InlineNode[] }
+  | { readonly kind: "emphasis"; readonly children: readonly InlineNode[] }
+  | { readonly kind: "delete"; readonly children: readonly InlineNode[] }
+  | { readonly kind: "code"; readonly value: string }
+  | { readonly kind: "link"; readonly href: string; readonly children: readonly InlineNode[] }
+  | { readonly kind: "image"; readonly src: string; readonly alt: string }
+
+/**
+ * A `link`'s `href`/an `image`'s `src` passes only when it carries NO scheme
+ * at all (relative, `./src/x.ts#42`, a bare fragment) or a scheme matching
+ * `https?`/`mailto` case-insensitively — one allowlist for both attributes,
+ * no per-attribute branch. `url` here is already entity-decoded by mdast
+ * (`link.url`/`image.url`), which is exactly what makes this check catch
+ * `javascript:` too — a client-side regex over raw source never sees
+ * the decoded form at all.
+ */
+const SCHEME_RE = /^([a-zA-Z][a-zA-Z0-9+.-]*):/
+const ALLOWED_SCHEME_RE = /^(https?|mailto)$/i
+
+/**
+ * Mirrors the two whitespace-removal passes the WHATWG URL parser — what a
+ * real `<a href>`/`<img src>` actually runs through — applies to the WHOLE
+ * input before it ever looks for a scheme: every ASCII tab/LF/CR is removed
+ * from anywhere in the string, and every LEADING (and trailing) C0 control
+ * (`U+0000`–`U+001F`) or space is trimmed off the ends. Skipping either pass
+ * leaves a `javascript:` reachable here: `java&#9;script:alert(1)` needs the
+ * first, a leading `&#32;`/`&#1;`/form-feed-prefixed `javascript:` (or an
+ * angle-bracket destination's own literal leading spaces) needs the second —
+ * both read as "no scheme, so allowed" here while the browser reads the
+ * stripped `javascript:alert(1)` and executes it.
+ */
+const stripUrlWhitespace = (url: string): string =>
+  url
+    .replace(/[\t\n\r]/g, "")
+    // eslint-disable-next-line no-control-regex -- the C0 control range IS the point: mirrors the WHATWG URL parser's own leading/trailing trim.
+    .replace(/^[\x00-\x1f ]+|[\x00-\x1f ]+$/g, "")
+
+const isAllowedUrl = (url: string): boolean => {
+  const match = SCHEME_RE.exec(stripUrlWhitespace(url))
+  return match === undefined || match === null || ALLOWED_SCHEME_RE.test(match[1]!)
+}
+
+/**
+ * A marker's shape once it's plain text — `[^name]`, no whitespace, no `]` —
+ * mirrors `Blocks.ts`'s own `MARKER_TEXT_RE` exactly (duplicated, not
+ * imported: that one is private to the string-flattening path this module
+ * doesn't otherwise touch). GFM only turns `[^name]` into a real
+ * `footnoteReference` NODE when a matching definition exists; a dangling
+ * marker with no definition never becomes one, so it survives as plain
+ * `text` — this strips it there too, so `inline`/`detailInline` drop a
+ * dangling marker the same way `stripMarkerText` already drops it from
+ * `title`/`detail`, instead of leaking it into the UI for the first time.
+ */
+const MARKER_TEXT_RE = /\[\^([^\s\]]+)\]/g
+
+/**
+ * One `identifier` (mdast's own normalized form: markdown whitespace
+ * collapsed, trimmed, case-folded) → the `definition` node it resolves to —
+ * what a `linkReference`/`imageReference` needs to become a real `link`/
+ * `image` instead of silently losing its own visible label/alt. Walks the
+ * WHOLE tree, not just `tree.children`: a definition can sit anywhere
+ * CommonMark allows one, not only at the document's top level.
+ */
+const collectDefinitions = (node: Node, into: Map<string, Definition>): void => {
+  if (node.type === "definition") into.set((node as Definition).identifier, node as Definition)
+  const children = (node as { children?: readonly Node[] }).children
+  if (children) children.forEach((child) => collectDefinitions(child, into))
+}
+
+/** Every link/image reference definition in `content`, by normalized identifier — built off `parseMarkdown`'s own memoized tree, so calling this alongside another same-content call in the same pass never re-parses. */
+export const definitionsOf = (content: string): ReadonlyMap<string, Definition> => {
+  const map = new Map<string, Definition>()
+  collectDefinitions(parseMarkdown(content), map)
+  return map
+}
+
+type Definitions = ReadonlyMap<string, Definition>
+
+/** A resolved `link`/`linkReference` — real `href` (already allowlist-checked) plus its own label children — or `undefined` when there is none to resolve to (no url at all, or an unresolved reference). */
+const resolveLink = (
+  url: string | undefined,
+  labelChildren: readonly PhrasingContent[],
+  definitions: Definitions,
+): readonly InlineNode[] => {
+  const children = projectInline(labelChildren, definitions)
+  if (url !== undefined && isAllowedUrl(url)) return [{ kind: "link", href: url, children }]
+  return children
+}
+
+/** A resolved `image`/`imageReference` — real `src` (already allowlist-checked) plus `alt` — or a degrade to plain `alt` text when there is nothing to resolve to. */
+const resolveImage = (url: string | undefined, alt: string): readonly InlineNode[] =>
+  url !== undefined && isAllowedUrl(url)
+    ? [{ kind: "image", src: url, alt }]
+    : [{ kind: "text", value: alt }]
+
+/** One recursive `children: readonly InlineNode[]` wrap — `strong`/`emphasis`/`delete` share this exact shape. */
+const projectWrapped = (
+  kind: "strong" | "emphasis" | "delete",
+  children: readonly PhrasingContent[],
+  definitions: Definitions,
+): readonly InlineNode[] => [{ kind, children: projectInline(children, definitions) }]
+
+/**
+ * One `PhrasingContent["type"]` → the `InlineNode`s it projects to (0, 1, or
+ * — for a rejected/unresolved link — its own several label children) — a
+ * lookup table, not a `switch`, so `projectInline` itself stays a single
+ * dispatch with no per-case branch of its own (mirrors `ProseBlock.tsx`'s
+ * own `BLOCK_RENDERERS`/`InlineRun.tsx`'s own `INLINE_RENDERERS`). A kind
+ * with no entry (there is none left; every `PhrasingContent` member is
+ * covered) projects to nothing.
+ */
+const NODE_PROJECTORS: {
+  readonly [K in PhrasingContent["type"]]: (
+    child: Extract<PhrasingContent, { readonly type: K }>,
+    definitions: Definitions,
+  ) => readonly InlineNode[]
+} = {
+  text: (child) => [{ kind: "text", value: child.value.replace(MARKER_TEXT_RE, "") }],
+  strong: (child, definitions) => projectWrapped("strong", child.children, definitions),
+  emphasis: (child, definitions) => projectWrapped("emphasis", child.children, definitions),
+  delete: (child, definitions) => projectWrapped("delete", child.children, definitions),
+  inlineCode: (child) => [{ kind: "code", value: child.value }],
+  break: () => [{ kind: "text", value: " " }],
+  html: (child) => [{ kind: "text", value: child.value }],
+  footnoteReference: () => [],
+  link: (child, definitions) => resolveLink(child.url, child.children, definitions),
+  image: (child) => resolveImage(child.url, child.alt ?? ""),
+  linkReference: (child, definitions) =>
+    resolveLink(definitions.get(child.identifier)?.url, child.children, definitions),
+  imageReference: (child, definitions) =>
+    resolveImage(definitions.get(child.identifier)?.url, child.alt ?? ""),
+}
+
+/**
+ * Projects one run of mdast `PhrasingContent` (a paragraph's/heading's own
+ * `children`, or any other phrasing-content array) into `InlineNode`s.
+ * `footnoteReference` is dropped outright — gtd's own review-note protocol,
+ * never document content — and a rejected `link`/`image` degrades rather
+ * than disappearing: a rejected link keeps its own (still-styled) label
+ * children, a rejected image keeps only its alt text. An inline `html` node
+ * (a real tag typed into prose) becomes a `text` node carrying its raw
+ * source verbatim — never parsed, never a carrier for markup in the model.
+ *
+ * `definitions` (`definitionsOf`) resolves a `linkReference`/`imageReference`
+ * (`[label][id]`/`![alt][id]`) to its own `link`/`image` the same way a
+ * bare `[label](url)` resolves — an UNRESOLVED reference (no matching
+ * definition, or the caller passed none) degrades exactly like a
+ * scheme-rejected one: the label's own children for a link, bare alt text
+ * for an image — never silently dropped.
+ */
+export const projectInline = (
+  children: readonly PhrasingContent[],
+  definitions: Definitions = new Map(),
+): readonly InlineNode[] =>
+  children.flatMap((child) => {
+    const project = NODE_PROJECTORS[child.type] as (
+      child: PhrasingContent,
+      definitions: Definitions,
+    ) => readonly InlineNode[]
+    return project(child, definitions)
+  })
+
+/** `nodes`, recursively, with every `image` replaced by a `text` node carrying its alt — the compact-row rule (R2): an image collapses to alt text server-side so a compact row can never fire a remote fetch. */
+export const collapseImages = (nodes: readonly InlineNode[]): readonly InlineNode[] =>
+  nodes.map((node) => {
+    if (node.kind === "image") return { kind: "text" as const, value: node.alt }
+    if ("children" in node) return { ...node, children: collapseImages(node.children) }
+    return node
+  })
+
+/** Joins several already-projected inline runs with a single `text: " "` separator, dropping empty runs entirely — mirrors `Blocks.ts`'s own `.join(" ")` flattening, structurally rather than on strings. */
+export const joinInlineRuns = (runs: readonly (readonly InlineNode[])[]): readonly InlineNode[] => {
+  const nonEmpty = runs.filter((run) => run.length > 0)
+  const result: InlineNode[] = []
+  nonEmpty.forEach((run, index) => {
+    if (index > 0) result.push({ kind: "text", value: " " })
+    result.push(...run)
+  })
+  return result
+}

package/src/steering/MarkdownTree.test.ts

@@ -0,0 +1,247 @@
+import { describe, expect, it } from "vitest"
+import fc from "fast-check"
+import {
+  blockNodeAt,
+  getParseCount,
+  headingSectionBodies,
+  headingSections,
+  headingText,
+  parseMarkdown,
+  sourceText,
+  taskItems,
+  toLspPosition,
+  toLspPositionFromOffset,
+} from "./MarkdownTree.js"
+import { steeringFormatFor } from "./index.js"
+import type { Heading, List, ListItem, Paragraph } from "mdast"
+
+describe("parseMarkdown", () => {
+  it("calls both GFM extensions: a task checkbox parses to checked === true, not null", () => {
+    const tree = parseMarkdown("- [x] a\n")
+    const list = tree.children[0] as List
+    const item = list.children[0] as ListItem
+    expect(item.checked).toBe(true)
+  })
+
+  it("parses strikethrough and a bare-URL autolink into real nodes", () => {
+    const tree = parseMarkdown("~~gone~~ and https://example.com/x\n")
+    const paragraph = tree.children[0] as Paragraph
+    expect(paragraph.children.some((c) => c.type === "delete")).toBe(true)
+    expect(
+      paragraph.children.some((c) => c.type === "link" && c.url === "https://example.com/x"),
+    ).toBe(true)
+  })
+
+  it("wiring the two new extensions leaves every flattened string byte-identical — sourceText and headingText slice raw source, not the parsed tree", () => {
+    const content =
+      "# A ~~gone~~ heading https://example.com/x\n\nSome ~~gone~~ text https://example.com/x here.\n"
+    const tree = parseMarkdown(content)
+    const heading = tree.children[0] as Heading
+    const paragraph = tree.children[1]!
+    expect(headingText(content, heading)).toBe("A ~~gone~~ heading https://example.com/x")
+    expect(sourceText(content, paragraph)).toBe("Some ~~gone~~ text https://example.com/x here.")
+  })
+
+  it("never throws and always returns a root, for arbitrary strings", () => {
+    fc.assert(
+      fc.property(fc.string(), (content) => {
+        const tree = parseMarkdown(content)
+        expect(tree.type).toBe("root")
+      }),
+    )
+  })
+
+  it("converts a node starting at source line 1 column 1 to LSP line 0 character 0", () => {
+    const tree = parseMarkdown("hello\n")
+    const paragraph = tree.children[0]!
+    // Sanity: mdast itself is 1-based — if this ever isn't true, the real
+    // assertion below (going through `toLspPosition`) would trivially pass
+    // for the wrong reason.
+    expect(paragraph.position!.start).toEqual({ line: 1, column: 1, offset: 0 })
+    expect(toLspPosition(paragraph.position!.start)).toEqual({ line: 0, character: 0 })
+  })
+
+  describe("memo", () => {
+    it("returns the identical tree object for two calls with the same string, advancing the counter once", () => {
+      const content = `unique content ${Math.PI}`
+      const before = getParseCount()
+      const first = parseMarkdown(content)
+      const second = parseMarkdown(content)
+      expect(second).toBe(first)
+      expect(getParseCount()).toBe(before + 1)
+    })
+
+    it("evicts the previous entry for a different string, advancing the counter again", () => {
+      const a = `content a ${Math.PI}`
+      const b = `content b ${Math.PI}`
+      const treeA = parseMarkdown(a)
+      const before = getParseCount()
+      const treeB = parseMarkdown(b)
+      expect(treeB).not.toBe(treeA)
+      expect(getParseCount()).toBe(before + 1)
+    })
+
+    it("holds one entry, not two: re-parsing the evicted string reparses rather than serving a stale cache hit", () => {
+      const a = `content c ${Math.PI}`
+      const b = `content d ${Math.PI}`
+      const firstA = parseMarkdown(a)
+      parseMarkdown(b) // evicts `a`
+      const before = getParseCount()
+      const secondA = parseMarkdown(a)
+      expect(getParseCount()).toBe(before + 1) // reparsed, not a cache hit
+      expect(secondA).not.toBe(firstA) // a fresh tree object, not the old one
+    })
+
+    it("performs one parse for a 2000-line document, not one per line", () => {
+      const content = Array.from({ length: 2000 }, (_, i) => `line ${i}`).join("\n")
+      const before = getParseCount()
+      parseMarkdown(content)
+      expect(getParseCount()).toBe(before + 1)
+    })
+
+    it("performs exactly one parse across one qa validate() call — the structural pass and the footnote pass share it", () => {
+      const content = [
+        "Build a thing.",
+        ...Array.from({ length: 1990 }, (_, i) => `Line ${i} of padding prose.`),
+        "",
+        "## Open Questions",
+        "",
+        "### Which backend?",
+        "",
+        "- [x] SQLite",
+        "- [ ] Postgres",
+        "",
+      ].join("\n")
+      const before = getParseCount()
+      steeringFormatFor("qa")!.validate(content)
+      expect(getParseCount()).toBe(before + 1)
+    })
+  })
+})
+
+describe("toLspPositionFromOffset", () => {
+  it("is line 0 character 0 for offset 0", () => {
+    expect(toLspPositionFromOffset("abc\ndef", 0)).toEqual({ line: 0, character: 0 })
+  })
+
+  it("lands on the second line after a newline", () => {
+    const content = "abc\ndef"
+    expect(toLspPositionFromOffset(content, content.indexOf("def"))).toEqual({
+      line: 1,
+      character: 0,
+    })
+  })
+
+  it("counts characters within a later line correctly", () => {
+    const content = "abc\ndefgh"
+    expect(toLspPositionFromOffset(content, content.indexOf("gh"))).toEqual({
+      line: 1,
+      character: 3,
+    })
+  })
+})
+
+describe("sourceText", () => {
+  it("keeps inline code verbatim and drops only a real footnote reference", () => {
+    const content = "A claim `a[^fn1]b` and a real [^fn2] ref.\n\n[^fn2]: def\n"
+    const tree = parseMarkdown(content)
+    const paragraph = tree.children[0] as Paragraph
+    expect(sourceText(content, paragraph)).toBe("A claim `a[^fn1]b` and a real ref.")
+  })
+
+  it("collapses a multi-line paragraph's whitespace to single spaces", () => {
+    const content = "one\ntwo\nthree\n"
+    const tree = parseMarkdown(content)
+    expect(sourceText(content, tree.children[0]!)).toBe("one two three")
+  })
+
+  it("keeps a link and emphasis verbatim, alongside a dropped footnote reference", () => {
+    const content = "See [the docs](https://example.com) for *why*[^fn1].\n\n[^fn1]: def\n"
+    const tree = parseMarkdown(content)
+    const paragraph = tree.children[0] as Paragraph
+    expect(sourceText(content, paragraph)).toBe("See [the docs](https://example.com) for *why*.")
+  })
+})
+
+describe("blockNodeAt", () => {
+  it("finds the top-level block containing a 0-based line", () => {
+    const content = "# heading\n\nsome paragraph text\n"
+    const tree = parseMarkdown(content)
+    expect(blockNodeAt(tree, 0)?.type).toBe("heading")
+    expect(blockNodeAt(tree, 2)?.type).toBe("paragraph")
+  })
+
+  it("is undefined past the end of the document", () => {
+    const tree = parseMarkdown("one line\n")
+    expect(blockNodeAt(tree, 50)).toBeUndefined()
+  })
+})
+
+describe("taskItems", () => {
+  it("returns both items for a nested two-space-indented task list item", () => {
+    const content = "- [x] a\n  - [x] b\n"
+    const tree = parseMarkdown(content)
+    const items = taskItems(tree)
+    expect(items).toHaveLength(2)
+    expect(items.every((i) => i.checked === true)).toBe(true)
+  })
+
+  it("excludes ordinary (non-task) list items", () => {
+    const content = "- a\n- [x] b\n"
+    const tree = parseMarkdown(content)
+    expect(taskItems(tree)).toHaveLength(1)
+  })
+})
+
+describe("headingSections", () => {
+  it("returns every top-level `## ` heading's text, in document order", () => {
+    const content = "# Title\n\n## First\n\nbody\n\n## Second\n\nmore body\n"
+    expect(headingSections(content)).toEqual(["First", "Second"])
+  })
+
+  it("excludes a `# ` (depth 1) and a `### ` (depth 3) heading — depth 2 only, by default", () => {
+    const content = "# Top\n\n## Section\n\n### Nested\n"
+    expect(headingSections(content)).toEqual(["Section"])
+  })
+
+  it("is empty for a package file with no `## ` sections — the fail-open case a dynamic-count judge template must detect", () => {
+    expect(headingSections("# Title\n\njust prose, no sections\n")).toEqual([])
+  })
+
+  it("takes an explicit depth", () => {
+    const content = "## Two\n\n### Three\n"
+    expect(headingSections(content, 3)).toEqual(["Three"])
+  })
+})
+
+describe("headingSectionBodies", () => {
+  it("finds headings the way the parser does — doubled spaces, a closing run, indentation", () => {
+    const content =
+      "##  Spaced  Title\nspaced body\n\n## Closed ##\nclosed body\n\n   ## Indented\nindented body\n"
+    expect(headingSectionBodies(content)).toEqual([
+      { title: "Spaced Title", body: "##  Spaced  Title\nspaced body" },
+      { title: "Closed", body: "## Closed ##\nclosed body" },
+      { title: "Indented", body: "   ## Indented\nindented body" },
+    ])
+  })
+
+  it("never ends a section at a plain line that happens to equal a title", () => {
+    const content = "## Plan\nPlan\nstill the plan\n\n## Next\nnext body\n"
+    expect(headingSectionBodies(content)[0]!.body).toBe("## Plan\nPlan\nstill the plan")
+  })
+
+  it("keeps two same-titled sections apart", () => {
+    const content = "## Note\nfirst\n\n## Note\nsecond\n"
+    expect(headingSectionBodies(content).map((s) => s.body)).toEqual([
+      "## Note\nfirst",
+      "## Note\nsecond",
+    ])
+  })
+
+  it("ends a section at a higher-level heading, and ignores a heading inside a code fence", () => {
+    const content = "## One\n```\n## not a heading\n```\n# Top\ntop body\n"
+    expect(headingSectionBodies(content)).toEqual([
+      { title: "One", body: "## One\n```\n## not a heading\n```" },
+    ])
+  })
+})