From 7c15b02258db863be9e58c02e3f8c1b39a4b1e03 Mon Sep 17 00:00:00 2001 From: Lilleman auf Larv Date: Tue, 29 Sep 2026 11:32:45 +0200 Subject: [PATCH 01/14] 35b - tests for the writer spelling the plain flavour and escaping its markers --- src/conformance/adf-property.test.ts | 21 +++++++++++-- src/conformance/property-harness.ts | 7 ++++- src/markdown/emit/plain-reduction.test.ts | 30 ++++++++++++------- .../parse/plain-markdown-to-adf.test.ts | 16 +++++++--- 4 files changed, 57 insertions(+), 17 deletions(-) diff --git a/src/conformance/adf-property.test.ts b/src/conformance/adf-property.test.ts index 25c4a3a..16de9d7 100644 --- a/src/conformance/adf-property.test.ts +++ b/src/conformance/adf-property.test.ts @@ -2,9 +2,10 @@ import assert from 'node:assert/strict' import fc from 'fast-check' import test from 'node:test' +import type { AdfNode } from '../adf/document.ts' import { adfDocument, propertyRuns, propertyTimeout } from './property-harness.ts' import { adfToMarkdown } from '../markdown/emit/adf-to-markdown.ts' -import { adfToPlainMarkdown } from '../markdown/emit/plain-reduction.ts' +import { adfToPlainMarkdown, reduceToPlain } from '../markdown/emit/plain-reduction.ts' import { directivePrefix } from '../markdown/directive-syntax.ts' import { markdownToAdf, plainMarkdownToAdf } from '../markdown/parse/markdown-to-adf.ts' import { toEditorNormal } from '../adf/editor-normal.ts' @@ -19,6 +20,20 @@ function readsNoDirective(markdown: string): boolean { return read.ok && renamed.ok && JSON.stringify(read.value).replaceAll(directivePrefix, renamedPrefix) === JSON.stringify(renamed.value) } +// Each block's text, an expand's title and an image's alt and url, in document order: what the plain pair keeps. +function shownText(nodes: readonly AdfNode[]): string[] { + const shown: string[] = [] + for (const node of nodes) { + const attrs = node.attrs ?? {} + if ((node.type === 'expand' || node.type === 'nestedExpand') && typeof attrs['title'] === 'string') shown.push(attrs['title']) + if (node.type === 'media') shown.push(`${JSON.stringify(attrs['alt'] ?? '')} ${JSON.stringify(attrs['url'])}`) + const content = node.content ?? [] + if (content.some((child) => child.type === 'text' || child.type === 'hardBreak')) shown.push(content.map((child) => child.text ?? '\n').join('')) + else for (const text of shownText(content)) shown.push(text) + } + return shown.filter((text) => text !== '') +} + test('a generated document refuses to emit, or its markdown reads back to it', { timeout: propertyTimeout }, () => { fc.assert( fc.property(adfDocument, (document) => { @@ -32,7 +47,7 @@ test('a generated document refuses to emit, or its markdown reads back to it', { ) }) -test('a generated document writes plain markdown refusing only what the guard refuses, and that markdown reads back to itself', { timeout: propertyTimeout }, () => { +test('a generated document writes plain markdown refusing only what the guard refuses, and that markdown reads back to its text and to itself', { timeout: propertyTimeout }, () => { fc.assert( fc.property(adfDocument, (document) => { const written = adfToPlainMarkdown(document) @@ -40,6 +55,8 @@ test('a generated document writes plain markdown refusing only what the guard re assert.ok(readsNoDirective(written.value), `a directive in ${JSON.stringify(written.value)}`) const read = plainMarkdownToAdf(written.value) assert.ok(read.ok, read.ok ? '' : `${read.error.code}: ${read.error.message} — reading ${JSON.stringify(written.value)}`) + const reduced = reduceToPlain(document) + assert.deepEqual(shownText(read.value.content ?? []), reduced.ok ? shownText(reduced.value.content ?? []) : reduced, `reading ${JSON.stringify(written.value)}`) assert.deepEqual(adfToPlainMarkdown(read.value), written, `reading ${JSON.stringify(written.value)}`) }), propertyRuns(gateRuns), diff --git a/src/conformance/property-harness.ts b/src/conformance/property-harness.ts index 832e74a..72bf66e 100644 --- a/src/conformance/property-harness.ts +++ b/src/conformance/property-harness.ts @@ -23,7 +23,7 @@ export const propertyTimeout = 600000 const depthIdentifier = fc.createDepthIdentifier() const emptyCell: AdfNode = { content: [{ type: 'paragraph' }], type: 'tableCell' } const flatCommonMarkShapeWeight = 4 -export const markdownPieces = fc.constantFrom(...'aZ09 \t\n!"#$%&\'()*+,-./:;<=>?@[\\]^_`{|}~é\xa0🎉', 'ab:', 'http://', directivePrefix, `${directivePrefix}a[`, `${directivePrefix}a{`) +export const markdownPieces = fc.constantFrom(...'aZ09 \t\n!"#$%&\'()*+,-./:;<=>?@[\\]^_`{|}~é\xa0🎉', '==', '[!NOTE]', '[x]', 'ab:', 'http://', directivePrefix, `${directivePrefix}a[`, `${directivePrefix}a{`) const nestingCommonMarkShapeWeight = 21 const spelledTypes = new Set(['text', ...Object.keys(blockNodes), ...Object.keys(inlineNodes), ...Object.keys(markAttributes)]) @@ -80,6 +80,7 @@ function pipeTable({ body, header }: { body: AdfNode[][]; header: AdfNode[] }): const mark: Arbitrary = fc.oneof( { arbitrary: fc.oneof(...Object.entries(markAttributes).map(([type, vocabulary]) => attributes(vocabulary).map((attrs) => ({ attrs, type })))), weight: 9 }, + { arbitrary: attributes({ color: 'string' }).map((attrs) => ({ attrs, type: 'backgroundColor' })), weight: 2 }, { arbitrary: fc.record({ attrs: fc.dictionary(jsonKey, jsonValue, { maxKeys: 2, noNullPrototype: true }), type: unknownType }), weight: 1 }, ) const marks = fc.uniqueArray(mark, { maxLength: 3, selector: (held) => held.type }) @@ -135,8 +136,12 @@ const positions = fc.letrec((tie) => { paragraph, fc.record({ body: fc.array(fc.array(cell('tableCell'), { maxLength: 3 }), { maxLength: 2 }), header: fc.array(cell('tableHeader'), { maxLength: 3, minLength: 1 }) }).map(pipeTable), ] + const task = (type: string, content: Arbitrary) => + fc.record({ content, state: fc.constantFrom('DONE', 'TODO') }).map(({ content: held, state }): AdfNode => ({ attrs: { state }, content: held, type })) + const taskItem = fc.oneof({ arbitrary: task('taskItem', inlineContent), weight: 3 }, { arbitrary: task('blockTaskItem', blockContent), weight: 1 }) const nestingCommonMarkShapes = [ blockContent.map((content): AdfNode => ({ content, type: 'blockquote' })), + fc.array(fc.oneof({ arbitrary: taskItem, weight: 3 }, { arbitrary: tie('block'), weight: 1 }), { depthIdentifier, maxLength: 3, minLength: 1 }).map((content): AdfNode => ({ content, type: 'taskList' })), listItems.map((content): AdfNode => ({ content, type: 'bulletList' })), fc .record({ content: listItems, order: fc.oneof({ arbitrary: fc.integer({ max: 3, min: 0 }), weight: 4 }, { arbitrary: fc.integer({ max: 999999999, min: 0 }), weight: 1 }) }) diff --git a/src/markdown/emit/plain-reduction.test.ts b/src/markdown/emit/plain-reduction.test.ts index 618c980..c12c343 100644 --- a/src/markdown/emit/plain-reduction.test.ts +++ b/src/markdown/emit/plain-reduction.test.ts @@ -2,9 +2,8 @@ import assert from 'node:assert/strict' import test from 'node:test' import type { AdfAttributes, AdfDocument, AdfMark, AdfNode } from '../../adf/document.ts' -import { adfToMarkdown } from './adf-to-markdown.ts' +import { adfToPlainMarkdown, reduceToPlain } from './plain-reduction.ts' import { largestNesting } from '../../nesting.ts' -import { reduceToPlain } from './plain-reduction.ts' const code: AdfMark = { type: 'code' } const em: AdfMark = { type: 'em' } @@ -19,11 +18,8 @@ function plain(...content: AdfNode[]): string { } function plainDocument(input: AdfDocument): string { - const reduced = reduceToPlain(input) - if (!reduced.ok) return `${reduced.error.code} at /${reduced.error.path.join('/')}` - const markdown = adfToMarkdown(reduced.value) - if (!markdown.ok) return `emit ${markdown.error.code}: ${markdown.error.message}` - return markdown.value + const markdown = adfToPlainMarkdown(input) + return markdown.ok ? markdown.value : `${markdown.error.code} at /${markdown.error.path.join('/')}` } function text(value: string, ...marks: AdfMark[]): AdfNode { @@ -119,6 +115,7 @@ test('spells an expand and a nested expand as a folded callout titled by the mar ) assert.equal(plain(node('expand', {}, said('Line.'))), '> [!NOTE]-\n>\n> Line.\n') assert.equal(plain(node('expand', { title: ' *Two*\nlines ' })), '> [!NOTE]- \\*Two\\* lines\n') + assert.equal(plain(node('expand', { title: '**x** [y](z) ==w==' }, said('b'))), '> [!NOTE]- \\*\\*x\\*\\* \\[y](z) ==w==\n>\n> b\n') }) test('spells a task list as a bullet list whose items lead with their state', () => { @@ -142,6 +139,18 @@ test('spells a highlight as a == pair around the run, whatever its colour', () = assert.equal(plain(paragraph(text('hi ', strong, highlight('#fff')), text('b'))), '**==hi==** b\n') assert.equal(plain(paragraph(text('a', strong, highlight('#fff')), text('b', highlight('#fff'), em))), '==**a**_b_==\n') assert.equal(plain(paragraph(text('a', highlight('#fff'), code))), '==`a`==\n') + assert.equal(plain(paragraph(text('=', highlight('#fff')), text(' '), text('a==b', highlight('#fff')))), '==\\=== ==a==b==\n') + assert.equal(plain(paragraph(text('x'), text('y', highlight('#fff')), text(' z'))), 'xy z\n') +}) + +test('escapes text that would read back as a flavour marker, and only there', () => { + assert.equal(plain(said('==x== a == b a==b ===')), '\\==x\\== a == b a==b \\=\\==\n') + assert.equal(plain({ content: [said('[!NOTE] x'), said('[!TIP]')], type: 'blockquote' }), '> \\[!NOTE] x\n>\n> [!TIP]\n') + assert.equal(plain({ content: [said('[!NOTE]x')], type: 'blockquote' }, said('[!NOTE]')), '> [!NOTE]x\n\n[!NOTE]\n') + assert.equal(plain(bulletList(item(said('[x] a')), item(said('[ ]')))), '- \\[x] a\n- [ ]\n') + assert.equal(plain(bulletList(item(said('[x] a')), item(said('b'))), node('orderedList', { order: 1 }, item(said('[x] c')))), '- [x] a\n- b\n\n1. [x] c\n') + const task = (state: string, value: string): AdfNode => node('taskItem', { state }, text(value)) + assert.equal(plain(node('taskList', {}, task('DONE', '[x] a'), task('TODO', '==b=='))), '- [x] [x] a\n- [ ] \\==b\\==\n') }) test('unwraps the containers plain markdown has no spelling for to their body blocks in order', () => { @@ -311,7 +320,8 @@ test('drops an empty paragraph and merges adjacent lists of one type', () => { assert.equal(plain(node('layoutSection', {}, column(bulletList(item(said('a')))), column(bulletList(item(said('b')))))), '- a\n- b\n') }) -test('returns a document the lossless emitter spells without a directive', () => { - const reduced = reduceToPlain(document(node('panel', { panelType: 'info' }, said('x')))) - assert.deepEqual(reduced.ok ? reduced.value : undefined, document({ content: [said('[!NOTE]'), said('x')], type: 'blockquote' })) +test('keeps the nodes the plain flavour spells and degrades only what it cannot', () => { + const tasks = node('taskList', {}, node('taskItem', { localId: '01a0d99b-1f58-7b95-829b-6f9860371d54', state: 'DONE' }, text('t'))) + const reduced = reduceToPlain(document(node('panel', { localId: '01a0d99b-1f56-7a50-889a-f4375f09ee05', panelType: 'info' }, said('x')), tasks)) + assert.deepEqual(reduced.ok ? reduced.value : undefined, document(node('panel', { panelType: 'info' }, said('x')), node('taskList', {}, node('taskItem', { state: 'DONE' }, text('t'))))) }) diff --git a/src/markdown/parse/plain-markdown-to-adf.test.ts b/src/markdown/parse/plain-markdown-to-adf.test.ts index f378da4..68f73a2 100644 --- a/src/markdown/parse/plain-markdown-to-adf.test.ts +++ b/src/markdown/parse/plain-markdown-to-adf.test.ts @@ -3,9 +3,9 @@ import test from 'node:test' import type { AdfAttributes, AdfDocument, AdfMark, AdfNode } from '../../adf/document.ts' import { adfToMarkdown } from '../emit/adf-to-markdown.ts' +import { adfToPlainMarkdown } from '../emit/plain-reduction.ts' import { largestNesting } from '../../nesting.ts' import { markdownToAdf, plainMarkdownToAdf } from './markdown-to-adf.ts' -import { reduceToPlain } from '../emit/plain-reduction.ts' import { toEditorNormal } from '../../adf/editor-normal.ts' const code: AdfMark = { type: 'code' } @@ -26,10 +26,8 @@ function document(...content: AdfNode[]): AdfDocument { return { content, type: 'doc', version: 1 } } -// ADF the reduction wrote, spelled and read back. function roundTripped(...content: AdfNode[]): readonly AdfNode[] | string { - const reduced = reduceToPlain(document(...content)) - const markdown = reduced.ok ? adfToMarkdown(reduced.value) : reduced + const markdown = adfToPlainMarkdown(document(...content)) return markdown.ok ? read(markdown.value) : markdown.error.code } @@ -190,6 +188,16 @@ test('reads what the reduction wrote back to the node it reduced, less the attri assert.deepEqual(roundTripped(tasks), [plainTasks]) const colour: AdfMark = { attrs: { color: '#c6edfb' }, type: 'backgroundColor' } assert.deepEqual(roundTripped(paragraph(text('a '), text('hi', colour, strong), text(' b'))), [paragraph(text('a '), text('hi', highlight, strong), text(' b'))]) + assert.deepEqual(roundTripped(paragraph(text('=', colour), text(' '), text('a==b', colour))), [paragraph(text('=', highlight), text(' '), text('a==b', highlight))]) + assert.deepEqual(roundTripped(paragraph(text('x'), text('y', colour))), [said('xy')]) + assert.deepEqual(roundTripped(node('expand', { title: '**x** [y](z)' }, said('b'))), [node('expand', { title: '**x** [y](z)' }, said('b'))]) +}) + +test('reads text the writer kept from reading as a marker back as text', () => { + const quote = bare('blockquote', said('[!NOTE] x')) + const list = bare('bulletList', bare('listItem', said('[x] a')), bare('listItem', said('[ ] b'))) + assert.deepEqual(roundTripped(said('==x== a==b'), quote, list), [said('==x== a==b'), quote, list]) + assert.deepEqual(roundTripped(bare('taskList', task('DONE', text('[x] ==a==')))), [bare('taskList', task('DONE', text('[x] ==a==')))]) }) test('keeps what markdownToAdf reads that no row reads, and refuses only what it refuses', () => { -- 2.52.0 From 06103ea2baf52c22b7af4eb095f0c9926141b960 Mon Sep 17 00:00:00 2001 From: Lilleman auf Larv Date: Tue, 29 Sep 2026 11:42:46 +0200 Subject: [PATCH 02/14] 35b - the writer spells the plain flavour and escapes text that would read as its markers --- src/markdown/emit/adf-to-markdown.ts | 143 +++++++++++++++++----- src/markdown/emit/inline-line.ts | 45 ++++--- src/markdown/emit/line-escaping.ts | 51 ++++++-- src/markdown/emit/pipe-table.ts | 5 +- src/markdown/emit/plain-inline.ts | 12 +- src/markdown/emit/plain-reduction.test.ts | 7 +- src/markdown/emit/plain-reduction.ts | 101 ++++++++++++--- src/markdown/parse/inline-content.ts | 16 +-- src/markdown/parse/markdown-to-adf.ts | 10 +- src/markdown/plain-conventions.ts | 22 ++++ 10 files changed, 305 insertions(+), 107 deletions(-) diff --git a/src/markdown/emit/adf-to-markdown.ts b/src/markdown/emit/adf-to-markdown.ts index 7077bd7..0603a49 100644 --- a/src/markdown/emit/adf-to-markdown.ts +++ b/src/markdown/emit/adf-to-markdown.ts @@ -1,6 +1,8 @@ import type { AdfDocument, AdfNode } from '../../adf/document.ts' import type { BlockNodeModel } from '../../adf/block-nodes.ts' +import type { Flavour } from '../plain-conventions.ts' import { adfDocumentFault, carriesOnly, nodeAttrs, nodeContent, nodeMarks } from '../../adf/document.ts' +import { alertMarker, foldedAlertMarker, leadingMarker, readAlertMarker, readTaskMarker, taskMarker } from '../plain-conventions.ts' import { blockDirectiveForm, listBreakSpelling } from '../block-directive.ts' import { blockNodeModel, blockNodes } from '../../adf/block-nodes.ts' import { carriedBlock } from '../opaque-carry.ts' @@ -24,28 +26,33 @@ type PlacedBlock = Omit & { node: AdfNode } export type SpellingMemo = Map type Walk = { blocks: readonly PlacedBlock[]; headroom: number } type WalkedItem = { node: AdfNode; walk: Walk } +export type Writing = { flavour: Flavour; memo: SpellingMemo | undefined } export const largestListMarker = 999999999 // Bare because tryList admits no item carrying attributes, marks or text. const listItemOpener = spellDirectiveOpener('listItem', undefined, '') export function adfToMarkdown(document: AdfDocument): Result { + return writeMarkdown(document, 'lossless') +} + +export function writeMarkdown(document: AdfDocument, flavour: Flavour): Result { const fault = adfDocumentFault(document) if (fault !== undefined) return faulted(fault, []) if (document.version !== 1) return failure('unsupported-document-version', `no markdown spelling carries ADF version ${document.version}`, []) - const walk = walkBlocks(nodeContent(document), [], 0, undefined) + const walk = walkBlocks(nodeContent(document), [], 0, { flavour, memo: undefined }) if (!walk.ok) return walk const text = joinBlocks(walk.value.blocks, 'document') return success(text === '' ? '' : `${text}\n`) } // headroom: the least slack any depth guard below the walk has. -function walkBlocks(nodes: readonly AdfNode[], path: ConvertErrorPath, depth: number, memo: SpellingMemo | undefined): Result { +function walkBlocks(nodes: readonly AdfNode[], path: ConvertErrorPath, depth: number, writing: Writing): Result { let headroom = largestNesting - depth if (headroom < 0) return tooDeep(path) const blocks: PlacedBlock[] = [] for (const [index, node] of nodes.entries()) { - const block = emitBlock(node, [...path, 'content', index], depth, memo) + const block = emitBlock(node, [...path, 'content', index], depth, writing) if (!block.ok) return block headroom = Math.min(headroom, block.value.headroom) blocks.push({ ...block.value, node }) @@ -81,51 +88,119 @@ function separationBetween(previous: PlacedBlock, next: PlacedBlock, container: function interruptsParagraph(node: AdfNode): boolean { const items = nodeContent(node) - const empty = items[0] === undefined || nodeContent(items[0]).length === 0 + const empty = node.type !== 'taskList' && (items[0] === undefined || nodeContent(items[0]).length === 0) if (node.type !== 'orderedList') return markerInterruptsParagraph(undefined, empty) return markerInterruptsParagraph(listStart(node, items.length) ?? 0, empty) } -function emitBlock(node: AdfNode, path: ConvertErrorPath, depth: number, memo: SpellingMemo | undefined): Result { +function emitBlock(node: AdfNode, path: ConvertErrorPath, depth: number, writing: Writing): Result { const model = blockNodeModel(node.type) if (model === undefined) return commonMarkLine(carriedBlock(node, path, depth)) - const readable = readableBlock(node, path, depth, memo) + const readable = readableBlock(node, path, depth, writing) if (readable !== undefined) return readable - return emitDirectiveBlock(node, model, path, depth, () => walkBlocks(nodeContent(node), path, depth + 1, memo)) + return emitDirectiveBlock(node, model, path, depth, () => walkBlocks(nodeContent(node), path, depth + 1, writing)) } -export function commonMarkSpelling(node: AdfNode, path: ConvertErrorPath, depth: number, memo: SpellingMemo): Result | undefined { - const readable = readableBlock(node, path, depth, memo) +export function commonMarkSpelling(node: AdfNode, path: ConvertErrorPath, depth: number, writing: Writing): Result | undefined { + const readable = readableBlock(node, path, depth, writing) if (readable === undefined) return undefined if (!readable.ok) return readable return readable.value.spelling === 'directive' ? undefined : success(null) } -function readableBlock(node: AdfNode, path: ConvertErrorPath, depth: number, memo: SpellingMemo | undefined): Result | undefined { +function readableBlock(node: AdfNode, path: ConvertErrorPath, depth: number, writing: Writing): Result | undefined { + const { memo } = writing const kept = memo?.get(node) if (kept !== undefined) { if (kept.block === undefined) return undefined // A read below the fill would skip the depth guards the walk it replaces runs (docs/decisions.md §The spelling memo). if (depth <= kept.depth) return success({ ...kept.block, headroom: kept.block.headroom + kept.depth - depth }) } - const spelled = spellReadableBlock(node, path, depth, memo) + const spelled = spellReadableBlock(node, path, depth, writing) if (spelled === undefined) memo?.set(node, { block: undefined, depth }) else if (spelled.ok) memo?.set(node, { block: spelled.value, depth }) return spelled } -function spellReadableBlock(node: AdfNode, path: ConvertErrorPath, depth: number, memo: SpellingMemo | undefined): Result | undefined { - if (node.type === 'blockquote') return tryBlockquote(node, path, depth, memo) - if (node.type === 'bulletList' || node.type === 'orderedList') return tryList(node, path, depth, memo) +function spellReadableBlock(node: AdfNode, path: ConvertErrorPath, depth: number, writing: Writing): Result | undefined { + const plain = writing.flavour === 'plain' ? spellPlainBlock(node, path, depth, writing) : undefined + if (plain !== undefined) return plain + if (node.type === 'blockquote') return tryBlockquote(node, path, depth, writing) + if (node.type === 'bulletList' || node.type === 'orderedList') return tryList(node, path, depth, writing) if (node.type === 'codeBlock') return tryCodeBlock(node, path) - if (node.type === 'heading') return tryHeading(node, path) + if (node.type === 'heading') return tryHeading(node, path, writing.flavour) if (node.type === 'mediaSingle') return readableText(tryImage(node, path)) - if (node.type === 'paragraph') return tryParagraph(node, path) + if (node.type === 'paragraph') return tryParagraph(node, path, writing.flavour) if (node.type === 'rule') return readableText(tryRule(node)) - if (node.type === 'table') return readableText(tryPipeTable(node, path)) + if (node.type === 'table') return readableText(tryPipeTable(node, path, writing.flavour)) return undefined } +// The plain flavour's nodes, in the shapes the plain reduction leaves them. +function spellPlainBlock(node: AdfNode, path: ConvertErrorPath, depth: number, writing: Writing): Result | undefined { + if (node.type === 'panel') return quotedUnder(alertMarker(nodeAttrs(node)['panelType']), node, path, depth, writing) + if (node.type === 'taskList') return tryTaskList(node, path, depth, writing) + if (node.type !== 'expand' && node.type !== 'nestedExpand') return undefined + const title = nodeAttrs(node)['title'] + if (typeof title !== 'string') return quotedUnder(foldedAlertMarker, node, path, depth, writing) + // The reader takes a title as lossless inline text. + const line = emitInlineLine([{ text: title, type: 'text' }], 'paragraph', path, 'lossless') + return line.ok ? quotedUnder(`${foldedAlertMarker} ${line.value}`, node, path, depth, writing) : line +} + +function quotedUnder(head: string, node: AdfNode, path: ConvertErrorPath, depth: number, writing: Writing): Result { + const inner = walkBlocks(nodeContent(node), path, depth + 1, writing) + if (!inner.ok) return inner + const body = joinBlocks(inner.value.blocks, 'document') + return success(commonMarkText(quoted(body === '' ? head : `${head}\n\n${body}`), inner.value.headroom)) +} + +function quoted(text: string): string { + return text + .split('\n') + .map((line) => (line === '' ? '>' : `> ${line}`)) + .join('\n') +} + +function tryTaskList(node: AdfNode, path: ConvertErrorPath, depth: number, writing: Writing): Result | undefined { + const items: PlacedBlock[][] = [] + let headroom = largestNesting - depth - 1 + // A child other than a task nests in the task before it. + for (const [index, child] of nodeContent(node).entries()) { + const task = child.type === 'taskItem' || child.type === 'blockTaskItem' + const walk = task ? taskBlocks(child, [...path, 'content', index], depth + 1, writing) : placedBlock(child, [...path, 'content', index], depth + 1, writing) + if (!walk.ok) return walk + headroom = Math.min(headroom, walk.value.headroom) + const previous = items.at(-1) + if (task || previous === undefined) items.push([...walk.value.blocks]) + else for (const block of walk.value.blocks) previous.push(block) + } + const lines = items.map((blocks) => tryListItemLines(joinBlocks(blocks, 'list-item'), '- ')) + return lines.includes(undefined) ? undefined : success({ headroom, spelling: 'list', text: lines.join('\n') }) +} + +function placedBlock(node: AdfNode, path: ConvertErrorPath, depth: number, writing: Writing): Result { + const block = emitBlock(node, path, depth, writing) + return block.ok ? success({ blocks: [{ ...block.value, node }], headroom: block.value.headroom }) : block +} + +// The marker leads the first paragraph, or stands as one where the blocks open with another. +function taskBlocks(task: AdfNode, path: ConvertErrorPath, depth: number, writing: Writing): Result { + const marker = taskMarker(nodeAttrs(task)['state']) + const markerBlock: PlacedBlock = { node: { type: 'paragraph' }, spelling: 'commonmark', text: marker } + if (task.type === 'taskItem') { + const content = nodeContent(task) + const line = content.length === 0 ? success('') : emitInlineLine(content, 'paragraph', path, writing.flavour) + if (!line.ok) return line + return success({ blocks: [{ ...markerBlock, text: line.value === '' ? marker : `${marker} ${line.value}` }], headroom: Number.POSITIVE_INFINITY }) + } + const walk = walkBlocks(nodeContent(task), path, depth, writing) + if (!walk.ok) return walk + const [first, ...rest] = walk.value.blocks + const blocks = first?.node.type === 'paragraph' ? [{ ...first, text: `${marker} ${first.text}` }, ...rest] : [markerBlock, ...walk.value.blocks] + return success({ blocks, headroom: walk.value.headroom }) +} + function readableText(text: string | undefined): Result | undefined { return text === undefined ? undefined : success(commonMarkText(text)) } @@ -156,7 +231,7 @@ function emitDirectiveBlock(node: AdfNode, model: BlockNodeModel, path: ConvertE function emitDirectiveBody(node: AdfNode, model: BlockNodeModel, opener: string, path: ConvertErrorPath, walkBody: () => Result): Result { if (blockDirectiveForm(node.type) === 'leaf') return success({ headroom: Number.POSITIVE_INFINITY, spelling: 'directive', text: opener }) if (model.contentModel === 'inline') { - const line = emitInlineLine(nodeContent(node), 'paragraph', path) + const line = emitInlineLine(nodeContent(node), 'paragraph', path, 'lossless') if (!line.ok) return line return success(directivePair(node, opener, line.value)) } @@ -165,15 +240,13 @@ function emitDirectiveBody(node: AdfNode, model: BlockNodeModel, opener: string, return success(directivePair(node, opener, joinBlocks(walk.value.blocks, 'directive'), walk.value.headroom)) } -function tryBlockquote(node: AdfNode, path: ConvertErrorPath, depth: number, memo: SpellingMemo | undefined): Result | undefined { +function tryBlockquote(node: AdfNode, path: ConvertErrorPath, depth: number, writing: Writing): Result | undefined { if (!carriesOnly(node, [])) return undefined - const inner = walkBlocks(nodeContent(node), path, depth + 1, memo) + const inner = walkBlocks(nodeContent(node), path, depth + 1, writing) if (!inner.ok) return inner const text = joinBlocks(inner.value.blocks, 'document') - .split('\n') - .map((line) => (line === '' ? '>' : `> ${line}`)) - .join('\n') - return success(commonMarkText(text, inner.value.headroom)) + const alert = writing.flavour === 'plain' && leadingMarker(text, readAlertMarker) !== undefined + return success(commonMarkText(quoted(alert ? `\\${text}` : text), inner.value.headroom)) } function tryCodeBlock(node: AdfNode, path: ConvertErrorPath): Result | undefined { @@ -216,19 +289,19 @@ function codeBlockText(node: AdfNode, path: ConvertErrorPath): Result { return success(text) } -function tryHeading(node: AdfNode, path: ConvertErrorPath): Result | undefined { +function tryHeading(node: AdfNode, path: ConvertErrorPath, flavour: Flavour): Result | undefined { if (!carriesOnly(node, ['level'])) return undefined const level = nodeAttrs(node)['level'] if (typeof level !== 'number' || !Number.isInteger(level) || level < 1 || level > 6) return undefined const hashes = '#'.repeat(level) const content = nodeContent(node) if (content.length === 0) return success(commonMarkText(hashes)) - const line = emitInlineLine(content, 'heading', path) + const line = emitInlineLine(content, 'heading', path, flavour) if (!line.ok) return line return success(commonMarkText(`${hashes} ${line.value}`)) } -function tryList(node: AdfNode, path: ConvertErrorPath, depth: number, memo: SpellingMemo | undefined): Result | undefined { +function tryList(node: AdfNode, path: ConvertErrorPath, depth: number, writing: Writing): Result | undefined { const ordered = node.type === 'orderedList' if (!carriesOnly(node, ordered ? ['order'] : [])) return undefined const items = nodeContent(node) @@ -238,14 +311,17 @@ function tryList(node: AdfNode, path: ConvertErrorPath, depth: number, memo: Spe const walked: WalkedItem[] = [] let headroom = Number.POSITIVE_INFINITY for (const [offset, item] of items.entries()) { - const walk = walkBlocks(nodeContent(item), [...path, 'content', offset], depth + 1, memo) + 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 }) } + const inners = walked.map((item) => joinBlocks(item.walk.blocks, 'list-item')) + // A bullet list whose every item opens with a task marker reads as a task list (README §Plain markdown). + if (writing.flavour === 'plain' && !ordered && inners.every((inner) => leadingMarker(inner, readTaskMarker) !== undefined)) inners[0] = `\\${inners[0] ?? ''}` const lines: string[] = [] - for (const [offset, item] of walked.entries()) { - const line = tryListItemLines(item.walk.blocks, ordered ? `${start + offset}. ` : '- ') + for (const [offset, inner] of inners.entries()) { + const line = tryListItemLines(inner, ordered ? `${start + offset}. ` : '- ') if (line === undefined) { // The directive form spends a level the walk did not count. if (headroom < 1) return tooDeep(path) @@ -267,8 +343,7 @@ function listStart(node: AdfNode, items: number): number | undefined { return start + items - 1 > largestListMarker ? undefined : start } -function tryListItemLines(blocks: readonly PlacedBlock[], marker: string): string | undefined { - const inner = joinBlocks(blocks, 'list-item') +function tryListItemLines(inner: string, marker: string): string | undefined { if (inner === '') return marker.trimEnd() const body = inner.split('\n') if (body.some((line) => line !== '' && isBlankLine(line))) return undefined @@ -278,10 +353,10 @@ function tryListItemLines(blocks: readonly PlacedBlock[], marker: string): strin return lines.join('\n') } -function tryParagraph(node: AdfNode, path: ConvertErrorPath): Result | undefined { +function tryParagraph(node: AdfNode, path: ConvertErrorPath, flavour: Flavour): Result | undefined { const content = nodeContent(node) if (content.length === 0 || !carriesOnly(node, [])) return undefined - const line = emitInlineLine(content, 'paragraph', path) + const line = emitInlineLine(content, 'paragraph', path, flavour) if (!line.ok) return line return success(commonMarkText(line.value)) } diff --git a/src/markdown/emit/inline-line.ts b/src/markdown/emit/inline-line.ts index 796c8e1..7ff708c 100644 --- a/src/markdown/emit/inline-line.ts +++ b/src/markdown/emit/inline-line.ts @@ -1,4 +1,5 @@ import type { AdfMark, AdfNode } from '../../adf/document.ts' +import type { Flavour } from '../plain-conventions.ts' import type { InlineNodeModel } from '../../adf/inline-nodes.ts' import type { LineContainer } from '../line-container.ts' import { assembleInlineLine, isSyntax, type InlineEscaping, type InlineSegment, type MarkRun, type NodeRange } from './line-escaping.ts' @@ -7,6 +8,7 @@ import { claimsLine, holdsNullCharacter, trimTrailingSpace } from '../commonmark import { commonMarkLink, linkHref, markSpelling, spellMarkAttributes } from '../mark-spellings.ts' import { escapeUnbalanced, spellDestination } from '../commonmark/link-syntax.ts' import { failure, faulted, success, type ConvertErrorPath, type Result } from '../../result.ts' +import { highlightDelimiter } from '../plain-conventions.ts' import { inlineNodeModel } from '../../adf/inline-nodes.ts' import { largestNesting } from '../../nesting.ts' import { longestBacktickRun } from '../commonmark/backtick-runs.ts' @@ -24,6 +26,7 @@ type InlineContext = { atBlockEnd: boolean bracketed: boolean carried: ReadonlySet + flavour: Flavour openingLinkAsDirective: boolean path: ConvertErrorPath spansLines: boolean @@ -33,32 +36,32 @@ type InlineRun = { index: number; kind: 'marked'; mark: AdfMark; nodes: AdfNode[ type LineAttempt = { fallback: NodeRange | 'opening-link'; line?: undefined } | { fallback?: undefined; line: string } -type LineFallbacks = { carried: Set; openingLinkAsDirective: boolean } +type LineFallbacks = { carried: Set; flavour: Flavour; openingLinkAsDirective: boolean } export type PlainLineFallback = { kind: 'claimed-line'; line: number; text: string } | { kind: 'opening-link' } | { kind: 'unspellable-run'; run: MarkRun } -export function emitInlineLine(nodes: readonly AdfNode[], container: LineContainer, path: ConvertErrorPath): Result { - const emitted = emitLine(nodes, container, path) +export function emitInlineLine(nodes: readonly AdfNode[], container: LineContainer, path: ConvertErrorPath, flavour: Flavour): Result { + const emitted = emitLine(nodes, container, path, flavour) if (!emitted.ok) return emitted return success(emitted.value.line) } export function openingLinkTakesDirective(nodes: readonly AdfNode[], path: ConvertErrorPath): Result { - const emitted = emitLine(nodes, 'paragraph', path) + const emitted = emitLine(nodes, 'paragraph', path, 'lossless') if (!emitted.ok) return emitted return success(emitted.value.openingLinkAsDirective) } export function plainLineFallback(nodes: readonly AdfNode[], container: LineContainer, path: ConvertErrorPath): Result { - const emission = lineSegments(nodes, container, path, { carried: new Set(), openingLinkAsDirective: false }) + const emission = lineSegments(nodes, container, path, { carried: new Set(), flavour: 'plain', openingLinkAsDirective: false }) if (!emission.ok) return emission if (emission.value.carry !== undefined) return failure('unsupported-node-shape', 'an inline node on a plain line has no spelling but the carry', path) - const verdict = lineVerdict(emission.value.segments, container) + const verdict = lineVerdict(emission.value.segments, container, 'plain') return success(verdict.kind === 'line' ? undefined : verdict) } -export function tryPipeCell(nodes: readonly AdfNode[], path: ConvertErrorPath): string | undefined { - const emitted = emitLine(nodes, 'table-cell', path) +export function tryPipeCell(nodes: readonly AdfNode[], path: ConvertErrorPath, flavour: Flavour): string | undefined { + const emitted = emitLine(nodes, 'table-cell', path, flavour) if (!emitted.ok) return undefined if (emitted.value.segments.some((segment) => isSyntax(segment.escaping) && segment.text.includes('|'))) return undefined return emitted.value.line @@ -69,12 +72,12 @@ export function tryImageLine(alt: string | undefined, href: string, path: Conver const destination = spellDestination(href) if (destination === undefined) return undefined const description: InlineSegment[] = alt === undefined ? [] : [{ escaping: 'bracketed', text: alt }] - const attempt = attemptLine([syntax('!['), ...description, syntax(`](${destination})`)], 'paragraph', path) + const attempt = attemptLine([syntax('!['), ...description, syntax(`](${destination})`)], 'paragraph', path, 'lossless') return attempt.ok ? attempt.value.line : undefined } -function emitLine(nodes: readonly AdfNode[], container: LineContainer, path: ConvertErrorPath): Result { - const fallbacks: LineFallbacks = { carried: new Set(), openingLinkAsDirective: false } +function emitLine(nodes: readonly AdfNode[], container: LineContainer, path: ConvertErrorPath, flavour: Flavour): Result { + const fallbacks: LineFallbacks = { carried: new Set(), flavour, openingLinkAsDirective: false } // Terminates because takeFallback refuses a pass that took no new fallback. for (;;) { const emission = lineSegments(nodes, container, path, fallbacks) @@ -84,7 +87,7 @@ function emitLine(nodes: readonly AdfNode[], container: LineContainer, path: Con if (!taken.ok) return taken continue } - const attempt = attemptLine(emission.value.segments, container, path) + const attempt = attemptLine(emission.value.segments, container, path, flavour) if (!attempt.ok) return attempt if (attempt.value.line !== undefined) { return success({ line: attempt.value.line, openingLinkAsDirective: fallbacks.openingLinkAsDirective, segments: emission.value.segments }) @@ -114,8 +117,8 @@ function lineSegments(nodes: readonly AdfNode[], container: LineContainer, path: return success({ segments: carryStrippedWhitespace(emission.value.segments) }) } -function attemptLine(segments: readonly InlineSegment[], container: LineContainer, path: ConvertErrorPath): Result { - const verdict = lineVerdict(segments, container) +function attemptLine(segments: readonly InlineSegment[], container: LineContainer, path: ConvertErrorPath, flavour: Flavour): Result { + const verdict = lineVerdict(segments, container, flavour) if (verdict.kind === 'opening-link') return success({ fallback: 'opening-link' }) if (verdict.kind === 'unspellable-run') return success({ fallback: verdict.run }) if (verdict.kind === 'claimed-line') return failure('unspellable-line-start', `block parsing would claim the emitted line ${JSON.stringify(verdict.text)}`, path) @@ -123,8 +126,8 @@ function attemptLine(segments: readonly InlineSegment[], container: LineContaine } // The fallbacks in the order a line takes them, or the line where it takes none. -function lineVerdict(segments: readonly InlineSegment[], container: LineContainer): PlainLineFallback | { kind: 'line'; text: string } { - const assembled = assembleInlineLine(segments, container) +function lineVerdict(segments: readonly InlineSegment[], container: LineContainer, flavour: Flavour): PlainLineFallback | { kind: 'line'; text: string } { + const assembled = assembleInlineLine(segments, container, flavour) if (assembled.openingLinkAsDirective) return { kind: 'opening-link' } if (assembled.unspellableRun !== undefined) return { kind: 'unspellable-run', run: assembled.unspellableRun } const lines = assembled.line.split('\n') @@ -270,6 +273,7 @@ function emitText(node: AdfNode, context: InlineContext, index: number, path: Co function emitMarkedRun(nodes: readonly AdfNode[], mark: AdfMark, depth: number, index: number, context: InlineContext): Result { const path = nodePath(context, index) const range: NodeRange = { first: index, last: index + nodes.length - 1 } + if (mark.type === 'backgroundColor' && context.flavour === 'plain') return emitHighlight(nodes, depth, range, context) const spelling = markSpelling(mark.type) if (spelling === undefined) return success({ carry: range }) const attributes = spellMarkAttributes(mark, spelling.attributes) @@ -298,6 +302,15 @@ function emitEmphasis(nodes: readonly AdfNode[], spelling: string, depth: number }) } +function emitHighlight(nodes: readonly AdfNode[], depth: number, range: NodeRange, context: InlineContext): Result { + const inner = emitRun(nodes, depth + 1, range.first, context) + if (!inner.ok || inner.value.carry !== undefined) return inner + const run = { ...range, depth } + return success({ + segments: [{ escaping: 'none', highlight: 'open', nodes: run, text: highlightDelimiter }, ...inner.value.segments, { escaping: 'none', highlight: 'close', nodes: run, text: highlightDelimiter }], + }) +} + function emitCodeSpan(nodes: readonly AdfNode[], depth: number, range: NodeRange, path: ConvertErrorPath): Result { let text = '' for (const node of nodes) { diff --git a/src/markdown/emit/line-escaping.ts b/src/markdown/emit/line-escaping.ts index 34e000f..16098a6 100644 --- a/src/markdown/emit/line-escaping.ts +++ b/src/markdown/emit/line-escaping.ts @@ -1,13 +1,15 @@ +import type { Flavour } from '../plain-conventions.ts' import type { LineContainer } from '../line-container.ts' import { backslashEscape, escapesLineClaim, inlineHtmlConstruct, opensBracketedAutolink, opensEmailAutolink, type LinePosition } from '../commonmark/grammar.ts' import { backtickRun, closingBacktickRun } from '../commonmark/backtick-runs.ts' import { claimsDirectivePrefix } from '../directive-syntax.ts' import { delimiterFlags, isWordCharacter, matchEmphasis, runLength } from '../commonmark/emphasis-matching.ts' +import { highlightDelimiter, highlightFlanking } from '../plain-conventions.ts' import { isBareDelimiterRow } from '../pipe-table-syntax.ts' import { opensLinkDefinition } from '../commonmark/link-reference-definitions.ts' import { readEntityReference } from '../commonmark/entity-references.ts' -export type EmphasisRole = 'close' | 'open' +export type DelimiterRole = 'close' | 'open' export type InlineEscaping = 'backslash' | 'bracketed' | 'bracketed-link-target' | 'none' @@ -16,9 +18,10 @@ export type NodeRange = { first: number; last: number } export type MarkRun = NodeRange & { depth: number } export type InlineSegment = - | { emphasis: EmphasisRole; escaping: 'none'; nodes: MarkRun; text: string } - | { emphasis?: undefined; escaping: 'none'; nodes: NodeRange; text: string } - | { emphasis?: undefined; escaping: InlineEscaping; nodes?: undefined; text: string } + | { emphasis: DelimiterRole; escaping: 'none'; highlight?: undefined; nodes: MarkRun; text: string } + | { emphasis?: undefined; escaping: 'none'; highlight: DelimiterRole; nodes: MarkRun; text: string } + | { emphasis?: undefined; escaping: 'none'; highlight?: undefined; nodes: NodeRange; text: string } + | { emphasis?: undefined; escaping: InlineEscaping; highlight?: undefined; nodes?: undefined; text: string } export type AssembledLine = { line: string; openingLinkAsDirective?: true; unspellableRun: MarkRun | undefined } @@ -32,8 +35,8 @@ const delimiters = ['*', '_', '`', '~'] const followsLinkText = /[([]/ -export function assembleInlineLine(segments: readonly InlineSegment[], container: LineContainer): AssembledLine { - return escape(resolveEmphasis(segments), container) +export function assembleInlineLine(segments: readonly InlineSegment[], container: LineContainer, flavour: Flavour): AssembledLine { + return escape(resolveEmphasis(segments), container, flavour === 'plain') } function resolveEmphasis(segments: readonly InlineSegment[]): InlineSegment[] { @@ -65,11 +68,11 @@ function resolveEmphasis(segments: readonly InlineSegment[]): InlineSegment[] { return resolved } -function escape(segments: readonly InlineSegment[], container: LineContainer): AssembledLine { +function escape(segments: readonly InlineSegment[], container: LineContainer, highlights: boolean): AssembledLine { const scan = segments.map((segment) => segment.text).join('') const escapings: InlineEscaping[] = [] for (const segment of segments) for (let index = 0; index < segment.text.length; index += 1) escapings.push(segment.escaping) - const escaped = escapeClosedRuns(scan, escapings, escapeClaims(scan, escapings, container)) + const escaped = escapeClosedRuns(scan, escapings, escapeClaims(scan, escapings, container, highlights)) const placements: number[] = [] let output = '' for (let index = 0; index < scan.length; index += 1) { @@ -84,28 +87,39 @@ function escape(segments: readonly InlineSegment[], container: LineContainer): A return { line: output, unspellableRun: unspellableRun(segments, output, placements) } } -function escapeClaims(scan: string, escapings: readonly InlineEscaping[], container: LineContainer): ReadonlySet { +function escapeClaims(scan: string, escapings: readonly InlineEscaping[], container: LineContainer, highlights: boolean): ReadonlySet { const escaped = new Set() const linkClose = lastLinkClose(scan, escapings) let line = scanLine(scan, 0) let afterEscape = false + // Whether the `=` before opens a `==` the reader takes whole, so this one starts nothing. + let pairsEquals = false for (let index = 0; index < scan.length; index += 1) { if (index > line.start + line.text.length) line = scanLine(scan, line.start + line.text.length + 1) const escaping = escapings[index] const escapable = escaping === 'backslash' || escaping === 'bracketed' + const opensEquals: boolean = highlights && !pairsEquals && scan.startsWith(highlightDelimiter, index) const claimed: boolean = (escapable && - (claimsLineStart(line, index, container) || + ((opensEquals && claimsHighlight(scan, index)) || + claimsLineStart(line, index, container) || mergesWithSyntax(scan, escapings, index) || opensConstruct(scan, linkClose, index, escaping === 'bracketed', container, afterEscape))) || (escaping === 'bracketed-link-target' && ((scan.charAt(index) === '`' && opensCodeSpan(scan, index, afterEscape)) || claimsDirectivePrefix(scan, index))) if (claimed) escaped.add(index) afterEscape = claimed + pairsEquals = opensEquals && !claimed } return escaped } +// Like an emphasis run, a `==` in text escapes where the reader can open or close with it. +function claimsHighlight(scan: string, index: number): boolean { + const flanking = highlightFlanking(scan, index) + return flanking.opens || flanking.closes +} + // CommonMark reads no escape inside a code span, so a backtick string an escape forms or splits off still closes one an earlier bare run opens. function escapeClosedRuns(scan: string, escapings: readonly InlineEscaping[], claimed: ReadonlySet): ReadonlySet { const escaped = new Set(claimed) @@ -137,7 +151,22 @@ function escapeClosedRuns(scan: string, escapings: readonly InlineEscaping[], cl function unspellableRun(segments: readonly InlineSegment[], output: string, placements: readonly number[]): MarkRun | undefined { const { nodes, runs } = emittedRuns(segments, placements, output) const pair = misflanked(runs) ?? unpaired(runs) - return pair === undefined ? undefined : nodes[pair] + return pair === undefined ? unreadHighlight(segments, output, placements) : nodes[pair] +} + +// No `==` in text can open or close, and highlights never nest, so a pair reads back where each delimiter flanks and both share a line. +function unreadHighlight(segments: readonly InlineSegment[], output: string, placements: readonly number[]): MarkRun | undefined { + let cursor = 0 + let opener = 0 + for (const segment of segments) { + const start = placements[cursor] ?? 0 + cursor += segment.text.length + if (segment.highlight === undefined) continue + const flanking = highlightFlanking(output, start) + if (segment.highlight === 'open') opener = start + if (segment.highlight === 'open' ? !flanking.opens : !flanking.closes || output.slice(opener, start).includes('\n')) return segment.nodes + } + return undefined } function misflanked(runs: readonly EmittedRun[]): number | undefined { diff --git a/src/markdown/emit/pipe-table.ts b/src/markdown/emit/pipe-table.ts index b3234fd..f200e6d 100644 --- a/src/markdown/emit/pipe-table.ts +++ b/src/markdown/emit/pipe-table.ts @@ -1,10 +1,11 @@ import type { AdfNode } from '../../adf/document.ts' import type { ConvertErrorPath } from '../../result.ts' +import type { Flavour } from '../plain-conventions.ts' import { carriesOnly, nodeContent } from '../../adf/document.ts' import { spellPipeDelimiter, spellPipeRow } from '../pipe-table-syntax.ts' import { tryPipeCell } from './inline-line.ts' -export function tryPipeTable(node: AdfNode, path: ConvertErrorPath): string | undefined { +export function tryPipeTable(node: AdfNode, path: ConvertErrorPath, flavour: Flavour): string | undefined { const rows = pipeRows(node) if (rows === undefined) return undefined const lines: string[] = [] @@ -12,7 +13,7 @@ export function tryPipeTable(node: AdfNode, path: ConvertErrorPath): string | un const cells: string[] = [] for (const [cellIndex, paragraph] of row.entries()) { const content = nodeContent(paragraph) - const line = content.length === 0 ? '' : tryPipeCell(content, [...path, 'content', rowIndex, 'content', cellIndex, 'content', 0]) + const line = content.length === 0 ? '' : tryPipeCell(content, [...path, 'content', rowIndex, 'content', cellIndex, 'content', 0], flavour) if (line === undefined) return undefined cells.push(line) } diff --git a/src/markdown/emit/plain-inline.ts b/src/markdown/emit/plain-inline.ts index 4fec787..9fb8bf2 100644 --- a/src/markdown/emit/plain-inline.ts +++ b/src/markdown/emit/plain-inline.ts @@ -2,7 +2,6 @@ import type { AdfAttributes, AdfMark, AdfNode } from '../../adf/document.ts' import type { LineContainer } from '../line-container.ts' import { blockNodeModel } from '../../adf/block-nodes.ts' import { failure, success, type ConvertErrorPath, type Result } from '../../result.ts' -import { highlightDelimiter } from '../plain-conventions.ts' import { largestNesting } from '../../nesting.ts' import { mergeAdjacentText, sameMark } from '../../adf/editor-normal.ts' import { nodeAttrs, nodeContent, nodeMarks } from '../../adf/document.ts' @@ -10,6 +9,7 @@ import { plainLineFallback, type PlainLineFallback } from './inline-line.ts' import { spellDestination, spellLinkTarget } from '../commonmark/link-syntax.ts' const highlight = 'backgroundColor' +const highlightMark: AdfMark = { type: highlight } const edgeStrippingMarks: readonly string[] = [highlight, 'em', 'strike', 'strong'] const keptMarks: readonly string[] = [...edgeStrippingMarks, 'code', 'link'] @@ -140,7 +140,9 @@ function plainMarks(marks: readonly AdfMark[], container: LineContainer, text: s if (plain !== undefined) kept.push(plain) } const rank = (mark: AdfMark): number => (mark.type === highlight ? 0 : mark.type === 'code' ? 2 : 1) - return kept.sort((first, second) => rank(first) - rank(second)) + // The reader highlights no code, as Atlassian's schema allows none. + const code = kept.some((mark) => mark.type === 'code') + return kept.filter((mark) => !code || mark.type !== highlight).sort((first, second) => rank(first) - rank(second)) } function plainLink(mark: AdfMark, container: LineContainer): AdfMark | undefined { @@ -163,7 +165,7 @@ export function writableHref(href: string): string { return written } -// The delimiters carry the marks the whole run shares, so they open and close inside them. +// The marks a whole highlight run shares go outside the highlight, so its delimiters open and close inside them. function highlighted(leaves: readonly AdfNode[]): AdfNode[] { const spelled: AdfNode[] = [] let run: AdfNode[] = [] @@ -173,10 +175,10 @@ function highlighted(leaves: readonly AdfNode[]): AdfNode[] { if (marks[0]?.type === highlight) { const held = marks.slice(1) shared = run.length === 0 ? held.filter((mark) => mark.type !== 'code') : shared.filter((mark) => held.some((other) => sameMark(other, mark))) - run.push(withMarks(leaf, held)) + run.push(leaf) continue } - if (run.length > 0) for (const held of [textLeaf(highlightDelimiter, shared), ...run, textLeaf(highlightDelimiter, shared)]) spelled.push(held) + for (const held of run) spelled.push(withMarks(held, [...shared, highlightMark, ...nodeMarks(held).slice(1).filter((mark) => !shared.some((other) => sameMark(other, mark)))])) run = [] spelled.push(leaf) } diff --git a/src/markdown/emit/plain-reduction.test.ts b/src/markdown/emit/plain-reduction.test.ts index c12c343..be91231 100644 --- a/src/markdown/emit/plain-reduction.test.ts +++ b/src/markdown/emit/plain-reduction.test.ts @@ -127,6 +127,9 @@ test('spells a task list as a bullet list whose items lead with their state', () const blockTask = node('blockTaskItem', { state: 'DONE' }, said('First.'), said('Second.')) const codeTask = node('blockTaskItem', { state: 'TODO' }, { content: [text('x')], type: 'codeBlock' }) assert.equal(plain(node('taskList', {}, blockTask, codeTask)), '- [x] First.\n\n Second.\n- [ ]\n\n ```\n x\n ```\n') + const listTask = node('blockTaskItem', { state: 'DONE' }, bulletList(item(said('a')))) + assert.equal(plain(node('taskList', {}, task('TODO', ''), listTask, node('taskList', {}, task('TODO', 'b')))), '- [ ]\n- [x]\n - a\n - [ ] b\n') + assert.equal(plain(node('taskList', {}, task('DONE', 'a'), node('taskList', {}, task('TODO', '')))), '- [x] a\n - [ ]\n') }) test('spells a decision list as a plain bullet list', () => { @@ -138,7 +141,7 @@ test('spells a highlight as a == pair around the run, whatever its colour', () = assert.equal(plain(paragraph(text('a '), text('hi', highlight('#fff')), text(' there', highlight('#000')), text(' b'))), 'a ==hi there== b\n') assert.equal(plain(paragraph(text('hi ', strong, highlight('#fff')), text('b'))), '**==hi==** b\n') assert.equal(plain(paragraph(text('a', strong, highlight('#fff')), text('b', highlight('#fff'), em))), '==**a**_b_==\n') - assert.equal(plain(paragraph(text('a', highlight('#fff'), code))), '==`a`==\n') + assert.equal(plain(paragraph(text('a', highlight('#fff'), code), text('b', highlight('#fff')))), '`a`==b==\n') assert.equal(plain(paragraph(text('=', highlight('#fff')), text(' '), text('a==b', highlight('#fff')))), '==\\=== ==a==b==\n') assert.equal(plain(paragraph(text('x'), text('y', highlight('#fff')), text(' z'))), 'xy z\n') }) @@ -323,5 +326,5 @@ test('drops an empty paragraph and merges adjacent lists of one type', () => { test('keeps the nodes the plain flavour spells and degrades only what it cannot', () => { const tasks = node('taskList', {}, node('taskItem', { localId: '01a0d99b-1f58-7b95-829b-6f9860371d54', state: 'DONE' }, text('t'))) const reduced = reduceToPlain(document(node('panel', { localId: '01a0d99b-1f56-7a50-889a-f4375f09ee05', panelType: 'info' }, said('x')), tasks)) - assert.deepEqual(reduced.ok ? reduced.value : undefined, document(node('panel', { panelType: 'info' }, said('x')), node('taskList', {}, node('taskItem', { state: 'DONE' }, text('t'))))) + assert.deepEqual(reduced.ok ? reduced.value : undefined, document(node('panel', { panelType: 'info' }, said('x')), { content: [node('taskItem', { state: 'DONE' }, text('t'))], type: 'taskList' })) }) diff --git a/src/markdown/emit/plain-reduction.ts b/src/markdown/emit/plain-reduction.ts index 107ac94..b360934 100644 --- a/src/markdown/emit/plain-reduction.ts +++ b/src/markdown/emit/plain-reduction.ts @@ -1,13 +1,13 @@ import type { AdfDocument, AdfNode } from '../../adf/document.ts' import { adfDocumentFault, nodeAttrs, nodeContent } from '../../adf/document.ts' -import { adfToMarkdown, commonMarkSpelling, largestListMarker, type SpellingMemo } from './adf-to-markdown.ts' -import { alertMarker, foldedAlertMarker, taskMarker } from '../plain-conventions.ts' +import { commonMarkSpelling, largestListMarker, writeMarkdown, type SpellingMemo } from './adf-to-markdown.ts' import { blockNodeModel } from '../../adf/block-nodes.ts' import { failure, faulted, success, type ConvertErrorPath, type Result } from '../../result.ts' import { inlineLeaves, isBlockNodeType, oneLine, reduceInline, writableHref } from './plain-inline.ts' import { inlineNodeModel } from '../../adf/inline-nodes.ts' import { languageSlot } from '../code-language.ts' import { largestNesting } from '../../nesting.ts' +import { taskMarker } from '../plain-conventions.ts' // depth: the level the node reduced stands at, counted as the emitter counts it. type Reduction = { depth: number; memo: SpellingMemo; path: ConvertErrorPath } @@ -20,7 +20,7 @@ type Placed = { index: number; loose: AdfNode[] } | { index: number; loose?: und const blockReducers: Readonly> = { blockCard: paragraphOfNode, - blockquote: (node, reduction) => quoted(success([]), node, reduction), + blockquote: (node, reduction) => contained({ type: 'blockquote' }, node, reduction), bulletList: reduceList, caption: (node, reduction) => paragraphOf(nodeContent(node), reduction), codeBlock: reduceCodeBlock, @@ -33,7 +33,7 @@ const blockReducers: Readonly> = { mediaSingle: (node, reduction) => concatenated(nodeContent(node).map((child, index) => reduceStanding(child, childReduction(reduction, index)))), nestedExpand: reduceExpand, orderedList: reduceList, - panel: (node, reduction) => quoted(success([paragraph([text(alertMarker(nodeAttrs(node)['panelType']))])]), node, reduction), + panel: reducePanel, paragraph: (node, reduction) => paragraphOf(nodeContent(node), reduction), rule: () => success([{ type: 'rule' }]), syncBlock: paragraphOfNode, @@ -43,7 +43,7 @@ const blockReducers: Readonly> = { export function adfToPlainMarkdown(document: AdfDocument): Result { const reduced = reduceToPlain(document) - return reduced.ok ? adfToMarkdown(reduced.value) : reduced + return reduced.ok ? writeMarkdown(reduced.value, 'plain') : reduced } export function reduceToPlain(document: AdfDocument): Result { @@ -112,7 +112,7 @@ function plainSequence(blocks: readonly AdfNode[], reduction: Reduction): Result const listed = sequence[index] if (listed === undefined || (listed.type !== 'bulletList' && listed.type !== 'orderedList')) continue const block = numberedPastMarkers(listed) - const spelled = block === listed && commonMarkSpelling(block, reduction.path, reduction.depth, reduction.memo)?.ok === true + const spelled = block === listed && commonMarkSpelling(block, reduction.path, reduction.depth, { flavour: 'plain', memo: reduction.memo })?.ok === true if (spelled) continue sequence = spliced(sequence, index, block === listed ? nodeContent(block).flatMap(nodeContent) : [block]) index = Math.max(0, index - 1) - 1 @@ -138,11 +138,12 @@ function numberedAsText(list: AdfNode): AdfNode { return { content: nodeContent(list).map((item, offset) => itemOf(marked(nodeContent(item), `${order + offset}.`))), type: 'bulletList' } } +// Adjacent lists of one marker read back as one list. function mergedLists(blocks: readonly AdfNode[]): AdfNode[] { const merged: AdfNode[] = [] for (const block of blocks) { let next = block - for (let previous = merged.at(-1); previous !== undefined && previous.type === next.type && isList(next); previous = merged.at(-1)) { + for (let previous = merged.at(-1); previous !== undefined && listMarker(next) !== undefined && listMarker(previous) === listMarker(next); previous = merged.at(-1)) { merged.pop() next = joinedLists(previous, next) } @@ -151,17 +152,30 @@ function mergedLists(blocks: readonly AdfNode[]): AdfNode[] { return merged } -function isList(block: AdfNode): boolean { - return block.type === 'bulletList' || block.type === 'orderedList' +function listMarker(block: AdfNode): string | undefined { + if (block.type === 'orderedList') return '.' + return block.type === 'bulletList' || block.type === 'taskList' ? '-' : undefined } -// Two numbered lists whose numbering breaks between them keep their numbers as text in one bullet list. +// Two numbered lists whose numbering breaks between them keep their numbers as text in one bullet list, and a task list joining a bullet list its markers. function joinedLists(first: AdfNode, second: AdfNode): AdfNode { const breaks = first.type === 'orderedList' && nodeAttrs(second)['order'] !== Number(nodeAttrs(first)['order']) + nodeContent(first).length - const [head, tail] = breaks ? [numberedAsText(first), numberedAsText(second)] : [first, second] + const [head, tail] = breaks ? [numberedAsText(first), numberedAsText(second)] : first.type === second.type ? [first, second] : [tasksAsText(first), tasksAsText(second)] return { ...head, content: [...nodeContent(head), ...nodeContent(tail)] } } +function tasksAsText(list: AdfNode): AdfNode { + if (list.type !== 'taskList') return list + const items: AdfNode[] = [] + for (const child of nodeContent(list)) { + const marker = taskMarker(nodeAttrs(child)['state']) + const previous = child.type === 'taskItem' || child.type === 'blockTaskItem' ? undefined : items.pop() + if (previous !== undefined) items.push(itemOf([...nodeContent(previous), child])) + else items.push(itemOf(child.type === 'taskItem' ? [paragraph(nodeContent(child).length === 0 ? [text(marker)] : [text(`${marker} `), ...nodeContent(child)])] : marked(nodeContent(child), marker))) + } + return { content: items, type: 'bulletList' } +} + function paragraph(content: readonly AdfNode[]): AdfNode { return { content: [...content], type: 'paragraph' } } @@ -183,15 +197,20 @@ function paragraphOfNode(node: AdfNode, reduction: Reduction): Result return paragraphOf([node], reduction) } -function quoted(head: Result, node: AdfNode, reduction: Reduction): Result { - const content = concatenated([head, reduceBlocks(nodeContent(node), { ...reduction, depth: reduction.depth + 1 })]) - return content.ok ? success([{ content: content.value, type: 'blockquote' }]) : content +function contained(shell: AdfNode, node: AdfNode, reduction: Reduction): Result { + const content = reduceBlocks(nodeContent(node), { ...reduction, depth: reduction.depth + 1 }) + return content.ok ? success([{ ...shell, content: content.value }]) : content +} + +function reducePanel(node: AdfNode, reduction: Reduction): Result { + const panelType = nodeAttrs(node)['panelType'] + return contained(typeof panelType === 'string' ? { attrs: { panelType }, type: 'panel' } : { type: 'panel' }, node, reduction) } function reduceExpand(node: AdfNode, reduction: Reduction): Result { - const title = nodeAttrs(node)['title'] - const marker = typeof title === 'string' ? `${foldedAlertMarker} ${title.replace(/^[ \t\n\r]+/, '').replaceAll('\n', ' ')}` : foldedAlertMarker - return quoted(paragraphOf([text(marker)], { ...reduction, depth: reduction.depth + 1 }), node, reduction) + const held = nodeAttrs(node)['title'] + const title = typeof held === 'string' ? oneLine(held).replace(/^[ \t]+|[ \t]+$/g, '') : '' + return contained(title === '' ? { type: node.type } : { attrs: { title }, type: node.type }, node, reduction) } function reduceHeading(node: AdfNode, reduction: Reduction): Result { @@ -230,8 +249,11 @@ function listItem(blocks: Result): Result { // A list item's first line reads as no rule and holds no line of spaces alone: the rule and the spaces give way. function itemOf(blocks: readonly AdfNode[]): AdfNode { const rules = blocks.findIndex((block) => block.type !== 'rule') - const content = blocks.slice(rules === -1 ? blocks.length : rules).map((block) => (block.type === 'codeBlock' ? { ...block, content: blankedLines(nodeContent(block)) } : block)) - return { content, type: 'listItem' } + return { content: blankedCode(blocks.slice(rules === -1 ? blocks.length : rules)), type: 'listItem' } +} + +function blankedCode(blocks: readonly AdfNode[]): AdfNode[] { + return blocks.map((block) => (block.type === 'codeBlock' ? { ...block, content: blankedLines(nodeContent(block)) } : block)) } function blankedLines(code: readonly AdfNode[]): AdfNode[] { @@ -239,7 +261,48 @@ function blankedLines(code: readonly AdfNode[]): AdfNode[] { return blanked === '' ? [] : [text(blanked)] } +// A task list opening with a task and holding tasks and task lists alone keeps its spelling; a list nests in the task before it. function reduceTaskList(node: AdfNode, reduction: Reduction): Result { + const children = nodeContent(node) + if (!isTask(children[0]) || children.some((child) => !isTask(child) && child.type !== 'taskList')) return reduceTasksAsText(node, reduction) + const tasks: AdfNode[] = [] + let nested: AdfNode[] = [] + for (const [index, child] of children.entries()) { + const at = childReduction(reduction, index) + const reduced = isTask(child) ? reduceTask(child, at) : reduceStanding(child, at) + if (!reduced.ok) return reduced + if (isTask(child)) { + nestIn(tasks, nested) + nested = [] + } + for (const block of reduced.value) (isTask(child) ? tasks : nested).push(block) + } + nestIn(tasks, nested) + return success([{ content: tasks, type: 'taskList' }]) +} + +// The writer nests a list in the task before it, so one closing a block task item's blocks merges with it. +function nestIn(tasks: AdfNode[], nested: readonly AdfNode[]): void { + const previous = tasks.at(-1) + if (previous?.type === 'blockTaskItem') tasks[tasks.length - 1] = { ...previous, content: mergedLists([...nodeContent(previous), ...nested]) } + else for (const block of mergedLists(nested)) tasks.push(block) +} + +function isTask(node: AdfNode | undefined): boolean { + return node?.type === 'taskItem' || node?.type === 'blockTaskItem' +} + +function reduceTask(task: AdfNode, at: Reduction): Result { + const attrs = { state: nodeAttrs(task)['state'] === 'DONE' ? 'DONE' : 'TODO' } + if (task.type === 'taskItem') { + const content = reduceInline(nodeContent(task), 'paragraph', at.path, at.depth) + return content.ok ? success([{ attrs, content: content.value, type: 'taskItem' }]) : content + } + const blocks = reduceBlocks(nodeContent(task), at) + return blocks.ok ? success([{ attrs, content: blankedCode(blocks.value), type: 'blockTaskItem' }]) : blocks +} + +function reduceTasksAsText(node: AdfNode, reduction: Reduction): Result { const items: AdfNode[] = [] for (const [index, child] of nodeContent(node).entries()) { const blocks = taskBlocks(child, childReduction(reduction, index)) diff --git a/src/markdown/parse/inline-content.ts b/src/markdown/parse/inline-content.ts index a30cf01..192fd1e 100644 --- a/src/markdown/parse/inline-content.ts +++ b/src/markdown/parse/inline-content.ts @@ -7,9 +7,9 @@ import type { LinkDefinition } from '../commonmark/link-syntax.ts' import { backslashEscape, decodeTextEscapes, inlineHtmlConstruct, readBracketedAutolink, readEmailAutolink, trimTrailingSpace } from '../commonmark/grammar.ts' import { backtickRun, closingBacktickRun } from '../commonmark/backtick-runs.ts' import { commonMarkLink, linkHref } from '../mark-spellings.ts' -import { delimiterFlags, isWordCharacter, matchEmphasis, runLength } from '../commonmark/emphasis-matching.ts' -import { highlightDelimiter } from '../plain-conventions.ts' +import { delimiterFlags, matchEmphasis, runLength } from '../commonmark/emphasis-matching.ts' import { failure, faulted, success, type ConvertErrorPath, type Result } from '../../result.ts' +import { highlightDelimiter, highlightFlanking } from '../plain-conventions.ts' import { inlineNodeModel } from '../../adf/inline-nodes.ts' import { mergeAdjacentText, sameMarks } from '../../adf/editor-normal.ts' import { noSpans, readInlineDirective } from '../directive-syntax.ts' @@ -301,22 +301,14 @@ function readDelimiterRun(scan: Scan, index: number): number { return index + length } -// A delimiter is bounded outside by the code point beyond it, and flanks by the character inside it. function readEquals(scan: Scan, index: number): number { if (!scan.highlights || !scan.source.startsWith(highlightDelimiter, index)) { scan.pending += '=' return index + 1 } - const end = index + highlightDelimiter.length - const before = Array.from(scan.source.slice(Math.max(0, index - 2), index)).at(-1) ?? '' - const after = Array.from(scan.source.slice(end, end + 2))[0] ?? '' flush(scan, false) - scan.pieces.push({ closes: flanks(before) && !isWordCharacter(after), kind: 'highlight', opens: flanks(after) && !isWordCharacter(before) }) - return end -} - -function flanks(character: string): boolean { - return character !== '' && !/\s/.test(character) + scan.pieces.push({ ...highlightFlanking(scan.source, index), kind: 'highlight' }) + return index + highlightDelimiter.length } function readAutolink(source: string, index: number): { length: number; node: AdfNode } | undefined { diff --git a/src/markdown/parse/markdown-to-adf.ts b/src/markdown/parse/markdown-to-adf.ts index a13ccf5..10c8f2c 100644 --- a/src/markdown/parse/markdown-to-adf.ts +++ b/src/markdown/parse/markdown-to-adf.ts @@ -10,11 +10,11 @@ import { commonMarkSpelling, type SpellingMemo } from '../emit/adf-to-markdown.t import { failure, faulted, positioned, success, type ConvertErrorPath, type ParseError, type Result, type SourcePosition } from '../../result.ts' import { languageSlot } from '../code-language.ts' import { largestNesting } from '../../nesting.ts' +import { leadingMarker, readAlertMarker, readTaskMarker } from '../plain-conventions.ts' import { listBreakName, listBreakSpelling } from '../block-directive.ts' import { nodeAttrs, nodeContent } from '../../adf/document.ts' import { parseBlocks } from './blocks.ts' import { parseInlineContent } from './inline-content.ts' -import { readAlertMarker, readTaskMarker } from '../plain-conventions.ts' import { readBlockDirectiveNode } from './directive-nodes.ts' import { unsupportedNodeShape } from '../directive-syntax.ts' @@ -102,10 +102,8 @@ function readBlock(block: Block, reading: Reading, path: ConvertErrorPath, depth function markerLed(block: Block | undefined, read: (text: string) => T | undefined): { marker: T; position: SourcePosition; text: string } | undefined { if (block?.kind !== 'paragraph') return undefined - const marker = read(block.text) - if (marker === undefined) return undefined - const text = block.text.slice(marker.length) - return text === '' || /^(?:[ \t\n]|\\\n)/.test(text) ? { marker, position: block.position, text } : undefined + const marker = leadingMarker(block.text, read) + return marker === undefined ? undefined : { marker, position: block.position, text: block.text.slice(marker.length) } } function markerLine(text: string): { line: string; rest: string } { @@ -179,7 +177,7 @@ function directiveNode(block: DirectiveBlock, reading: Reading, path: ConvertErr const inExpand = reading.inExpand || read.value.node.type === 'expand' || read.value.node.type === 'nestedExpand' const built = directiveBody(read.value, block.blocks, { ...reading, inExpand }, path, depth) if (!built.ok) return built - const readable = commonMarkSpelling(built.value, path, depth, reading.memo) + const readable = commonMarkSpelling(built.value, path, depth, { flavour: 'lossless', memo: reading.memo }) if (readable === undefined) return built if (!readable.ok) return readable return failure('unsupported-node-shape', `${built.value.type} takes the CommonMark spelling, not the directive form`, path) diff --git a/src/markdown/plain-conventions.ts b/src/markdown/plain-conventions.ts index 04de876..8275b16 100644 --- a/src/markdown/plain-conventions.ts +++ b/src/markdown/plain-conventions.ts @@ -1,3 +1,5 @@ +import { isWordCharacter } from './commonmark/emphasis-matching.ts' + export type Flavour = 'lossless' | 'plain' type AlertMarker = { folded: boolean; length: number; panelType: string } @@ -45,6 +47,26 @@ export function readAlertMarker(text: string): AlertMarker | undefined { return { folded: marker[2] !== '', length: marker[0].length, panelType: panelType ?? 'info' } } +// A marker leads text that ends at it or goes on past whitespace or a hard break. +export function leadingMarker(text: string, read: (text: string) => T | undefined): T | undefined { + const marker = read(text) + if (marker === undefined) return undefined + const rest = text.slice(marker.length) + return rest === '' || /^(?:[ \t\n]|\\\n)/.test(rest) ? marker : undefined +} + +// A delimiter is bounded outside by the code point beyond it, and flanks by the character inside it. +export function highlightFlanking(source: string, index: number): { closes: boolean; opens: boolean } { + const end = index + highlightDelimiter.length + const before = Array.from(source.slice(Math.max(0, index - 2), index)).at(-1) ?? '' + const after = Array.from(source.slice(end, end + 2))[0] ?? '' + return { closes: flanks(before) && !isWordCharacter(after), opens: flanks(after) && !isWordCharacter(before) } +} + +function flanks(character: string): boolean { + return character !== '' && !/\s/.test(character) +} + export function taskMarker(state: unknown): string { return state === 'DONE' ? '[x]' : '[ ]' } -- 2.52.0 From 52cf681a1cb21cbe66556c7da890e3816fb64339 Mon Sep 17 00:00:00 2001 From: Lilleman auf Larv Date: Tue, 29 Sep 2026 11:42:50 +0200 Subject: [PATCH 03/14] 35b - 35 done --- todo.md | 13 ------------- 1 file changed, 13 deletions(-) diff --git a/todo.md b/todo.md index 0481134..b0473bd 100644 --- a/todo.md +++ b/todo.md @@ -2,19 +2,6 @@ ## 0.2.0 -- **35 — Read and write plain markdown as a flavour of the markdown grammar.** Per Goal 2 and - `docs/decisions.md` §Plain markdown is a flavour of the grammar, README §Plain markdown's rows are - read by `markdownToAdf`'s parser and written by `adfToMarkdown`'s writer. The - exports, their refusals and those rows stay as they are. - - **35b — Spell the plain flavour in the writer.** Panels, expands, task lists and highlights are - written by the writer, which escapes text that would read back as one, so - `plainMarkdownToAdf(adfToPlainMarkdown(doc))` keeps a literal `==x==`, a quote opening `[!NOTE]` - and a list whose items all open `[x] ` as text. A highlighted `=` (today `=====`) and `a==b` - (today `==a==b==`, highlighting `a` alone) come back highlighted whole, or lose the highlight - where no spelling holds them; the plain pair's byte-for-byte property misses both, since the - wrong document re-spells to the same bytes. An expand titled `**x** [y](z)` comes back an - expand, where today its escaped marker reads back as a quote. The reduction keeps only - degrading what the flavour cannot spell. - **10f — Give task nodes read from plain markdown position ids.** Per `docs/decisions.md` §Plain task ids come from position, README §Plain markdown's `localId` bullet saying so. The id spelling is part of the chunk. -- 2.52.0 From 1d369ec5c54d1426779e76ec8d4ec32a7907f133 Mon Sep 17 00:00:00 2001 From: Lilleman auf Larv Date: Tue, 29 Sep 2026 11:45:15 +0200 Subject: [PATCH 04/14] 35b - a leading marker reads two characters past it --- src/markdown/plain-conventions.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/markdown/plain-conventions.ts b/src/markdown/plain-conventions.ts index 8275b16..308ccbe 100644 --- a/src/markdown/plain-conventions.ts +++ b/src/markdown/plain-conventions.ts @@ -51,7 +51,7 @@ export function readAlertMarker(text: string): AlertMarker | undefined { export function leadingMarker(text: string, read: (text: string) => T | undefined): T | undefined { const marker = read(text) if (marker === undefined) return undefined - const rest = text.slice(marker.length) + const rest = text.slice(marker.length, marker.length + 2) return rest === '' || /^(?:[ \t\n]|\\\n)/.test(rest) ? marker : undefined } -- 2.52.0 From 33f3bf7ee4876d8531ede6e289d4efe4e640ed59 Mon Sep 17 00:00:00 2001 From: Lilleman auf Larv Date: Tue, 29 Sep 2026 12:01:56 +0200 Subject: [PATCH 05/14] 35b - review: tests for dropping every unread highlight, a phantom task item and a title's trailing blanks --- src/markdown/emit/plain-reduction.test.ts | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/src/markdown/emit/plain-reduction.test.ts b/src/markdown/emit/plain-reduction.test.ts index be91231..74e1751 100644 --- a/src/markdown/emit/plain-reduction.test.ts +++ b/src/markdown/emit/plain-reduction.test.ts @@ -115,6 +115,7 @@ test('spells an expand and a nested expand as a folded callout titled by the mar ) assert.equal(plain(node('expand', {}, said('Line.'))), '> [!NOTE]-\n>\n> Line.\n') assert.equal(plain(node('expand', { title: ' *Two*\nlines ' })), '> [!NOTE]- \\*Two\\* lines\n') + assert.equal(plain(node('expand', { title: '\ta \t b\t ' })), '> [!NOTE]- a \t b\n') assert.equal(plain(node('expand', { title: '**x** [y](z) ==w==' }, said('b'))), '> [!NOTE]- \\*\\*x\\*\\* \\[y](z) ==w==\n>\n> b\n') }) @@ -123,6 +124,8 @@ test('spells a task list as a bullet list whose items lead with their state', () const nested = node('taskList', {}, task('TODO', 'Review')) assert.equal(plain(node('taskList', {}, task('DONE', 'Write the spec'), nested, task('TODO', 'Ship it'))), '- [x] Write the spec\n - [ ] Review\n- [ ] Ship it\n') assert.equal(plain(node('taskList', {}, nested, task('DONE', ''), said('Stray'))), '- - [ ] Review\n- [x]\n- Stray\n') + assert.equal(plain(node('taskList', {}, node('taskList', {}), task('DONE', 'a'), said('b'), node('taskList', {}, task('TODO', 'c')))), '- [x] a\n- b\n - [ ] c\n') + assert.equal(plain(bulletList(item(said('x'))), node('taskList', {}, task('DONE', 'a'), node('taskList', {}, task('TODO', 'c')))), '- x\n- [x] a\n - [ ] c\n') assert.equal(plain(node('taskList', {}), task('TODO', 'Loose')), 'Loose\n') const blockTask = node('blockTaskItem', { state: 'DONE' }, said('First.'), said('Second.')) const codeTask = node('blockTaskItem', { state: 'TODO' }, { content: [text('x')], type: 'codeBlock' }) @@ -292,6 +295,8 @@ test('drops the mark of a run CommonMark flanking or matching cannot spell', () assert.equal(plain(paragraph(text('un'), text('-real', strong), text('istic'))), 'un-realistic\n') assert.equal(plain(paragraph(text('a', em), text('b', strong), text('c', em))), '_a_**b**_c_\n') assert.equal(plain(paragraph(text('x'), text('*', em), text('y'))), 'x\\*y\n') + const highlight: AdfMark = { type: 'backgroundColor' } + assert.equal(plain(paragraph(text('a'), text('b', highlight), text(' c'), text('d', highlight), text(' '), text('e', highlight))), 'ab cd ==e==\n') }) test('breaks a line at a newline and trims whitespace at every edge CommonMark strips', () => { -- 2.52.0 From 43869a7219a85d7f085a112c0738fd097b949987 Mon Sep 17 00:00:00 2001 From: Lilleman auf Larv Date: Tue, 29 Sep 2026 12:05:04 +0200 Subject: [PATCH 06/14] 35b - review: drop every unread highlight in one pass, one task-as-text path, a linear title trim --- README.md | 2 +- src/markdown/emit/adf-to-markdown.ts | 5 ++- src/markdown/emit/inline-line.ts | 5 ++- src/markdown/emit/line-escaping.ts | 26 +++++++------ src/markdown/emit/plain-inline.ts | 19 +++++++--- src/markdown/emit/plain-reduction.ts | 57 +++++++++++++--------------- 6 files changed, 61 insertions(+), 53 deletions(-) diff --git a/README.md b/README.md index e2e65bb..ca48cd6 100644 --- a/README.md +++ b/README.md @@ -147,7 +147,7 @@ read replaces mentions, attachments and macros with text. `_(image not included)_`, `_(jira-issues-table not included)_`, `_(synced block not included)_`, `_(link card not included)_`, `_(extension not included)_`. - `backgroundColor`, `code`, `em`, `link`, `strike` and `strong` stay; every other mark drops, - keeping its text, and so does a mark CommonMark cannot spell where it stands. + keeping its text, and so does a mark the flavour cannot spell where it stands. - A newline in text is a hard break and in an expand's title a space, edge whitespace outside a link or code span is trimmed, carriage returns and null characters are removed, and an empty paragraph drops. diff --git a/src/markdown/emit/adf-to-markdown.ts b/src/markdown/emit/adf-to-markdown.ts index 0603a49..459142d 100644 --- a/src/markdown/emit/adf-to-markdown.ts +++ b/src/markdown/emit/adf-to-markdown.ts @@ -162,7 +162,7 @@ function quoted(text: string): string { .join('\n') } -function tryTaskList(node: AdfNode, path: ConvertErrorPath, depth: number, writing: Writing): Result | undefined { +function tryTaskList(node: AdfNode, path: ConvertErrorPath, depth: number, writing: Writing): Result { const items: PlacedBlock[][] = [] let headroom = largestNesting - depth - 1 // A child other than a task nests in the task before it. @@ -176,7 +176,8 @@ function tryTaskList(node: AdfNode, path: ConvertErrorPath, depth: number, writi else for (const block of walk.value.blocks) previous.push(block) } const lines = items.map((blocks) => tryListItemLines(joinBlocks(blocks, 'list-item'), '- ')) - return lines.includes(undefined) ? undefined : success({ headroom, spelling: 'list', text: lines.join('\n') }) + // The plain reduction leaves no task a list item cannot hold: a directive here would break the flavour. + return lines.includes(undefined) ? failure('unsupported-node-shape', 'a task holds blocks no list item spells', path) : success({ headroom, spelling: 'list', text: lines.join('\n') }) } function placedBlock(node: AdfNode, path: ConvertErrorPath, depth: number, writing: Writing): Result { diff --git a/src/markdown/emit/inline-line.ts b/src/markdown/emit/inline-line.ts index 7ff708c..265da48 100644 --- a/src/markdown/emit/inline-line.ts +++ b/src/markdown/emit/inline-line.ts @@ -38,7 +38,7 @@ type LineAttempt = { fallback: NodeRange | 'opening-link'; line?: undefined } | type LineFallbacks = { carried: Set; flavour: Flavour; openingLinkAsDirective: boolean } -export type PlainLineFallback = { kind: 'claimed-line'; line: number; text: string } | { kind: 'opening-link' } | { kind: 'unspellable-run'; run: MarkRun } +export type PlainLineFallback = { kind: 'claimed-line'; line: number; text: string } | { kind: 'opening-link' } | { kind: 'unspellable-run'; run: MarkRun; runs: MarkRun[] } export function emitInlineLine(nodes: readonly AdfNode[], container: LineContainer, path: ConvertErrorPath, flavour: Flavour): Result { const emitted = emitLine(nodes, container, path, flavour) @@ -129,7 +129,8 @@ function attemptLine(segments: readonly InlineSegment[], container: LineContaine function lineVerdict(segments: readonly InlineSegment[], container: LineContainer, flavour: Flavour): PlainLineFallback | { kind: 'line'; text: string } { const assembled = assembleInlineLine(segments, container, flavour) if (assembled.openingLinkAsDirective) return { kind: 'opening-link' } - if (assembled.unspellableRun !== undefined) return { kind: 'unspellable-run', run: assembled.unspellableRun } + const [run] = assembled.unspellableRuns + if (run !== undefined) return { kind: 'unspellable-run', run, runs: assembled.unspellableRuns } const lines = assembled.line.split('\n') const claimed = container === 'paragraph' ? lines.findIndex((single, index) => claimsLine(single, index === 0 ? 'first' : 'later')) : -1 return claimed === -1 ? { kind: 'line', text: assembled.line } : { kind: 'claimed-line', line: claimed, text: lines[claimed] ?? '' } diff --git a/src/markdown/emit/line-escaping.ts b/src/markdown/emit/line-escaping.ts index 16098a6..253df18 100644 --- a/src/markdown/emit/line-escaping.ts +++ b/src/markdown/emit/line-escaping.ts @@ -23,7 +23,7 @@ export type InlineSegment = | { emphasis?: undefined; escaping: 'none'; highlight?: undefined; nodes: NodeRange; text: string } | { emphasis?: undefined; escaping: InlineEscaping; highlight?: undefined; nodes?: undefined; text: string } -export type AssembledLine = { line: string; openingLinkAsDirective?: true; unspellableRun: MarkRun | undefined } +export type AssembledLine = { line: string; openingLinkAsDirective?: true; unspellableRuns: MarkRun[] } type ScanLine = { position: LinePosition; start: number; text: string } @@ -81,10 +81,10 @@ function escape(segments: readonly InlineSegment[], container: LineContainer, hi output += scan.charAt(index) } if (container === 'paragraph' && opensLinkDefinition(output)) { - if (segments[0]?.nodes !== undefined) return { line: output, openingLinkAsDirective: true, unspellableRun: undefined } - return { line: `\\${output}`, unspellableRun: unspellableRun(segments, output, placements) } + if (segments[0]?.nodes !== undefined) return { line: output, openingLinkAsDirective: true, unspellableRuns: [] } + return { line: `\\${output}`, unspellableRuns: unspellableRuns(segments, output, placements) } } - return { line: output, unspellableRun: unspellableRun(segments, output, placements) } + return { line: output, unspellableRuns: unspellableRuns(segments, output, placements) } } function escapeClaims(scan: string, escapings: readonly InlineEscaping[], container: LineContainer, highlights: boolean): ReadonlySet { @@ -148,25 +148,27 @@ function escapeClosedRuns(scan: string, escapings: readonly InlineEscaping[], cl return escaped } -function unspellableRun(segments: readonly InlineSegment[], output: string, placements: readonly number[]): MarkRun | undefined { +// One emphasis run, the innermost, or every highlight run the line cannot spell. +function unspellableRuns(segments: readonly InlineSegment[], output: string, placements: readonly number[]): MarkRun[] { const { nodes, runs } = emittedRuns(segments, placements, output) const pair = misflanked(runs) ?? unpaired(runs) - return pair === undefined ? unreadHighlight(segments, output, placements) : nodes[pair] + const run = pair === undefined ? undefined : nodes[pair] + return run === undefined ? unreadHighlights(segments, output, placements) : [run] } -// No `==` in text can open or close, and highlights never nest, so a pair reads back where each delimiter flanks and both share a line. -function unreadHighlight(segments: readonly InlineSegment[], output: string, placements: readonly number[]): MarkRun | undefined { +// No `==` in text can open or close, and highlights never nest, so a pair reads back where each delimiter flanks. +function unreadHighlights(segments: readonly InlineSegment[], output: string, placements: readonly number[]): MarkRun[] { + const unread: MarkRun[] = [] let cursor = 0 - let opener = 0 for (const segment of segments) { const start = placements[cursor] ?? 0 cursor += segment.text.length if (segment.highlight === undefined) continue const flanking = highlightFlanking(output, start) - if (segment.highlight === 'open') opener = start - if (segment.highlight === 'open' ? !flanking.opens : !flanking.closes || output.slice(opener, start).includes('\n')) return segment.nodes + const flanks = segment.highlight === 'open' ? flanking.opens : flanking.closes + if (!flanks && unread.at(-1) !== segment.nodes) unread.push(segment.nodes) } - return undefined + return unread } function misflanked(runs: readonly EmittedRun[]): number | undefined { diff --git a/src/markdown/emit/plain-inline.ts b/src/markdown/emit/plain-inline.ts index 9fb8bf2..7da6adc 100644 --- a/src/markdown/emit/plain-inline.ts +++ b/src/markdown/emit/plain-inline.ts @@ -1,5 +1,6 @@ import type { AdfAttributes, AdfMark, AdfNode } from '../../adf/document.ts' import type { LineContainer } from '../line-container.ts' +import type { MarkRun } from './line-escaping.ts' import { blockNodeModel } from '../../adf/block-nodes.ts' import { failure, success, type ConvertErrorPath, type Result } from '../../result.ts' import { largestNesting } from '../../nesting.ts' @@ -130,7 +131,7 @@ function textLeaf(text: string, marks: readonly AdfMark[]): AdfNode { return marks.length === 0 ? { text, type: 'text' } : { marks: [...marks], text, type: 'text' } } -// A highlight goes outermost so its run is one run at depth 0, and code innermost, the only place its spelling holds. +// A highlight goes first, where `highlighted` looks for it, and code last, the only place its spelling holds. function plainMarks(marks: readonly AdfMark[], container: LineContainer, text: string): AdfMark[] { const kept: AdfMark[] = [] for (const mark of marks) { @@ -174,7 +175,7 @@ function highlighted(leaves: readonly AdfNode[]): AdfNode[] { const marks = nodeMarks(leaf) if (marks[0]?.type === highlight) { const held = marks.slice(1) - shared = run.length === 0 ? held.filter((mark) => mark.type !== 'code') : shared.filter((mark) => held.some((other) => sameMark(other, mark))) + shared = run.length === 0 ? held : shared.filter((mark) => held.some((other) => sameMark(other, mark))) run.push(leaf) continue } @@ -265,7 +266,7 @@ function spellableLine(leaves: AdfNode[], container: LineContainer, path: Conver } function withoutFallback(leaves: readonly AdfNode[], fallback: PlainLineFallback): AdfNode[] | undefined { - if (fallback.kind === 'unspellable-run') return withoutMark(leaves, fallback.run.first, fallback.run.last, fallback.run.depth) + if (fallback.kind === 'unspellable-run') return withoutMarks(leaves, fallback.runs) const first = fallback.kind === 'opening-link' ? 0 : lineStart(leaves, fallback.line) const mark = nodeMarks(leaves[first] ?? {})[0] if (mark === undefined || mark.type !== (fallback.kind === 'opening-link' ? 'link' : 'code')) return undefined @@ -274,7 +275,7 @@ function withoutFallback(leaves: readonly AdfNode[], fallback: PlainLineFallback // A code span is what binds the `]` a link definition reads, and dropping it keeps the link target. const spans = leaves.slice(first, last + 1).some((leaf) => nodeMarks(leaf).length > 1 && nodeMarks(leaf).at(-1)?.type === 'code') if (mark.type === 'link' && spans) return leaves.map((leaf, index) => (index < first || index > last ? leaf : withMarks(leaf, nodeMarks(leaf).filter((held) => held.type !== 'code')))) - return withoutMark(leaves, first, last, 0) + return withoutMarks(leaves, [{ depth: 0, first, last }]) } function lineStart(leaves: readonly AdfNode[], line: number): number { @@ -283,6 +284,12 @@ function lineStart(leaves: readonly AdfNode[], line: number): number { return index } -function withoutMark(leaves: readonly AdfNode[], first: number, last: number, depth: number): AdfNode[] { - return leaves.map((leaf, index) => (index < first || index > last ? leaf : withMarks(leaf, nodeMarks(leaf).filter((_, held) => held !== depth)))) +// The runs cover disjoint leaves, so one pass drops them all. +function withoutMarks(leaves: readonly AdfNode[], runs: readonly MarkRun[]): AdfNode[] { + const depths = new Map() + for (const run of runs) for (let index = run.first; index <= run.last; index += 1) depths.set(index, run.depth) + return leaves.map((leaf, index) => { + const depth = depths.get(index) + return depth === undefined ? leaf : withMarks(leaf, nodeMarks(leaf).filter((_, held) => held !== depth)) + }) } diff --git a/src/markdown/emit/plain-reduction.ts b/src/markdown/emit/plain-reduction.ts index b360934..72af133 100644 --- a/src/markdown/emit/plain-reduction.ts +++ b/src/markdown/emit/plain-reduction.ts @@ -164,18 +164,24 @@ function joinedLists(first: AdfNode, second: AdfNode): AdfNode { return { ...head, content: [...nodeContent(head), ...nodeContent(tail)] } } +// A task keeps its marker as text; a list item stands as one, and anything else nests in the item before it. function tasksAsText(list: AdfNode): AdfNode { if (list.type !== 'taskList') return list const items: AdfNode[] = [] for (const child of nodeContent(list)) { - const marker = taskMarker(nodeAttrs(child)['state']) - const previous = child.type === 'taskItem' || child.type === 'blockTaskItem' ? undefined : items.pop() - if (previous !== undefined) items.push(itemOf([...nodeContent(previous), child])) - else items.push(itemOf(child.type === 'taskItem' ? [paragraph(nodeContent(child).length === 0 ? [text(marker)] : [text(`${marker} `), ...nodeContent(child)])] : marked(nodeContent(child), marker))) + const previous = isTask(child) || child.type === 'listItem' ? undefined : items.pop() + items.push(itemOf(previous === undefined ? taskAsText(child) : mergedLists([...nodeContent(previous), child]))) } return { content: items, type: 'bulletList' } } +function taskAsText(child: AdfNode): readonly AdfNode[] { + const marker = taskMarker(nodeAttrs(child)['state']) + if (child.type === 'taskItem') return [paragraph(nodeContent(child).length === 0 ? [text(marker)] : [text(`${marker} `), ...nodeContent(child)])] + if (child.type === 'blockTaskItem') return marked(nodeContent(child), marker) + return child.type === 'listItem' ? nodeContent(child) : [child] +} + function paragraph(content: readonly AdfNode[]): AdfNode { return { content: [...content], type: 'paragraph' } } @@ -209,10 +215,17 @@ function reducePanel(node: AdfNode, reduction: Reduction): Result { function reduceExpand(node: AdfNode, reduction: Reduction): Result { const held = nodeAttrs(node)['title'] - const title = typeof held === 'string' ? oneLine(held).replace(/^[ \t]+|[ \t]+$/g, '') : '' + const title = typeof held === 'string' ? withoutTrailingBlanks(oneLine(held).replace(/^[ \t]+/, '')) : '' return contained(title === '' ? { type: node.type } : { attrs: { title }, type: node.type }, node, reduction) } +// A backward scan: an unanchored-end regex retries from every blank in a long run. +function withoutTrailingBlanks(text: string): string { + let end = text.length + while (end > 0 && (text.charAt(end - 1) === ' ' || text.charAt(end - 1) === '\t')) end -= 1 + return text.slice(0, end) +} + function reduceHeading(node: AdfNode, reduction: Reduction): Result { const level = nodeAttrs(node)['level'] if (typeof level !== 'number' || !Number.isInteger(level) || level < 1 || level > 6) return paragraphOf(nodeContent(node), reduction) @@ -261,16 +274,21 @@ function blankedLines(code: readonly AdfNode[]): AdfNode[] { return blanked === '' ? [] : [text(blanked)] } -// A task list opening with a task and holding tasks and task lists alone keeps its spelling; a list nests in the task before it. +// A task list opening with a task and holding tasks and task lists alone keeps its spelling, a list nesting in the task before it; any other keeps its markers as text. function reduceTaskList(node: AdfNode, reduction: Reduction): Result { const children = nodeContent(node) - if (!isTask(children[0]) || children.some((child) => !isTask(child) && child.type !== 'taskList')) return reduceTasksAsText(node, reduction) + const regular = isTask(children[0]) && children.every((child) => isTask(child) || child.type === 'taskList') const tasks: AdfNode[] = [] let nested: AdfNode[] = [] for (const [index, child] of children.entries()) { const at = childReduction(reduction, index) const reduced = isTask(child) ? reduceTask(child, at) : reduceStanding(child, at) if (!reduced.ok) return reduced + if (!regular) { + const standsAlone = !isTask(child) && child.type !== 'taskList' + for (const block of standsAlone ? [{ content: reduced.value, type: 'listItem' }] : reduced.value) tasks.push(block) + continue + } if (isTask(child)) { nestIn(tasks, nested) nested = [] @@ -278,7 +296,8 @@ function reduceTaskList(node: AdfNode, reduction: Reduction): Result for (const block of reduced.value) (isTask(child) ? tasks : nested).push(block) } nestIn(tasks, nested) - return success([{ content: tasks, type: 'taskList' }]) + if (regular) return success([{ content: tasks, type: 'taskList' }]) + return success(listOf(nodeContent(tasksAsText({ content: tasks, type: 'taskList' })), 'bulletList')) } // The writer nests a list in the task before it, so one closing a block task item's blocks merges with it. @@ -302,28 +321,6 @@ function reduceTask(task: AdfNode, at: Reduction): Result { return blocks.ok ? success([{ attrs, content: blankedCode(blocks.value), type: 'blockTaskItem' }]) : blocks } -function reduceTasksAsText(node: AdfNode, reduction: Reduction): Result { - const items: AdfNode[] = [] - for (const [index, child] of nodeContent(node).entries()) { - const blocks = taskBlocks(child, childReduction(reduction, index)) - if (!blocks.ok) return blocks - const previous = child.type === 'taskList' ? items.pop() : undefined - items.push(itemOf(previous === undefined ? blocks.value : mergedLists([...nodeContent(previous), ...blocks.value]))) - } - return success(listOf(items, 'bulletList')) -} - -function taskBlocks(child: AdfNode, at: Reduction): Result { - const marker = taskMarker(nodeAttrs(child)['state']) - if (child.type === 'taskItem') { - const content = reduceInline(nodeContent(child), 'paragraph', at.path, at.depth) - return content.ok ? success([paragraph(content.value.length === 0 ? [text(marker)] : [text(`${marker} `), ...content.value])]) : content - } - if (child.type !== 'blockTaskItem') return reduceStanding(child, at) - const blocks = reduceBlocks(nodeContent(child), at) - return blocks.ok ? success(marked(blocks.value, marker)) : blocks -} - // The marker leads the first paragraph, or stands as one where the blocks open with another. function marked(blocks: readonly AdfNode[], marker: string): AdfNode[] { const [first, ...rest] = blocks -- 2.52.0 From 6c8ed03d3655806af1bad93c06d7f5e6f4d26ddc Mon Sep 17 00:00:00 2001 From: Lilleman auf Larv Date: Tue, 29 Sep 2026 12:13:00 +0200 Subject: [PATCH 07/14] 35b - review: test that a stray task-list child reducing to nothing writes no item --- src/markdown/emit/plain-reduction.test.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/src/markdown/emit/plain-reduction.test.ts b/src/markdown/emit/plain-reduction.test.ts index 74e1751..bcfecb4 100644 --- a/src/markdown/emit/plain-reduction.test.ts +++ b/src/markdown/emit/plain-reduction.test.ts @@ -125,6 +125,7 @@ test('spells a task list as a bullet list whose items lead with their state', () assert.equal(plain(node('taskList', {}, task('DONE', 'Write the spec'), nested, task('TODO', 'Ship it'))), '- [x] Write the spec\n - [ ] Review\n- [ ] Ship it\n') assert.equal(plain(node('taskList', {}, nested, task('DONE', ''), said('Stray'))), '- - [ ] Review\n- [x]\n- Stray\n') assert.equal(plain(node('taskList', {}, node('taskList', {}), task('DONE', 'a'), said('b'), node('taskList', {}, task('TODO', 'c')))), '- [x] a\n- b\n - [ ] c\n') + assert.equal(plain(node('taskList', {}, paragraph(), task('DONE', 'a'))), '- [x] a\n') assert.equal(plain(bulletList(item(said('x'))), node('taskList', {}, task('DONE', 'a'), node('taskList', {}, task('TODO', 'c')))), '- x\n- [x] a\n - [ ] c\n') assert.equal(plain(node('taskList', {}), task('TODO', 'Loose')), 'Loose\n') const blockTask = node('blockTaskItem', { state: 'DONE' }, said('First.'), said('Second.')) -- 2.52.0 From 6681bec391866798e94e1978671b7db232b2b49e Mon Sep 17 00:00:00 2001 From: Lilleman auf Larv Date: Tue, 29 Sep 2026 12:13:11 +0200 Subject: [PATCH 08/14] 35b - review: runs as a non-empty tuple, no item for a stray child reducing to nothing, 42 filed --- src/markdown/emit/inline-line.ts | 8 ++++---- src/markdown/emit/plain-reduction.ts | 2 +- todo.md | 4 ++++ 3 files changed, 9 insertions(+), 5 deletions(-) diff --git a/src/markdown/emit/inline-line.ts b/src/markdown/emit/inline-line.ts index 265da48..6e719e0 100644 --- a/src/markdown/emit/inline-line.ts +++ b/src/markdown/emit/inline-line.ts @@ -38,7 +38,7 @@ type LineAttempt = { fallback: NodeRange | 'opening-link'; line?: undefined } | type LineFallbacks = { carried: Set; flavour: Flavour; openingLinkAsDirective: boolean } -export type PlainLineFallback = { kind: 'claimed-line'; line: number; text: string } | { kind: 'opening-link' } | { kind: 'unspellable-run'; run: MarkRun; runs: MarkRun[] } +export type PlainLineFallback = { kind: 'claimed-line'; line: number; text: string } | { kind: 'opening-link' } | { kind: 'unspellable-run'; runs: [MarkRun, ...MarkRun[]] } export function emitInlineLine(nodes: readonly AdfNode[], container: LineContainer, path: ConvertErrorPath, flavour: Flavour): Result { const emitted = emitLine(nodes, container, path, flavour) @@ -120,7 +120,7 @@ function lineSegments(nodes: readonly AdfNode[], container: LineContainer, path: function attemptLine(segments: readonly InlineSegment[], container: LineContainer, path: ConvertErrorPath, flavour: Flavour): Result { const verdict = lineVerdict(segments, container, flavour) if (verdict.kind === 'opening-link') return success({ fallback: 'opening-link' }) - if (verdict.kind === 'unspellable-run') return success({ fallback: verdict.run }) + if (verdict.kind === 'unspellable-run') return success({ fallback: verdict.runs[0] }) if (verdict.kind === 'claimed-line') return failure('unspellable-line-start', `block parsing would claim the emitted line ${JSON.stringify(verdict.text)}`, path) return success({ line: verdict.text }) } @@ -129,8 +129,8 @@ function attemptLine(segments: readonly InlineSegment[], container: LineContaine function lineVerdict(segments: readonly InlineSegment[], container: LineContainer, flavour: Flavour): PlainLineFallback | { kind: 'line'; text: string } { const assembled = assembleInlineLine(segments, container, flavour) if (assembled.openingLinkAsDirective) return { kind: 'opening-link' } - const [run] = assembled.unspellableRuns - if (run !== undefined) return { kind: 'unspellable-run', run, runs: assembled.unspellableRuns } + const [run, ...others] = assembled.unspellableRuns + if (run !== undefined) return { kind: 'unspellable-run', runs: [run, ...others] } const lines = assembled.line.split('\n') const claimed = container === 'paragraph' ? lines.findIndex((single, index) => claimsLine(single, index === 0 ? 'first' : 'later')) : -1 return claimed === -1 ? { kind: 'line', text: assembled.line } : { kind: 'claimed-line', line: claimed, text: lines[claimed] ?? '' } diff --git a/src/markdown/emit/plain-reduction.ts b/src/markdown/emit/plain-reduction.ts index 72af133..a1072eb 100644 --- a/src/markdown/emit/plain-reduction.ts +++ b/src/markdown/emit/plain-reduction.ts @@ -285,7 +285,7 @@ function reduceTaskList(node: AdfNode, reduction: Reduction): Result const reduced = isTask(child) ? reduceTask(child, at) : reduceStanding(child, at) if (!reduced.ok) return reduced if (!regular) { - const standsAlone = !isTask(child) && child.type !== 'taskList' + const standsAlone = !isTask(child) && child.type !== 'taskList' && reduced.value.length > 0 for (const block of standsAlone ? [{ content: reduced.value, type: 'listItem' }] : reduced.value) tasks.push(block) continue } diff --git a/todo.md b/todo.md index b0473bd..80498cb 100644 --- a/todo.md +++ b/todo.md @@ -34,6 +34,10 @@ paragraph of 2000 × `un` plus `**-r**`: each run its flanking cannot spell re-emits the whole line before riding the carry, quadratic in the runs (Goal 9), and the plain reduction's `spellableLine` drops one mark per re-emit the same way. Make both linear. +- **42 — Trim a text leaf's trailing blanks in linear time.** `plain-inline.ts`'s `leafEdges` finds + the trail with an unanchored `/[ \t]*$/`, quadratic in a run of blanks inside one leaf: a + paragraph of `a`, 80 000 spaces, `b` takes 6.5 s in `adfToPlainMarkdown` (Goal 9). Scan backward, + as the expand title's trim does. - **34 — Read emphasis flanking by the whole character beside an astral symbol.** Check whether `line-escaping.ts`'s `charAt` and the parser's flanking read one UTF-16 unit beside an astral symbol — a lone surrogate is neither punctuation nor symbol, where CommonMark reads `😀` as -- 2.52.0 From 95ff9ee91052a53920f606f9de664ece15d22a0d Mon Sep 17 00:00:00 2001 From: Lilleman auf Larv Date: Tue, 29 Sep 2026 12:13:54 +0200 Subject: [PATCH 09/14] 35b - review: a task-list child reducing to nothing counts toward neither spelling --- src/markdown/emit/plain-reduction.ts | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/src/markdown/emit/plain-reduction.ts b/src/markdown/emit/plain-reduction.ts index a1072eb..145ecf4 100644 --- a/src/markdown/emit/plain-reduction.ts +++ b/src/markdown/emit/plain-reduction.ts @@ -274,26 +274,29 @@ function blankedLines(code: readonly AdfNode[]): AdfNode[] { return blanked === '' ? [] : [text(blanked)] } -// A task list opening with a task and holding tasks and task lists alone keeps its spelling, a list nesting in the task before it; any other keeps its markers as text. +// A task list opening with a task and holding tasks and task lists alone keeps its spelling, a list nesting in the task before it; any other keeps its markers as text. A child reducing to nothing counts for neither. function reduceTaskList(node: AdfNode, reduction: Reduction): Result { - const children = nodeContent(node) - const regular = isTask(children[0]) && children.every((child) => isTask(child) || child.type === 'taskList') - const tasks: AdfNode[] = [] - let nested: AdfNode[] = [] - for (const [index, child] of children.entries()) { + const kept: { blocks: AdfNode[]; child: AdfNode }[] = [] + for (const [index, child] of nodeContent(node).entries()) { const at = childReduction(reduction, index) const reduced = isTask(child) ? reduceTask(child, at) : reduceStanding(child, at) if (!reduced.ok) return reduced + if (reduced.value.length > 0) kept.push({ blocks: reduced.value, child }) + } + const regular = isTask(kept[0]?.child) && kept.every(({ child }) => isTask(child) || child.type === 'taskList') + const tasks: AdfNode[] = [] + let nested: AdfNode[] = [] + for (const { blocks, child } of kept) { if (!regular) { - const standsAlone = !isTask(child) && child.type !== 'taskList' && reduced.value.length > 0 - for (const block of standsAlone ? [{ content: reduced.value, type: 'listItem' }] : reduced.value) tasks.push(block) + const standsAlone = !isTask(child) && child.type !== 'taskList' + for (const block of standsAlone ? [{ content: blocks, type: 'listItem' }] : blocks) tasks.push(block) continue } if (isTask(child)) { nestIn(tasks, nested) nested = [] } - for (const block of reduced.value) (isTask(child) ? tasks : nested).push(block) + for (const block of blocks) (isTask(child) ? tasks : nested).push(block) } nestIn(tasks, nested) if (regular) return success([{ content: tasks, type: 'taskList' }]) -- 2.52.0 From 2395cf077e1b3656275863b9157eb4bf161ca804 Mon Sep 17 00:00:00 2001 From: Lilleman auf Larv Date: Tue, 29 Sep 2026 12:17:52 +0200 Subject: [PATCH 10/14] 35b - review: tests for escaping every list item's task marker --- src/markdown/emit/plain-reduction.test.ts | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/src/markdown/emit/plain-reduction.test.ts b/src/markdown/emit/plain-reduction.test.ts index bcfecb4..0853849 100644 --- a/src/markdown/emit/plain-reduction.test.ts +++ b/src/markdown/emit/plain-reduction.test.ts @@ -123,16 +123,16 @@ test('spells a task list as a bullet list whose items lead with their state', () const task = (state: string, value: string): AdfNode => node('taskItem', { localId: '01a0d99b-1f58-7b95-829b-6f9860371d54', state }, text(value)) const nested = node('taskList', {}, task('TODO', 'Review')) assert.equal(plain(node('taskList', {}, task('DONE', 'Write the spec'), nested, task('TODO', 'Ship it'))), '- [x] Write the spec\n - [ ] Review\n- [ ] Ship it\n') - assert.equal(plain(node('taskList', {}, nested, task('DONE', ''), said('Stray'))), '- - [ ] Review\n- [x]\n- Stray\n') - assert.equal(plain(node('taskList', {}, node('taskList', {}), task('DONE', 'a'), said('b'), node('taskList', {}, task('TODO', 'c')))), '- [x] a\n- b\n - [ ] c\n') + assert.equal(plain(node('taskList', {}, nested, task('DONE', ''), said('Stray'))), '- - [ ] Review\n- \\[x]\n- Stray\n') + assert.equal(plain(node('taskList', {}, node('taskList', {}), task('DONE', 'a'), said('b'), node('taskList', {}, task('TODO', 'c')))), '- \\[x] a\n- b\n - [ ] c\n') assert.equal(plain(node('taskList', {}, paragraph(), task('DONE', 'a'))), '- [x] a\n') - assert.equal(plain(bulletList(item(said('x'))), node('taskList', {}, task('DONE', 'a'), node('taskList', {}, task('TODO', 'c')))), '- x\n- [x] a\n - [ ] c\n') + assert.equal(plain(bulletList(item(said('x'))), node('taskList', {}, task('DONE', 'a'), node('taskList', {}, task('TODO', 'c')))), '- x\n- \\[x] a\n - [ ] c\n') assert.equal(plain(node('taskList', {}), task('TODO', 'Loose')), 'Loose\n') const blockTask = node('blockTaskItem', { state: 'DONE' }, said('First.'), said('Second.')) const codeTask = node('blockTaskItem', { state: 'TODO' }, { content: [text('x')], type: 'codeBlock' }) assert.equal(plain(node('taskList', {}, blockTask, codeTask)), '- [x] First.\n\n Second.\n- [ ]\n\n ```\n x\n ```\n') const listTask = node('blockTaskItem', { state: 'DONE' }, bulletList(item(said('a')))) - assert.equal(plain(node('taskList', {}, task('TODO', ''), listTask, node('taskList', {}, task('TODO', 'b')))), '- [ ]\n- [x]\n - a\n - [ ] b\n') + assert.equal(plain(node('taskList', {}, task('TODO', ''), listTask, node('taskList', {}, task('TODO', 'b')))), '- [ ]\n- [x]\n - a\n - \\[ ] b\n') assert.equal(plain(node('taskList', {}, task('DONE', 'a'), node('taskList', {}, task('TODO', '')))), '- [x] a\n - [ ]\n') }) @@ -154,8 +154,8 @@ test('escapes text that would read back as a flavour marker, and only there', () assert.equal(plain(said('==x== a == b a==b ===')), '\\==x\\== a == b a==b \\=\\==\n') assert.equal(plain({ content: [said('[!NOTE] x'), said('[!TIP]')], type: 'blockquote' }), '> \\[!NOTE] x\n>\n> [!TIP]\n') assert.equal(plain({ content: [said('[!NOTE]x')], type: 'blockquote' }, said('[!NOTE]')), '> [!NOTE]x\n\n[!NOTE]\n') - assert.equal(plain(bulletList(item(said('[x] a')), item(said('[ ]')))), '- \\[x] a\n- [ ]\n') - assert.equal(plain(bulletList(item(said('[x] a')), item(said('b'))), node('orderedList', { order: 1 }, item(said('[x] c')))), '- [x] a\n- b\n\n1. [x] c\n') + assert.equal(plain(bulletList(item(said('[x] a')), item(said('[ ]')))), '- \\[x] a\n- \\[ ]\n') + assert.equal(plain(bulletList(item(said('[x] a')), item(said('b'))), node('orderedList', { order: 1 }, item(said('[x] c')))), '- \\[x] a\n- b\n\n1. \\[x] c\n') const task = (state: string, value: string): AdfNode => node('taskItem', { state }, text(value)) assert.equal(plain(node('taskList', {}, task('DONE', '[x] a'), task('TODO', '==b=='))), '- [x] [x] a\n- [ ] \\==b\\==\n') }) @@ -184,7 +184,7 @@ test('keeps the CommonMark blocks in their spelling and drops their attributes a assert.equal(plain(node('orderedList', { order: 1e10 }, item(said('Alpha')), item(code), item())), '- 10000000000. Alpha\n- 10000000001.\n\n ```\n x\n ```\n- 10000000002.\n') const long = node('orderedList', { order: 1e10 }, item(said('y'))) assert.equal(plain(bulletList(item(said('x'))), long, bulletList(item(said('z')))), '- x\n- 10000000000. y\n- z\n') - assert.equal(plain(node('taskList', {}, node('taskItem', { state: 'DONE' }, text('t'))), long), '- [x] t\n- 10000000000. y\n') + assert.equal(plain(node('taskList', {}, node('taskItem', { state: 'DONE' }, text('t'))), long), '- \\[x] t\n- 10000000000. y\n') assert.equal(plain(bulletList(item(said('a'), bulletList(item(said('x'))), long))), '- a\n - x\n - 10000000000. y\n') const givesWay = node('orderedList', { order: 1e10 }, item(node('rule', {})), item(bulletList(item(bulletList(item()))))) assert.equal(plain(givesWay, bulletList(item(said('z')))), '- 10000000000.\n- 10000000001.\n - -\n- z\n') -- 2.52.0 From c3e86f843071878bde52a8774a67a2507abc8b20 Mon Sep 17 00:00:00 2001 From: Lilleman auf Larv Date: Tue, 29 Sep 2026 12:18:21 +0200 Subject: [PATCH 11/14] 35b - review: escape a task marker opening any list item's first paragraph --- src/markdown/emit/adf-to-markdown.ts | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/markdown/emit/adf-to-markdown.ts b/src/markdown/emit/adf-to-markdown.ts index 459142d..0d41fe4 100644 --- a/src/markdown/emit/adf-to-markdown.ts +++ b/src/markdown/emit/adf-to-markdown.ts @@ -317,12 +317,12 @@ function tryList(node: AdfNode, path: ConvertErrorPath, depth: number, writing: headroom = Math.min(headroom, walk.value.headroom) walked.push({ node: item, walk: walk.value }) } - const inners = walked.map((item) => joinBlocks(item.walk.blocks, 'list-item')) - // A bullet list whose every item opens with a task marker reads as a task list (README §Plain markdown). - if (writing.flavour === 'plain' && !ordered && inners.every((inner) => leadingMarker(inner, readTaskMarker) !== undefined)) inners[0] = `\\${inners[0] ?? ''}` const lines: string[] = [] - for (const [offset, inner] of inners.entries()) { - const line = tryListItemLines(inner, ordered ? `${start + offset}. ` : '- ') + for (const [offset, item] of walked.entries()) { + const inner = joinBlocks(item.walk.blocks, 'list-item') + // GitHub reads a task marker opening any item's first paragraph as a checkbox, whatever its siblings hold. + const escaped = writing.flavour === 'plain' && leadingMarker(inner, readTaskMarker) !== undefined ? `\\${inner}` : inner + const line = tryListItemLines(escaped, ordered ? `${start + offset}. ` : '- ') if (line === undefined) { // The directive form spends a level the walk did not count. if (headroom < 1) return tooDeep(path) -- 2.52.0 From 9bdbcd880e493a1cd5ae2bab642c06caf598d9cd Mon Sep 17 00:00:00 2001 From: Lilleman auf Larv Date: Tue, 29 Sep 2026 12:20:46 +0200 Subject: [PATCH 12/14] 35b - review: README names when a task list keeps its states as text --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index ca48cd6..08287d6 100644 --- a/README.md +++ b/README.md @@ -153,6 +153,8 @@ read replaces mentions, attachments and macros with text. paragraph drops. - An ordered list numbered past `999999999`, or adjacent ordered lists whose numbering does not continue, is one bullet list keeping its numbers as text. +- A task list beside a bullet or decision list, or holding a block other than a task, joins one + bullet list keeping its states as text: `- \[x] Done`. - A node read back carries no `localId`, which Atlassian's schema requires on `taskList`, `taskItem` and `blockTaskItem`: mint one where the receiving site requires it. -- 2.52.0 From 1a266d5661c0d58a4e6300d6a40cd140fa4e488c Mon Sep 17 00:00:00 2001 From: Lilleman auf Larv Date: Tue, 29 Sep 2026 12:21:51 +0200 Subject: [PATCH 13/14] 35b - review: the escape test names the renderer --- src/markdown/emit/plain-reduction.test.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/markdown/emit/plain-reduction.test.ts b/src/markdown/emit/plain-reduction.test.ts index 0853849..3c15be7 100644 --- a/src/markdown/emit/plain-reduction.test.ts +++ b/src/markdown/emit/plain-reduction.test.ts @@ -150,7 +150,7 @@ test('spells a highlight as a == pair around the run, whatever its colour', () = assert.equal(plain(paragraph(text('x'), text('y', highlight('#fff')), text(' z'))), 'xy z\n') }) -test('escapes text that would read back as a flavour marker, and only there', () => { +test('escapes text a renderer would take as a flavour marker, and only there', () => { assert.equal(plain(said('==x== a == b a==b ===')), '\\==x\\== a == b a==b \\=\\==\n') assert.equal(plain({ content: [said('[!NOTE] x'), said('[!TIP]')], type: 'blockquote' }), '> \\[!NOTE] x\n>\n> [!TIP]\n') assert.equal(plain({ content: [said('[!NOTE]x')], type: 'blockquote' }, said('[!NOTE]')), '> [!NOTE]x\n\n[!NOTE]\n') -- 2.52.0 From a4b6b48635adff0b53876d9bf35886736cf7f5f5 Mon Sep 17 00:00:00 2001 From: Lilleman auf Larv Date: Tue, 29 Sep 2026 12:23:16 +0200 Subject: [PATCH 14/14] 35b - review: README names the marker escapes, a spec line reflowed --- README.md | 3 +++ spec/flavour.md | 4 +--- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 08287d6..518bfed 100644 --- a/README.md +++ b/README.md @@ -155,6 +155,9 @@ read replaces mentions, attachments and macros with text. continue, is one bullet list keeping its numbers as text. - A task list beside a bullet or decision list, or holding a block other than a task, joins one bullet list keeping its states as text: `- \[x] Done`. +- Text that would read as a marker takes a backslash: `==` wherever it could open or close a + highlight, `[!…]` opening a quote, and `[x]` or `[ ]` opening any list item, since GitHub reads + that marker per item. - A node read back carries no `localId`, which Atlassian's schema requires on `taskList`, `taskItem` and `blockTaskItem`: mint one where the receiving site requires it. diff --git a/spec/flavour.md b/spec/flavour.md index 2f589eb..1917825 100644 --- a/spec/flavour.md +++ b/spec/flavour.md @@ -67,9 +67,7 @@ normalizes to it through the round-trip. matching below, which is what lets the emitter decide its own pairings. - Blocks separated by one blank line at document level, inside a blockquote and between CommonMark blocks; inside a directive container a pair holding a directive block takes none. No trailing - whitespace outside a code - block's - content, single trailing newline; a document with no blocks is the empty string. + whitespace outside a code block's content, single trailing newline; a document with no blocks is the empty string. ## Directives -- 2.52.0