3
0
mirror of https://github.com/larvit/adf-codec.git synced 2026-11-18 22:25:44 +01:00

Answer stability round 1: the guard's comment holds at both its call sites, and a giving-way list's items keep the list's path

This commit is contained in:
2026-10-13 01:09:32 +02:00
committed by Lillem4n
parent 7caa8237f0
commit 4657796d4d
5 changed files with 16 additions and 25 deletions
+4 -4
View File
@@ -86,10 +86,10 @@
- Fix a document whose markdown would be longer than 536,870,888 characters, V8's longest string:
`adfToLosslessMarkdown` and `adfToPortableMarkdown` refuse it as `unsupported-node-shape` on
every engine, where they threw or ran out of memory.
- Fix a directive whose CommonMark spelling would be that long: `losslessMarkdownToAdf` refuses it
as `unsupported-node-shape`, where a few megabytes of nested list lines ran it out of memory. The
markdown readers return `unsupported-node-shape` where they threw past the longest string or
array the JavaScript engine builds.
- Fix a directive that, written out as plain CommonMark, would be that long: `losslessMarkdownToAdf`
refuses it as `unsupported-node-shape`, where a few megabytes of nested list lines ran it out of
memory. The markdown readers return `unsupported-node-shape` where they threw past the longest
string or array the JavaScript engine builds.
- Fix deeply nested compact JSON in an `adf:` fence: `losslessMarkdownToAdf` refuses it as
`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
+7 -7
View File
@@ -409,10 +409,10 @@ typed on `ConvertError` takes both.
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 on one engine — there is no I/O anywhere — so a
retry returns the identical error: fix the input, or set the document aside. Only the refusal naming
the longest string or array this JavaScript engine builds differs between engines; on
JavaScriptCore (Bun, Safari), retry it once, since that engine reports a heap running short the
same way.
retry returns the identical error: fix the input, or set the document aside. Only a refusal past
the engine's own limits differs between engines: on JavaScriptCore (Bun, Safari), retry once a
writer's `unsupported-node-shape` at the empty path, since that engine reports a heap running short
the same way.
### Parsing
@@ -445,7 +445,7 @@ The emitter raises these, and so does a parse, which asks the emitter how to spe
| 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-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, or writes as a directive a node whose CommonMark spelling would be longer than 536,870,888 characters. 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 536,870,888 characters, V8's longest string, on every engine; in `adfToPortableMarkdown`, also a document whose text alone is that long, edge whitespace included. In every call: a conversion that passes the longest string or array the JavaScript engine builds | 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 536,870,888 characters or the engine's limit, set the document aside: keep the ADF and pass it 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, or writes as a directive a node that, written out as plain CommonMark, would be longer than 536870888 characters. 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 536870888 characters, V8's longest string, on every engine; in `adfToPortableMarkdown`, also a document whose text alone is that long, edge whitespace included. In every call: a conversion that passes the longest string or array the JavaScript engine builds | 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 536870888 characters or the engine's limit, writing: set the document aside, keeping the ADF and passing it over or showing it read-only; reading: shorten the markdown, or nest its lists and quotes less deeply |
## The guarantees
@@ -458,8 +458,8 @@ Serves [Goals](#goals) 1, 4 and 5.
([Unknown nodes ride the carry](https://github.com/larvit/adf-codec/blob/main/docs/decisions.md#unknown-nodes-ride-the-carry)).
- Markdown this library reads, and markdown it writes, means what the CommonMark spec says. The
bullets below name every exception.
- CommonMark is valid input to `commonMarkToAdf`, apart from the raw HTML `unmappable-html` names
and nesting past 500 levels.
- CommonMark is valid input to `commonMarkToAdf`, apart from the raw HTML `unmappable-html` names,
nesting past 500 levels, and input past what the JavaScript engine holds.
- The other readers claim shapes CommonMark reads as text or code. `losslessMarkdownToAdf` claims
four: literal text matching directive, pipe-table or strikethrough syntax, and a code fence whose
info string opens `adf:`. `portableMarkdownToAdf` claims what [Portable
+1 -1
View File
@@ -44,7 +44,7 @@ test('refuses a value that is not an ADF document, naming the check it failed',
assert.equal(markdown(adfToLosslessMarkdown({ type: 'doc', version: Number.NaN })), 'not-an-adf-document: an ADF document holds a version number: found NaN')
})
const tooLong = 'unsupported-node-shape: spelled as markdown, this would be longer than 536870888 characters, the longest string V8 holds'
const tooLong = 'unsupported-node-shape: spelled as markdown, this would be longer than 536870888 characters, the longest markdown this library writes'
// A code block of 300 lines; two of these together fall some 1000 characters short of V8's longest string, so only what their spelling adds passes it.
function nearlyHalfTheBound(): AdfNode {
+2 -3
View File
@@ -8,14 +8,13 @@ const pastLongestString = ['InternalError: allocation size overflow', 'RangeErro
const pastEngineLimit = ['RangeError: Invalid array length', 'RangeError: Out of memory']
export function tooLong<T>(): Result<T> {
return failure('unsupported-node-shape', `spelled as markdown, this would be longer than ${longestMarkdown} characters, the longest string V8 holds`, [])
return failure('unsupported-node-shape', `spelled as markdown, this would be longer than ${longestMarkdown} characters, the longest markdown this library writes`, [])
}
export function withinLongest(text: string): Result<string> {
return text.length > longestMarkdown ? tooLong() : success(text)
}
// Joins the pieces as they come, so a spelling that grows far past its input stops at the bound unbuilt.
export function joinedWithin(pieces: Iterable<string>): Result<string> {
const kept: string[] = []
let length = 0
@@ -27,7 +26,7 @@ export function joinedWithin(pieces: Iterable<string>): Result<string> {
return success(kept.join(''))
}
// Any concatenation can pass an engine's longest string or array, so this wraps a whole conversion.
// Any concatenation can pass an engine's longest string or array; wrap every call that builds one.
export function withinEngineLimits<T>(convert: () => Result<T>): Result<T> {
try {
return convert()
@@ -138,21 +138,13 @@ function portableSequence(blocks: readonly Sourced[], reduction: Reduction): Res
continue
}
// Back on `pending`: a replacement may take the directive form itself.
const replacement = block === next.block ? listItemBlocks(block, next.path) : [{ block, path: next.path }]
const { path } = next
const replacement = (block === next.block ? nodeContent(block).flatMap(nodeContent) : [block]).map((node) => ({ block: node, path }))
for (const node of replacement.reverse()) pending.push(node)
}
return success(sequence)
}
// Offsets are the reduced item's, which are the caller's while the item's blocks reduce one to one.
function listItemBlocks(list: AdfNode, path: ConvertErrorPath): Sourced[] {
const blocks: Sourced[] = []
for (const [index, item] of nodeContent(list).entries()) {
for (const [offset, block] of nodeContent(item).entries()) blocks.push({ block, path: [...path, 'content', index, 'content', offset] })
}
return blocks
}
// A numbered list whose markers run past CommonMark's keeps its numbers as text in a bullet list.
function numberedPastMarkers(list: AdfNode): AdfNode {
const order = nodeAttrs(list)['order']