3
0
mirror of https://github.com/larvit/adf-codec.git synced 2026-11-19 22:55:44 +01:00

Write a block's localId as an !adf:{…} marker beside its CommonMark spelling

This commit is contained in:
2026-11-19 16:46:13 +01:00
committed by Lillem4n
parent 67787d2ec0
commit ee00d2c859
11 changed files with 760 additions and 101 deletions
+223
View File
@@ -0,0 +1,223 @@
import assert from 'node:assert/strict'
import test from 'node:test'
import type { AdfAttributes, AdfDocument, AdfMark, AdfNode } from '../../adf/document.ts'
import type { ConvertErrorCode, ParseError, Result, SourcePosition } from '../../result.ts'
import { adfToLosslessMarkdown, adfToPortableMarkdown, commonMarkToAdf, losslessMarkdownToAdf, portableMarkdownToAdf } from '../../index.ts'
function document(...content: AdfNode[]): AdfDocument {
return { content, type: 'doc', version: 1 }
}
function text(value: string, ...marks: AdfMark[]): AdfNode {
return marks.length === 0 ? { text: value, type: 'text' } : { marks, text: value, type: 'text' }
}
function node(type: string, attrs: AdfAttributes, ...content: AdfNode[]): AdfNode {
const built: AdfNode = Object.keys(attrs).length === 0 ? { type } : { attrs, type }
return content.length === 0 ? built : { ...built, content }
}
function said(localId: string | undefined, value: string): AdfNode {
return node('paragraph', localId === undefined ? {} : { localId }, text(value))
}
function written(result: Result<string>): string {
return result.ok ? result.value : `${result.error.code}: ${result.error.message}`
}
function read(result: Result<AdfDocument, ParseError>): AdfNode[] | string {
return result.ok ? (result.value.content ?? []) : `${result.error.code}: ${result.error.message}`
}
function spells(content: AdfNode[], markdown: string): void {
assert.equal(written(adfToLosslessMarkdown(document(...content))), markdown)
assert.deepEqual(read(losslessMarkdownToAdf(markdown)), content)
}
function refused(markdown: string, code: ConvertErrorCode, at: SourcePosition, ...facts: string[]): void {
const result = losslessMarkdownToAdf(markdown)
assert.equal(result.ok ? `built ${JSON.stringify(result.value)}` : result.error.code, code, markdown)
if (result.ok) return
assert.deepEqual(result.error.position, at, markdown)
for (const fact of facts) assert.ok(result.error.message.includes(fact), `${JSON.stringify(result.error.message)} names ${fact}`)
}
const jiraDescription = [
node('heading', { level: 2, localId: 'a1b2c3d40001' }, text('Background')),
node('paragraph', { localId: 'a1b2c3d40002' }, text('Exports time out for accounts with more than '), text('10 000', { type: 'strong' }), text(' rows.')),
node('heading', { level: 2, localId: 'a1b2c3d40003' }, text('Acceptance criteria')),
node(
'bulletList',
{ localId: 'a1b2c3d40008' },
node('listItem', { localId: 'a1b2c3d40005' }, said('a1b2c3d40004', 'An export of 50 000 rows finishes within 30 seconds.')),
node('listItem', { localId: 'a1b2c3d40007' }, said('a1b2c3d40006', 'The user sees progress while it runs.')),
),
node('panel', { localId: 'a1b2c3d40009', panelType: 'warning' }, said('a1b2c3d4000a', "Don't change the CSV column order.")),
]
test('writes a Jira description in CommonMark, each id in a marker, and the panel alone as a directive', () => {
spells(
jiraDescription,
[
'## Background !adf:{localId=a1b2c3d40001}',
'',
'!adf:{localId=a1b2c3d40002}',
'Exports time out for accounts with more than **10 000** rows.',
'',
'## Acceptance criteria !adf:{localId=a1b2c3d40003}',
'',
'!adf:{localId=a1b2c3d40008}',
'- !adf:{localId=a1b2c3d40005} An export of 50 000 rows finishes within 30 seconds. !adf:{localId=a1b2c3d40004}',
'- !adf:{localId=a1b2c3d40007} The user sees progress while it runs. !adf:{localId=a1b2c3d40006}',
'',
'!adf:panel warning {localId=a1b2c3d40009}',
'!adf:{localId=a1b2c3d4000a}',
"Don't change the CSV column order.",
'!adf:/panel',
'',
].join('\n'),
)
})
test('writes a paragraph id on the line above it, and on the end of the last line where the paragraph opens a quote or a list item', () => {
spells([node('paragraph', { localId: 'p1' }, text('first line'), { type: 'hardBreak' }, text('second line'))], '!adf:{localId=p1}\nfirst line\\\nsecond line\n')
spells([node('blockquote', { localId: 'q1' }, said('p3', 'Quoted text'), said('p4', 'More'))], '!adf:{localId=q1}\n> Quoted text !adf:{localId=p3}\n>\n> !adf:{localId=p4}\n> More\n')
spells([node('blockquote', {}, node('paragraph', { localId: 'p3' }, text('a'), { type: 'hardBreak' }, text('b')))], '> a\\\n> b !adf:{localId=p3}\n')
spells([node('bulletList', {}, node('listItem', {}, said('p1', 'First item'), said('p2', 'More')))], '- First item !adf:{localId=p1}\n\n !adf:{localId=p2}\n More\n')
})
test('writes a heading id at the end of its line, wherever the heading stands', () => {
spells([node('heading', { level: 2, localId: 'h1' }, text('Background'))], '## Background !adf:{localId=h1}\n')
spells([node('blockquote', {}, said(undefined, 'a'), node('heading', { level: 1, localId: 'h 2' }, text('b')))], '> a\n>\n> # b !adf:{localId="h 2"}\n')
spells([node('bulletList', {}, node('listItem', {}, node('heading', { level: 3, localId: 'h3' }, text('c'))))], '- ### c !adf:{localId=h3}\n')
})
test('writes a list id on the line above the list, and each item id after its marker', () => {
const items = [node('listItem', { localId: 'i1' }, said('p1', 'First item')), node('listItem', { localId: 'i2' }, said(undefined, 'Second item'))]
spells([node('bulletList', { localId: 'l1' }, ...items)], '!adf:{localId=l1}\n- !adf:{localId=i1} First item !adf:{localId=p1}\n- !adf:{localId=i2} Second item\n')
spells([node('orderedList', { localId: 'l1', order: 1 }, ...items)], '!adf:{localId=l1}\n1. !adf:{localId=i1} First item !adf:{localId=p1}\n2. !adf:{localId=i2} Second item\n')
spells([node('orderedList', { localId: 'l1', order: 2 }, ...items)], '!adf:{localId=l1}\n\n2. !adf:{localId=i1} First item !adf:{localId=p1}\n3. !adf:{localId=i2} Second item\n')
spells([node('bulletList', {}, node('listItem', {}, said(undefined, 'a'), node('bulletList', { localId: 'l2' }, node('listItem', {}, said(undefined, 'b')))))], '- a\n !adf:{localId=l2}\n - b\n')
const list = node('bulletList', {}, node('listItem', {}, said(undefined, 'a')))
spells([list, node('bulletList', { localId: 'l2' }, node('listItem', {}, said(undefined, 'b')))], '- a\n\n!adf:{localId=l2}\n* b\n')
spells([node('bulletList', { localId: 'l3' }, node('listItem', {}), node('listItem', {}, said(undefined, 'b')))], '!adf:{localId=l3}\n\n-\n- b\n')
})
test('writes a quote, code block and rule id on the line above, a blank line parting it from the rule', () => {
spells([node('blockquote', { localId: 'q1' }, said(undefined, 'a'))], '!adf:{localId=q1}\n> a\n')
spells([node('codeBlock', { language: 'rust', localId: 'c1' }, text('fn main() {}'))], '!adf:{localId=c1}\n```rust\nfn main() {}\n```\n')
spells([node('rule', { localId: 'r1' })], '!adf:{localId=r1}\n\n---\n')
spells([node('blockquote', {}, node('codeBlock', { localId: 'c1' }, text('x')))], '> !adf:{localId=c1}\n> ```\n> x\n> ```\n')
})
test('keeps the directive form where an id has no place beside the CommonMark spelling, or the node carries more', () => {
spells([node('paragraph', { localId: 'p1' })], '!adf:paragraph {localId=p1}\n!adf:/paragraph\n')
spells([node('heading', { level: 1, localId: 'h1' })], '!adf:heading {level=1 localId=h1}\n!adf:/heading\n')
spells([{ attrs: { localId: 'p1' }, content: [text('a')], marks: [{ attrs: { align: 'center' }, type: 'alignment' }], type: 'paragraph' }], '!adf:paragraph {localId=p1 marks="alignment{align=center}"}\na\n!adf:/paragraph\n')
spells([node('rule', { localId: 'r1', style: 'dashed' })], '!adf:rule {localId=r1 style=dashed}\n')
spells([node('bulletList', {}, node('listItem', {}, node('codeBlock', { localId: 'c1' }, text('x'))))], '!adf:bulletList\n!adf:listItem\n!adf:{localId=c1}\n```\nx\n```\n!adf:/listItem\n!adf:/bulletList\n')
spells([node('bulletList', {}, node('listItem', { localId: 'i1' }, node('heading', { level: 1 }, text('h'))))], '!adf:bulletList\n!adf:listItem {localId=i1}\n# h\n!adf:/listItem\n!adf:/bulletList\n')
spells([node('bulletList', { localId: 'l1' }, node('listItem', { localId: 'i1' }), node('listItem', {}, said('p1', 'b')))], '!adf:bulletList {localId=l1}\n!adf:listItem {localId=i1}\n!adf:/listItem\n!adf:listItem\n!adf:{localId=p1}\nb\n!adf:/listItem\n!adf:/bulletList\n')
})
test('escapes a literal text spelling a marker, and spells an id holding one in quotes', () => {
spells([said(undefined, 'a !adf:{localId=x}')], 'a \\!adf:{localId=x}\n')
spells([said(undefined, '!adf:{localId=x}')], '\\!adf:{localId=x}\n')
spells([node('blockquote', {}, said('p', 'a !adf:{localId=x}'))], '> a \\!adf:{localId=x} !adf:{localId=p}\n')
spells([node('blockquote', {}, said(' !adf:{x=y}', 'a'))], '> a !adf:{localId=" !adf:{x=y}"}\n')
spells([node('heading', { level: 1, localId: '' }, text('a'))], '# a !adf:{localId=""}\n')
})
test('reads the directive form 0.3 wrote for a node holding only an id', () => {
const directives = [
'!adf:heading {level=2 localId=a1b2c3d40001}', 'Background', '!adf:/heading', '',
'!adf:paragraph {localId=a1b2c3d40002}', 'Exports time out for accounts with more than **10 000** rows.', '!adf:/paragraph', '',
'!adf:heading {level=2 localId=a1b2c3d40003}', 'Acceptance criteria', '!adf:/heading', '',
'!adf:bulletList {localId=a1b2c3d40008}',
'!adf:listItem {localId=a1b2c3d40005}', '!adf:paragraph {localId=a1b2c3d40004}', 'An export of 50 000 rows finishes within 30 seconds.', '!adf:/paragraph', '!adf:/listItem',
'!adf:listItem {localId=a1b2c3d40007}', '!adf:paragraph {localId=a1b2c3d40006}', 'The user sees progress while it runs.', '!adf:/paragraph', '!adf:/listItem',
'!adf:/bulletList', '',
'!adf:panel warning {localId=a1b2c3d40009}', '!adf:paragraph {localId=a1b2c3d4000a}', "Don't change the CSV column order.", '!adf:/paragraph', '!adf:/panel', '',
]
assert.deepEqual(read(losslessMarkdownToAdf(directives.join('\n'))), jiraDescription)
assert.deepEqual(read(losslessMarkdownToAdf('!adf:bulletList\n!adf:listItem {localId=i1}\na\n!adf:/listItem\n!adf:/bulletList\n')), [node('bulletList', {}, node('listItem', { localId: 'i1' }, said(undefined, 'a')))])
assert.deepEqual(read(losslessMarkdownToAdf('!adf:orderedList {localId=l1 order=3}\n!adf:listItem\na\n!adf:/listItem\n!adf:/orderedList\n')), [node('orderedList', { localId: 'l1', order: 3 }, node('listItem', {}, said(undefined, 'a')))])
assert.deepEqual(read(losslessMarkdownToAdf('!adf:blockquote {localId=q1}\na\n!adf:/blockquote\n')), [node('blockquote', { localId: 'q1' }, said(undefined, 'a'))])
assert.deepEqual(read(losslessMarkdownToAdf('!adf:codeBlock {localId=c1}\n```rust\nx\n```\n!adf:/codeBlock\n')), [node('codeBlock', { language: 'rust', localId: 'c1' }, text('x'))])
assert.deepEqual(read(losslessMarkdownToAdf('!adf:rule {localId=r1}\n')), [node('rule', { localId: 'r1' })])
assert.deepEqual(read(losslessMarkdownToAdf('- !adf:paragraph {localId=p1}\n a\n !adf:/paragraph\n')), [node('bulletList', {}, node('listItem', {}, said('p1', 'a')))])
})
test('names a marker with no block below it to carry its id', () => {
refused('!adf:{localId=p}\n', 'malformed-directive', { line: 1, offset: 0 }, 'no block')
refused('Part.\n\n> !adf:{localId=p}\n', 'malformed-directive', { line: 3, offset: 7 }, 'no block')
refused('!adf:{localId=p}\n!adf:{localId=q}\nPart.\n', 'malformed-directive', { line: 2, offset: 17 }, 'two')
})
test('names the blank line a marker and its block keep or leave out', () => {
refused('!adf:{localId=p}\n\nPart.\n', 'malformed-directive', { line: 1, offset: 0 }, 'right above')
refused('!adf:{localId=r}\n---\n', 'malformed-directive', { line: 1, offset: 0 }, 'blank line')
refused('!adf:{localId=l}\n2. a\n', 'malformed-directive', { line: 1, offset: 0 }, 'blank line')
})
test('names the block a marker line stands above that carries its id another way, or not at all', () => {
refused('!adf:{localId=h}\n# Part\n', 'unsupported-node-shape', { line: 1, offset: 0 }, 'heading', 'end of its line')
refused('> !adf:{localId=p}\n> Part.\n', 'unsupported-node-shape', { line: 1, offset: 0 }, 'end of its last line')
refused('- !adf:{localId=p}\n Part.\n', 'unsupported-node-shape', { line: 1, offset: 0 }, 'list item')
refused('!adf:{localId=t}\n| a |\n| - |\n', 'unsupported-node-shape', { line: 1, offset: 0 }, 'table')
refused('!adf:{localId=x}\n!adf:panel info\n!adf:/panel\n', 'unsupported-node-shape', { line: 1, offset: 0 }, 'panel')
refused('!adf:{localId=x}\n```adf:blockCard\n{}\n```\n', 'unsupported-node-shape', { line: 1, offset: 0 }, 'blockCard')
refused('!adf:{localId=x}\n![a](/u)\n', 'unsupported-node-shape', { line: 1, offset: 0 }, 'mediaSingle')
})
test('names a trailing marker standing where the id takes the line above, or on no CommonMark spelling', () => {
refused('Part !adf:{localId=p}\n', 'unsupported-node-shape', { line: 1, offset: 0 }, 'line above')
refused('> a\n>\n> Part !adf:{localId=p}\n', 'unsupported-node-shape', { line: 3, offset: 6 }, 'line above')
refused('!adf:paragraph {localId=p}\nPart !adf:{localId=q}\n!adf:/paragraph\n', 'unsupported-node-shape', { line: 2, offset: 27 }, 'directive')
refused('!adf:{localId=a}\nPart !adf:{localId=b}\n', 'malformed-directive', { line: 2, offset: 17 }, 'two')
refused('> Part !adf:{localId=p}\n', 'malformed-directive', { line: 1, offset: 0 }, 'one space')
refused('## Part\t!adf:{localId=h}\n', 'malformed-directive', { line: 1, offset: 0 }, 'completes no directive')
})
test('reads a trailing marker ahead of the link reference definitions and the setext underline its paragraph holds', () => {
refused('> [a]: /u !adf:{localId=p}\n', 'malformed-directive', { line: 1, offset: 0 }, 'link reference definitions')
refused('[a]: /u !adf:{localId=h}\n===\n', 'malformed-directive', { line: 1, offset: 0 }, 'link reference definitions')
assert.deepEqual(read(losslessMarkdownToAdf('Part !adf:{localId=h}\n===\n')), [node('heading', { level: 1, localId: 'h' }, text('Part'))])
assert.deepEqual(read(losslessMarkdownToAdf('> [a]: /u\n> Part !adf:{localId=p}\n')), [node('blockquote', {}, said('p', 'Part'))])
})
test('names an item marker standing before no paragraph', () => {
refused('- !adf:{localId=i} # Part\n', 'unsupported-node-shape', { line: 1, offset: 0 }, 'paragraph')
refused('- !adf:{localId=i} ![a](/u)\n', 'unsupported-node-shape', { line: 1, offset: 0 }, 'paragraph')
})
test('names a marker spelled outside its one canonical form', () => {
refused('!adf:{localId="p"}\nPart.\n', 'unsupported-node-shape', { line: 1, offset: 0 }, 'localId=p')
refused('!adf:{level=2}\nPart.\n', 'unsupported-node-shape', { line: 1, offset: 0 }, 'localId alone', 'level')
refused('!adf:{}\nPart.\n', 'unsupported-node-shape', { line: 1, offset: 0 }, 'localId alone')
refused('- !adf:{localId=i style=x} Part\n', 'unsupported-node-shape', { line: 1, offset: 0 }, 'localId alone', 'style')
refused('# Part !adf:{localId="h"}\n', 'unsupported-node-shape', { line: 1, offset: 0 }, 'localId=h')
refused('!adf:{localId=p b=1}\nPart.\n', 'malformed-directive', { line: 1, offset: 0 }, 'alphabetical')
refused('!adf:{localId=p} Part.\n', 'malformed-directive', { line: 1, offset: 0 }, 'alone on its line')
})
test('leaves a marker the text it is in the readers claiming no directive, and writes none there', () => {
assert.deepEqual(read(portableMarkdownToAdf('!adf:{localId=p}\nPart.\n')), [said(undefined, '!adf:{localId=p} Part.')])
assert.deepEqual(read(commonMarkToAdf('- !adf:{localId=i} Part !adf:{localId=p}\n')), [node('bulletList', {}, node('listItem', {}, said(undefined, '!adf:{localId=i} Part !adf:{localId=p}')))])
assert.equal(written(adfToPortableMarkdown(document(...jiraDescription))), [
'## Background',
'',
'Exports time out for accounts with more than **10 000** rows.',
'',
'## Acceptance criteria',
'',
'- An export of 50 000 rows finishes within 30 seconds.',
'- The user sees progress while it runs.',
'',
'> [!WARNING]',
'>',
"> Don't change the CSV column order.",
'',
].join('\n'))
})
+55
View File
@@ -0,0 +1,55 @@
import type { ConvertErrorPath, Read, Result } from '../../result.ts'
import type { DirectiveAttributes } from './syntax.ts'
import { directivePrefix, malformedDirective, markerOpener, pairFault, readAttributes, spellAttributes, spellStringAttribute } from './syntax.ts'
import { failure, success } from '../../result.ts'
// spec/flavour.md, The CommonMark blocks: text is what the line keeps once the marker after it is read.
export type TrailingMarker = { attributes: Read<DirectiveAttributes>; text: string }
export const idKey = 'localId'
const blankToEnd = /[ \t]*$/y
const trailingOpener = ` ${markerOpener}`
export function spellIdAttributes(id: string | undefined): string {
return spellAttributes(id === undefined ? [] : [[idKey, spellStringAttribute(id)]])
}
export function spellIdMarker(id: string): string {
return `${directivePrefix}${spellIdAttributes(id)}`
}
// A quoted id may hold the opener, so the marker is the last opener whose attributes end the text; one at the start would trail nothing.
export function readTrailingMarker(text: string): TrailingMarker | undefined {
for (let start = text.lastIndexOf(trailingOpener); start > 0; start = text.lastIndexOf(trailingOpener, start - 1)) {
const read = readAttributes(text, start + trailingOpener.length - 1, pairFault)
if (read.fault !== undefined) continue
blankToEnd.lastIndex = read.value.end
if (!blankToEnd.test(text)) continue
const kept = text.slice(0, start)
const parted = kept.endsWith(' ') || kept.endsWith('\t')
return { attributes: parted ? { fault: malformedDirective(`one space parts an ${markerOpener}…} marker from the text before it: this one is parted by more`) } : { value: read.value.attributes }, text: kept }
}
return undefined
}
// The marker after a list item's marker, and the rest of the line after the one space following it; `undefined` where none stands there.
export function readItemMarker(text: string): { attributes: DirectiveAttributes; rest: number } | undefined {
if (!text.startsWith(markerOpener)) return undefined
const read = readAttributes(text, directivePrefix.length, pairFault)
if (read.fault !== undefined || text.charAt(read.value.end) !== ' ') return undefined
const next = text.charAt(read.value.end + 1)
return next === '' || next === ' ' || next === '\t' ? undefined : { attributes: read.value.attributes, rest: read.value.end + 1 }
}
export function readMarkerId(attributes: DirectiveAttributes, type: string, path: ConvertErrorPath): Result<string> {
const spelled = attributes.get(idKey)
if (spelled === undefined || attributes.size !== 1) {
let other = 'nothing'
for (const key of attributes.keys()) if (key !== idKey) other = key
return failure('unsupported-node-shape', `an ${markerOpener}…} marker carries ${idKey} alone: this one on a ${type} carries ${other}; write the ${type} as its directive to carry more`, path)
}
const spelling = spellStringAttribute(spelled.decoded)
if (spelling !== spelled.spelling) return failure('unsupported-node-shape', `${type} spells its ${idKey} attribute as ${idKey}=${spelling}`, path)
return success(spelled.decoded)
}
+16 -3
View File
@@ -24,6 +24,7 @@ export type DirectiveAttributes = ReadonlyMap<string, DirectiveValue>
export type DirectiveLine =
| { argument: string | undefined; attributes: DirectiveAttributes; kind: 'opener'; name: string }
| { attributes: DirectiveAttributes; kind: 'marker' }
| { kind: 'closer'; name: string }
// spans keys index content, so the two travel together: separate them and every offset is wrong.
@@ -39,13 +40,16 @@ type DirectiveContent = { end: number; spans: NestedSpans }
export const directivePrefix = '!adf:'
// spec/flavour.md, The CommonMark blocks: the nameless attribute block carrying an id beside a CommonMark spelling.
export const markerOpener = `${directivePrefix}{`
const claimedPrefix: unique symbol = Symbol('claimed prefix')
const bareTokenSource = '[A-Za-z0-9_-]+'
const bareRun = new RegExp(bareTokenSource, 'y')
const bareToken = new RegExp(`^${bareTokenSource}$`)
const directiveName = /[a-z][A-Za-z0-9]*/y
const inlineDirectiveOpener = new RegExp(`${directivePrefix}[a-z][A-Za-z0-9]*[[{]`, 'y')
const lineEnd = /^[ \t]*$/
export const lineEnd = /^[ \t]*$/
// A quoted value spells these as \uXXXX: CommonMark binds a code span, entity, HTML tag or pipe cell before a directive.
const reservedSource = '[&<`|]'
const quotedEscapes = new RegExp(reservedSource, 'g')
@@ -61,8 +65,9 @@ export const directiveEscape = `\\${directivePrefix} keeps the prefix literal`
const closerFault = `a closer carries nothing after its name: this one does; ${directiveEscape}`
const emptyFault = 'an empty {attrs} is omitted unless the { itself claims the directive: this one spells {}'
const openerFault = `a directive opener reads a name, one bare argument and {attrs}, one space apart: this one does not; ${directiveEscape}`
const markerFault = `an ${markerOpener}…} marker stands alone on its line, after a list item's marker or at the end of a paragraph's or heading's last line: this one does not; ${directiveEscape}`
const orderFault = 'the {attrs} keys read in alphabetical order'
const pairFault = `${attributePairCause}; ${directiveEscape}`
export const pairFault = `${attributePairCause}; ${directiveEscape}`
const prefixFault = `an unescaped ${directivePrefix} completes no directive; ${directiveEscape}`
export function attributeValue(text: string, kind: AttributeKind): AttributeReading {
@@ -102,7 +107,9 @@ export function malformedDirective(message: string): ConvertFault {
export function readDirectiveLine(line: string): Read<DirectiveLine> | undefined {
if (!claimsDirectivePrefix(line, 0)) return undefined
return line.charAt(directivePrefix.length) === '/' ? readCloserLine(line) : readOpenerLine(line)
const form = line.charAt(directivePrefix.length)
if (form === '{') return readMarkerLine(line)
return form === '/' ? readCloserLine(line) : readOpenerLine(line)
}
export function readInlineDirective(inline: InlineSource, prefix: ClaimedPrefix): Read<DirectiveSpan> {
@@ -204,6 +211,12 @@ function readCloserLine(line: string): Read<DirectiveLine> | undefined {
return lineEnd.test(line.slice(start + name.length)) ? { value: { kind: 'closer', name } } : { fault: malformedDirective(closerFault) }
}
function readMarkerLine(line: string): Read<DirectiveLine> {
const read = readAttributes(line, directivePrefix.length, pairFault)
if (read.fault !== undefined) return read
return lineEnd.test(line.slice(read.value.end)) ? { value: { attributes: read.value.attributes, kind: 'marker' } } : { fault: malformedDirective(markerFault) }
}
function readOpenerLine(line: string): Read<DirectiveLine> | undefined {
const name = readDirectiveName(line, directivePrefix.length)
if (name === undefined) return undefined
+96 -40
View File
@@ -11,15 +11,16 @@ import { fencedCodeBlock } from '../commonmark/backtick-runs.ts'
import { flavourClaims } from '../flavour.ts'
import { holdsNullCharacter, markerInterruptsParagraph } from '../commonmark/grammar.ts'
import { holdsOnlyAttributes, isUnmarkedSpellableText, nodeAttrs, nodeContent, readAdfDocument, writableContent } from '../../adf/document.ts'
import { idKey, spellIdAttributes, spellIdMarker } from '../directive/id-marker.ts'
import { languageSlot, type LanguageSlot } from '../code-language.ts'
import { largestNesting } from '../../nesting.ts'
import { markerOpener, spellDirectiveCloser, spellDirectiveOpener } from '../directive/syntax.ts'
import { withinEngineLimits, withinLongest } from '../../length-bound.ts'
import { spellBlockDirectiveOpener } from '../directive/block-spelling.ts'
import { spellDirectiveCloser, spellDirectiveOpener } from '../directive/syntax.ts'
import { tryImage } from './image.ts'
import { tryPipeTable } from './pipe-table.ts'
type BlockContainer = 'directive' | 'document' | 'list-item'
type BlockContainer = 'directive' | 'document' | 'list-item' | 'quote'
type Delimiters = readonly [string, string]
// headroom: the nesting levels the deepest node below may still spend before `largestNesting` refuses it.
export type EmittedBlock = SpelledBlock & { headroom: number }
@@ -32,19 +33,17 @@ export type FlavourBlockWriters = {
type KeptSpelling = { block: EmittedBlock | undefined; depth: number }
export type PlacedBlock = SpelledBlock & { node: AdfNode }
export type PlacedBlocks = { blocks: readonly PlacedBlock[]; headroom: number }
// CommonMark starts a new list where the marker changes, so every second list in a run of one kind takes `alternateText`.
type SpelledBlock = { spelling: 'commonmark' | 'directive'; text: BlockText } | { alternateText: BlockText; interruptsParagraph: boolean; ordered: boolean; spelling: 'list'; text: BlockText }
// CommonMark starts a new list where the marker changes, so every second list in a run of one kind takes `alternateText`; `trailing` is a paragraph's spelling with its id at the end, where it opens a quote or a list item.
type SpelledBlock = { spelling: 'commonmark' | 'directive'; text: BlockText; trailing?: BlockText } | { alternateText: BlockText; interruptsParagraph: boolean; ordered: boolean; spelling: 'list'; text: BlockText }
type Spell = () => Result<EmittedBlock> | undefined
// take: read and drop the node's kept spelling, else spell it; ask: as take, keeping a fresh spelling unless refused.
export type SpellingMemo = Readonly<Record<'ask' | 'take', (node: AdfNode, depth: number, spell: Spell) => Result<EmittedBlock> | undefined>>
type WalkedItem = { node: AdfNode; walk: PlacedBlocks }
type WalkedItem = { id: MarkedId; node: AdfNode; walk: PlacedBlocks }
export type WrittenAs = { flavour: 'lossless' } | { blocks: FlavourBlockWriters; flavour: 'portable' }
export type Writing = WrittenAs & { memo: SpellingMemo | undefined }
const bulletDelimiters: Delimiters = ['-', '*']
export const largestListMarker = 999999999
// Bare because tryList admits no item carrying attributes, marks or text.
const listItemOpener = spellDirectiveOpener('listItem', undefined, '')
const orderedDelimiters: Delimiters = ['.', ')']
export function adfToLosslessMarkdown(document: AdfDocument): Result<string> {
@@ -96,11 +95,16 @@ export function joinBlocks(blocks: readonly PlacedBlock[], container: BlockConta
const previous = blocks[index - 1]
if (previous !== undefined && blankLineBetween(previous, block, container)) parts.push(emptyLine)
alternated = !alternated && previous !== undefined && sharesMarker(previous, block)
parts.push(alternated && block.spelling === 'list' ? block.alternateText : block.text)
parts.push(blockSpelling(block, alternated, index === 0 && (container === 'list-item' || container === 'quote')))
}
return joinedText(parts)
}
function blockSpelling(block: PlacedBlock, alternated: boolean, opensContainer: boolean): BlockText {
if (block.spelling === 'list') return alternated ? block.alternateText : block.text
return opensContainer ? (block.trailing ?? block.text) : block.text
}
function sharesMarker(previous: PlacedBlock, next: PlacedBlock): boolean {
return previous.spelling === 'list' && next.spelling === 'list' && previous.ordered === next.ordered
}
@@ -164,12 +168,15 @@ type ReadableSpelling = {
const readableSpellings: ReadonlyMap<string, ReadableSpelling> = new Map<string, ReadableSpelling>([
['blockquote', {
describe: () => 'each line behind `> `',
spell: (node, path, depth, writing) => holdsOnlyAttributes(node, []) ? quotedBlocks(node, path, depth, writing, (body) => alertEscaped(body, writing)) : undefined,
spell: (node, path, depth, writing) => {
const id = markedId(node, [], writing.flavour)
return id === undefined ? undefined : quotedBlocks(node, path, depth, writing, (body) => alertEscaped(body, writing), id)
},
}],
['bulletList', { describe: () => 'each item behind `- `, or behind `* ` where the list right before it takes `- `', spell: tryList }],
['codeBlock', {
describe: () => 'its text in a fence of more backticks than any run it holds, its language after the opening fence',
spell: (node, _path, _depth, writing) => readableText(tryCodeBlock(node, writing.flavour)),
spell: (node, _path, _depth, writing) => readableLines(tryCodeBlock(node, writing.flavour)),
}],
['heading', { describe: () => 'one `#` per level before its text, `## Title` at level 2', spell: (node, path, _depth, writing) => tryHeading(node, path, writing.flavour) }],
['mediaSingle', {
@@ -184,7 +191,7 @@ const readableSpellings: ReadonlyMap<string, ReadableSpelling> = new Map<string,
spell: tryList,
}],
['paragraph', { describe: () => 'its text alone', spell: (node, path, _depth, writing) => tryParagraph(node, path, writing.flavour) }],
['rule', { describe: () => '`---`', spell: (node) => readableText(tryRule(node)) }],
['rule', { describe: () => '`---`', spell: (node, _path, _depth, writing) => readableLines(tryRule(node, writing.flavour)) }],
['table', { describe: () => 'a pipe table', spell: (node, path, _depth, writing) => readableText(tryPipeTable(node, path, writing.flavour)) }],
])
@@ -199,7 +206,11 @@ function spellReadableBlock(node: AdfNode, path: ConvertErrorPath, depth: number
}
function readableText(text: string | undefined): Result<EmittedBlock> | undefined {
return text === undefined ? undefined : success(commonMarkText(blockText(text)))
return readableLines(text === undefined ? undefined : blockText(text))
}
function readableLines(text: BlockText | undefined): Result<EmittedBlock> | undefined {
return text === undefined ? undefined : success(commonMarkText(text))
}
function carriedFence(carried: Result<{ headroom: number; text: string }>): Result<EmittedBlock> {
@@ -241,19 +252,41 @@ function alertEscaped(body: BlockText, writing: Writing): BlockText {
}
// Quote spellers call this directly, never through a wrapper: each frame a quote level adds lowers the depth the stack holds (docs/decisions.md §Nothing recurses unbounded).
export function quotedBlocks(node: AdfNode, path: ConvertErrorPath, depth: number, writing: Writing, bodyText: (body: BlockText) => BlockText): Result<EmittedBlock> {
export function quotedBlocks(node: AdfNode, path: ConvertErrorPath, depth: number, writing: Writing, bodyText: (body: BlockText) => BlockText, id: MarkedId = { id: undefined }): Result<EmittedBlock> {
const inner = walkBlocks(nodeContent(node), path, depth + 1, writing)
if (!inner.ok) return inner
return success(commonMarkText(quotedText(bodyText(joinBlocks(inner.value.blocks, 'document'))), inner.value.headroom))
return success(commonMarkText(markedLines(id, quotedText(bodyText(joinBlocks(inner.value.blocks, 'quote'))), false), inner.value.headroom))
}
function tryCodeBlock(node: AdfNode, flavour: WrittenFlavour): string | undefined {
if (!holdsOnlyAttributes(node, ['language'])) return undefined
// The id a marker carries beside a CommonMark spelling holding the attributes `spelled` names; `undefined` where the node holds another attribute, or an id no marker carries.
type MarkedId = { id: string | undefined }
function markedId(node: AdfNode, spelled: readonly string[], flavour: WrittenFlavour): MarkedId | undefined {
if (!holdsOnlyAttributes(node, [...spelled, idKey])) return undefined
const id = nodeAttrs(node)[idKey]
if (id === undefined) return { id }
return typeof id === 'string' && flavour === 'lossless' ? { id } : undefined
}
// spec/flavour.md, The CommonMark blocks: the marker on the line above, a blank line parting it from lines CommonMark would otherwise read with it.
function markedLines(marked: MarkedId, text: BlockText, parted: boolean): BlockText {
if (marked.id === undefined) return text
const marker = blockText(spellIdMarker(marked.id))
return joinedText(parted ? [marker, emptyLine, text] : [marker, text])
}
function trailingMarker(marked: MarkedId): string {
return marked.id === undefined ? '' : ` ${spellIdMarker(marked.id)}`
}
function tryCodeBlock(node: AdfNode, flavour: WrittenFlavour): BlockText | undefined {
const id = markedId(node, ['language'], flavour)
if (id === undefined) return undefined
const slot = languageSlot(nodeAttrs(node)['language'], flavourClaims[flavour])
if (slot.kind === 'attribute') return undefined
const [only, ...others] = fencedTexts(node) ?? []
if (only === undefined || others.length > 0) return undefined
return fencedCodeBlock(slot.kind === 'fence' ? slot.info : '', only)
return markedLines(id, blockText(fencedCodeBlock(slot.kind === 'fence' ? slot.info : '', only)), false)
}
// spec/flavour.md, The CommonMark blocks: one fence per text node, the language on each; with no fence to carry it, the attribute does.
@@ -280,57 +313,76 @@ function fencedTexts(node: AdfNode): string[] | undefined {
}
function tryHeading(node: AdfNode, path: ConvertErrorPath, flavour: WrittenFlavour): Result<EmittedBlock> | undefined {
if (!holdsOnlyAttributes(node, ['level'])) return undefined
const id = markedId(node, ['level'], flavour)
const level = nodeAttrs(node)['level']
if (!isHeadingLevel(level)) return undefined
if (id === undefined || !isHeadingLevel(level)) return undefined
const hashes = '#'.repeat(level)
const content = nodeContent(node)
if (content.length === 0) return success(commonMarkText(blockText(hashes)))
if (content.length === 0) return id.id === undefined ? success(commonMarkText(blockText(hashes))) : undefined
const line = emitInlineLine(content, 'heading', path, flavour)
if (!line.ok) return line
return success(commonMarkText(blockText(`${hashes} ${line.value}`)))
return success(commonMarkText(blockText(`${hashes} ${line.value}${trailingMarker(id)}`)))
}
function tryList(node: AdfNode, path: ConvertErrorPath, depth: number, writing: Writing): Result<EmittedBlock> | undefined {
const ordered = node.type === 'orderedList'
if (!holdsOnlyAttributes(node, ordered ? ['order'] : [])) return undefined
const id = markedId(node, ordered ? ['order'] : [], writing.flavour)
if (id === undefined) return undefined
const items = nodeContent(node)
const start = listStart(node, items.length)
if (start === undefined || items.length === 0) return undefined
if (items.some((item) => item.type !== 'listItem' || !holdsOnlyAttributes(item, []))) return undefined
const walked: WalkedItem[] = []
let headroom = Number.POSITIVE_INFINITY
for (const [offset, item] of items.entries()) {
const itemId = item.type === 'listItem' ? markedId(item, [], writing.flavour) : undefined
if (itemId === undefined) return undefined
const walk = walkBlocks(nodeContent(item), [...path, 'content', offset], depth + 1, writing)
if (!walk.ok) return walk
headroom = Math.min(headroom, walk.value.headroom)
walked.push({ node: item, walk: walk.value })
walked.push({ id: itemId, node: item, walk: walk.value })
}
const inners = walked.map((item) => {
const inner = joinBlocks(item.walk.blocks, 'list-item')
return writing.flavour === 'portable' && writing.blocks.claimsItem(inner) ? prefixedText('\\', '', inner) : inner
})
const list = spelledList(inners, ordered ? start : undefined, headroom)
if (list !== undefined) return success(list)
const list = walked.every(holdsItemMarker) ? spelledList(inners, ordered ? start : undefined, headroom, walked.map((item) => item.id.id)) : undefined
if (list !== undefined) return success(markedList(id, list))
// The directive form spends a level the walk did not count.
if (headroom < 1) return tooDeep(path)
return emitDirectiveBlock(node, ordered ? blockNodes.orderedList : blockNodes.bulletList, path, depth, () => success({ blocks: directiveItems(walked), headroom: headroom - 1 }))
}
// start: an ordered list's first number, undefined for a bullet list.
export function spelledList(inners: readonly BlockText[], start: number | undefined, headroom: number): EmittedBlock | undefined {
// The line after an item's marker holds its own id, so an item whose first block takes the line above for its id, or whose id stands beside no paragraph, has no CommonMark spelling.
function holdsItemMarker(item: WalkedItem): boolean {
const [first] = item.walk.blocks
if (first?.node.type === 'paragraph' && first.spelling === 'commonmark') return true
if (item.id.id !== undefined) return false
return first === undefined || first.spelling === 'directive' || !opensWithMarker(first.text)
}
function opensWithMarker(text: BlockText): boolean {
return text.first.character === '!' && text.first.text.startsWith(markerOpener)
}
function markedList(id: MarkedId, list: Extract<EmittedBlock, { spelling: 'list' }>): EmittedBlock {
const parted = !list.interruptsParagraph
return { ...list, alternateText: markedLines(id, list.alternateText, parted), text: markedLines(id, list.text, parted) }
}
// start: an ordered list's first number, undefined for a bullet list; ids: each item's own id, where it holds one.
export function spelledList(inners: readonly BlockText[], start: number | undefined, headroom: number, ids: readonly (string | undefined)[] = []): Extract<EmittedBlock, { spelling: 'list' }> | undefined {
const [usual, alternate] = start === undefined ? bulletDelimiters : orderedDelimiters
const number = (offset: number): string => (start === undefined ? '' : `${start + offset}`)
const text = listLines(inners, number, usual)
const alternateText = listLines(inners, number, alternate)
const text = listLines(inners, ids, number, usual)
const alternateText = listLines(inners, ids, number, alternate)
if (text === undefined || alternateText === undefined) return undefined
return { alternateText, headroom, interruptsParagraph: markerInterruptsParagraph(start, inners[0]?.length === 0), ordered: start !== undefined, spelling: 'list', text }
}
function listLines(inners: readonly BlockText[], number: (offset: number) => string, delimiter: string): BlockText | undefined {
function listLines(inners: readonly BlockText[], ids: readonly (string | undefined)[], number: (offset: number) => string, delimiter: string): BlockText | undefined {
const lines: BlockText[] = []
for (const [offset, inner] of inners.entries()) {
const line = tryListItemLines(inner, `${number(offset)}${delimiter} `)
const line = tryListItemLines(inner, `${number(offset)}${delimiter} `, ids[offset])
if (line === undefined) return undefined
lines.push(line)
}
@@ -338,7 +390,7 @@ function listLines(inners: readonly BlockText[], number: (offset: number) => str
}
function directiveItems(items: readonly WalkedItem[]): PlacedBlock[] {
return items.map((item) => ({ ...directivePair(item.node, listItemOpener, joinBlocks(item.walk.blocks, 'directive')), node: item.node }))
return items.map((item) => ({ ...directivePair(item.node, spellDirectiveOpener('listItem', undefined, spellIdAttributes(item.id.id)), joinBlocks(item.walk.blocks, 'directive')), node: item.node }))
}
function listStart(node: AdfNode, items: number): number | undefined {
@@ -348,11 +400,13 @@ function listStart(node: AdfNode, items: number): number | undefined {
return start + items - 1 > largestListMarker ? undefined : start
}
function tryListItemLines(inner: BlockText, marker: string): BlockText | undefined {
// id: the item's own, standing between its marker and its first paragraph's text.
function tryListItemLines(inner: BlockText, marker: string, id: string | undefined): BlockText | undefined {
if (inner.length === 0) return blockText(marker.trimEnd())
if (holdsBlankLine(inner)) return undefined
const indent = ' '.repeat(marker.length)
const lines = prefixedText(marker, indent, inner)
const head = id === undefined ? marker : `${marker}${spellIdMarker(id)} `
const lines = prefixedText(head, indent, inner)
if (!opensWithThematicBreak(lines)) return lines
// An item opens with `*` only as text, a list there taking `- ` and a rule `---`; a backslash keeps a first line reading as a rule text.
return inner.first.character === '*' ? prefixedText(`${marker}\\`, indent, inner) : undefined
@@ -360,13 +414,15 @@ function tryListItemLines(inner: BlockText, marker: string): BlockText | undefin
function tryParagraph(node: AdfNode, path: ConvertErrorPath, flavour: WrittenFlavour): Result<EmittedBlock> | undefined {
const content = nodeContent(node)
if (content.length === 0 || !holdsOnlyAttributes(node, [])) return undefined
const id = markedId(node, [], flavour)
if (content.length === 0 || id === undefined) return undefined
const line = emitInlineLine(content, 'paragraph', path, flavour)
if (!line.ok) return line
return success(commonMarkText(blockText(line.value)))
const text = commonMarkText(markedLines(id, blockText(line.value), false))
return success(id.id === undefined ? text : { ...text, trailing: blockText(`${line.value}${trailingMarker(id)}`) })
}
function tryRule(node: AdfNode): string | undefined {
if (!holdsOnlyAttributes(node, [])) return undefined
return '---'
function tryRule(node: AdfNode, flavour: WrittenFlavour): BlockText | undefined {
const id = markedId(node, [], flavour)
return id === undefined ? undefined : markedLines(id, blockText('---'), true)
}
+37 -13
View File
@@ -1,5 +1,5 @@
import type { Claims, Flavour } from '../flavour.ts'
import type { ConvertFault, SourcePosition } from '../../result.ts'
import type { ConvertFault, Read, SourcePosition } from '../../result.ts'
import type { DirectiveAttributes, DirectiveLine } from '../directive/syntax.ts'
import type { LinkDefinition } from '../commonmark/link-syntax.ts'
import {
@@ -22,8 +22,9 @@ import {
} from '../commonmark/grammar.ts'
import { barePipeCells, isDelimiterRow, isPipeAlignment, malformedPipeTable, pipeCells } from '../pipe-table-syntax.ts'
import { blockDirectiveForm } from '../directive/block.ts'
import { directiveEscape, malformedDirective, readDirectiveLine, spellDirectiveCloser } from '../directive/syntax.ts'
import { directiveEscape, malformedDirective, markerOpener, readDirectiveLine, spellDirectiveCloser } from '../directive/syntax.ts'
import { flavourClaims } from '../flavour.ts'
import { readItemMarker, readTrailingMarker, type TrailingMarker } from '../directive/id-marker.ts'
import { readLinkDefinitions } from '../commonmark/link-reference-definitions.ts'
export type Block = { position: SourcePosition } & (
@@ -34,8 +35,10 @@ export type Block = { position: SourcePosition } & (
| { delimiter: string; items: Block[][]; kind: 'bulletList' }
| { delimiter: string; items: Block[][]; kind: 'orderedList'; start: number }
| { kind: 'code'; language: string; text: string }
| { kind: 'heading'; level: number; text: string }
| { kind: 'paragraph'; text: string }
| { kind: 'heading'; level: number; text: string; trailing?: Read<DirectiveAttributes> }
// item: right after a list item's marker; line: alone on the line above its block.
| { attributes: DirectiveAttributes; kind: 'marker'; placement: 'item' | 'line' }
| { kind: 'paragraph'; text: string; trailing?: Read<DirectiveAttributes> }
| { kind: 'rule' }
| { kind: 'table'; rows: string[][] }
)
@@ -44,6 +47,10 @@ export type ParsedBlocks = { blocks: Block[]; definitions: Map<string, LinkDefin
export type DirectiveBlock = Extract<Block, { kind: 'directive' }>
export type MarkerBlock = Extract<Block, { kind: 'marker' }>
type ParagraphBlock = Extract<Block, { kind: 'paragraph' }>
type ListBlock = Extract<Block, { items: Block[][] }>
type OpenDirective = { blocks: Block[]; index: number; kind: 'directive'; name: string; parent: Block[]; position: SourcePosition }
@@ -216,7 +223,7 @@ function openContainers(walk: Walk, line: Line, paragraphOpen: boolean, depth: n
if (!opened) closeContainers(walk, depth)
opened = true
openContainer(walk, start)
rest = start.rest
rest = start.kind === 'item' && walk.claims.directives ? afterItemMarker(walk, start.rest) : start.rest
}
return { opened, rest }
}
@@ -275,6 +282,13 @@ function openContainer(walk: Walk, start: ContainerStart): void {
walk.stack.push({ blocks, indentation: start.indentation, kind: 'item', list })
}
function afterItemMarker(walk: Walk, line: Line): Line {
const marker = line.spaces === 0 ? readItemMarker(line.text) : undefined
if (marker === undefined) return line
currentBlocks(walk).push({ attributes: marker.attributes, kind: 'marker', placement: 'item', position: walk.position })
return { column: line.column + marker.rest, spaces: 0, text: line.text.slice(marker.rest) }
}
// An empty item closes at the blank line after it, yet the next item continues its list unless endList ended it.
function openedList(walk: Walk, start: Extract<ContainerStart, { kind: 'item' }>): ListBlock {
if (!start.fresh) return start.list
@@ -309,6 +323,7 @@ function closeContainers(walk: Walk, depth: number): void {
function applyDirectiveLine(walk: Walk, directive: DirectiveLine): void {
if (directive.kind === 'closer') closeDirective(walk, directive.name)
else if (directive.kind === 'marker') currentBlocks(walk).push({ attributes: directive.attributes, kind: 'marker', placement: 'line', position: walk.position })
else openDirective(walk, directive)
}
@@ -476,7 +491,7 @@ function readLineBlock(walk: Walk, opener: string): boolean {
if (level !== undefined) {
const paragraph = takeParagraph(walk)
if (paragraph !== undefined) {
currentBlocks(walk).push(bareTableFault(paragraph, walk.claims) ?? { kind: 'heading', level, position: paragraph.position, text: paragraph.text })
currentBlocks(walk).push(paragraph.kind === 'fault' ? paragraph : (bareTableFault(paragraph, walk.claims) ?? { ...paragraph, kind: 'heading', level }))
return true
}
}
@@ -488,7 +503,8 @@ function readLineBlock(walk: Walk, opener: string): boolean {
const heading = atxHeading(opener)
if (heading === undefined) return false
closeLeaf(walk)
currentBlocks(walk).push({ kind: 'heading', level: heading.level, position: walk.position, text: heading.text })
const trailed = walk.claims.directives ? readTrailingMarker(heading.text) : undefined
currentBlocks(walk).push({ kind: 'heading', level: heading.level, position: walk.position, ...trailedText(trailed?.text ?? heading.text, trailed) })
return true
}
@@ -508,7 +524,7 @@ function closeLeaf(walk: Walk): void {
if (leaf.kind === 'paragraph') {
const paragraph = takeParagraph(walk)
if (paragraph === undefined) endList(walk)
else currentBlocks(walk).push(bareTableFault(paragraph, walk.claims) ?? paragraph)
else currentBlocks(walk).push(paragraph.kind === 'fault' ? paragraph : (bareTableFault(paragraph, walk.claims) ?? paragraph))
return
}
walk.leaf = undefined
@@ -565,7 +581,7 @@ function pipeTableBlock(rows: readonly [string[], ...string[][]], position: Sour
}
// spec/flavour.md, Tables: GFM's table without the leading pipes, which no line of it claims.
function bareTableFault(paragraph: Extract<Block, { kind: 'paragraph' }>, claims: Claims): Block | undefined {
function bareTableFault(paragraph: ParagraphBlock, claims: Claims): Block | undefined {
if (claims.pipeTables !== 'flavour') return undefined
let header: string[] | undefined
for (const line of paragraph.text.split('\n')) {
@@ -586,15 +602,23 @@ function faultedBlock(message: string, position: SourcePosition): Block {
return { fault: malformedPipeTable(message), kind: 'fault', position }
}
// The definitions a paragraph gives up are whole lines, so what is left starts at one this held.
function takeParagraph(walk: Walk): Extract<Block, { kind: 'paragraph' }> | undefined {
// The definitions a paragraph gives up are whole lines, so what is left starts at one this held. A trailing marker is read first: its id is no definition's destination.
function takeParagraph(walk: Walk): Extract<Block, { kind: 'fault' }> | ParagraphBlock | undefined {
const leaf = walk.leaf
if (leaf?.kind !== 'paragraph') return undefined
walk.leaf = undefined
const text = readLinkDefinitions(walk.definitions, leaf.lines.map((line) => line.text).join('\n'))
const lines = leaf.lines.map((line) => line.text).join('\n')
const trailed = walk.claims.directives ? readTrailingMarker(lines) : undefined
const text = readLinkDefinitions(walk.definitions, trailed?.text ?? lines)
if (text === '' && trailed !== undefined) return { fault: malformedDirective(`an ${markerOpener}…} marker ends a paragraph holding no text once its link reference definitions are read; ${directiveEscape}`), kind: 'fault', position: leaf.position }
if (text === '') return undefined
const kept = leaf.lines[leaf.lines.length - text.split('\n').length]
return { kind: 'paragraph', position: kept?.position ?? leaf.position, text }
return { kind: 'paragraph', position: kept?.position ?? leaf.position, ...trailedText(text, trailed) }
}
// No trailing key where no marker trails, so a block reads as it did before markers.
function trailedText(text: string, trailed: TrailingMarker | undefined): { text: string; trailing?: Read<DirectiveAttributes> } {
return trailed === undefined ? { text } : { text, trailing: trailed.attributes }
}
function currentBlocks(walk: Walk): Block[] {
+104 -13
View File
@@ -1,22 +1,25 @@
import type { AdfDocument, AdfNode } from '../../adf/document.ts'
import type { Block, DirectiveBlock } from './blocks.ts'
import type { Block, DirectiveBlock, MarkerBlock } from './blocks.ts'
import type { BlockDirectiveNode } from '../directive/node-reading.ts'
import type { ConvertFault } from '../../result.ts'
import type { ConvertFault, SourcePosition } from '../../result.ts'
import type { DirectiveAttributes } from '../directive/syntax.ts'
import type { LineContainer } from '../line-container.ts'
import type { LinkDefinitions } from '../inline-content.ts'
import { carryFenceType, readCarriedBlock } from '../opaque-carry.ts'
import { commonMarkSpelling, describeCommonMarkSpelling, spellingMemo, type SpellingMemo } from '../emit/spelling-questions.ts'
import { directiveEscape, markerOpener, spellStringAttribute, unsupportedNodeShape } from '../directive/syntax.ts'
import { documentAttribute, documentName, documentSpelling } from '../directive/block.ts'
import { emptyKeys, nodeAttrs } from '../../adf/document.ts'
import { emptyKeys, nodeAttrs, nodeContent } from '../../adf/document.ts'
import { failure, faulted, positioned, success, type ConvertErrorPath, type ParseError, type Result } from '../../result.ts'
import { flavourClaims } from '../flavour.ts'
import { idKey, readMarkerId } from '../directive/id-marker.ts'
import { languageSlot } from '../code-language.ts'
import { largestNesting } from '../../nesting.ts'
import { markerInterruptsParagraph } from '../commonmark/grammar.ts'
import { notAString } from '../../not-a-string.ts'
import { parseBlocks } from './blocks.ts'
import { readBlockDirectiveNode } from '../directive/node-reading.ts'
import { readInlineContent } from './inline-content.ts'
import { spellStringAttribute, unsupportedNodeShape } from '../directive/syntax.ts'
import { spellsEmpty } from '../directive/empty-keys.ts'
import { withinEngineLimits } from '../../length-bound.ts'
@@ -28,6 +31,9 @@ export type FlavourBlockReaders = {
export type FlavourReading = Extract<Reading, { flavour: 'portable' }>
// trailing: the container's first paragraph ends its last line with its id, the line above it being the container's.
type Opening = 'line' | 'trailing'
export type ReadAs = { flavour: 'commonmark' | 'lossless' } | { blocks: FlavourBlockReaders; flavour: 'portable' }
export type Reading = ReadAs & { definitions: LinkDefinitions; memo: SpellingMemo }
@@ -60,11 +66,17 @@ function readMarkdown(markdown: string, readAs: ReadAs): Result<AdfDocument> {
return content.ok ? success({ content: content.value, type: 'doc', version: 1 }) : content
}
export function readBlocks(blocks: readonly Block[], reading: Reading, path: ConvertErrorPath, depth: number): Result<AdfNode[]> {
export function readBlocks(blocks: readonly Block[], reading: Reading, path: ConvertErrorPath, depth: number, opening: Opening = 'line'): Result<AdfNode[]> {
if (depth > largestNesting) return tooDeep(path)
const content: AdfNode[] = []
let marker: MarkerBlock | undefined
for (const block of blocks) {
const nodePath = [...path, 'content', content.length]
if (block.kind === 'marker') {
if (marker !== undefined) return positioned(failure('malformed-directive', twoMarkers, nodePath), block.position)
marker = block
continue
}
if (block.kind === 'directive' && block.name === documentName) {
const fault = documentFault(block) ?? unsupportedNodeShape(`delete the ${documentSpelling} line to give the document content: it stands only as the whole document`)
return positioned(faulted(fault, nodePath), block.position)
@@ -77,9 +89,62 @@ export function readBlocks(blocks: readonly Block[], reading: Reading, path: Con
}
const node = positioned(readBlock(block, reading, nodePath, depth), block.position)
if (!node.ok) return node
content.push(node.value)
const marked = markedNode(node.value, block, marker, opening === 'trailing' && content.length === 0, nodePath)
if (!marked.ok) return marked
content.push(marked.value)
marker = undefined
}
return success(content)
if (marker === undefined) return success(content)
return positioned(failure('malformed-directive', `an ${markerOpener}…} marker carries the id of the block right below it: no block follows this one; ${directiveEscape}`, [...path, 'content', content.length]), marker.position)
}
const twoMarkers = `a block carries one ${markerOpener}…} marker: this one carries two`
// spec/flavour.md, The CommonMark blocks: the blocks a marker line stands above, by the node each builds.
const markedTypes: ReadonlyMap<Block['kind'], string> = new Map([
['blockquote', 'blockquote'],
['bulletList', 'bulletList'],
['code', 'codeBlock'],
['orderedList', 'orderedList'],
['paragraph', 'paragraph'],
['rule', 'rule'],
])
function markedNode(node: AdfNode, block: Exclude<Block, MarkerBlock>, line: MarkerBlock | undefined, trails: boolean, path: ConvertErrorPath): Result<AdfNode, ParseError> {
const trailing = block.kind === 'heading' || block.kind === 'paragraph' ? block.trailing : undefined
if (trailing === undefined) return line === undefined ? success(node) : lineMarkedNode(node, block, line, trails, path)
if (trailing.fault !== undefined) return positioned(faulted(trailing.fault, path), block.position)
if (line !== undefined) return positioned(failure('malformed-directive', twoMarkers, path), block.position)
if (block.kind === 'paragraph' && !trails) {
return positioned(failure('unsupported-node-shape', `a paragraph carries its ${markerOpener}…} marker on the line above it, unless it opens a quote or a list item: move this one there`, path), block.position)
}
if (node.type !== block.kind) return positioned(failure('unsupported-node-shape', `this paragraph reads as a ${node.type}, whose id rides its directive: write the ${node.type} as its directive`, path), block.position)
return identified(node, trailing.value, path, block.position)
}
function lineMarkedNode(node: AdfNode, block: Exclude<Block, MarkerBlock>, line: MarkerBlock, trails: boolean, path: ConvertErrorPath): Result<AdfNode, ParseError> {
const at = (message: string): Result<AdfNode, ParseError> => positioned(failure('unsupported-node-shape', message, path), line.position)
if (block.kind === 'heading') return at(`a heading carries its ${markerOpener}…} marker at the end of its line, one space after its text: move this one there`)
if (block.kind === 'paragraph' && trails) return at(`the paragraph opening a quote or a list item carries its ${markerOpener}…} marker at the end of its last line, the line above being the container's: move this one there`)
if (markedTypes.get(block.kind) !== node.type) return at(`an ${markerOpener}…} marker stands above a paragraph, list, quote, code block or rule spelled in CommonMark: this one stands above a ${node.type}`)
const gap = block.position.line - line.position.line
if (gap !== (blankBelowMarker(block) ? 2 : 1)) {
const placement = blankBelowMarker(block) ? `one blank line parts an ${markerOpener}…} marker from the ${node.type} below it, which CommonMark would otherwise read with the marker` : `an ${markerOpener}…} marker stands on the line right above its ${node.type}`
return positioned(failure('malformed-directive', `${placement}: this one stands ${gap} lines above it`, path), line.position)
}
return identified(node, line.attributes, path, line.position)
}
// A text line above a rule makes a setext heading, and one above a list its marker cannot interrupt continues the line.
function blankBelowMarker(block: Exclude<Block, MarkerBlock>): boolean {
if (block.kind === 'rule') return true
if (block.kind !== 'bulletList' && block.kind !== 'orderedList') return false
return !markerInterruptsParagraph(block.kind === 'orderedList' ? block.start : undefined, block.items[0]?.length === 0)
}
function identified(node: AdfNode, attributes: DirectiveAttributes, path: ConvertErrorPath, position: SourcePosition): Result<AdfNode, ParseError> {
const id = positioned(readMarkerId(attributes, node.type, path), position)
return id.ok ? success({ ...node, attrs: { ...node.attrs, [idKey]: id.value } }) : id
}
export function tooDeep<T>(path: ConvertErrorPath): Result<T> {
@@ -95,10 +160,10 @@ function documentFault(block: DirectiveBlock): ConvertFault | undefined {
return unsupportedNodeShape(`${documentName} spells the one form ${documentSpelling}: this one spells another`)
}
function readBlock(block: Block, reading: Reading, path: ConvertErrorPath, depth: number): Result<AdfNode> {
function readBlock(block: Exclude<Block, MarkerBlock>, reading: Reading, path: ConvertErrorPath, depth: number): Result<AdfNode> {
switch (block.kind) {
case 'blockquote':
return reading.flavour === 'portable' ? reading.blocks.quote(block.blocks, reading, path, depth) : containerNode({ type: 'blockquote' }, block.blocks, reading, path, depth)
return reading.flavour === 'portable' ? reading.blocks.quote(block.blocks, reading, path, depth) : containerNode({ type: 'blockquote' }, block.blocks, reading, path, depth, 'trailing')
case 'bulletList':
// readBlocks reads a portable bullet list before it reaches here.
return listNode({ type: 'bulletList' }, block.items, reading, path, depth)
@@ -131,11 +196,21 @@ function directiveNode(block: DirectiveBlock, reading: Reading, path: ConvertErr
// Refused here so V8's throw past the bound is placed at this directive, like the bound check on other engines.
const readable = withinEngineLimits(() => commonMarkSpelling(built.value, path, depth, { flavour: 'lossless', memo: reading.memo }))
if (!readable.ok) return readable
if (!readable.value) return built
if (!readable.value || writtenByEarlierRelease(built.value)) return built
const spelling = describeCommonMarkSpelling(built.value)
return failure('unsupported-node-shape', `${built.value.type} takes the CommonMark spelling, not the directive form${spelling === undefined ? '' : `: write ${spelling}`}`, path)
}
// 0.3 wrote each of these nodes as its directive where it, or one of a list's items, held an id.
function writtenByEarlierRelease(node: AdfNode): boolean {
if (node.type === 'bulletList' || node.type === 'orderedList') return holdsId(node) || nodeContent(node).some(holdsId)
return holdsId(node)
}
function holdsId(node: AdfNode): boolean {
return nodeAttrs(node)[idKey] !== undefined
}
function directiveBody(read: BlockDirectiveNode, blocks: Block[] | undefined, reading: Reading, path: ConvertErrorPath, depth: number): Result<AdfNode> {
const { contentModel, node } = read
if (blocks === undefined) return success(node)
@@ -193,11 +268,12 @@ function inlineBodyNode(node: AdfNode, blocks: readonly Block[], reading: Readin
const only = blocks.length === 1 ? blocks[0] : undefined
if (only?.kind === 'fault') return positioned(faulted(only.fault, path), only.position)
if (only?.kind !== 'paragraph') return failure('unsupported-node-shape', `${node.type} takes one paragraph as its body: this body is not one`, path)
if (only.trailing !== undefined) return positioned(failure('unsupported-node-shape', `a directive carries its ${node.type}'s ${idKey} in its {attrs}, never in a trailing ${markerOpener}…} marker`, path), only.position)
return positioned(contentNode(node, only.text, reading, path, 'paragraph'), only.position)
}
export function containerNode(node: AdfNode, blocks: readonly Block[], reading: Reading, path: ConvertErrorPath, depth: number): Result<AdfNode> {
const content = readBlocks(blocks, reading, path, depth + 1)
export function containerNode(node: AdfNode, blocks: readonly Block[], reading: Reading, path: ConvertErrorPath, depth: number, opening: Opening = 'line'): Result<AdfNode> {
const content = readBlocks(blocks, reading, path, depth + 1, opening)
if (!content.ok) return content
return success(withContent(node, content.value))
}
@@ -209,13 +285,28 @@ function withContent(node: AdfNode, content: readonly AdfNode[]): AdfNode {
export function listNode(node: AdfNode, items: readonly Block[][], reading: Reading, path: ConvertErrorPath, depth: number): Result<AdfNode> {
const content: AdfNode[] = []
for (const [index, blocks] of items.entries()) {
const item = containerNode({ type: 'listItem' }, blocks, reading, [...path, 'content', index], depth)
const item = listItemNode(blocks, reading, [...path, 'content', index], depth)
if (!item.ok) return item
content.push(item.value)
}
return success({ ...node, content })
}
// spec/flavour.md, The CommonMark blocks: an item's id stands right after its list marker, before its first paragraph's text.
function listItemNode(blocks: readonly Block[], reading: Reading, path: ConvertErrorPath, depth: number): Result<AdfNode> {
const [first] = blocks
if (first?.kind !== 'marker') return containerNode({ type: 'listItem' }, blocks, reading, path, depth, 'trailing')
if (first.placement === 'line') {
return positioned(failure('unsupported-node-shape', `a list item's first line carries the item's own ${markerOpener}…} marker, right after its list marker: write the list as directives to give the block opening this item an id`, path), first.position)
}
const item = containerNode({ type: 'listItem' }, blocks.slice(1), reading, path, depth, 'trailing')
if (!item.ok) return item
if (nodeContent(item.value)[0]?.type !== 'paragraph') {
return positioned(failure('unsupported-node-shape', `a list item's ${markerOpener}…} marker stands before its first paragraph's text: this item opens with no paragraph; write the list as directives to give it an id`, path), first.position)
}
return identified(item.value, first.attributes, path, first.position)
}
function codeBlockNode(language: string, text: string, reading: Reading, path: ConvertErrorPath, depth: number): Result<AdfNode> {
const carriedType = flavourClaims[reading.flavour].carryFence ? carryFenceType(language) : undefined
if (carriedType !== undefined) {