diff --git a/corpus/README.md b/corpus/README.md index 6df1efe..23ecb71 100644 --- a/corpus/README.md +++ b/corpus/README.md @@ -1,6 +1,6 @@ # The corpus -One directory per contract kind: +One directory per contract kind, each landing with its milestone: - `round-trip/` — `.json` + `.md`: the markdown `adfToMarkdown` must emit for that document, byte for byte, and that `markdownToAdf` must read back to it (AGENTS.md §2). Grouped @@ -10,8 +10,8 @@ One directory per contract kind: - `errors/` — `.md`: markdown input that must not convert. A `.error` beside it pins which error. - `unspellable/` — `.json`: ADF `adfToMarkdown` must refuse, the `ConvertErrorCode` in the - `.error` beside it. A maintainer decision (`todo.md`) moves a document from here to - `round-trip/`. + `.error` beside it. Two populations live here: refusals that stay contract, and documents + a maintainer decision (`todo.md`) moves to `round-trip/`. - `real-payloads/` — `.json`: sanitized live ADF, round-tripped ADF→markdown→ADF. No expected markdown. diff --git a/corpus/round-trip/block-nodes/container-crossing.json b/corpus/round-trip/block-nodes/container-crossing.json new file mode 100644 index 0000000..95bd7b3 --- /dev/null +++ b/corpus/round-trip/block-nodes/container-crossing.json @@ -0,0 +1,77 @@ +{ + "content": [ + { + "attrs": { + "panelType": "info" + }, + "content": [ + { + "content": [ + { + "content": [ + { + "attrs": { + "panelType": "warning" + }, + "content": [ + { + "content": [ + { + "text": "Check the torque before signing off.", + "type": "text" + } + ], + "type": "paragraph" + } + ], + "type": "panel" + } + ], + "type": "listItem" + }, + { + "content": [ + { + "content": [ + { + "text": "Plain item.", + "type": "text" + } + ], + "type": "paragraph" + } + ], + "type": "listItem" + } + ], + "type": "bulletList" + }, + { + "content": [ + { + "attrs": { + "title": "Full build log" + }, + "content": [ + { + "content": [ + { + "text": "The build ran for 11 minutes.", + "type": "text" + } + ], + "type": "paragraph" + } + ], + "type": "expand" + } + ], + "type": "blockquote" + } + ], + "type": "panel" + } + ], + "type": "doc", + "version": 1 +} diff --git a/corpus/round-trip/block-nodes/container-crossing.md b/corpus/round-trip/block-nodes/container-crossing.md new file mode 100644 index 0000000..8af9334 --- /dev/null +++ b/corpus/round-trip/block-nodes/container-crossing.md @@ -0,0 +1,10 @@ +::::panel info +- :::panel warning + Check the torque before signing off. + ::: +- Plain item. + +> :::expand {title="Full build log"} +> The build ran for 11 minutes. +> ::: +:::: diff --git a/src/adf-document.ts b/src/adf-document.ts index 139457f..747906e 100644 --- a/src/adf-document.ts +++ b/src/adf-document.ts @@ -2,6 +2,8 @@ import { isJsonValue, type JsonValue } from './json-value.ts' export type AdfAttributes = { [key: string]: JsonValue } +export type AttributeKind = 'boolean' | 'json' | 'number' | 'string' + export type AdfMark = { attrs?: AdfAttributes type: string diff --git a/src/adf-to-markdown.ts b/src/adf-to-markdown.ts index 9554e31..54c5b1a 100644 --- a/src/adf-to-markdown.ts +++ b/src/adf-to-markdown.ts @@ -2,21 +2,21 @@ import type { AdfDocument, AdfNode } from './adf-document.ts' import type { BlockDirective } from './block-directives.ts' import type { JsonValue } from './json-value.ts' import { blockDirective, spellDirectiveHeader } from './block-directives.ts' -import { emitImageLine, emitInlineLine } from './markdown-inline.ts' -import { emitPipeTable } from './markdown-tables.ts' +import { emitImage } from './markdown-image.ts' +import { emitInlineLine } from './markdown-inline.ts' +import { emitPipeTable } from './markdown-pipe-table.ts' import { failure, success, type ConvertErrorPath, type Result } from './result.ts' import { holdsNullCharacter, isThematicBreak } from './commonmark-grammar.ts' import { isAdfDocument } from './adf-document.ts' import { largestNesting } from './nesting.ts' import { longestBacktickRun } from './backtick-runs.ts' -import { serializeCanonicalJson } from './canonical-json.ts' type BlockContainer = 'directive' | 'document' | 'list-item' +type BlockSpelling = 'commonmark' | 'directive' type EmittedBody = { fenceColons: number; text: string } -type EmittedBlock = EmittedBody & { node: AdfNode; path: ConvertErrorPath } +type EmittedBlock = EmittedBody & { spelling: BlockSpelling } +type PlacedBlock = EmittedBlock & { node: AdfNode; path: ConvertErrorPath } -const centeredMediaSingle = '{"layout":"center"}' -const imageAttributes = ['alt', 'type', 'url'] const largestListMarker = 999999999 const listTypes = ['bulletList', 'orderedList'] @@ -30,7 +30,7 @@ export function adfToMarkdown(document: AdfDocument): Result { function emitBlocks(nodes: readonly AdfNode[], container: BlockContainer, path: ConvertErrorPath, depth: number): Result { if (depth > largestNesting) return failure('unsupported-node-shape', `the document nests deeper than the ${largestNesting} levels the emitter carries`, path) - const blocks: EmittedBlock[] = [] + const blocks: PlacedBlock[] = [] for (const [index, node] of nodes.entries()) { const nodePath = [...path, 'content', index] const block = emitBlock(node, nodePath, depth) @@ -52,7 +52,7 @@ function emitBlocks(nodes: readonly AdfNode[], container: BlockContainer, path: return success({ fenceColons, text }) } -function separationBetween(previous: EmittedBlock, next: EmittedBlock, container: BlockContainer): Result { +function separationBetween(previous: PlacedBlock, next: PlacedBlock, container: BlockContainer): Result { if (listTypes.includes(next.node.type) && previous.node.type === next.node.type) { return failure('unspellable-adjacent-lists', `two adjacent ${next.node.type} nodes read back as one list`, next.path) } @@ -63,8 +63,8 @@ function separationBetween(previous: EmittedBlock, next: EmittedBlock, container return success('\n') } if (container !== 'directive') return success('\n\n') - if (previous.fenceColons === 0 && next.fenceColons === 0) return success('\n\n') - if (previous.fenceColons > 0 && next.fenceColons > 0) return success('\n') + if (previous.spelling === 'commonmark' && next.spelling === 'commonmark') return success('\n\n') + if (previous.spelling === 'directive' && next.spelling === 'directive') return success('\n') return failure( 'unspelled-block-separation', `the canonical form leaves the separation between a ${previous.node.type} and a ${next.node.type} in a container body unspelled`, @@ -77,13 +77,13 @@ function interruptsParagraph(node: AdfNode): boolean { return ((node.content ?? [])[0]?.content ?? []).length > 0 } -function emitBlock(node: AdfNode, path: ConvertErrorPath, depth: number): Result { - if (node.type === 'blockquote') return plainBlock(emitBlockquote(node, path, depth)) - if (node.type === 'bulletList' || node.type === 'orderedList') return plainBlock(emitList(node, path, depth)) - if (node.type === 'codeBlock') return plainBlock(emitCodeBlock(node, path)) - if (node.type === 'heading') return plainBlock(emitHeading(node, path)) +function emitBlock(node: AdfNode, path: ConvertErrorPath, depth: number): Result { + if (node.type === 'blockquote') return commonMarkContainer(emitBlockquote(node, path, depth)) + if (node.type === 'bulletList' || node.type === 'orderedList') return commonMarkContainer(emitList(node, path, depth)) + if (node.type === 'codeBlock') return commonMarkLine(emitCodeBlock(node, path)) + if (node.type === 'heading') return commonMarkLine(emitHeading(node, path)) if (node.type === 'paragraph') return emitParagraph(node, path) - if (node.type === 'rule') return plainBlock(emitRule(node, path)) + if (node.type === 'rule') return commonMarkLine(emitRule(node, path)) const directive = blockDirective(node.type) if (directive !== undefined) { if (node.type === 'mediaSingle') return emitMediaSingle(node, directive, path, depth) @@ -96,71 +96,62 @@ function emitBlock(node: AdfNode, path: ConvertErrorPath, depth: number): Result return failure('unsupported-node-type', `the canonical form spells no block node of type ${node.type}`, path) } -function plainBlock(text: Result): Result { +function commonMarkLine(text: Result): Result { if (!text.ok) return text - return success({ fenceColons: 0, text: text.value }) + return success({ fenceColons: 0, spelling: 'commonmark', text: text.value }) } -function emitDirectiveBlock(node: AdfNode, directive: BlockDirective, path: ConvertErrorPath, depth: number): Result { +function commonMarkContainer(body: Result): Result { + if (!body.ok) return body + return success({ ...body.value, spelling: 'commonmark' }) +} + +function emitDirectiveBlock(node: AdfNode, directive: BlockDirective, path: ConvertErrorPath, depth: number): Result { if (node.text !== undefined) return failure('unsupported-node-shape', `a ${node.type} carries no text`, path) const header = spellDirectiveHeader(node, directive, path) if (!header.ok) return header const content = node.content ?? [] if (directive.body === 'none') { if (content.length > 0) return failure('unsupported-node-shape', `a ${node.type} holds no content`, path) - return success({ fenceColons: 2, text: `::${header.value}` }) + return success({ fenceColons: 2, spelling: 'directive', text: `::${header.value}` }) } const body = directive.body === 'inline' ? emitInlineBody(content, path) : emitBlocks(content, 'directive', path, depth + 1) if (!body.ok) return body const fenceColons = Math.max(3, body.value.fenceColons + 1) const fence = ':'.repeat(fenceColons) const lines = body.value.text === '' ? '' : `${body.value.text}\n` - return success({ fenceColons, text: `${fence}${header.value}\n${lines}${fence}` }) + return success({ fenceColons, spelling: 'directive', text: `${fence}${header.value}\n${lines}${fence}` }) } function emitInlineBody(content: readonly AdfNode[], path: ConvertErrorPath): Result { if (content.length === 0) return success({ fenceColons: 0, text: '' }) - return plainBlock(emitInlineLine(content, 'paragraph', path)) + const line = emitInlineLine(content, 'paragraph', path) + if (!line.ok) return line + return success({ fenceColons: 0, text: line.value }) } -function emitMediaSingle(node: AdfNode, directive: BlockDirective, path: ConvertErrorPath, depth: number): Result { - const image = imageShape(node) +function emitMediaSingle(node: AdfNode, directive: BlockDirective, path: ConvertErrorPath, depth: number): Result { + const image = emitImage(node, path) if (image === undefined) return emitDirectiveBlock(node, directive, path, depth) - const mediaPath = [...path, 'content', 0] - if (image.alt === '') return failure('ambiguous-empty-media-alt', 'an empty media alt and an absent one share one image spelling', mediaPath) - return plainBlock(emitImageLine(image.alt, image.url, mediaPath)) + return commonMarkLine(image) } -function imageShape(node: AdfNode): { alt: string | undefined; url: string } | undefined { - const content = node.content ?? [] - const media = content[0] - if (serializeCanonicalJson(node.attrs ?? {}, 'compact') !== centeredMediaSingle || (node.marks ?? []).length > 0) return undefined - if (media === undefined || content.length !== 1 || media.type !== 'media' || (media.marks ?? []).length > 0 || (media.content ?? []).length > 0) return undefined - const attrs = media.attrs ?? {} - const alt = attrs['alt'] - const url = attrs['url'] - if (Object.keys(attrs).some((key) => !imageAttributes.includes(key)) || attrs['type'] !== 'external') return undefined - if (typeof url !== 'string' || (alt !== undefined && typeof alt !== 'string')) return undefined - return { alt, url } -} - -function emitTable(node: AdfNode, directive: BlockDirective, path: ConvertErrorPath, depth: number): Result { +function emitTable(node: AdfNode, directive: BlockDirective, path: ConvertErrorPath, depth: number): Result { const pipe = emitPipeTable(node, path) if (pipe === undefined) return emitDirectiveBlock(node, directive, path, depth) - return plainBlock(pipe) + return commonMarkLine(pipe) } -function emitBlockquote(node: AdfNode, path: ConvertErrorPath, depth: number): Result { +function emitBlockquote(node: AdfNode, path: ConvertErrorPath, depth: number): Result { const validation = validateBlockNode(node, [], path) if (!validation.ok) return validation const inner = emitBlocks(node.content ?? [], 'document', path, depth + 1) if (!inner.ok) return inner - return success( - inner.value.text - .split('\n') - .map((line) => (line === '' ? '>' : `> ${line}`)) - .join('\n'), - ) + const text = inner.value.text + .split('\n') + .map((line) => (line === '' ? '>' : `> ${line}`)) + .join('\n') + return success({ fenceColons: inner.value.fenceColons, text }) } function emitCodeBlock(node: AdfNode, path: ConvertErrorPath): Result { @@ -211,54 +202,63 @@ function emitHeading(node: AdfNode, path: ConvertErrorPath): Result { return success(`${hashes} ${line.value}`) } -function emitList(node: AdfNode, path: ConvertErrorPath, depth: number): Result { +function emitList(node: AdfNode, path: ConvertErrorPath, depth: number): Result { const ordered = node.type === 'orderedList' const validation = validateBlockNode(node, ordered ? ['order'] : [], path) if (!validation.ok) return validation const items = node.content ?? [] - if (items.length === 0) return failure('unsupported-node-shape', `a ${node.type} holds at least one listItem`, path) - const start = ordered ? node.attrs?.['order'] : 0 - if (ordered && (start === undefined || start === 1)) { - return failure('ambiguous-ordered-list-start', 'an orderedList starting at 1 and one with no order share one markdown spelling', path) - } - if (typeof start !== 'number' || !Number.isInteger(start) || start < 0 || start > largestListMarker) { - return failure('unsupported-node-shape', `no list marker spells the order ${JSON.stringify(start ?? null)}`, path) - } - if (start + items.length - 1 > largestListMarker) { - return failure('unspellable-list-marker', `no list marker spells the ${items.length} items a list starting at ${start} needs`, path) - } + const start = listStart(node, items.length, path) + if (!start.ok) return start const lines: string[] = [] + let fenceColons = 0 for (const [offset, item] of items.entries()) { const itemPath = [...path, 'content', offset] if (item.type !== 'listItem') return failure('unsupported-node-shape', `a ${node.type} holds listItem nodes only`, itemPath) - const emitted = emitListItem(item, ordered ? `${start + offset}. ` : '- ', itemPath, depth) + const emitted = emitListItem(item, ordered ? `${start.value + offset}. ` : '- ', itemPath, depth) if (!emitted.ok) return emitted - lines.push(emitted.value) + fenceColons = Math.max(fenceColons, emitted.value.fenceColons) + lines.push(emitted.value.text) } - return success(lines.join('\n')) + return success({ fenceColons, text: lines.join('\n') }) } -function emitListItem(item: AdfNode, marker: string, path: ConvertErrorPath, depth: number): Result { +function listStart(node: AdfNode, items: number, path: ConvertErrorPath): Result { + if (items === 0) return failure('unsupported-node-shape', `a ${node.type} holds at least one listItem`, path) + if (node.type !== 'orderedList') return success(0) + const start = node.attrs?.['order'] + if (start === undefined || start === 1) { + return failure('ambiguous-ordered-list-start', 'an orderedList starting at 1 and one with no order share one markdown spelling', path) + } + if (typeof start !== 'number' || !Number.isInteger(start) || start < 0 || start > largestListMarker) { + return failure('unsupported-node-shape', `no list marker spells the order ${JSON.stringify(start)}`, path) + } + if (start + items - 1 > largestListMarker) { + return failure('unspellable-list-marker', `no list marker spells the ${items} items a list starting at ${start} needs`, path) + } + return success(start) +} + +function emitListItem(item: AdfNode, marker: string, path: ConvertErrorPath, depth: number): Result { const validation = validateBlockNode(item, [], path) if (!validation.ok) return validation const inner = emitBlocks(item.content ?? [], 'list-item', path, depth + 1) if (!inner.ok) return inner - if (inner.value.text === '') return success(marker.trimEnd()) + if (inner.value.text === '') return success({ fenceColons: 0, text: marker.trimEnd() }) const indent = ' '.repeat(marker.length) const lines = inner.value.text.split('\n').map((line, index) => (index === 0 ? `${marker}${line}` : line === '' ? '' : `${indent}${line}`)) const first = lines[0] ?? '' if (isThematicBreak(first)) { return failure('unspellable-line-start', `block parsing would claim the emitted line ${JSON.stringify(first)}`, path) } - return success(lines.join('\n')) + return success({ fenceColons: inner.value.fenceColons, text: lines.join('\n') }) } -function emitParagraph(node: AdfNode, path: ConvertErrorPath): Result { +function emitParagraph(node: AdfNode, path: ConvertErrorPath): Result { const validation = validateBlockNode(node, [], path) if (!validation.ok) return validation const content = node.content ?? [] - if (content.length === 0) return success({ fenceColons: 2, text: '::paragraph' }) - return plainBlock(emitInlineLine(content, 'paragraph', path)) + if (content.length === 0) return success({ fenceColons: 2, spelling: 'directive', text: '::paragraph' }) + return commonMarkLine(emitInlineLine(content, 'paragraph', path)) } function emitRule(node: AdfNode, path: ConvertErrorPath): Result { diff --git a/src/block-directives.ts b/src/block-directives.ts index 5c88841..9a34d65 100644 --- a/src/block-directives.ts +++ b/src/block-directives.ts @@ -1,5 +1,4 @@ -import type { AdfMark, AdfNode } from './adf-document.ts' -import type { AttributeKind } from './directive-attributes.ts' +import type { AdfMark, AdfNode, AttributeKind } from './adf-document.ts' import type { JsonValue } from './json-value.ts' import { failure, success, type ConvertErrorPath, type Result } from './result.ts' import { isBareToken, spellAttributeValue, spellAttributes, spellJsonAttribute } from './directive-attributes.ts' diff --git a/src/corpus.test.ts b/src/corpus.test.ts index 79118fd..762408f 100644 --- a/src/corpus.test.ts +++ b/src/corpus.test.ts @@ -72,6 +72,50 @@ for (const directory of emittingDirectories) { } } +// The rule spec/flavour.md states as "a container's fence is longer than every directive fence line +// in its body", checked against the emitted bytes: a hand-written fixture cannot be its own witness. +function fenceNestingFault(markdown: string): string | undefined { + const open: number[] = [] + let codeFence: string | undefined + for (const line of markdown.split('\n')) { + const content = line.replace(/^ {0,3}(?:(?:> ?|[-*+] |\d{1,9}[.)] ) {0,3})*/, '') + const backticks = /^(`{3,}|~{3,})/.exec(content)?.[1] + if (codeFence !== undefined) { + if (backticks !== undefined && backticks[0] === codeFence[0] && backticks.length >= codeFence.length) codeFence = undefined + continue + } + if (backticks !== undefined) { + codeFence = backticks + continue + } + const colons = /^(:{2,})(.*)$/.exec(content) + if (colons === null) continue + const run = colons[1]?.length ?? 0 + const enclosing = open[open.length - 1] + if (colons[2] === '') { + open.pop() + continue + } + if (enclosing !== undefined && run >= enclosing) return `${JSON.stringify(line)} sits in a container fenced with ${enclosing} colons` + if (run > 2) open.push(run) + } + return undefined +} + +test('the fence nesting check catches a fence a container cannot hold', () => { + assert.equal(fenceNestingFault(':::panel info\n- :::panel warning\n B\n :::\n:::'), '"- :::panel warning" sits in a container fenced with 3 colons') + assert.equal(fenceNestingFault('::::panel info\n- :::panel warning\n B\n :::\n::::'), undefined) + assert.equal(fenceNestingFault(':::tableCell\n```text\n:::::::panel warning\n:::\n```\n:::'), undefined) +}) + +for (const directory of emittingDirectories) { + for (const name of fixtureNames(directory, '.md')) { + test(`${directory}/${name} fences every container longer than its body`, () => { + assert.equal(fenceNestingFault(readFileSync(join(roundTripRoot, directory, `${name}.md`), 'utf8')), undefined) + }) + } +} + test('unspellable pairs every .json with an .error', () => { assert.deepEqual(names(unspellableRoot, '.json'), names(unspellableRoot, '.error')) }) diff --git a/src/directive-attributes.ts b/src/directive-attributes.ts index 76f697b..6ef832c 100644 --- a/src/directive-attributes.ts +++ b/src/directive-attributes.ts @@ -1,8 +1,7 @@ +import type { AttributeKind } from './adf-document.ts' import type { JsonValue } from './json-value.ts' import { serializeCanonicalJson } from './canonical-json.ts' -export type AttributeKind = 'boolean' | 'json' | 'number' | 'string' - const bareToken = /^[A-Za-z0-9_-]+$/ export function isBareToken(text: string): boolean { diff --git a/src/markdown-image.ts b/src/markdown-image.ts new file mode 100644 index 0000000..5778ad8 --- /dev/null +++ b/src/markdown-image.ts @@ -0,0 +1,28 @@ +import type { AdfNode } from './adf-document.ts' +import { emitImageLine } from './markdown-inline.ts' +import { failure, type ConvertErrorPath, type Result } from './result.ts' +import { serializeCanonicalJson } from './canonical-json.ts' + +const centeredMediaSingle = '{"layout":"center"}' +const imageAttributes = ['alt', 'type', 'url'] + +export function emitImage(node: AdfNode, path: ConvertErrorPath): Result | undefined { + const image = imageShape(node) + if (image === undefined) return undefined + const mediaPath = [...path, 'content', 0] + if (image.alt === '') return failure('ambiguous-empty-media-alt', 'an empty media alt and an absent one share one image spelling', mediaPath) + return emitImageLine(image.alt, image.url, mediaPath) +} + +function imageShape(node: AdfNode): { alt: string | undefined; url: string } | undefined { + const content = node.content ?? [] + const media = content[0] + if (serializeCanonicalJson(node.attrs ?? {}, 'compact') !== centeredMediaSingle || (node.marks ?? []).length > 0) return undefined + if (media === undefined || content.length !== 1 || media.type !== 'media' || (media.marks ?? []).length > 0 || (media.content ?? []).length > 0) return undefined + const attrs = media.attrs ?? {} + const alt = attrs['alt'] + const url = attrs['url'] + if (Object.keys(attrs).some((key) => !imageAttributes.includes(key)) || attrs['type'] !== 'external') return undefined + if (typeof url !== 'string' || (alt !== undefined && typeof alt !== 'string')) return undefined + return { alt, url } +} diff --git a/src/markdown-tables.ts b/src/markdown-pipe-table.ts similarity index 100% rename from src/markdown-tables.ts rename to src/markdown-pipe-table.ts diff --git a/todo.md b/todo.md index bf79310..99d1f6e 100644 --- a/todo.md +++ b/todo.md @@ -100,11 +100,16 @@ detail is settled at its own milestone. assumes — CommonMark flanking, as for `*` — which `spec/flavour.md` does not yet pin. `src/` gets its hierarchy at the same split — `adf/`, `markdown/`, `html/`, the grammar module shared inside `markdown/` — while the rename is - still mechanical. + still mechanical. `block-directives.ts` is the one file that does not move whole: the node + table is ADF knowledge milestones 6-7 need too and belongs in `adf/`, `spellDirectiveHeader` + in `markdown/`. The table is a second copy of `spec/flavour.md`'s prose with no drift guard, + and a mistyped attribute name degrades into a false refusal no test catches. - [ ] **4 — Round-trip property tests** over the corpus, both ways — the thing that proves 2 and 3. Editor-normal (§2) gets its implementation here — `toEditorNormal(doc)` and the equality the round-trip asserts, which over normalized input is the canonical serializer's compact - spelling — rather than staying spelled inline as `?? []` at every reader. + spelling — rather than staying spelled inline as `?? []` at every reader. The reading half is + `nodeContent`/`nodeAttrs`/`nodeMarks` over the ~28 sites spelling it inline today, which also + lifts the branch floor §10 keeps below 100 for exactly those halves. Generators emit editor-normal ADF (§2). Real sanitized ADF from live Atlassian APIs lands here too (§10), in `corpus/real-payloads/`: an ADF→markdown→ADF check with no expected markdown, the payloads supplied by the maintainer.