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

Add adfToPlainText, writing a document's text with no markup

This commit is contained in:
2026-11-14 15:29:07 +01:00
committed by Lillem4n
parent dd67df7339
commit 53cb73e1ab
9 changed files with 405 additions and 50 deletions
+1
View File
@@ -4,6 +4,7 @@ export type { ConvertError, ConvertErrorCode, ConvertErrorPath, ParseError, Resu
export type { JsonValue } from './json-value.ts'
export { adfToHtml } from './html/emit/adf-to-html.ts'
export { adfToLosslessMarkdown } from './markdown/emit/adf-to-markdown.ts'
export { adfToPlainText } from './plain-text/adf-to-plain-text.ts'
export { adfToPortableMarkdown } from './markdown/portable/adf-to-portable-markdown.ts'
export { commonMarkToAdf, losslessMarkdownToAdf } from './markdown/parse/markdown-to-adf.ts'
export { htmlToAdf } from './html/parse/html-to-adf.ts'
+176
View File
@@ -0,0 +1,176 @@
import assert from 'node:assert/strict'
import test from 'node:test'
import type { AdfDocument, AdfMark, AdfNode } from '../adf/document.ts'
import type { Result } from '../result.ts'
import { adfToHtml, adfToPlainText } from '../index.ts'
import { largestNesting } from '../nesting.ts'
function document(...content: AdfNode[]): AdfDocument {
return { content, type: 'doc', version: 1 }
}
function plain(result: Result<string>): string {
return result.ok ? result.value : `${result.error.code}: ${result.error.message}`
}
function refusal(result: Result<unknown>): string {
return result.ok ? 'written' : `${result.error.code} at /${result.error.path.join('/')}`
}
function paragraph(...content: AdfNode[]): AdfNode {
return content.length === 0 ? { type: 'paragraph' } : { content, type: 'paragraph' }
}
function text(value: string, ...marks: AdfMark[]): AdfNode {
return marks.length === 0 ? { text: value, type: 'text' } : { marks, text: value, type: 'text' }
}
function item(...content: AdfNode[]): AdfNode {
return { content, type: 'listItem' }
}
function bullets(...items: AdfNode[]): AdfNode {
return { content: items, type: 'bulletList' }
}
function numbers(...items: AdfNode[]): AdfNode {
return { content: items, type: 'orderedList' }
}
function line(value: string): AdfNode {
return paragraph(text(value))
}
test('writes blocks as their text, a blank line apart, with bullets, numbers and nesting indented', () => {
const mention: AdfNode = { attrs: { id: '557058:ann', text: '@Ann Lee' }, type: 'mention' }
const written = adfToPlainText(
document(
{ attrs: { level: 2 }, content: [text('Release notes')], type: 'heading' },
line('Ship on Friday.'),
paragraph(text('Ask '), mention, text(' first.'), { type: 'hardBreak' }, text('Then ship.')),
bullets(item(line('Fix login')), item(line('Fix export'), bullets(item(line('CSV')), item(line('JSON')))), item(line('Docs'))),
numbers(item(line('Build')), item(line('Test')), item(line('Ship'))),
{ content: [line('Measure twice.')], type: 'blockquote' },
{ content: [text('npm test')], type: 'codeBlock' },
line('Done.'),
),
)
assert.equal(
plain(written),
[
'Release notes',
'',
'Ship on Friday.',
'',
'Ask @Ann Lee first.',
'Then ship.',
'',
'• Fix login',
'• Fix export',
' • CSV',
' • JSON',
'• Docs',
'',
'1. Build',
'2. Test',
'3. Ship',
'',
'Measure twice.',
'',
'npm test',
'',
'Done.',
].join('\n'),
)
})
test('writes marks as the text they mark, and an empty document as nothing', () => {
const link: AdfMark = { attrs: { href: 'https://example.com/', title: 'Home' }, type: 'link' }
assert.equal(plain(adfToPlainText(document(paragraph(text('a ', { type: 'strong' }), text('b', link, { type: 'em' }), text(' c', { type: 'code' }))))), 'a b c')
assert.equal(plain(adfToPlainText(document())), '')
assert.equal(plain(adfToPlainText({ type: 'doc', version: 1 })), '')
})
test('writes nothing for a block holding no text, and parts the blocks around it once', () => {
assert.equal(plain(adfToPlainText(document(paragraph(), line('a'), { type: 'rule' }, paragraph(), line('b'), bullets(item())))), 'a\n\nb')
})
test('numbers an ordered list from its first number, and widens the indent to the marker', () => {
const list: AdfNode = { attrs: { order: 9 }, content: [item(line('nine'), paragraph(text('a'), { type: 'hardBreak' }), line('b')), item(line('ten'), bullets(item(line('x'))))], type: 'orderedList' }
assert.equal(plain(adfToPlainText(document(list))), '9. nine\n a\n b\n10. ten\n • x')
assert.equal(plain(adfToPlainText(document({ attrs: { order: 1.5 }, content: [item(line('a'))], type: 'orderedList' }))), '1. a')
})
test('keeps a marker for an item whose first content is a nested list', () => {
assert.equal(plain(adfToPlainText(document(bullets(item(bullets(item(line('x')))), item(line('y')))))), '• • x\n• y')
})
test('writes a task list and a decision list as bullets', () => {
const tasks: AdfNode = { content: [{ attrs: { state: 'DONE' }, content: [text('Write the spec')], type: 'taskItem' }, { attrs: { state: 'TODO' }, content: [text('Ship')], type: 'taskItem' }], type: 'taskList' }
const decisions: AdfNode = { content: [{ attrs: { state: 'DECIDED' }, content: [text('Use Node')], type: 'decisionItem' }], type: 'decisionList' }
assert.equal(plain(adfToPlainText(document(tasks, decisions))), '• Write the spec\n• Ship\n\n• Use Node')
})
test('writes a mention, an emoji, a date and a status as the text they show', () => {
const nodes: AdfNode[] = [
{ attrs: { id: '557058:ann' }, type: 'mention' },
{ attrs: { shortName: ':smile:', text: '😄' }, type: 'emoji' },
{ attrs: { timestamp: '1756080000000' }, type: 'date' },
{ attrs: { color: 'green', text: 'Done' }, type: 'status' },
]
assert.equal(plain(adfToPlainText(document(paragraph(...nodes.flatMap((node) => [node, text(' ')]))))), '@557058:ann 😄 2025-08-25 Done ')
})
test('writes a table\'s cells as blocks, until a table has its own spelling', () => {
const cell = (value: string): AdfNode => ({ content: [line(value)], type: 'tableCell' })
const table: AdfNode = { content: [{ content: [cell('a'), cell('b')], type: 'tableRow' }, { content: [cell('c'), cell('d')], type: 'tableRow' }], type: 'table' }
assert.equal(plain(adfToPlainText(document(table))), 'a\n\nb\n\nc\n\nd')
})
test('writes a node of an unknown type as the text it holds, its children a blank line apart', () => {
const unknown: AdfNode = { content: [line('one'), { content: [text('two'), text(' three')], type: 'unknownBlock' }], type: 'unknownContainer' }
assert.equal(plain(adfToPlainText(document(unknown, { text: 'loose', type: 'unknownText' }, paragraph({ content: [text('in'), text(' line')], type: 'unknownInline' })))), 'one\n\ntwo three\n\nloose\n\nin line')
})
test('writes a code block\'s lines and a list item\'s continuation lines under their indent, never a blank line with spaces', () => {
const code: AdfNode = { content: [text('a\n\nb')], type: 'codeBlock' }
assert.equal(plain(adfToPlainText(document(bullets(item(code))))), '• a\n\n b')
})
test('refuses what adfToHtml refuses, with the same code and path', () => {
const deep = (levels: number): AdfNode => {
let node = line('x')
for (let level = 0; level < levels; level += 1) node = { content: [node], type: 'blockquote' }
return node
}
const refused: AdfDocument[] = [
{ type: 'doc', version: Number.NaN },
{ type: 'doc', version: 2 },
document(deep(largestNesting + 1)),
document(paragraph(text('See '), { attrs: { url: 'https://example.com/' }, marks: [{ attrs: { href: 'https://example.com/' }, type: 'link' }], type: 'inlineCard' })),
]
for (const input of refused) {
assert.notEqual(refusal(adfToHtml(input)), 'written')
assert.equal(refusal(adfToPlainText(input)), refusal(adfToHtml(input)))
}
})
test('writes blocks nested 500 levels', () => {
let node = line('x')
for (let level = 0; level < largestNesting; level += 1) node = { content: [node], type: 'blockquote' }
assert.equal(plain(adfToPlainText(document(node))), 'x')
let list = line('x')
for (let level = 0; level < largestNesting; level += 1) list = bullets(item(list))
assert.equal(plain(adfToPlainText(document(list))), `${'• '.repeat(largestNesting)}x`)
assert.equal(refusal(adfToPlainText(document(bullets(item(list))))), refusal(adfToHtml(document(bullets(item(list))))))
assert.equal(refusal(adfToPlainText(document(bullets(item(list))))).startsWith('unsupported-nesting-depth at /content/0/content/0/content/0'), true)
})
test('refuses text past V8\'s longest string, which the indent of a deep list can add', () => {
let list: AdfNode = { content: [text('a\n'.repeat(400000))], type: 'codeBlock' }
for (let level = 0; level < 400; level += 1) list = bullets(item(list))
const refused = adfToPlainText(document(list, list))
assert.equal(!refused.ok && refused.error.code, 'unsupported-node-shape')
assert.equal(!refused.ok && refused.error.message.includes('536870888'), true)
})
+118
View File
@@ -0,0 +1,118 @@
import type { AdfDocument, AdfNode } from '../adf/document.ts'
import { blockNodeModel } from '../adf/block-nodes.ts'
import { failure, success, type ConvertErrorPath, type Result } from '../result.ts'
import { inlineNodeModel } from '../adf/inline-nodes.ts'
import { largestNesting } from '../nesting.ts'
import { longestOutput, tooLong, withinEngineLimits } from '../length-bound.ts'
import { nodeAttrs, nodeContent, readAdfDocument, writableContent } from '../adf/document.ts'
import { shownText } from '../adf/shown-text.ts'
// `gap`: the line feeds the next text needs before it, at least; `leave`: the state a list item restores; `marker`: the list marker of the item a node is; `depth`: the nesting level, as `largestNesting` counts it; `parent`: the node holding this one, from which its path is built when a refusal needs it.
type Place = { index: number; parent: Place | undefined }
type Step =
| { kind: 'gap'; lines: number }
| { kind: 'leave'; indent: string; lead: string | undefined; written: number }
| { depth: number; kind: 'node'; marker: string | undefined; node: AdfNode; place: Place | undefined }
// `lines`: the line feeds between a node's children; `level`: how much deeper they nest.
type Layout = { level: number; lines: number }
const bulletLists = ['bulletList', 'decisionList', 'taskList']
const itemTypes = ['blockTaskItem', 'listItem']
const shownTextTypes = ['date', 'emoji', 'mention', 'status']
export function adfToPlainText(document: AdfDocument): Result<string> {
return withinEngineLimits(() => {
const read = readAdfDocument(document)
if (!read.ok) return read
const content = writableContent(read.value)
return content.ok ? writeText(content.value ?? []) : content
})
}
// A stack rather than recursion (docs/decisions.md §Nothing recurses unbounded). Text is written the moment it is met: `gap` holds the line feeds it owes first, `lead` the marker of the item it opens, `indent` the margin of every line after that.
function writeText(content: readonly AdfNode[]): Result<string> {
const pieces: string[] = []
let length = 0
let gap = 0
let indent = ''
let lead: string | undefined
let written = 0
function emit(text: string): void {
if (text === '') return
if (lead !== undefined && gap === 0) gap = 1
const atLineStart = written === 0 || gap > 0
const head = atLineStart ? `${written === 0 ? '' : '\n'.repeat(gap)}${lead ?? indent}` : ''
const body = indent === '' ? text : text.replaceAll(/\n(?=[^\n])/g, `\n${indent}`)
pieces.push(head, body)
length += head.length + body.length
gap = 0
lead = undefined
written += 1
}
const pending: Step[] = childSteps(content, { level: 1, lines: 2 }, 0, undefined, () => undefined).reverse()
for (let step = pending.pop(); step !== undefined; step = pending.pop()) {
if (step.kind === 'gap') {
gap = Math.max(gap, step.lines)
continue
}
if (step.kind === 'leave') {
indent = step.indent
lead = step.written === written ? step.lead : undefined
continue
}
const { depth, marker, node, place } = step
if (depth > largestNesting) return failure('unsupported-nesting-depth', `the document nests deeper than the ${largestNesting} levels the writer carries`, pathTo(place))
if (marker !== undefined) {
pending.push({ indent, kind: 'leave', lead, written })
lead = lead === undefined ? `${indent}${marker}` : `${lead}${marker}`
indent = `${indent}${' '.repeat(marker.length)}`
}
if (node.type === 'hardBreak') gap = Math.max(gap, 1)
else if (node.type === 'text') emit(node.text ?? '')
else if (shownTextTypes.includes(node.type)) emit(shownText(node) ?? '')
else {
if (typeof node.text === 'string') emit(node.text)
const layout = layoutOf(node)
for (const child of childSteps(nodeContent(node), layout, depth + layout.level, place, markerFor(node)).reverse()) pending.push(child)
}
if (length > longestOutput) return tooLong()
}
return success(pieces.join(''))
}
// The steps for `nodes` in document order, `layout.lines` line feeds apart.
function childSteps(nodes: readonly AdfNode[], layout: Layout, depth: number, parent: Place | undefined, markerFor: (index: number) => string | undefined): Step[] {
const steps: Step[] = []
for (const [index, node] of nodes.entries()) {
if (index > 0 && layout.lines > 0) steps.push({ kind: 'gap', lines: layout.lines })
steps.push({ depth, kind: 'node', marker: markerFor(index), node, place: { index, parent } })
}
return steps
}
// Children are written in a line where they are inline, a line apart inside a list and an item, a blank line apart between blocks. A list's items nest one level below it, an item's blocks at its own.
function layoutOf(node: AdfNode): Layout {
if (bulletLists.includes(node.type) || node.type === 'orderedList') return { level: 1, lines: 1 }
if (itemTypes.includes(node.type)) return { level: 0, lines: 1 }
if (node.type === 'tableCell' || node.type === 'tableHeader') return { level: 0, lines: 2 }
const model = blockNodeModel(node.type)
if (model !== undefined) return model.contentModel === 'block' ? { level: 1, lines: 2 } : { level: 0, lines: 0 }
return nodeContent(node).every((child) => child.type === 'text' || inlineNodeModel(child.type) !== undefined) ? { level: 0, lines: 0 } : { level: 1, lines: 2 }
}
function markerFor(node: AdfNode): (index: number) => string | undefined {
if (bulletLists.includes(node.type)) return () => '• '
if (node.type !== 'orderedList') return () => undefined
const order = nodeAttrs(node)['order']
const first = typeof order === 'number' && Number.isSafeInteger(order) ? order : 1
return (index) => `${first + index}. `
}
function pathTo(place: Place | undefined): ConvertErrorPath {
const indexes: number[] = []
for (let held = place; held !== undefined; held = held.parent) indexes.push(held.index)
return indexes.reverse().flatMap((index) => ['content', index])
}