AGENTS.md

@@ -313,6 +313,12 @@ someone spells it or pins it.
   scan may keep what it read for a later walk of the same text, and the fallback where it kept
   nothing must be the same reader over the same text at the same index, so the two cannot disagree
   — which is what makes the kept value a memo rather than a second spelling (4c).
+- The parse keeps each node's readable spelling in a memo, so the `commonMarkSpelling` ask spells a
+  node once rather than once per level above it (18). The node reference is the key, which holds
+  because the parse builds one object per position; `adfToMarkdown` passes no memo, where a
+  consumer's document may hold one node at two positions (4b). A kept spelling rebases: `text` and
+  `spelling` carry no depth, `headroom` is affine in it, and a reuse sits at or above the depth that
+  filled it. Only what succeeded is kept, so no path minted at another position is ever read.
 - No casts: `as`, `as unknown as`, non-null `!`. A boundary owes a type guard validating the
   fields it claims (`isAdfDocument`); past it everything is typed. Make invalid states
   unrepresentable.

src/markdown/emit/adf-to-markdown.ts

@@ -19,7 +19,9 @@ import { tryPipeTable } from './pipe-table.ts'
 type BlockContainer = 'directive' | 'document' | 'list-item'
 type BlockSpelling = 'commonmark' | 'directive' | 'list'
 type EmittedBlock = { headroom: number; spelling: BlockSpelling; text: string }
+type KeptSpelling = { block: EmittedBlock | undefined; depth: number }
 type PlacedBlock = EmittedBlock & { node: AdfNode }
+export type SpellingMemo = Map<AdfNode, KeptSpelling>
 type Walk = { blocks: readonly PlacedBlock[]; headroom: number }
 type WalkedItem = { node: AdfNode; walk: Walk }
 
@@ -31,19 +33,19 @@ export function adfToMarkdown(document: AdfDocument): Result<string> {
   const fault = adfDocumentFault(document)
   if (fault !== undefined) return faulted(fault, [])
   if (document.version !== 1) return failure('unsupported-document-version', `no markdown spelling carries ADF version ${document.version}`, [])
-  const walk = walkBlocks(nodeContent(document), [], 0)
+  const walk = walkBlocks(nodeContent(document), [], 0, undefined)
   if (!walk.ok) return walk
   const text = joinBlocks(walk.value.blocks, 'document')
   return success(text === '' ? '' : `${text}\n`)
 }
 
 // headroom: the least slack any depth guard below the walk has.
