3
0
mirror of https://github.com/larvit/adf-codec.git synced 2026-11-18 14:15: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
@@ -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
+1
View File
@@ -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
+40 -3
View File
@@ -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<AdfDocument>
commonMarkToAdf(markdown: string): Result<AdfDocument, ParseError>
adfToPlainText(doc: AdfDocument): Result<string>
adfToPortableMarkdown(doc: AdfDocument): Result<string>
portableMarkdownToAdf(markdown: string): Result<AdfDocument, ParseError>
@@ -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 |
+25
View File
@@ -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.
+16
View File
@@ -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
+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])
}
+27 -47
View File
@@ -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<string>`. 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 `@<id>` 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