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:
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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 |
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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'
|
||||
|
||||
@@ -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)
|
||||
})
|
||||
@@ -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])
|
||||
}
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user