3
0
mirror of https://github.com/larvit/adf-codec.git synced 2026-11-21 15:42:58 +01:00

Answer prose round 1: the README says which refusal differs between engines, items 106 and 107 read one idea a sentence, and two test titles and a comment read on one pass

This commit is contained in:
2026-10-11 20:54:59 +02:00
parent 29ad58d942
commit 1167a440ae
7 changed files with 27 additions and 27 deletions
+1 -1
View File
@@ -88,7 +88,7 @@
`adfToLosslessMarkdown` and `adfToPortableMarkdown` refuse it as `unsupported-node-shape`, where `adfToLosslessMarkdown` and `adfToPortableMarkdown` refuse it as `unsupported-node-shape`, where
they threw. they threw.
- Fix deeply nested compact JSON in an `adf:` fence: `losslessMarkdownToAdf` refuses it as - Fix deeply nested compact JSON in an `adf:` fence: `losslessMarkdownToAdf` refuses it as
`unsupported-node-shape`, like any compact JSON there, where a megabyte of it threw. `unsupported-node-shape`, as it refuses any compact JSON there, where about a megabyte of it threw.
- Add `adfToPortableMarkdown` and `portableMarkdownToAdf`, a lossy pair converting ADF to and from - Add `adfToPortableMarkdown` and `portableMarkdownToAdf`, a lossy pair converting ADF to and from
markdown GitHub, GitLab and Obsidian render: alerts, callouts, task lists, `==highlights==` and markdown GitHub, GitLab and Obsidian render: alerts, callouts, task lists, `==highlights==` and
pipe tables. A task item keeps its paragraphs, then its nested task lists; the rest of the item, pipe tables. A task item keeps its paragraphs, then its nested task lists; the rest of the item,
+4 -3
View File
@@ -408,8 +408,9 @@ A parse always names a position, so the three markdown readers return `ParseErro
typed on `ConvertError` takes both. typed on `ConvertError` takes both.
A call reports the first refusal in document order and stops, so a document with several surfaces A call reports the first refusal in document order and stops, so a document with several surfaces
them one per call. Every refusal is deterministic — there is no I/O anywhere — so a retry returns them one per call. Every refusal is deterministic on one engine — there is no I/O anywhere — so a
the identical error: fix the input, or set the document aside. retry returns the identical error: fix the input, or set the document aside. Only the engine-limit
refusal under `unsupported-node-shape` differs between engines.
### Parsing ### Parsing
@@ -442,7 +443,7 @@ The emitter raises these, and so does a parse, which asks the emitter how to spe
| Code | Fires when | What you can do | | Code | Fires when | What you can do |
| --- | --- | --- | | --- | --- | --- |
| `unsupported-nesting-depth` | blocks, marks, an attribute's JSON or a carried node's JSON nest past 500 levels | keep the ADF and pass the document over, or show it read-only; flatten the input where you are the one who wrote it | | `unsupported-nesting-depth` | blocks, marks, an attribute's JSON or a carried node's JSON nest past 500 levels | keep the ADF and pass the document over, or show it read-only; flatten the input where you are the one who wrote it |
| `unsupported-node-shape` | parsing, in `losslessMarkdownToAdf`: markdown spells a node with an attribute, value, argument or body its type does not take, or without one it needs, wraps a directive mark around nothing or only hard breaks, writes as a directive a node or mark the lossless flavour spells as CommonMark, or puts a reserved directive out of place: `!adf:textBreak{}` parting nothing, `!adf:doc` anywhere but as the whole document. Emitting, in `adfToLosslessMarkdown`: a node not riding the carry that carries one mark type twice, a block or a non-text inline node holding `text`, or a leaf block or a non-text inline node holding `content`. Emitting, in `adfToPortableMarkdown`: a line or task list the portable writer cannot spell, a bug in this library. Emitting, in both writers: a document whose markdown would be longer than the longest string or array the JavaScript engine builds — on V8, about 537 million characters of markdown, or about 134 million in one text node | fix what the message names; [`spec/flavour.md`](https://github.com/larvit/adf-codec/blob/main/spec/flavour.md) lists every type's attributes and body. For a portable line or task list, report it. Past the engine's longest string or array, keep the ADF and pass the document over, or show it read-only | | `unsupported-node-shape` | parsing, in `losslessMarkdownToAdf`: markdown spells a node with an attribute, value, argument or body its type does not take, or without one it needs, wraps a directive mark around nothing or only hard breaks, writes as a directive a node or mark the lossless flavour spells as CommonMark, or puts a reserved directive out of place: `!adf:textBreak{}` parting nothing, `!adf:doc` anywhere but as the whole document. Emitting, in `adfToLosslessMarkdown`: a node not riding the carry that carries one mark type twice, a block or a non-text inline node holding `text`, or a leaf block or a non-text inline node holding `content`. Emitting, in `adfToPortableMarkdown`: a line or task list the portable writer cannot spell, a bug in this library. Emitting, in both writers: a document whose markdown would be longer than the longest string or array the JavaScript engine builds — on V8, about 537 million characters of markdown, or about 134 million in one text node | fix what the message names; [`spec/flavour.md`](https://github.com/larvit/adf-codec/blob/main/spec/flavour.md) lists every type's attributes and body. For a portable line or task list, report it as a bug. Past the engine's longest string or array, keep the ADF and pass the document over, or show it read-only |
## The guarantees ## The guarantees
+3 -3
View File
@@ -463,9 +463,9 @@ handles one cause alike whichever node, attribute or direction raised it.
emitting — no document holds one, so no round-trip crosses them (2026-09-23). emitting — no document holds one, so no round-trip crosses them (2026-09-23).
- A document whose markdown would be longer than the longest string or array the JavaScript engine - A document whose markdown would be longer than the longest string or array the JavaScript engine
builds is `unsupported-node-shape` at the document's path, in either writer: the document does builds is `unsupported-node-shape` at the document's path, in either writer: the document does
not convert, and the bound is the engine's own. A carried node reaches it on about 1 MB of not convert, and no spelling in the input causes the bound (§The code list). A carried node
deeply nested JSON, since the block carry indents two spaces a level; `todo.md` item 107 spells passes it on about 1 MB of deeply nested JSON, since the block carry indents two spaces a level;
it in a length linear in its JSON (2026-10-11). `todo.md` item 107 respells the carry in a length linear in its JSON (2026-10-11).
- The markdown readers and `htmlToAdf` refuse a value that is not a string as `not-a-string`, at - The markdown readers and `htmlToAdf` refuse a value that is not a string as `not-a-string`, at
position `{ line: 1, offset: 0 }` with an empty path: no existing code reads true of it, and position `{ line: 1, offset: 0 }` with an empty path: no existing code reads true of it, and
`not-an-adf-document` names the emitters' input (2026-10-05). `not-an-adf-document` names the emitters' input (2026-10-05).
+1 -2
View File
@@ -15,7 +15,7 @@ export function serializeCanonicalJson(value: JsonValue, spelling: JsonSpelling)
return text.join('') return text.join('')
} }
// Stops at the first piece `text` does not hold: two-space indentation can spell a short compact text past the engine's longest string. // Stops at the first piece that does not match `text`: re-spelled with two-space indentation, a short compact text can pass the engine's longest string.
export function spellsCanonicalJson(value: JsonValue, spelling: JsonSpelling, text: string): boolean { export function spellsCanonicalJson(value: JsonValue, spelling: JsonSpelling, text: string): boolean {
let offset = 0 let offset = 0
const whole = writeCanonicalJson(value, spelling, (piece) => { const whole = writeCanonicalJson(value, spelling, (piece) => {
@@ -26,7 +26,6 @@ export function spellsCanonicalJson(value: JsonValue, spelling: JsonSpelling, te
return whole && offset === text.length return whole && offset === text.length
} }
// `write` returns false to stop the walk, and the walk then returns false.
function writeCanonicalJson(value: JsonValue, spelling: JsonSpelling, write: (piece: string) => boolean): boolean { function writeCanonicalJson(value: JsonValue, spelling: JsonSpelling, write: (piece: string) => boolean): boolean {
const indent = spelling === 'compact' ? '' : ' ' const indent = spelling === 'compact' ? '' : ' '
const pending: Pending[] = [{ depth: 0, value }] const pending: Pending[] = [{ depth: 0, value }]
+1 -1
View File
@@ -448,7 +448,7 @@ test('names the canonical spelling a carried JSON reads alone', () => {
assert.equal(content(losslessMarkdownToAdf('!adf:carry{json="{\\"type\\":\\"blockCard\\",\\"attrs\\":{}}"}\n')), `${canonically}compact, keys sorted${literal}`) assert.equal(content(losslessMarkdownToAdf('!adf:carry{json="{\\"type\\":\\"blockCard\\",\\"attrs\\":{}}"}\n')), `${canonically}compact, keys sorted${literal}`)
}) })
test('refuses compact JSON in the carry fence without spelling it two-space past the engine\'s longest string', () => { test('refuses compact JSON in the carry fence without building its two-space spelling', () => {
const json = `{"attrs":{"value":${'['.repeat(495)}${new Array(2_200_000).fill(0).join(',')}${']'.repeat(495)}}}` const json = `{"attrs":{"value":${'['.repeat(495)}${new Array(2_200_000).fill(0).join(',')}${']'.repeat(495)}}}`
assert.equal( assert.equal(
content(losslessMarkdownToAdf(`\`\`\`adf:unknownBlock\n${json}\n\`\`\`\n`)), content(losslessMarkdownToAdf(`\`\`\`adf:unknownBlock\n${json}\n\`\`\`\n`)),
@@ -70,7 +70,7 @@ test('refuses what the document guard refuses, and nothing else', () => {
assert.match(portableDocument(document(paragraph(deepInline))), /^unsupported-nesting-depth at /) assert.match(portableDocument(document(paragraph(deepInline))), /^unsupported-nesting-depth at /)
}) })
test('refuses a document whose text merges past the engine\'s longest string', () => { test('refuses a paragraph whose merged text passes the engine\'s longest string', () => {
const long = 'a'.repeat(2 ** 28) const long = 'a'.repeat(2 ** 28)
const merged = paragraph(...Array.from({ length: 9 }, () => text(long))) const merged = paragraph(...Array.from({ length: 9 }, () => text(long)))
assert.equal(portableDocument(document(merged)), 'unsupported-node-shape at /') assert.equal(portableDocument(document(merged)), 'unsupported-node-shape at /')
+16 -16
View File
@@ -25,7 +25,7 @@
| ID | Release | Exempt | Item | R | S | A | G | Goals | Score | | ID | Release | Exempt | Item | R | S | A | G | Goals | Score |
|---|---|---|---|---|---|---|---|---|---| |---|---|---|---|---|---|---|---|---|---|
| 106 | 0.2.0 | defect | **Refuse a document or markdown whose spelling would pass a stated length before building it, so no call exhausts the heap.** | 4 | 6 | 5 | 8 | 1, 9 | 20.5 | | 106 | 0.2.0 | defect | **Refuse a document or markdown whose output would pass a stated length before building it, so no call exhausts the heap.** | 4 | 6 | 5 | 8 | 1, 9 | 20.5 |
| 103 | 0.2.0 | | **Fold `unspellable-whitespace` into `unsupported-node-shape`, so a line ending and a null character in a content slot take one code.** | 2 | 2 | 5 | 6 | 1 | 19.5 | | 103 | 0.2.0 | | **Fold `unspellable-whitespace` into `unsupported-node-shape`, so a line ending and a null character in a content slot take one code.** | 2 | 2 | 5 | 6 | 1 | 19.5 |
| 84 | 0.2.0 | | **Read GFM's pipe table without leading pipes, and with alignment colons, in `portableMarkdownToAdf`, dropping the alignment.** | 3 | 4 | 7 | 7 | 4, 7 | 19.4 | | 84 | 0.2.0 | | **Read GFM's pipe table without leading pipes, and with alignment colons, in `portableMarkdownToAdf`, dropping the alignment.** | 3 | 4 | 7 | 7 | 4, 7 | 19.4 |
| 52 | 0.2.0 | | **Spell `colwidth` as a comma list, `colwidth="340,420"`.** | 3 | 3 | 5 | 6 | 6 | 11.5 | | 52 | 0.2.0 | | **Spell `colwidth` as a comma list, `colwidth="340,420"`.** | 3 | 3 | 5 | 6 | 6 | 11.5 |
@@ -73,19 +73,19 @@
## Details ## Details
### 106. Refuse a document or markdown whose spelling would pass a stated length before building it, so no call exhausts the heap. ### 106. Refuse a document or markdown whose output would pass a stated length before building it, so no call exhausts the heap.
The writers return `unsupported-node-shape` where the engine throws past its longest string, but The writers return `unsupported-node-shape` where the engine throws past its longest string, but
some documents exhaust the heap first, which no catch survives. `losslessMarkdownToAdf` on 2.1 MB some documents exhaust the heap first, which no catch survives. `losslessMarkdownToAdf` on 2.1 MB of
of markdown, a `!adf:blockquote` holding a list nested 490 levels whose paragraph runs on in 700,000 markdown, a `!adf:blockquote` holding a list nested 490 levels whose paragraph runs on in 700,000
lazy lines `b\`, crashed Node 24 out of heap: `directiveNode` re-spells the subtree, indenting each lazy lines `b\`, crashed Node 24 out of heap: `directiveNode` re-spells the subtree, indenting each
line to its depth. `adfToLosslessMarkdown` on nine text nodes sharing one 2^28-character string line to its depth. `adfToLosslessMarkdown` on nine text nodes sharing one 2^28-character string got
got Bun OOM-killed under 8 GB: `escape` in `line-escaping.ts` pushes one array element per Bun OOM-killed under 8 GB: `escape` in `line-escaping.ts` pushes one array element per character.
character. Where the heap holds out, the readers' re-spelling can still throw a `RangeError`, and Where the heap holds out, the readers' re-spelling can still throw a `RangeError`. JavaScriptCore's
JavaScriptCore's `Out of memory`, which the writers refuse, may also mean a failed allocation a `Out of memory`, which the writers refuse, may also mean a failed allocation that a retry survives.
retry survives. The length to refuse past is a number no entry states yet (AGENTS.md §Stated numbers): The candidate length to refuse past is V8's 2^29 − 24 on every engine, so the same document converts
V8's 2^29 − 24 on every engine, so the same document converts alike everywhere, is the candidate. alike everywhere; no entry states it yet (AGENTS.md §Stated numbers). Found by the principles audit
Found by the principles audit of item 83, 2026-10-11. of item 83, 2026-10-11.
### 103. Fold `unspellable-whitespace` into `unsupported-node-shape`, so a line ending and a null character in a content slot take one code. ### 103. Fold `unspellable-whitespace` into `unsupported-node-shape`, so a line ending and a null character in a content slot take one code.
@@ -313,11 +313,11 @@ interim sentence.
### 107. Spell the block carry's JSON so its length stays linear in the node's JSON. ### 107. Spell the block carry's JSON so its length stays linear in the node's JSON.
The block carry indents two spaces a level, so a carried node's JSON about 1 MB deep in nested The block carry indents two spaces a level, so about 1 MB of deeply nested arrays in a carried
arrays spells past V8's longest string, which the writers refuse as `unsupported-node-shape`; the node's JSON spells past V8's longest string, which the writers refuse as `unsupported-node-shape`;
inline carry's compact JSON would fit. §The code list calls a refusal no spelling recovers from a the inline carry's compact JSON would fit. docs/decisions.md §The code list calls a refusal no
gap in the flavour. A format change: §The formats are API. Found by the README-goals audit of item spelling recovers from a gap in the flavour. Respelling the carry changes the format (§The formats
83, 2026-10-11. are API). Found by the README-goals audit of item 83, 2026-10-11.
### 51. Match a reference label to its definition under Unicode case folding. ### 51. Match a reference label to its definition under Unicode case folding.