Give the CommonMark blocks a directive form for what their spelling cannot hold

src/adf-to-markdown.test.ts

@@ -26,7 +26,7 @@ function path(result: Result<string>): readonly (number | string)[] {
 }
 
 test('names the node a refusal came from', () => {
-  const unspellable: AdfNode = { attrs: { localId: 'a' }, type: 'paragraph' }
+  const unspellable: AdfNode = { text: 'x', type: 'paragraph' }
   const list: AdfNode = { content: [{ content: [paragraph({ text: 'x', type: 'text' })], type: 'listItem' }, { content: [unspellable], type: 'listItem' }], type: 'bulletList' }
   assert.deepEqual(path(adfToMarkdown(document(paragraph({ text: 'x', type: 'text' }), list))), ['content', 1, 'content', 1, 'content', 0])
   assert.deepEqual(path(adfToMarkdown(document(paragraph({ text: 'x', type: 'text' }, { type: 'text' })))), ['content', 0, 'content', 1])
@@ -41,28 +41,31 @@ test('refuses a document version the markdown cannot carry', () => {
   assert.equal(code(adfToMarkdown({ type: 'doc', version: 2 })), 'unsupported-document-version')
 })
 
-test('refuses an attribute the canonical form does not spell', () => {
-  assert.equal(code(adfToMarkdown(document({ attrs: { localId: 'a' }, type: 'paragraph' }))), 'unspelled-node-attribute')
-  assert.equal(code(adfToMarkdown(document({ attrs: { wrap: true }, type: 'codeBlock' }))), 'unspelled-node-attribute')
-  assert.equal(code(adfToMarkdown(document(paragraph({ attrs: { localId: 'a' }, type: 'hardBreak' }, { text: 'x', type: 'text' })))), 'unspelled-node-attribute')
+test('refuses a text node attribute the canonical form does not spell', () => {
+  assert.equal(code(adfToMarkdown(document(paragraph({ attrs: { localId: 'a' }, text: 'x', type: 'text' })))), 'unspelled-node-attribute')
 })
 
-test('refuses marks on a block node', () => {
-  assert.equal(code(adfToMarkdown(document({ marks: [{ type: 'border' }], type: 'blockquote' }))), 'unspelled-block-marks')
+test('spells a CommonMark block as a directive where its own spelling holds neither attribute nor mark', () => {
+  assert.equal(markdown(adfToMarkdown(document({ attrs: { localId: 'a' }, type: 'paragraph' }))), '::paragraph {localId=a}\n')
+  assert.equal(markdown(adfToMarkdown(document({ attrs: { wrap: true }, type: 'codeBlock' }))), ':::codeBlock {wrap=true}\n```\n```\n:::\n')
+  assert.equal(markdown(adfToMarkdown(document(paragraph({ attrs: { localId: 'a' }, type: 'hardBreak' }, { text: 'x', type: 'text' })))), ':hardBreak{localId=a}x\n')
+  assert.equal(markdown(adfToMarkdown(document({ marks: [{ type: 'border' }], type: 'blockquote' }))), ':::blockquote {marks="[{\\"type\\":\\"border\\"}]"}\n:::\n')
+  assert.equal(markdown(adfToMarkdown(document({ type: 'listItem' }))), ':::listItem\n:::\n')
 })
 
-test('refuses an ordered list whose markdown start is ambiguous', () => {
+test('spells an ordered list from the order attribute its first marker is', () => {
   const items: AdfNode[] = [{ content: [paragraph({ text: 'x', type: 'text' })], type: 'listItem' }]
-  assert.equal(code(adfToMarkdown(document({ content: items, type: 'orderedList' }))), 'ambiguous-attribute-spelling')
-  assert.equal(code(adfToMarkdown(document({ attrs: { order: 1 }, content: items, type: 'orderedList' }))), 'ambiguous-attribute-spelling')
+  assert.equal(markdown(adfToMarkdown(document({ content: items, type: 'orderedList' }))), '::::orderedList\n:::listItem\nx\n:::\n::::\n')
+  assert.equal(markdown(adfToMarkdown(document({ attrs: { order: 1 }, content: items, type: 'orderedList' }))), '1. x\n')
   assert.equal(markdown(adfToMarkdown(document({ attrs: { order: 2 }, content: items, type: 'orderedList' }))), '2. x\n')
 })
 
-test('refuses the code block info strings the fence cannot hold', () => {
-  assert.equal(code(adfToMarkdown(document({ attrs: { language: '' }, type: 'codeBlock' }))), 'ambiguous-attribute-spelling')
-  assert.equal(code(adfToMarkdown(document({ attrs: { language: 'a`b' }, type: 'codeBlock' }))), 'unspellable-code-block-language')
-  assert.equal(code(adfToMarkdown(document({ attrs: { language: ' sql' }, type: 'codeBlock' }))), 'unspellable-code-block-language')
-  assert.equal(code(adfToMarkdown(document({ attrs: { language: '&#97;df' }, type: 'codeBlock' }))), 'unspellable-code-block-language')
+test('spells a code block language no info string holds as an attribute', () => {
+  const language = (value: string): string => markdown(adfToMarkdown(document({ attrs: { language: value }, type: 'codeBlock' })))
+  assert.equal(language(''), ':::codeBlock {language=""}\n```\n```\n:::\n')
+  assert.equal(language('a`b'), ':::codeBlock {language="a\\u0060b"}\n```\n```\n:::\n')
+  assert.equal(language(' sql'), ':::codeBlock {language=" sql"}\n```\n```\n:::\n')
+  assert.equal(language('&#97;df'), ':::codeBlock {language="\\u0026#97;df"}\n```\n```\n:::\n')
 })
 
 test('refuses a link destination CommonMark cannot spell', () => {
@@ -131,15 +134,11 @@ test('carries a node type no section spells', () => {
   assert.equal(markdown(adfToMarkdown(document({ type: 'toString' }))), '```adf\n{\n  "type": "toString"\n}\n```\n')
   assert.equal(markdown(adfToMarkdown(document(paragraph({ type: 'blockCard' })))), ':adf{json="{\\"type\\":\\"blockCard\\"}"}\n')
   assert.equal(markdown(adfToMarkdown(document({ text: 'x', type: 'text' }))), '```adf\n{\n  "text": "x",\n  "type": "text"\n}\n```\n')
-  assert.equal(markdown(adfToMarkdown(document({ type: 'listItem' }))), '```adf\n{\n  "type": "listItem"\n}\n```\n')
   assert.equal(markdown(adfToMarkdown(document({ type: 'hardBreak' }))), '```adf\n{\n  "type": "hardBreak"\n}\n```\n')
 })
 
-test('carries the code block whose language is the reserved info string', () => {
-  assert.equal(
-    markdown(adfToMarkdown(document({ attrs: { language: 'adf' }, type: 'codeBlock' }))),
-    '```adf\n{\n  "attrs": {\n    "language": "adf"\n  },\n  "type": "codeBlock"\n}\n```\n',
-  )
+test('spells the code block whose language is the reserved info string', () => {
+  assert.equal(markdown(adfToMarkdown(document({ attrs: { language: 'adf' }, type: 'codeBlock' }))), ':::codeBlock {language=adf}\n```\n```\n:::\n')
 })
 
 test('breaks a mark run at the node it carries', () => {
@@ -166,13 +165,13 @@ test('refuses a node whose content model the canonical form cannot emit', () =>
   assert.equal(code(adfToMarkdown(document({ attrs: { order: 2 }, content: [], type: 'orderedList' }))), 'unsupported-node-shape')
 })
 
-test('refuses an ordered list no marker spells', () => {
+test('spells an ordered list no marker fits as a directive', () => {
   const item: AdfNode = { content: [paragraph({ text: 'x', type: 'text' })], type: 'listItem' }
   const list = (order: number, items: number): AdfDocument =>
     document({ attrs: { order }, content: Array.from({ length: items }, () => item), type: 'orderedList' })
-  assert.equal(code(adfToMarkdown(list(1.5, 1))), 'unsupported-node-shape')
+  assert.equal(markdown(adfToMarkdown(list(1.5, 1))), '::::orderedList {order="1.5"}\n:::listItem\nx\n:::\n::::\n')
   assert.equal(markdown(adfToMarkdown(list(999999999, 1))), '999999999. x\n')
-  assert.equal(code(adfToMarkdown(list(999999999, 2))), 'unspellable-list-marker')
+  assert.equal(markdown(adfToMarkdown(list(999999999, 2))), '::::orderedList {order=999999999}\n:::listItem\nx\n:::\n:::listItem\nx\n:::\n::::\n')
 })
 
 test('carries a code mark over anything but text', () => {
@@ -182,9 +181,9 @@ test('carries a code mark over anything but text', () => {
   )
 })
 
-test('refuses a heading level outside the ATX range', () => {
-  assert.equal(code(adfToMarkdown(document({ attrs: { level: 7 }, content: [{ text: 'x', type: 'text' }], type: 'heading' }))), 'unsupported-heading-level')
-  assert.equal(code(adfToMarkdown(document({ content: [{ text: 'x', type: 'text' }], type: 'heading' }))), 'unsupported-heading-level')
+test('spells a heading level no ATX heading fits as a directive', () => {
+  assert.equal(markdown(adfToMarkdown(document({ attrs: { level: 7 }, content: [{ text: 'x', type: 'text' }], type: 'heading' }))), ':::heading {level=7}\nx\n:::\n')
+  assert.equal(markdown(adfToMarkdown(document({ content: [{ text: 'x', type: 'text' }], type: 'heading' }))), ':::heading\nx\n:::\n')
 })
 
 test('escapes only text that would otherwise open a construct', () => {
@@ -480,7 +479,7 @@ test('spells a table as a pipe table only where every row and cell is plain', ()
   assert.ok(directive(adfToMarkdown(table(cell('tableHeader', text('Part'))))))
   assert.ok(directive(adfToMarkdown(table(row(cell('tableHeader'))))))
   assert.ok(directive(adfToMarkdown(table(row(cell('tableHeader', text('a'), text('b')))))))
-  assert.equal(code(adfToMarkdown(table(row(cell('tableHeader', { attrs: { localId: 'a' }, type: 'paragraph' }))))), 'unspelled-node-attribute')
+  assert.ok(directive(adfToMarkdown(table(row(cell('tableHeader', { attrs: { localId: 'a' }, type: 'paragraph' }))))))
   assert.equal(
     markdown(adfToMarkdown(table(row(cell('tableHeader', { content: [{ attrs: { url: 'a|b' }, type: 'blockCard' }], type: 'paragraph' }))))),
     '| :adf{json="{\\"attrs\\":{\\"url\\":\\"a\\u007cb\\"},\\"type\\":\\"blockCard\\"}"} |\n| --- |\n',

src/adf-to-markdown.ts

@@ -54,17 +54,19 @@ function emitBlocks(nodes: readonly AdfNode[], container: BlockContainer, path:
 }
 
 function separationBetween(previous: PlacedBlock, next: PlacedBlock, container: BlockContainer): Result<string> {
-  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)
-  }
-  if (container === 'list-item' && listTypes.includes(next.node.type)) {
-    if (!interruptsParagraph(next.node)) {
-      return failure('unspellable-line-start', `a ${next.node.type} that cannot interrupt the block above it has no tight spelling`, next.path)
+  const plainPair = previous.spelling === 'commonmark' && next.spelling === 'commonmark'
+  if (plainPair && listTypes.includes(next.node.type)) {
+    if (previous.node.type === next.node.type) {
+      return failure('unspellable-adjacent-lists', `two adjacent ${next.node.type} nodes read back as one list`, next.path)
+    }
+    if (container === 'list-item') {
+      if (!interruptsParagraph(next.node)) {
+        return failure('unspellable-line-start', `a ${next.node.type} that cannot interrupt the block above it has no tight spelling`, next.path)
+      }
+      return success('\n')
     }
-    return success('\n')
   }
-  if (container !== 'directive') return success('\n\n')
-  if (previous.spelling === 'commonmark' && next.spelling === 'commonmark') return success('\n\n')
+  if (container !== 'directive' || plainPair) return success('\n\n')
   if (previous.spelling === 'directive' && next.spelling === 'directive') return success('\n')
   return failure(
     'unspelled-block-separation',
@@ -79,19 +81,27 @@ function interruptsParagraph(node: AdfNode): boolean {
 }
 
 function emitBlock(node: AdfNode, path: ConvertErrorPath, depth: number): Result<EmittedBlock> {
-  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 commonMarkLine(emitRule(node, path))
   const directive = blockDirective(node.type)
-  if (directive !== undefined) {
-    if (node.type === 'mediaSingle') return emitMediaSingle(node, directive, path, depth)
-    if (node.type === 'table') return emitTable(node, directive, path, depth)
-    return emitDirectiveBlock(node, directive, path, depth)
-  }
-  return commonMarkLine(carriedBlock(node, path))
+  if (directive === undefined) return commonMarkLine(carriedBlock(node, path))
+  const readable = readableBlock(node, path, depth)
+  if (readable !== undefined) return readable
+  return emitDirectiveBlock(node, directive, path, depth)
+}
+
+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)
+  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))
+  if (node.type === 'paragraph') return emitParagraph(node, path)
+  if (node.type === 'rule') return emitRule(node)
+  if (node.type === 'table') return readableText(tryPipeTable(node, path))
+  return undefined
+}
+
+function readableText(text: string | undefined): Result<EmittedBlock> | undefined {
+  return text === undefined ? undefined : success(commonMarkText(text))
 }
 
 function commonMarkLine(text: Result<string>): Result<EmittedBlock> {
@@ -103,18 +113,17 @@ function commonMarkText(text: string): EmittedBlock {
   return { fenceColons: 0, spelling: 'commonmark', text }
 }
 
-function commonMarkContainer(body: Result<EmittedBody>): Result<EmittedBlock> {
-  if (!body.ok) return body
-  return success({ ...body.value, spelling: 'commonmark' })
-}
-
 function emitDirectiveBlock(node: AdfNode, directive: BlockDirective, path: ConvertErrorPath, depth: number): Result<EmittedBlock> {
   if (node.text !== undefined) return failure('unsupported-node-shape', `a ${node.type} carries no text`, path)
   const content = node.content ?? []
   if (directive.body === 'none' && content.length > 0) return failure('unsupported-node-shape', `a ${node.type} holds no content`, path)
+  if (directive.body === 'code') return emitCodeDirective(node, directive, path)
   const header = spellDirectiveHeader(node, directive)
   if (header === undefined) return commonMarkLine(carriedBlock(node, path))
-  if (directive.body === 'none') return success({ fenceColons: 2, spelling: 'directive', text: `::${header}` })
+  // spec/flavour.md, The CommonMark blocks: an empty paragraph is the leaf.
+  if (directive.body === 'none' || (node.type === 'paragraph' && content.length === 0)) {
+    return success({ fenceColons: 2, spelling: 'directive', text: `::${header}` })
+  }
   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)
@@ -130,36 +139,36 @@ function emitInlineBody(content: readonly AdfNode[], path: ConvertErrorPath): Re
   return success({ fenceColons: 0, text: line.value })
 }
 
-function emitMediaSingle(node: AdfNode, directive: BlockDirective, path: ConvertErrorPath, depth: number): Result<EmittedBlock> {
-  const image = tryImage(node, path)
-  if (image === undefined) return emitDirectiveBlock(node, directive, path, depth)
-  return success(commonMarkText(image))
-}
-
-function emitTable(node: AdfNode, directive: BlockDirective, path: ConvertErrorPath, depth: number): Result<EmittedBlock> {
-  const pipe = tryPipeTable(node, path)
-  if (pipe === undefined) return emitDirectiveBlock(node, directive, path, depth)
-  return success(commonMarkText(pipe))
-}
-
-function emitBlockquote(node: AdfNode, path: ConvertErrorPath, depth: number): Result<EmittedBody> {
-  const validation = validateBlockNode(node, [], path)
-  if (!validation.ok) return validation
+function emitBlockquote(node: AdfNode, path: ConvertErrorPath, depth: number): Result<EmittedBlock> | undefined {
+  if (!commonMarkHead(node, [])) return undefined
   const inner = emitBlocks(node.content ?? [], 'document', path, depth + 1)
   if (!inner.ok) return inner
   const text = inner.value.text
     .split('\n')
     .map((line) => (line === '' ? '>' : `> ${line}`))
     .join('\n')
-  return success({ fenceColons: inner.value.fenceColons, text })
+  return success({ fenceColons: inner.value.fenceColons, spelling: 'commonmark', text })
 }
 
-function emitCodeBlock(node: AdfNode, path: ConvertErrorPath): Result<string> {
-  if (node.attrs?.['language'] === carryName) return carriedBlock(node, path)
-  const validation = validateBlockNode(node, ['language'], path)
-  if (!validation.ok) return validation
-  const info = spellCodeFenceInfo(node.attrs?.['language'], path)
-  if (!info.ok) return info
+function emitCodeBlock(node: AdfNode, path: ConvertErrorPath): Result<EmittedBlock> | undefined {
+  if (!commonMarkHead(node, ['language'])) return undefined
+  const info = fenceInfo(node.attrs?.['language'])
+  if (info === undefined) return undefined
+  const text = codeBlockText(node, path)
+  if (!text.ok) return text
+  return success(commonMarkText(fencedCodeBlock(info, text.value)))
+}
+
+function emitCodeDirective(node: AdfNode, directive: BlockDirective, path: ConvertErrorPath): Result<EmittedBlock> {
+  const info = fenceInfo(node.attrs?.['language'])
+  const header = spellDirectiveHeader(node, directive, info === undefined ? [] : ['language'])
+  if (header === undefined) return commonMarkLine(carriedBlock(node, path))
+  const text = codeBlockText(node, path)
+  if (!text.ok) return text
+  return success({ fenceColons: 3, spelling: 'directive', text: `:::${header}\n${fencedCodeBlock(info ?? '', text.value)}\n:::` })
+}
+
+function codeBlockText(node: AdfNode, path: ConvertErrorPath): Result<string> {
   let text = ''
   for (const [index, child] of (node.content ?? []).entries()) {
     const childPath = [...path, 'content', index]
@@ -177,78 +186,57 @@ function emitCodeBlock(node: AdfNode, path: ConvertErrorPath): Result<string> {
     if (holdsNullCharacter(child.text)) return failure('unspellable-character', 'a codeBlock holds a null character CommonMark replaces', childPath)
     text += child.text
   }
-  return success(fencedCodeBlock(info.value, text))
+  return success(text)
 }
 
-function spellCodeFenceInfo(language: JsonValue | undefined, path: ConvertErrorPath): Result<string> {
-  if (language === undefined) return success('')
-  if (typeof language !== 'string') return failure('unsupported-node-shape', 'a codeBlock language is no string', path)
-  if (language === '') {
-    return failure('ambiguous-attribute-spelling', 'an empty codeBlock language and an absent one share one markdown spelling', path)
-  }
-  if (/[`\n\r]/.test(language) || language !== language.trim()) {
-    return failure('unspellable-code-block-language', 'a fence info string holds no backtick and no edge whitespace', path)
-  }
-  if (holdsEntityReference(language)) {
-    return failure('unspellable-code-block-language', 'a fence info string shaped like an entity reference decodes on the way back', path)
-  }
-  return success(language)
+// spec/flavour.md, The CommonMark blocks: the languages an info string holds, the absent one as the empty string.
+function fenceInfo(language: JsonValue | undefined): string | undefined {
+  if (language === undefined) return ''
+  if (typeof language !== 'string' || language === '' || language === carryName) return undefined
+  if (/[`\n\r]/.test(language) || language !== language.trim() || holdsEntityReference(language)) return undefined
+  return language
 }
 
-function emitHeading(node: AdfNode, path: ConvertErrorPath): Result<string> {
-  const validation = validateBlockNode(node, ['level'], path)
-  if (!validation.ok) return validation
+function emitHeading(node: AdfNode, path: ConvertErrorPath): Result<EmittedBlock> | undefined {
+  if (!commonMarkHead(node, ['level'])) return undefined
   const level = node.attrs?.['level']
-  if (typeof level !== 'number' || !Number.isInteger(level) || level < 1 || level > 6) {
-    return failure('unsupported-heading-level', `no ATX heading spells level ${JSON.stringify(level ?? null)}`, path)
-  }
+  if (typeof level !== 'number' || !Number.isInteger(level) || level < 1 || level > 6) return undefined
   const hashes = '#'.repeat(level)
   const content = node.content ?? []
-  if (content.length === 0) return success(hashes)
+  if (content.length === 0) return success(commonMarkText(hashes))
   const line = emitInlineLine(content, 'heading', path)
   if (!line.ok) return line
-  return success(`${hashes} ${line.value}`)
+  return success(commonMarkText(`${hashes} ${line.value}`))
 }
 
-function emitList(node: AdfNode, path: ConvertErrorPath, depth: number): Result<EmittedBody> {
+function emitList(node: AdfNode, path: ConvertErrorPath, depth: number): Result<EmittedBlock> | undefined {
   const ordered = node.type === 'orderedList'
-  const validation = validateBlockNode(node, ordered ? ['order'] : [], path)
-  if (!validation.ok) return validation
+  if (!commonMarkHead(node, ordered ? ['order'] : [])) return undefined
   const items = node.content ?? []
-  const start = listStart(node, items.length, path)
-  if (!start.ok) return start
+  const start = listStart(node, items.length)
+  if (start === undefined || items.some((item) => !commonMarkHead(item, []))) return undefined
+  if (items.length === 0) return failure('unsupported-node-shape', `a ${node.type} holds at least one listItem`, path)
   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.value + offset}. ` : '- ', itemPath, depth)
+    const emitted = emitListItem(item, ordered ? `${start + offset}. ` : '- ', itemPath, depth)
     if (!emitted.ok) return emitted
     fenceColons = Math.max(fenceColons, emitted.value.fenceColons)
     lines.push(emitted.value.text)
   }
-  return success({ fenceColons, text: lines.join('\n') })
+  return success({ fenceColons, spelling: 'commonmark', text: lines.join('\n') })
 }
 
-function listStart(node: AdfNode, items: number, path: ConvertErrorPath): Result<number> {
-  if (items === 0) return failure('unsupported-node-shape', `a ${node.type} holds at least one listItem`, path)
-  if (node.type !== 'orderedList') return success(0)
+function listStart(node: AdfNode, items: number): number | undefined {
+  if (node.type !== 'orderedList') return 0
   const start = node.attrs?.['order']
-  if (start === undefined || start === 1) {
-    return failure('ambiguous-attribute-spelling', '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)
+  if (typeof start !== 'number' || !Number.isInteger(start) || start < 0 || start > largestListMarker) return undefined
+  return start + items - 1 > largestListMarker ? undefined : start
 }
 
 function emitListItem(item: AdfNode, marker: string, path: ConvertErrorPath, depth: number): Result<EmittedBody> {
-  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({ fenceColons: 0, text: marker.trimEnd() })
@@ -261,29 +249,20 @@ function emitListItem(item: AdfNode, marker: string, path: ConvertErrorPath, dep
   return success({ fenceColons: inner.value.fenceColons, text: lines.join('\n') })
 }
 
-function emitParagraph(node: AdfNode, path: ConvertErrorPath): Result<EmittedBlock> {
-  const validation = validateBlockNode(node, [], path)
-  if (!validation.ok) return validation
+function emitParagraph(node: AdfNode, path: ConvertErrorPath): Result<EmittedBlock> | undefined {
   const content = node.content ?? []
-  if (content.length === 0) return success({ fenceColons: 2, spelling: 'directive', text: '::paragraph' })
-  return commonMarkLine(emitInlineLine(content, 'paragraph', path))
+  if (content.length === 0 || !commonMarkHead(node, [])) return undefined
+  const line = emitInlineLine(content, 'paragraph', path)
+  if (!line.ok) return line
+  return success(commonMarkText(line.value))
 }
 
-function emitRule(node: AdfNode, path: ConvertErrorPath): Result<string> {
-  const validation = validateBlockNode(node, [], path)
-  if (!validation.ok) return validation
-  if ((node.content ?? []).length > 0) return failure('unsupported-node-shape', 'a rule holds no content', path)
-  return success('---')
+function emitRule(node: AdfNode): Result<EmittedBlock> | undefined {
+  if (!commonMarkHead(node, []) || (node.content ?? []).length > 0) return undefined
+  return success(commonMarkText('---'))
 }
 
-function validateBlockNode(node: AdfNode, spelled: readonly string[], path: ConvertErrorPath): Result<null> {
-  if ((node.marks ?? []).length > 0) {
-    return failure('unspelled-block-marks', `the canonical form has no place for the marks a ${node.type} carries`, path)
-  }
-  if (node.text !== undefined) return failure('unsupported-node-shape', `a ${node.type} carries no text`, path)
-  const unspelled = Object.keys(node.attrs ?? {}).find((key) => !spelled.includes(key))
-  if (unspelled !== undefined) {
-    return failure('unspelled-node-attribute', `the ${node.type} attribute ${unspelled} has no canonical markdown spelling`, path)
-  }
-  return success(null)
+function commonMarkHead(node: AdfNode, spelled: readonly string[]): boolean {
+  if ((node.marks ?? []).length > 0 || node.text !== undefined) return false
+  return Object.keys(node.attrs ?? {}).every((key) => spelled.includes(key))
 }

src/block-directives.ts

@@ -5,7 +5,7 @@ import { isBareToken, spellAttributes, spellJsonAttribute, vocabularyPairs } fro
 export type BlockDirective = {
   argument?: string
   attributes: AttributeVocabulary
-  body: 'block' | 'inline' | 'none'
+  body: 'block' | 'code' | 'inline' | 'none'
 }
 
 const cellAttributes: AttributeVocabulary = {
@@ -28,7 +28,7 @@ const extensionAttributes: AttributeVocabulary = {
   text: 'string',
 }
 
-const itemAttributes: AttributeVocabulary = { localId: 'string' }
+const localIdAttributes: AttributeVocabulary = { localId: 'string' }
 
 const mediaAttributes: AttributeVocabulary = {
   alt: 'string',
@@ -45,44 +45,55 @@ const mediaAttributes: AttributeVocabulary = {
 const syncBlockAttributes: AttributeVocabulary = { localId: 'string', resourceId: 'string' }
 
 const blockDirectives: Readonly<Record<string, BlockDirective>> = {
-  blockTaskItem: { argument: 'state', attributes: itemAttributes, body: 'block' },
+  blockTaskItem: { argument: 'state', attributes: localIdAttributes, body: 'block' },
+  blockquote: { attributes: localIdAttributes, body: 'block' },
   bodiedExtension: { attributes: extensionAttributes, body: 'block' },
   bodiedSyncBlock: { attributes: syncBlockAttributes, body: 'block' },
-  caption: { attributes: itemAttributes, body: 'inline' },
+  bulletList: { attributes: localIdAttributes, body: 'block' },
+  caption: { attributes: localIdAttributes, body: 'inline' },
+  codeBlock: {
+    attributes: { hideLineNumbers: 'boolean', language: 'string', localId: 'string', uniqueId: 'string', wrap: 'boolean' },
+    body: 'code',
+  },
   decisionItem: { attributes: { localId: 'string', state: 'string' }, body: 'inline' },
-  decisionList: { attributes: itemAttributes, body: 'block' },
+  decisionList: { attributes: localIdAttributes, body: 'block' },
   expand: { attributes: expandAttributes, body: 'block' },
   extension: { attributes: extensionAttributes, body: 'none' },
   extensionFrame: { attributes: {}, body: 'block' },
+  heading: { attributes: { level: 'number', localId: 'string' }, body: 'inline' },
   layoutColumn: { attributes: { localId: 'string', valign: 'string', width: 'number' }, body: 'block' },
-  layoutSection: { attributes: itemAttributes, body: 'block' },
+  layoutSection: { attributes: localIdAttributes, body: 'block' },
+  listItem: { attributes: localIdAttributes, body: 'block' },
   media: { attributes: mediaAttributes, body: 'none' },
   mediaGroup: { attributes: {}, body: 'block' },
   mediaSingle: { attributes: { layout: 'string', localId: 'string', width: 'number', widthType: 'string' }, body: 'block' },
   multiBodiedExtension: { attributes: extensionAttributes, body: 'block' },
   nestedExpand: { attributes: expandAttributes, body: 'block' },
+  orderedList: { attributes: { localId: 'string', order: 'number' }, body: 'block' },
   panel: {
     argument: 'panelType',
     attributes: { localId: 'string', panelColor: 'string', panelIcon: 'string', panelIconId: 'string', panelIconText: 'string' },
     body: 'block',
   },
+  paragraph: { attributes: localIdAttributes, body: 'inline' },
+  rule: { attributes: localIdAttributes, body: 'none' },
   syncBlock: { attributes: syncBlockAttributes, body: 'none' },
   table: { attributes: { displayMode: 'string', isNumberColumnEnabled: 'boolean', layout: 'string', localId: 'string', width: 'number' }, body: 'block' },
   tableCell: { attributes: cellAttributes, body: 'block' },
   tableHeader: { attributes: cellAttributes, body: 'block' },
-  tableRow: { attributes: itemAttributes, body: 'block' },
-  taskItem: { argument: 'state', attributes: itemAttributes, body: 'inline' },
-  taskList: { attributes: itemAttributes, body: 'block' },
+  tableRow: { attributes: localIdAttributes, body: 'block' },
+  taskItem: { argument: 'state', attributes: localIdAttributes, body: 'inline' },
+  taskList: { attributes: localIdAttributes, body: 'block' },
 }
 
 export function blockDirective(type: string): BlockDirective | undefined {
   return Object.hasOwn(blockDirectives, type) ? blockDirectives[type] : undefined
 }
 
-export function spellDirectiveHeader(node: AdfNode, directive: BlockDirective): string | undefined {
+export function spellDirectiveHeader(node: AdfNode, directive: BlockDirective, spelledByBody: readonly string[] = []): string | undefined {
   const argument = spellArgument(node, directive)
   if (argument === undefined) return undefined
-  const pairs = vocabularyPairs(node.attrs ?? {}, directive.attributes, directive.argument)
+  const pairs = vocabularyPairs(node.attrs ?? {}, directive.attributes, [directive.argument, ...spelledByBody])
   if (pairs === undefined) return undefined
   const marks = node.marks ?? []
   if (marks.length > 0) pairs.push(['marks', spellJsonAttribute(markValues(marks))])

src/directive-attributes.ts

@@ -11,10 +11,14 @@ export function isBareToken(text: string): boolean {
   return bareToken.test(text)
 }
 
-export function vocabularyPairs(attrs: AdfAttributes, vocabulary: AttributeVocabulary, slot: string | undefined): [string, string][] | undefined {
+export function vocabularyPairs(
+  attrs: AdfAttributes,
+  vocabulary: AttributeVocabulary,
+  spelledElsewhere: readonly (string | undefined)[],
+): [string, string][] | undefined {
   const pairs: [string, string][] = []
   for (const [key, value] of Object.entries(attrs)) {
-    if (key === slot) continue
+    if (spelledElsewhere.includes(key)) continue
     const kind = Object.hasOwn(vocabulary, key) ? vocabulary[key] : undefined
     if (kind === undefined) return undefined
     const spelled = spellAttributeValue(value, kind)

src/inline-directives.ts

@@ -13,6 +13,7 @@ export type MarkSpelling =
 const inlineDirectives: Readonly<Record<string, InlineDirective>> = {
   date: { attributes: { localId: 'string', timestamp: 'string' } },
   emoji: { attributes: { id: 'string', localId: 'string', shortName: 'string' }, slot: 'text' },
+  hardBreak: { attributes: { localId: 'string', text: 'string' } },
   inlineCard: { attributes: { data: 'json', localId: 'string', url: 'string' } },
   mediaInline: {
     attributes: {
@@ -52,11 +53,11 @@ export function markSpelling(type: string): MarkSpelling | undefined {
 }
 
 export function spellInlineNodeAttributes(node: AdfNode, directive: InlineDirective): string | undefined {
-  const pairs = vocabularyPairs(node.attrs ?? {}, directive.attributes, directive.slot)
+  const pairs = vocabularyPairs(node.attrs ?? {}, directive.attributes, [directive.slot])
   return pairs === undefined ? undefined : spellAttributes(pairs)
 }
 
 export function spellMarkAttributes(mark: AdfMark, vocabulary: AttributeVocabulary): string | undefined {
-  const pairs = vocabularyPairs(mark.attrs ?? {}, vocabulary, undefined)
+  const pairs = vocabularyPairs(mark.attrs ?? {}, vocabulary, [])
   return pairs === undefined ? undefined : spellAttributes(pairs)
 }

src/markdown-inline.ts

@@ -174,7 +174,7 @@ function nodePath(context: InlineContext, index: number): ConvertErrorPath {
 
 function carries(node: AdfNode, carried: ReadonlySet<number>, index: number): boolean {
   if (carried.has(index)) return true
-  return node.type !== 'hardBreak' && node.type !== 'text' && inlineDirective(node.type) === undefined
+  return node.type !== 'text' && inlineDirective(node.type) === undefined
 }
 
 function emitLeaf(node: AdfNode, context: InlineContext, index: number): Result<Emission> {
@@ -187,18 +187,18 @@ function emitLeaf(node: AdfNode, context: InlineContext, index: number): Result<
   const types = (node.marks ?? []).map((mark) => mark.type)
   if (new Set(types).size !== types.length) return failure('unsupported-node-shape', `a ${node.type} node carries one mark type twice`, path)
   const directive = inlineDirective(node.type)
-  if (directive !== undefined) return emitInlineDirective(node, directive, index, path)
-  if (node.type === 'hardBreak') return emitHardBreak(node, context, path)
-  return emitText(node, context, path)
+  if (directive === undefined) return emitText(node, context, path)
+  if (node.type === 'hardBreak') return emitHardBreak(node, directive, context, index, path)
+  return emitInlineDirective(node, directive, index, path)
 }
 
-function emitHardBreak(node: AdfNode, context: InlineContext, path: ConvertErrorPath): Result<Emission> {
-  const unspelled = Object.keys(node.attrs ?? {})[0]
-  if (unspelled !== undefined) return failure('unspelled-node-attribute', `the hardBreak attribute ${unspelled} has no canonical markdown spelling`, path)
+function emitHardBreak(node: AdfNode, directive: InlineDirective, context: InlineContext, index: number, path: ConvertErrorPath): Result<Emission> {
   const empty = refuseContentAndText(node, path)
   if (!empty.ok) return empty
-  if (context.spansLines && !context.atBlockEnd) return success({ segments: [syntax('\\\n')] })
-  return success({ segments: [syntax(spellLeafDirective('hardBreak', ''))] })
+  const attributes = spellInlineNodeAttributes(node, directive)
+  if (attributes === undefined) return success({ carry: { first: index, last: index } })
+  if (attributes === '' && context.spansLines && !context.atBlockEnd) return success({ segments: [syntax('\\\n')] })
+  return success({ segments: [syntax(spellLeafDirective('hardBreak', attributes))] })
 }
 
 function emitInlineDirective(node: AdfNode, directive: InlineDirective, index: number, path: ConvertErrorPath): Result<Emission> {

src/result.ts

@@ -1,19 +1,14 @@
 export type ConvertErrorCode =
-  | 'ambiguous-attribute-spelling'
   | 'not-an-adf-document'
   | 'unspellable-adjacent-lists'
   | 'unspellable-character'
-  | 'unspellable-code-block-language'
   | 'unspellable-line-start'
   | 'unspellable-link-destination'
   | 'unspellable-link-title'
-  | 'unspellable-list-marker'
   | 'unspellable-whitespace'
-  | 'unspelled-block-marks'
   | 'unspelled-block-separation'
   | 'unspelled-node-attribute'
   | 'unsupported-document-version'
-  | 'unsupported-heading-level'
   | 'unsupported-node-shape'
 
 export type ConvertErrorPath = readonly (number | string)[]