-function walkBlocks(nodes: readonly AdfNode[], path: ConvertErrorPath, depth: number): Result<Walk> {
+function walkBlocks(nodes: readonly AdfNode[], path: ConvertErrorPath, depth: number, memo: SpellingMemo | undefined): Result<Walk> {
   let headroom = largestNesting - depth
   if (headroom < 0) return tooDeep(path)
   const blocks: PlacedBlock[] = []
   for (const [index, node] of nodes.entries()) {
-    const block = emitBlock(node, [...path, 'content', index], depth)
+    const block = emitBlock(node, [...path, 'content', index], depth, memo)
     if (!block.ok) return block
     headroom = Math.min(headroom, block.value.headroom)
     blocks.push({ ...block.value, node })
@@ -84,24 +86,34 @@ function interruptsParagraph(node: AdfNode): boolean {
   return markerInterruptsParagraph(listStart(node, items.length) ?? 0, empty)
 }
 
-function emitBlock(node: AdfNode, path: ConvertErrorPath, depth: number): Result<EmittedBlock> {
+function emitBlock(node: AdfNode, path: ConvertErrorPath, depth: number, memo: SpellingMemo | undefined): Result<EmittedBlock> {
   const directive = blockDirective(node.type)
   if (directive === undefined) return commonMarkLine(carriedBlock(node, path, depth))
-  const readable = readableBlock(node, path, depth)
+  const readable = readableBlock(node, path, depth, memo)
   if (readable !== undefined) return readable
-  return emitDirectiveBlock(node, directive, path, depth, () => walkBlocks(nodeContent(node), path, depth + 1))
+  return emitDirectiveBlock(node, directive, path, depth, () => walkBlocks(nodeContent(node), path, depth + 1, memo))
 }
 
-export function commonMarkSpelling(node: AdfNode, path: ConvertErrorPath, depth: number): Result<null> | undefined {
-  const readable = readableBlock(node, path, depth)
+export function commonMarkSpelling(node: AdfNode, path: ConvertErrorPath, depth: number, memo: SpellingMemo): Result<null> | undefined {
+  const readable = readableBlock(node, path, depth, memo)
   if (readable === undefined) return undefined
   if (!readable.ok) return readable
   return readable.value.spelling === 'directive' ? undefined : success(null)
 }
 
-function readableBlock(node: AdfNode, path: ConvertErrorPath, depth: number): Result<EmittedBlock> | undefined {
-  if (node.type === 'blockquote') return emitBlockquote(node, path, depth)
-  if (node.type === 'bulletList' || node.type === 'orderedList') return emitList(node, path, depth)
+function readableBlock(node: AdfNode, path: ConvertErrorPath, depth: number, memo: SpellingMemo | undefined): Result<EmittedBlock> | undefined {
+  const kept = memo?.get(node)
+  // A reuse sits no deeper than the fill it reads, so the kept headroom only ever grows (AGENTS.md §11).
+  if (kept !== undefined) return kept.block === undefined ? undefined : success({ ...kept.block, headroom: kept.block.headroom + kept.depth - depth })
+  const spelled = spellReadableBlock(node, path, depth, memo)
+  if (spelled === undefined) memo?.set(node, { block: undefined, depth })
+  else if (spelled.ok) memo?.set(node, { block: spelled.value, depth })
+  return spelled
+}
+
+function spellReadableBlock(node: AdfNode, path: ConvertErrorPath, depth: number, memo: SpellingMemo | undefined): Result<EmittedBlock> | undefined {
+  if (node.type === 'blockquote') return emitBlockquote(node, path, depth, memo)
+  if (node.type === 'bulletList' || node.type === 'orderedList') return emitList(node, path, depth, memo)
   if (node.type === 'codeBlock') return emitCodeBlock(node, path)
   if (node.type === 'heading') return emitHeading(node, path)
   if (node.type === 'mediaSingle') return readableText(tryImage(node, path))
@@ -149,9 +161,9 @@ function emitDirectiveBody(node: AdfNode, directive: BlockDirective, opener: str
   return success(directivePair(node, opener, joinBlocks(walk.value.blocks, 'directive'), walk.value.headroom))
 }
 
-function emitBlockquote(node: AdfNode, path: ConvertErrorPath, depth: number): Result<EmittedBlock> | undefined {
+function emitBlockquote(node: AdfNode, path: ConvertErrorPath, depth: number, memo: SpellingMemo | undefined): Result<EmittedBlock> | undefined {
   if (!carriesOnly(node, [])) return undefined
-  const inner = walkBlocks(nodeContent(node), path, depth + 1)
+  const inner = walkBlocks(nodeContent(node), path, depth + 1, memo)
   if (!inner.ok) return inner
   const text = joinBlocks(inner.value.blocks, 'document')
     .split('\n')
@@ -211,7 +223,7 @@ function emitHeading(node: AdfNode, path: ConvertErrorPath): Result<EmittedBlock
   return success(commonMarkText(`${hashes} ${line.value}`))
 }
 
-function emitList(node: AdfNode, path: ConvertErrorPath, depth: number): Result<EmittedBlock> | undefined {
+function emitList(node: AdfNode, path: ConvertErrorPath, depth: number, memo: SpellingMemo | undefined): Result<EmittedBlock> | undefined {
   const ordered = node.type === 'orderedList'
   if (!carriesOnly(node, ordered ? ['order'] : [])) return undefined
   const items = nodeContent(node)
@@ -221,7 +233,7 @@ function emitList(node: AdfNode, path: ConvertErrorPath, depth: number): Result<
   const walked: WalkedItem[] = []
   let headroom = Number.POSITIVE_INFINITY
   for (const [offset, item] of items.entries()) {
-    const walk = walkBlocks(nodeContent(item), [...path, 'content', offset], depth + 1)
+    const walk = walkBlocks(nodeContent(item), [...path, 'content', offset], depth + 1, memo)
     if (!walk.ok) return walk
     headroom = Math.min(headroom, walk.value.headroom)
     walked.push({ node: item, walk: walk.value })

src/markdown/parse/markdown-to-adf.ts

@@ -5,7 +5,7 @@ import type { ConvertFault } from '../../result.ts'
 import type { LineContainer } from '../emit/line-escaping.ts'
 import type { LinkDefinitions } from './inline-content.ts'
 import { carryName, readCarriedBlock } from '../opaque-carry.ts'
-import { commonMarkSpelling } from '../emit/adf-to-markdown.ts'
+import { commonMarkSpelling, type SpellingMemo } from '../emit/adf-to-markdown.ts'
 import { failure, faulted, positioned, success, type ConvertErrorPath, type ParseError, type Result, type SourcePosition } from '../../result.ts'
 import { languageSlot } from '../code-language.ts'
 import { largestNesting } from '../../nesting.ts'
@@ -20,12 +20,12 @@ const documentStart: SourcePosition = { line: 1, offset: 0 }
 
 export function markdownToAdf(markdown: string): Result<AdfDocument, ParseError> {
   const parsed = parseBlocks(markdown)
-  const content = positioned(blockNodes(parsed.blocks, parsed.definitions, [], 0), documentStart)
+  const content = positioned(blockNodes(parsed.blocks, parsed.definitions, [], 0, new Map()), documentStart)
   if (!content.ok) return content
   return success(content.value.length === 0 ? { type: 'doc', version: 1 } : { content: content.value, type: 'doc', version: 1 })
 }
 
-function blockNodes(blocks: readonly Block[], definitions: LinkDefinitions, path: ConvertErrorPath, depth: number): Result<AdfNode[]> {
+function blockNodes(blocks: readonly Block[], definitions: LinkDefinitions, path: ConvertErrorPath, depth: number, memo: SpellingMemo): Result<AdfNode[]> {
   if (depth > largestNesting) return failure('unsupported-nesting-depth', `the input nests deeper than the ${largestNesting} levels the parser carries`, path)
   const content: AdfNode[] = []
   for (const [index, block] of blocks.entries()) {
@@ -35,7 +35,7 @@ function blockNodes(blocks: readonly Block[], definitions: LinkDefinitions, path
       if (fault !== undefined) return positioned(faulted(fault, nodePath), block.position)
       continue
     }
-    const node = positioned(blockNode(block, definitions, nodePath, depth), block.position)
+    const node = positioned(blockNode(block, definitions, nodePath, depth, memo), block.position)
     if (!node.ok) return node
     content.push(node.value)
   }
@@ -55,16 +55,16 @@ function partsFault(): ConvertFault {
   return unsupportedNodeShape(`${listBreakName} parts two adjacent lists of one type: this one parts something else`)
 }
 
-function blockNode(block: Block, definitions: LinkDefinitions, path: ConvertErrorPath, depth: number): Result<AdfNode> {
+function blockNode(block: Block, definitions: LinkDefinitions, path: ConvertErrorPath, depth: number, memo: SpellingMemo): Result<AdfNode> {
   switch (block.kind) {
     case 'blockquote':
-      return containerNode({ type: 'blockquote' }, block.blocks, definitions, path, depth)
+      return containerNode({ type: 'blockquote' }, block.blocks, definitions, path, depth, memo)
     case 'bulletList':
-      return listNode({ type: 'bulletList' }, block.items, definitions, path, depth)
+      return listNode({ type: 'bulletList' }, block.items, definitions, path, depth, memo)
     case 'code':
       return codeBlockNode(block.language, block.text, path, depth)
     case 'directive':
-      return directiveNode(block, definitions, path, depth)
+      return directiveNode(block, definitions, path, depth, memo)
     case 'fault':
       return faulted(block.fault, path)
     case 'heading':
@@ -72,7 +72,7 @@ function blockNode(block: Block, definitions: LinkDefinitions, path: ConvertErro
     case 'html':
       return failure('unmappable-html', `no raw HTML converts at this version: ${block.construct}`, path)
     case 'orderedList':
-      return listNode({ attrs: { order: block.start }, type: 'orderedList' }, block.items, definitions, path, depth)
+      return listNode({ attrs: { order: block.start }, type: 'orderedList' }, block.items, definitions, path, depth, memo)
     case 'paragraph':
       return paragraphNode(block.text, definitions, path)
     case 'rule':
@@ -82,23 +82,23 @@ function blockNode(block: Block, definitions: LinkDefinitions, path: ConvertErro
   }
 }
 
-function directiveNode(block: DirectiveBlock, definitions: LinkDefinitions, path: ConvertErrorPath, depth: number): Result<AdfNode> {
+function directiveNode(block: DirectiveBlock, definitions: LinkDefinitions, path: ConvertErrorPath, depth: number, memo: SpellingMemo): Result<AdfNode> {
   const read = readBlockDirectiveNode(block.name, block.argument, block.attributes, path)
   if (!read.ok) return read
-  const built = directiveBody(read.value, block.blocks, definitions, path, depth)
+  const built = directiveBody(read.value, block.blocks, definitions, path, depth, memo)
   if (!built.ok) return built
-  const readable = commonMarkSpelling(built.value, path, depth)
+  const readable = commonMarkSpelling(built.value, path, depth, memo)
   if (readable === undefined) return built
   if (!readable.ok) return readable
   return failure('unsupported-node-shape', `${built.value.type} takes the CommonMark spelling, not the directive form`, path)
 }
 
-function directiveBody(read: BlockDirectiveNode, blocks: Block[] | undefined, definitions: LinkDefinitions, path: ConvertErrorPath, depth: number): Result<AdfNode> {
+function directiveBody(read: BlockDirectiveNode, blocks: Block[] | undefined, definitions: LinkDefinitions, path: ConvertErrorPath, depth: number, memo: SpellingMemo): Result<AdfNode> {
   const { contentModel, node } = read
   if (blocks === undefined) return success(node)
   if (contentModel === 'code') return codeDirectiveNode(node, blocks, path)
   if (contentModel === 'inline') return inlineBodyNode(node, blocks, definitions, path)
-  return containerNode(node, blocks, definitions, path, depth)
+  return containerNode(node, blocks, definitions, path, depth, memo)
 }
 
 function codeDirectiveNode(node: AdfNode, blocks: readonly Block[], path: ConvertErrorPath): Result<AdfNode> {
@@ -137,8 +137,8 @@ function inlineBodyNode(node: AdfNode, blocks: readonly Block[], definitions: Li
   return positioned(contentNode(node, only.text, definitions, path, 'paragraph'), only.position)
 }
 
-function containerNode(node: AdfNode, blocks: readonly Block[], definitions: LinkDefinitions, path: ConvertErrorPath, depth: number): Result<AdfNode> {
-  const content = blockNodes(blocks, definitions, path, depth + 1)
+function containerNode(node: AdfNode, blocks: readonly Block[], definitions: LinkDefinitions, path: ConvertErrorPath, depth: number, memo: SpellingMemo): Result<AdfNode> {
+  const content = blockNodes(blocks, definitions, path, depth + 1, memo)
   if (!content.ok) return content
   return success(withContent(node, content.value))
 }
@@ -147,10 +147,10 @@ function withContent(node: AdfNode, content: readonly AdfNode[]): AdfNode {
   return content.length === 0 ? node : { ...node, content: [...content] }
 }
 
-function listNode(node: AdfNode, items: readonly Block[][], definitions: LinkDefinitions, path: ConvertErrorPath, depth: number): Result<AdfNode> {
+function listNode(node: AdfNode, items: readonly Block[][], definitions: LinkDefinitions, path: ConvertErrorPath, depth: number, memo: SpellingMemo): Result<AdfNode> {
   const content: AdfNode[] = []
   for (const [index, blocks] of items.entries()) {
-    const item = containerNode({ type: 'listItem' }, blocks, definitions, [...path, 'content', index], depth)
+    const item = containerNode({ type: 'listItem' }, blocks, definitions, [...path, 'content', index], depth, memo)
     if (!item.ok) return item
     content.push(item.value)
   }