From 4ab1ed5132242d071bedb3d8f10abfc1e99796cd Mon Sep 17 00:00:00 2001 From: Lilleman auf Larv Date: Sat, 19 Sep 2026 13:18:33 +0200 Subject: [PATCH] 18 - the parse keeps each node's readable spelling, so the directive ask spells it once --- AGENTS.md | 6 ++++ src/markdown/emit/adf-to-markdown.ts | 42 +++++++++++++++++---------- src/markdown/parse/markdown-to-adf.ts | 36 +++++++++++------------ 3 files changed, 51 insertions(+), 33 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 96dbcba..9d54004 100644 --- a/AGENTS.md +++ b/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. diff --git a/src/markdown/emit/adf-to-markdown.ts b/src/markdown/emit/adf-to-markdown.ts index 00190ab..ac1a936 100644 --- a/src/markdown/emit/adf-to-markdown.ts +++ b/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 type Walk = { blocks: readonly PlacedBlock[]; headroom: number } type WalkedItem = { node: AdfNode; walk: Walk } @@ -31,19 +33,19 @@ export function adfToMarkdown(document: AdfDocument): Result { 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 { +function walkBlocks(nodes: readonly AdfNode[], path: ConvertErrorPath, depth: number, memo: SpellingMemo | undefined): Result { 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 { +function emitBlock(node: AdfNode, path: ConvertErrorPath, depth: number, memo: SpellingMemo | undefined): Result { 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 | undefined { - const readable = readableBlock(node, path, depth) +export function commonMarkSpelling(node: AdfNode, path: ConvertErrorPath, depth: number, memo: SpellingMemo): Result | 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 | 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 | 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 | 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 | undefined { +function emitBlockquote(node: AdfNode, path: ConvertErrorPath, depth: number, memo: SpellingMemo | undefined): Result | 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 | undefined { +function emitList(node: AdfNode, path: ConvertErrorPath, depth: number, memo: SpellingMemo | undefined): Result | 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 }) diff --git a/src/markdown/parse/markdown-to-adf.ts b/src/markdown/parse/markdown-to-adf.ts index 2c2425b..20eb3a5 100644 --- a/src/markdown/parse/markdown-to-adf.ts +++ b/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 { 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 { +function blockNodes(blocks: readonly Block[], definitions: LinkDefinitions, path: ConvertErrorPath, depth: number, memo: SpellingMemo): Result { 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 { +function blockNode(block: Block, definitions: LinkDefinitions, path: ConvertErrorPath, depth: number, memo: SpellingMemo): Result { 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 { +function directiveNode(block: DirectiveBlock, definitions: LinkDefinitions, path: ConvertErrorPath, depth: number, memo: SpellingMemo): Result { 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 { +function directiveBody(read: BlockDirectiveNode, blocks: Block[] | undefined, definitions: LinkDefinitions, path: ConvertErrorPath, depth: number, memo: SpellingMemo): Result { 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 { @@ -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 { - const content = blockNodes(blocks, definitions, path, depth + 1) +function containerNode(node: AdfNode, blocks: readonly Block[], definitions: LinkDefinitions, path: ConvertErrorPath, depth: number, memo: SpellingMemo): Result { + 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 { +function listNode(node: AdfNode, items: readonly Block[][], definitions: LinkDefinitions, path: ConvertErrorPath, depth: number, memo: SpellingMemo): Result { 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) }