diff --git a/AGENTS.md b/AGENTS.md index 5829458..16c45a9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -91,6 +91,7 @@ In `docs/decisions.md`: - The comparison tables list every ADF converter that starts and converts - The real-world corpus holds anonymized documents from sites whose licence it records - The feature table is a section per corpus example, led by a summary table +- Plain text is blocks a blank line apart, with `• ` and `1.` markers and nesting indented ## 1. Nothing about any consumer in the library diff --git a/CHANGELOG.md b/CHANGELOG.md index d273287..bb34438 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,7 @@ ## Unreleased +- `adfToPlainText` writes a document as text with no markup, for a search index, a notification or an email: blocks a blank line apart, `• ` and `1.` list markers with nesting indented, a hard break as a line feed, and a mention, emoji, date or status as the text it shows. It refuses what `adfToHtml` refuses. A table writes its cells as blocks for now. - `readAdfDocument` and the three writers name the node `not-an-adf-document` refuses: `path` leads to a node that is not an ADF node, and the message says what is wrong with it, such as which attribute holds a value that is not JSON. A getter, an object holding itself, a throwing Proxy diff --git a/README.md b/README.md index 7d5e884..a2fae02 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,7 @@ products store as ADF. * `adfToPortableMarkdown` — ADF to markdown that GitHub, GitLab and Obsidian render. Keeps the content and drops colours, layout and other attributes. * `adfToHtml` — ADF to HTML. * `htmlToAdf` — HTML to ADF. +* `adfToPlainText` — ADF to text for an email, a notification or a search index: blocks a blank line apart, lists as `• ` and `1.`, no markup. ## Features and perks @@ -164,6 +165,34 @@ const back = html.ok ? htmlToAdf(html.value) : undefined if (back?.ok) console.log(back.value) // deep-equals page ``` +### ADF to plain text + +```ts +import { adfToPlainText, type AdfDocument } from '@larvit/adf-codec' + +const note: AdfDocument = { + content: [ + { content: [{ text: 'Ship on Friday.', type: 'text' }], type: 'paragraph' }, + { + content: [ + { content: [{ content: [{ text: 'Fix login', type: 'text' }], type: 'paragraph' }], type: 'listItem' }, + { content: [{ content: [{ text: 'Fix export', type: 'text' }], type: 'paragraph' }], type: 'listItem' }, + ], + type: 'bulletList', + }, + ], + type: 'doc', + version: 1, +} + +const text = adfToPlainText(note) +if (text.ok) console.log(text.value) +// Ship on Friday. +// +// • Fix login +// • Fix export +``` + ### Handle a result's error Full reference: [The errors](#the-errors). @@ -224,6 +253,10 @@ whatever it costs; the Achieve goals are weighed against each other in the order 7. **Maintain:** Lossy conversion drops form, never content. A link's or an image's title counts as content. 8. **Maintain:** Runs in any JavaScript engine, with no runtime dependencies and nothing to configure or connect. 9. **Maintain:** Fast, and linear in the document's size as JSON. +10. **Achieve:** Plain text reads like text written for people reading an email. + - Signal: readers shown the candidate texts pick the one the library already writes. + - Counter-signal: issues report plain text that reads as markup or runs blocks together. + - Why: a search index, a notification and an email each show the text as it is, with no renderer to tidy it. ## Audience @@ -315,6 +348,8 @@ readAdfDocument(v: unknown): Result commonMarkToAdf(markdown: string): Result +adfToPlainText(doc: AdfDocument): Result + adfToPortableMarkdown(doc: AdfDocument): Result portableMarkdownToAdf(markdown: string): Result @@ -328,6 +363,7 @@ Each call's name says which format it reads or writes: | --- | --- | --- | | `adfToHtml` | writes HTML: the elements [HTML](#html) lists, and an `adf-carry` element holding everything else | `engine-limit`, `not-an-adf-document`, `unsupported-document-version`, `unsupported-nesting-depth`, `unsupported-node-shape` | | `adfToLosslessMarkdown` | writes the lossless flavour: CommonMark plus GFM's pipe tables and `~~`, with `!adf:` directives and `adf:` fences for everything else | `engine-limit`, `not-an-adf-document`, `unsupported-document-version`, `unsupported-nesting-depth`, `unsupported-node-shape` | +| `adfToPlainText` | writes text with no markup: blocks a blank line apart, list items on a line each under `• ` or `1.`, nesting indented, a hard break a line feed, a mention, emoji, date and status as the text they show | `engine-limit`, `not-an-adf-document`, `unsupported-document-version`, `unsupported-nesting-depth`, `unsupported-node-shape` | | `adfToPortableMarkdown` | writes markdown GitHub, GitLab and Obsidian render; drops what they cannot show, and writes no directive | `engine-limit`, `not-an-adf-document`, `unsupported-document-version`, `unsupported-nesting-depth`, `unsupported-node-shape` | | `commonMarkToAdf` | reads strict CommonMark as its spec says: a directive, a pipe table, `~~`, `==` and an `adf:` fence read as text and code | `engine-limit`, `not-a-string`, `unmappable-html`, `unsupported-nesting-depth`, `unsupported-node-shape` | | `htmlToAdf` | reads the HTML `adfToHtml` writes, also as a browser's `innerHTML` or a form post spells it, a carry element from its `data-adf`; refuses any other HTML, an edit to what a carry element shows included | `engine-limit`, `not-a-string`, `unmappable-html`, `unsupported-nesting-depth`, `unsupported-node-shape` | @@ -609,7 +645,7 @@ Which reader raises which code: [The calls](#the-calls). Codes every direction r ### Emitting -`adfToLosslessMarkdown`, `adfToPortableMarkdown` and `adfToHtml` raise these, and the codes under +`adfToLosslessMarkdown`, `adfToPlainText`, `adfToPortableMarkdown` and `adfToHtml` raise these, and the codes under [Either direction](#either-direction). `readAdfDocument` raises `not-an-adf-document` and `unsupported-node-shape`, and `engine-limit`. @@ -657,7 +693,7 @@ Every call can raise `engine-limit`, and every conversion `unsupported-nesting-d - **Writing, in `adfToLosslessMarkdown`**: a node not riding the carry that carries one mark type twice. Keep the ADF and show the document read-only; where you built the ADF, fix what the message names. -- **Writing, in `adfToHtml`, `adfToLosslessMarkdown` and `adfToPortableMarkdown`**: a shape +- **Writing, in `adfToHtml`, `adfToLosslessMarkdown`, `adfToPlainText` and `adfToPortableMarkdown`**: a shape Atlassian's schema forbids, even inside a node that rides the carry: an inline card a link marks, a known block holding `text`, a known non-text inline node holding `text` or non-empty `content`, or a known block that takes no content, such as `rule`, holding non-empty `content`. Keep the ADF @@ -669,7 +705,7 @@ Every call can raise `engine-limit`, and every conversion `unsupported-nesting-d 10,000,000 JSON values, each object, array, string, number, boolean and null counting one. Keep the ADF and pass the document over or show it read-only; where you built the ADF, split it. - **Past the engine's longest string**: - - a writer's markdown or HTML would pass 536870888 characters, V8's longest string, on every + - a writer's markdown, HTML or text would pass 536870888 characters, V8's longest string, on every engine; - in `adfToPortableMarkdown`, the document's text alone would, edge whitespace included; - in `losslessMarkdownToAdf`, a directive's plain CommonMark would; @@ -778,6 +814,7 @@ Contract: [`docs/decisions.md`](https://github.com/larvit/adf-codec/blob/main/do | `SourcePosition` | type | an error's place in the markdown or HTML read | | `adfToHtml` | function | ADF to HTML | | `adfToLosslessMarkdown` | function | ADF to the lossless flavour | +| `adfToPlainText` | function | ADF to text with no markup | | `adfToPortableMarkdown` | function | ADF to portable markdown, lossy | | `commonMarkToAdf` | function | strict CommonMark to ADF | | `htmlToAdf` | function | `adfToHtml`'s HTML, read back to ADF | diff --git a/docs/decisions.md b/docs/decisions.md index a5e16b3..8603c85 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -1296,3 +1296,28 @@ expectations as input. The Date row drew 1 of 3 not reasonable, so four more rea reader of the markdown, export/indexing, viewer/editor) read it, and 5 of 7 found it reasonable. `adfToLosslessMarkdown` keeps writing `!adf:date{timestamp=1756080000000}`. The two who rejected it wanted the day shown, as `!adf:date[2025-08-25]{timestamp=…}`. + +## Plain text is blocks a blank line apart, with `• ` and `1.` markers and nesting indented + +2026-11-14, a reader panel of 7 (export/indexing, LLM/agent, support agent, viewer/editor, bot, +product manager, engineer), then the maintainer. Goal 10. Valid while the audience of the text is +people reading an email. + +Each reader wrote the text they expected, then picked among six shuffled candidates. All seven +expected a blank line between blocks, a hard break as one line feed and a mention as its display +text. Three picked blank lines with no markers and no indent, three picked `• ` bullets with `1.` +numbers kept and nesting indented, one picked `- ` and `1.` markers. Less than five of seven is a +missing goal, so the maintainer chose the second and worded the goal for people reading an email. + +`adfToPlainText` writes: + +- Blocks a blank line apart, an item's blocks and a list's items a line apart. +- `• ` for a bullet list, a task list and a decision list, and `n. ` for an ordered list, counting + from its `order`. A nested list and an item's later lines are indented to the marker's width. +- A hard break as a line feed, a mention, emoji, date and status as the text they show, and marks + as the text they mark. +- A block holding no text as nothing, with no extra blank line. +- A table as its cells written as blocks, until a plan item gives it a spelling. + +The depth and length refusals are `adfToHtml`'s: a document nesting past 500 levels, or text past +V8's longest string, indentation included. diff --git a/docs/reading-cost.md b/docs/reading-cost.md index 36ee870..de15170 100644 --- a/docs/reading-cost.md +++ b/docs/reading-cost.md @@ -1060,3 +1060,19 @@ Read most (opens and searches): - `README.md` 1 - `docs/decisions.md` 1 - `src/markdown/parse/markdown-to-adf.ts` 1 + +## Reading cost, chunk 1125f4a3a4ad, finished 2026-11-14T10:38:41Z + +124303 new input tokens before the first commit. + +Read most (opens and searches): + +- `todo.md` 10 +- `README.md` 5 +- `src/adf/shown-text.ts` 3 +- `docs/decisions.md` 2 +- `src/index.ts` 2 +- `AGENTS.md` 1 +- `docs/score-anchors.md` 1 +- `src/adf/inline-nodes.ts` 1 +- `src/html/emit/adf-to-html.ts` 1 diff --git a/src/index.ts b/src/index.ts index a8b2de4..37332ea 100644 --- a/src/index.ts +++ b/src/index.ts @@ -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' diff --git a/src/plain-text/adf-to-plain-text.test.ts b/src/plain-text/adf-to-plain-text.test.ts new file mode 100644 index 0000000..6ccfe23 --- /dev/null +++ b/src/plain-text/adf-to-plain-text.test.ts @@ -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 { + return result.ok ? result.value : `${result.error.code}: ${result.error.message}` +} + +function refusal(result: Result): 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) +}) diff --git a/src/plain-text/adf-to-plain-text.ts b/src/plain-text/adf-to-plain-text.ts new file mode 100644 index 0000000..e960309 --- /dev/null +++ b/src/plain-text/adf-to-plain-text.ts @@ -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 { + 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 { + 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]) +} diff --git a/todo.md b/todo.md index ab6ba1b..5b9b41a 100644 --- a/todo.md +++ b/todo.md @@ -12,38 +12,37 @@ | ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score | |---|---|---|---|---|---|---|---|---|---|---|---| -| 179 | 0.4.0 | | | **Ship `adfToPlainText`, writing a document's text with no markup, under a README goal for plain text.** | 2 | 2 | 2 | 4 | 5 | 3 by 4, 6 by 2 | 3.7 | -| 180 | 0.4.0 | 179 | | **Write a table in `adfToPlainText` as one line per row, so a CSV export or a search index reads its cells.** | 2 | 2 | 2 | 4 | 3 | 3 by 1, 6 by 3 | 6.1 | -| 181 | 0.4.0 | 179 | | **Write media, link cards, extensions and expand titles in `adfToPlainText` as the text each shows, and answer developer-community topic 41858.** | 2 | 2 | 2 | 4 | 4 | 3 by 2, 6 by 2 | 4.1 | -| 141 | 0.4.0 | | decision | **Write `strike` as HTML in `adfToHtml` and read it back in `htmlToAdf`, in place of the carry element.** | 1 | 1 | 1 | 1 | 2 | 6 by 2 | 4.0 | -| 135 | 0.4.0 | | | **Write media, media groups and captions as semantic HTML in `adfToHtml` and read them back in `htmlToAdf`, in place of the carry element.** | 2 | 2 | 2 | 4 | 4 | 6 by 2 | 2.0 | -| 136 | 0.4.0 | | | **Write underline, text and background colours, subscript, superscript, alignment and indentation as HTML in `adfToHtml` and read them back in `htmlToAdf`, in place of the carry element.** | 2 | 2 | 2 | 4 | 4 | 6 by 2 | 2.0 | -| 134 | 0.4.0 | | decision | **Write panels, expands, task lists and decision lists as semantic HTML in `adfToHtml` and read them back in `htmlToAdf`, in place of the carry element.** | 2 | 2 | 2 | 4 | 5 | 6 by 3 | 1.8 | -| 46 | 0.4.0 | 134, 135, 136 | | **Publish the bundle size in the README, failing the release pipeline when it drifts.** | 2 | 2 | 1 | 3 | 4 | 3 by 3 | 3.2 | -| 174 | 0.4.0 | | defect | **Bound the passes `trimmedEdges` takes by a constant, so a line of alternating code and emphasized blanks trims in linear time.** | 3 | 1 | 2 | 4 | 7 | 9 by 3 | 2.3 | -| 51 | 0.4.0 | | | **Match a reference label to its definition under Unicode case folding.** | 2 | 1 | 2 | 3 | 4 | 4 by 2 | 2.1 | -| 148 | 0.4.0 | | | **Ship conversion between ADF and Jira wiki markup both ways, under a README goal for wiki markup.** | 3 | 2 | 2 | 5 | 7 | 3 by 5 | 0.9 | -| 149 | 0.4.0 | | | **Read any HTML into ADF, in a call or option a developer panel picks, under a README goal for foreign HTML.** | 3 | 2 | 2 | 5 | 7 | 3 by 5 | 0.9 | -| 172 | 0.4.0 | | principle | **Build one test per reader or case in place of a loop inside a test body, in the 26 test files that loop.** | 3 | 1 | 1 | 3 | 8 | code health by 2 | 0.8 | +| 180 | 0.4.0 | | | **Write a table in `adfToPlainText` as one line per row, so a CSV export or a search index reads its cells.** | 2 | 2 | 2 | 4 | 3 | 3 by 1, 6 by 3 | 4.9 | +| 181 | 0.4.0 | | | **Write media, link cards, extensions and expand titles in `adfToPlainText` as the text each shows, and answer developer-community topic 41858.** | 2 | 2 | 2 | 4 | 4 | 3 by 2, 6 by 2 | 3.3 | +| 141 | 0.4.0 | | decision | **Write `strike` as HTML in `adfToHtml` and read it back in `htmlToAdf`, in place of the carry element.** | 1 | 1 | 1 | 1 | 2 | 6 by 2 | 3.2 | +| 135 | 0.4.0 | | | **Write media, media groups and captions as semantic HTML in `adfToHtml` and read them back in `htmlToAdf`, in place of the carry element.** | 2 | 2 | 2 | 4 | 4 | 6 by 2 | 1.6 | +| 136 | 0.4.0 | | | **Write underline, text and background colours, subscript, superscript, alignment and indentation as HTML in `adfToHtml` and read them back in `htmlToAdf`, in place of the carry element.** | 2 | 2 | 2 | 4 | 4 | 6 by 2 | 1.6 | +| 134 | 0.4.0 | | decision | **Write panels, expands, task lists and decision lists as semantic HTML in `adfToHtml` and read them back in `htmlToAdf`, in place of the carry element.** | 2 | 2 | 2 | 4 | 5 | 6 by 3 | 1.5 | +| 46 | 0.4.0 | 134, 135, 136 | | **Publish the bundle size in the README, failing the release pipeline when it drifts.** | 2 | 2 | 1 | 3 | 4 | 3 by 3 | 2.6 | +| 174 | 0.4.0 | | defect | **Bound the passes `trimmedEdges` takes by a constant, so a line of alternating code and emphasized blanks trims in linear time.** | 3 | 1 | 2 | 4 | 7 | 9 by 3 | 1.9 | +| 51 | 0.4.0 | | | **Match a reference label to its definition under Unicode case folding.** | 2 | 1 | 2 | 3 | 4 | 4 by 2 | 1.7 | +| 148 | 0.4.0 | | | **Ship conversion between ADF and Jira wiki markup both ways, under a README goal for wiki markup.** | 3 | 2 | 2 | 5 | 7 | 3 by 5 | 0.8 | +| 149 | 0.4.0 | | | **Read any HTML into ADF, in a call or option a developer panel picks, under a README goal for foreign HTML.** | 3 | 2 | 2 | 5 | 7 | 3 by 5 | 0.8 | +| 172 | 0.4.0 | | principle | **Build one test per reader or case in place of a loop inside a test body, in the 26 test files that loop.** | 3 | 1 | 1 | 3 | 8 | code health by 2 | 0.6 | | 107 | 0.4.0 | | decision | **Spell the block carry's JSON so its length stays linear in the node's JSON.** | 3 | 1 | 3 | 5 | 5 | | 0.0 | | 170 | 0.4.0 | | owner | **Bundle the packed tarball with webpack, esbuild, Rollup and Bun in the gate, failing on any bundler warning, and run each bundle's round-trip in Node.** | 3 | 1 | 1 | 3 | 5 | | 0.0 | -| 42 | 0.5.0 | | defect | **Trim a text leaf's trailing blanks in linear time.** | 1 | 1 | 2 | 2 | 2 | 9 by 3 | 26.2 | -| 31 | 0.5.0 | | | **Make the branch-coverage figure repeat across runs of an unchanged tree.** | 2 | 1 | 1 | 2 | 3 | code health by 3 | 19.6 | -| 57 | 0.5.0 | | | **Make each `ci.sh` leg build what it reads, so one leg run alone tests the current tree.** | 2 | 1 | 1 | 2 | 3 | code health by 3 | 19.6 | -| 38 | 0.5.0 | | defect | **Spell a lone surrogate in a text node so it survives a UTF-8 encode.** | 1 | 1 | 2 | 2 | 2 | 1 by 2 | 17.4 | -| 76 | 0.5.0 | | | **State the files the package does not ship once, so the build, the lint ceiling, the coverage exclusions and the mutation run cannot drift apart.** | 1 | 1 | 1 | 1 | 2 | code health by 2 | 17.4 | -| 56 | 0.5.0 | | | **Give each piece of `blocks.ts`'s block-walk state and `inline-content.ts`'s `Scan` one owner that returns what it changes.** | 3 | 1 | 2 | 4 | 5 | code health by 5 | 13.1 | -| 118 | 0.5.0 | | | **Spell a portable link's title through `oneLine`.** | 1 | 1 | 1 | 1 | 1 | code health by 1 | 10.5 | -| 82 | 0.5.0 | | | **Give the directive tests and fixtures random UUID v7 ids in place of `a-1`, `a`, `x` and `h`.** | 2 | 1 | 1 | 2 | 3 | code health by 1 | 6.5 | -| 178 | 0.5.0 | | owner | **Reach the comprehension floor: move the reasoning behind the emitter's fallback and escape loops into the code that runs them, so each reads on its own.** | 3 | 1 | 2 | 4 | 7 | code health by 8 | 6.2 | -| 58 | 0.5.0 | | | **Port `ci.sh`, `publish.sh`, `docker-runner.sh` and `mutation-tests/run.sh` to standalone Python scripts.** | 4 | 2 | 2 | 6 | 6 | code health by 3 | 4.4 | -| 9 | 0.5.0 | | | **Ship an online sandbox: a web page with two textboxes converting between ADF and markdown on the library's browser build.** | 3 | 2 | 1 | 4 | 6 | 3 by 6 | 2.1 | -| 34 | 0.5.0 | | | **Read emphasis flanking by the whole character beside an astral symbol.** | 2 | 1 | 2 | 3 | 3 | 4 by 1 | 1.5 | +| 42 | 0.5.0 | | defect | **Trim a text leaf's trailing blanks in linear time.** | 1 | 1 | 2 | 2 | 2 | 9 by 3 | 21.2 | +| 31 | 0.5.0 | | | **Make the branch-coverage figure repeat across runs of an unchanged tree.** | 2 | 1 | 1 | 2 | 3 | code health by 3 | 15.9 | +| 57 | 0.5.0 | | | **Make each `ci.sh` leg build what it reads, so one leg run alone tests the current tree.** | 2 | 1 | 1 | 2 | 3 | code health by 3 | 15.9 | +| 38 | 0.5.0 | | defect | **Spell a lone surrogate in a text node so it survives a UTF-8 encode.** | 1 | 1 | 2 | 2 | 2 | 1 by 2 | 14.2 | +| 76 | 0.5.0 | | | **State the files the package does not ship once, so the build, the lint ceiling, the coverage exclusions and the mutation run cannot drift apart.** | 1 | 1 | 1 | 1 | 2 | code health by 2 | 14.2 | +| 56 | 0.5.0 | | | **Give each piece of `blocks.ts`'s block-walk state and `inline-content.ts`'s `Scan` one owner that returns what it changes.** | 3 | 1 | 2 | 4 | 5 | code health by 5 | 10.6 | +| 118 | 0.5.0 | | | **Spell a portable link's title through `oneLine`.** | 1 | 1 | 1 | 1 | 1 | code health by 1 | 8.5 | +| 82 | 0.5.0 | | | **Give the directive tests and fixtures random UUID v7 ids in place of `a-1`, `a`, `x` and `h`.** | 2 | 1 | 1 | 2 | 3 | code health by 1 | 5.3 | +| 178 | 0.5.0 | | owner | **Reach the comprehension floor: move the reasoning behind the emitter's fallback and escape loops into the code that runs them, so each reads on its own.** | 3 | 1 | 2 | 4 | 7 | code health by 8 | 5.0 | +| 58 | 0.5.0 | | | **Port `ci.sh`, `publish.sh`, `docker-runner.sh` and `mutation-tests/run.sh` to standalone Python scripts.** | 4 | 2 | 2 | 6 | 6 | code health by 3 | 3.5 | +| 9 | 0.5.0 | | | **Ship an online sandbox: a web page with two textboxes converting between ADF and markdown on the library's browser build.** | 3 | 2 | 1 | 4 | 6 | 3 by 6 | 1.7 | +| 34 | 0.5.0 | | | **Read emphasis flanking by the whole character beside an astral symbol.** | 2 | 1 | 2 | 3 | 3 | 4 by 1 | 1.2 | | 74 | 0.5.0 | | owner | **Keep the release path publishing after npm retires bypass-2FA tokens.** | 3 | 2 | 4 | 7 | 4 | | 0.0 | | 8 | 0.6.0 | | owner | **Ship a CLI.** | 3 | 2 | 1 | 4 | 7 | | 0.0 | -| 139 | 0.7.0 | | decision | **Ship the calls between markdown and HTML, composed through ADF and each named by its flavour.** | 2 | 1 | 2 | 3 | 4 | 3 by 3 | 3.2 | -| 137 | 0.7.0 | | decision | **Read foreign HTML in `htmlToAdf` the three ways `docs/decisions.md` §Foreign HTML sorts three ways states.** | 2 | 1 | 2 | 3 | 4 | 4 by 2 | 2.1 | -| 138 | 0.7.0 | 137 | | **Read raw HTML in every markdown reader through `htmlToAdf`'s foreign-element mapping, in place of refusing it as `unmappable-html`.** | 3 | 1 | 3 | 5 | 5 | 4 by 4 | 2.5 | +| 139 | 0.7.0 | | decision | **Ship the calls between markdown and HTML, composed through ADF and each named by its flavour.** | 2 | 1 | 2 | 3 | 4 | 3 by 3 | 2.6 | +| 137 | 0.7.0 | | decision | **Read foreign HTML in `htmlToAdf` the three ways `docs/decisions.md` §Foreign HTML sorts three ways states.** | 2 | 1 | 2 | 3 | 4 | 4 by 2 | 1.7 | +| 138 | 0.7.0 | 137 | | **Read raw HTML in every markdown reader through `htmlToAdf`'s foreign-element mapping, in place of refusing it as `unmappable-html`.** | 3 | 1 | 3 | 5 | 5 | 4 by 4 | 2.0 | ## Renamed @@ -51,25 +50,6 @@ ## Details -### 179. Ship `adfToPlainText`, writing a document's text with no markup, under a README goal for plain text. - -Asked on the Atlassian developer community for search indexing, notifications, emails and CSV -exports, where markdown's markers are noise. Add the goal to the README's `## Goals` in the same -change. Its wording and rank among the goals are the maintainer's to approve in the PR. The -maintainer chose 0.4.0 for it, to ship what exists first. - -The call takes an `AdfDocument` and returns `Result`. It refuses what `adfToHtml` refuses, -with the same codes: `engine-limit`, `not-an-adf-document`, `unsupported-document-version`, -`unsupported-nesting-depth` and `unsupported-node-shape`. It has no reader, so goal 1's -losslessness can't apply, but it still returns a result and never throws. Goal 7 applies: the call -drops markup, never content. A node writes its text, and a container its children. A hard break is -a newline. A mention writes `@Display Name` from its `text`, as `src/adf/shown-text.ts` does, which -falls back to `@` only where the mention has no text. A node of an unknown type writes the text -it holds, so no content is lost before items 180 and 181 refine the nodes. - -A reader panel (`AGENTS.md`, "Ask, don't guess") picks how blocks part and how a list's items read: -markers, indentation or numbers. The verdict lands in `docs/decisions.md`. - ### 180. Write a table in `adfToPlainText` as one line per row, so a CSV export or a search index reads its cells. A reader panel picks the cell separator, and what a header row, a merged cell and a block nested in