mirror of
https://github.com/larvit/adf-codec.git
synced 2026-11-21 15:42:58 +01:00
Answer prose round 1: 0 🔴, 6 🟡; list unsupported-node-shape causes as sub-items with their remedies
This commit is contained in:
@@ -452,31 +452,33 @@ Every call can raise these:
|
|||||||
| --- | --- | --- |
|
| --- | --- | --- |
|
||||||
| `engine-limit` | in every call: a conversion that passes the longest array, `Map` or `Set` the JavaScript engine builds, or that the engine reports as out of memory; on JavaScriptCore (Bun, Safari), also one that passes its longest string, 2^31 − 1 characters | retry once; if it repeats, 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 |
|
| `engine-limit` | in every call: a conversion that passes the longest array, `Map` or `Set` the JavaScript engine builds, or that the engine reports as out of memory; on JavaScriptCore (Bun, Safari), also one that passes its longest string, 2^31 − 1 characters | retry once; if it repeats, 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 |
|
||||||
| `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` | a node the call cannot read or write in its shape; the list below names each cause | the list below names each cause's remedy |
|
| `unsupported-node-shape` | each cause listed below the table | the remedy beside each cause below |
|
||||||
|
|
||||||
`unsupported-node-shape` fires on these causes:
|
- **Reading, in `losslessMarkdownToAdf`.** Fix what the message names;
|
||||||
|
|
||||||
- **Reading, in `losslessMarkdownToAdf`**: markdown spells a node with an attribute, value,
|
|
||||||
argument or body its type does not take, or without one it needs, puts a line ending or a null
|
|
||||||
character in an `emoji`, `mention` or `status` content slot, 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. Fix what the message names;
|
|
||||||
[`spec/flavour.md`](https://github.com/larvit/adf-codec/blob/main/spec/flavour.md) lists every
|
[`spec/flavour.md`](https://github.com/larvit/adf-codec/blob/main/spec/flavour.md) lists every
|
||||||
type's attributes and body. For a line ending in a content slot, replace it with a space or write
|
type's attributes and body. The markdown:
|
||||||
the node as `!adf:carry`; for a null character there, write the node as `!adf:carry`.
|
- spells a node with an attribute, value, argument or body its type does not take, or without
|
||||||
|
one it needs;
|
||||||
|
- puts a line ending or a null character in an `emoji`, `mention` or `status` content slot:
|
||||||
|
replace a line ending with a space, or, for either, write the node as `!adf:carry`;
|
||||||
|
- wraps a directive mark around nothing or only hard breaks;
|
||||||
|
- writes as a directive a node or mark the lossless flavour spells as CommonMark;
|
||||||
|
- puts `!adf:textBreak{}` where it parts nothing, or `!adf:doc` anywhere but as the whole
|
||||||
|
document.
|
||||||
- **Writing, in `adfToLosslessMarkdown`**: a node not riding the carry that carries one mark type
|
- **Writing, 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
|
twice, a block or a non-text inline node holding `text`, or a leaf block or a non-text inline node
|
||||||
holding `content`. Fix what the message names in the ADF.
|
holding `content`. Keep the ADF and show the document read-only; where you built the ADF, fix
|
||||||
|
what the message names.
|
||||||
- **Writing, in `adfToPortableMarkdown`**: a line or task list the portable writer cannot spell.
|
- **Writing, in `adfToPortableMarkdown`**: a line or task list the portable writer cannot spell.
|
||||||
This is a bug in this library: report it.
|
This is a bug in this library: report it.
|
||||||
- **Past the longest string**: in both writers, a document whose markdown would be longer than
|
- **Past the engine's longest string**:
|
||||||
536870888 characters, V8's longest string, on every engine, and in `adfToPortableMarkdown` also a
|
- a writer's markdown would pass 536870888 characters, V8's longest string, on every engine;
|
||||||
document whose text alone is that long, edge whitespace included; in `losslessMarkdownToAdf`, a
|
- in `adfToPortableMarkdown`, the document's text alone would, edge whitespace included;
|
||||||
directive whose plain CommonMark would be that long; in every call, a conversion that passes V8's
|
- in `losslessMarkdownToAdf`, a directive's plain CommonMark would;
|
||||||
or SpiderMonkey's longest string. Writing, set the document aside, keeping the ADF and passing it
|
- in every call, a conversion passes V8's or SpiderMonkey's longest string.
|
||||||
over or showing it read-only; reading, shorten the markdown, or nest its lists and quotes less
|
|
||||||
deeply.
|
When writing, set the document aside: keep the ADF, and pass it over or show it read-only. When
|
||||||
|
reading, shorten the markdown, or nest its lists and quotes less deeply.
|
||||||
|
|
||||||
## The guarantees
|
## The guarantees
|
||||||
|
|
||||||
@@ -518,9 +520,9 @@ Serves [Goals](#goals) 1, 4 and 5.
|
|||||||
the outer brackets literal text, which the spec requires and the reference itself breaks, nesting
|
the outer brackets literal text, which the spec requires and the reference itself breaks, nesting
|
||||||
one `<a>` in the other.
|
one `<a>` in the other.
|
||||||
- Not every document converts back: `adfToLosslessMarkdown` refuses a document nesting past 500
|
- Not every document converts back: `adfToLosslessMarkdown` refuses a document nesting past 500
|
||||||
levels, the causes `unsupported-node-shape` lists, and a conversion `engine-limit`
|
levels, a document meeting a writing or longest-string cause `unsupported-node-shape` lists, and
|
||||||
stops. Show the refusal and keep the document read-only; saving markdown you could not produce is the loss the round-trip exists to
|
a conversion `engine-limit` stops. Show the refusal and keep the document read-only; saving
|
||||||
stop.
|
markdown you could not produce is the loss the round-trip exists to stop.
|
||||||
- Both readers narrow GFM's pipe table. A body row whose cell count differs from the header's is
|
- Both readers narrow GFM's pipe table. A body row whose cell count differs from the header's is
|
||||||
an error result, where GFM pads or cuts it. A line holding no `|` ends the table, where GFM reads
|
an error result, where GFM pads or cuts it. A line holding no `|` ends the table, where GFM reads
|
||||||
it as a row.
|
it as a row.
|
||||||
|
|||||||
@@ -134,7 +134,7 @@ function readNamedMark(type: string, text: string, index: number, path: ConvertE
|
|||||||
const vocabulary = markVocabularies.get(name)
|
const vocabulary = markVocabularies.get(name)
|
||||||
if (vocabulary === undefined) return failure('unsupported-node-shape', `the ${marksAttribute} attribute of ${type} names ${name}, no mark the flavour lists: write the marks as their JSON array, marks="[{\\"type\\":\\"${name}\\"}]"`, path)
|
if (vocabulary === undefined) return failure('unsupported-node-shape', `the ${marksAttribute} attribute of ${type} names ${name}, no mark the flavour lists: write the marks as their JSON array, marks="[{\\"type\\":\\"${name}\\"}]"`, path)
|
||||||
const start = index + name.length
|
const start = index + name.length
|
||||||
// A quoted value holds no directive, so a malformed pair takes no escape hint.
|
// These {attrs} sit inside the quoted marks value, where no directive opens, so a malformed pair takes no escape hint.
|
||||||
const attributes = text.charAt(start) === '{' ? readAttributes(text, start, attributePairCause) : { value: { attributes: new Map<string, DirectiveValue>(), end: start } }
|
const attributes = text.charAt(start) === '{' ? readAttributes(text, start, attributePairCause) : { value: { attributes: new Map<string, DirectiveValue>(), end: start } }
|
||||||
if (attributes.fault !== undefined) {
|
if (attributes.fault !== undefined) {
|
||||||
return failure('unsupported-node-shape', `the ${name} mark in the ${marksAttribute} attribute of ${type}: ${attributes.fault.message}`, path)
|
return failure('unsupported-node-shape', `the ${name} mark in the ${marksAttribute} attribute of ${type}: ${attributes.fault.message}`, path)
|
||||||
|
|||||||
@@ -227,7 +227,7 @@ document's whole tree. Give the node's path, and name its type and the attribute
|
|||||||
`emitLeaf` (`emit/inline-line.ts`) and `emitDirectiveBlock` (`emit/adf-to-markdown.ts`)
|
`emitLeaf` (`emit/inline-line.ts`) and `emitDirectiveBlock` (`emit/adf-to-markdown.ts`)
|
||||||
refuse these with `unsupported-node-shape`, though `isAdfDocument` accepts them and the carry
|
refuse these with `unsupported-node-shape`, though `isAdfDocument` accepts them and the carry
|
||||||
round-trips them; `docs/decisions.md` §The code list gives a cause the carry answers no code. Drop
|
round-trips them; `docs/decisions.md` §The code list gives a cause the carry answers no code. Drop
|
||||||
them from the emitting half of the README's `unsupported-node-shape` row. Found by the README-goals
|
them from the README's `unsupported-node-shape` cause "Writing, in `adfToLosslessMarkdown`". Found by the README-goals
|
||||||
audit, 2026-10-04.
|
audit, 2026-10-04.
|
||||||
|
|
||||||
### 75. Make the generated-markdown property write block carries as `adf:` fences, canonical and hostile.
|
### 75. Make the generated-markdown property write block carries as `adf:` fences, canonical and hostile.
|
||||||
|
|||||||
Reference in New Issue
Block a user