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 comments and test name say what ends a list, the README says because, the changelog leads with the rename and gives the definition's trigger, and items 56 and 98 state their claims plainly

This commit is contained in:
2026-10-10 11:21:18 +02:00
committed by Lillem4n
parent 419bb10324
commit cea9137495
5 changed files with 28 additions and 27 deletions
+11 -10
View File
@@ -2,12 +2,6 @@
## Unreleased ## Unreleased
- **Breaking:** a list whose bullet character or ordered delimiter changes reads as two lists, as
CommonMark reads it: `- a` then `* b`, `1. a` then `1) b`. `adfToLosslessMarkdown` gives a list
right after one of its kind the other marker, `* ` or `1)`, in place of the `::listBreak`
separator. Convert stored markdown per `MIGRATION.md`.
- **Breaking:** a link reference definition between two list items ends the list, as CommonMark
reads it: `- a`, `[r]: /u`, `- b` read as two lists, where `0.1.0` read one; see `MIGRATION.md`.
- **Breaking:** each call names the markdown it reads or writes. `adfToMarkdown` and `markdownToAdf` - **Breaking:** each call names the markdown it reads or writes. `adfToMarkdown` and `markdownToAdf`
are now `adfToLosslessMarkdown` and `losslessMarkdownToAdf`. A bot's or a model's markdown reads are now `adfToLosslessMarkdown` and `losslessMarkdownToAdf`. A bot's or a model's markdown reads
in `portableMarkdownToAdf`, and markdown known to be strict CommonMark in the new in `portableMarkdownToAdf`, and markdown known to be strict CommonMark in the new
@@ -58,11 +52,18 @@
`losslessMarkdownToAdf` refuses a directive mark wrapping only hard breaks as `losslessMarkdownToAdf` refuses a directive mark wrapping only hard breaks as
`unsupported-node-shape`. `adfToLosslessMarkdown` writes a hard break holding marks as `unsupported-node-shape`. `adfToLosslessMarkdown` writes a hard break holding marks as
`!adf:carry{json="…"}`. See `MIGRATION.md`. `!adf:carry{json="…"}`. See `MIGRATION.md`.
- **Breaking:** a list whose bullet character or ordered delimiter changes reads as two lists, as
CommonMark reads it: `- a` then `* b`, `1. a` then `1) b`. `adfToLosslessMarkdown` gives a list
right after one of its kind the other marker, `* ` or `1)`, in place of the `::listBreak`
separator. Convert stored markdown per `MIGRATION.md`.
- **Breaking:** a link reference definition between two list items, after a blank line and at the
list's own indentation, ends the list, as CommonMark reads it; `0.1.0` read one list. See
`MIGRATION.md`.
- Fix the time `adfToLosslessMarkdown` and `adfToPortableMarkdown` take on text holding a long run of - Fix the time `adfToLosslessMarkdown` and `adfToPortableMarkdown` take on text holding a long run of
`*`, `_`, `~` or backticks, or a heading ending in a long run of `#`: it is linear in the run, and `*`, `_`, `~` or backticks, or a heading ending in a long run of `#`: the time is linear in the
a run of 20000 `*` takes milliseconds where it took seconds. run, and a run of 20000 `*` takes milliseconds where it took seconds.
- Fix the round-trip: `losslessMarkdownToAdf(adfToLosslessMarkdown(doc))` deep-equals `doc` as - Fix the round-trip, so `losslessMarkdownToAdf(adfToLosslessMarkdown(doc))` deep-equals `doc` as
`JSON.parse` builds it: two adjacent text nodes CommonMark would read back as one are parted by `JSON.parse` builds it. Two adjacent text nodes CommonMark would read back as one are parted by
`!adf:textBreak{}`, an empty `attrs`, `content` or `marks` is spelled `{attrs=empty}`, `!adf:textBreak{}`, an empty `attrs`, `content` or `marks` is spelled `{attrs=empty}`,
`{content=empty}` or `{marks=empty}`, `-0` is spelled `-0`, and a `codeBlock` of several text `{content=empty}` or `{marks=empty}`, `-0` is spelled `-0`, and a `codeBlock` of several text
nodes is a fence per node. A `codeBlock` holding other than plain text nodes rides the block nodes is a fence per node. A `codeBlock` holding other than plain text nodes rides the block
+8 -8
View File
@@ -239,8 +239,8 @@ Serves Goals 1, 4 and 5.
without a delimiter row, is an error result; each can be kept literal (`spec/flavour.md`). without a delimiter row, is an error result; each can be kept literal (`spec/flavour.md`).
- A document any reader built, written back with `adfToLosslessMarkdown`, takes the library's - A document any reader built, written back with `adfToLosslessMarkdown`, takes the library's
canonical spelling, which round-trips byte-identically. canonical spelling, which round-trips byte-identically.
- These CommonMark spellings parse without an error and build a document the reference - These CommonMark spellings parse without an error but build a document the reference
implementation renders differently, where ADF holds no node for what it renders: implementation renders differently, because ADF holds no node for what the reference renders:
- An empty link text reads as its destination, `[](/url)` as `/url` linked to `/url`, and `[]()` - An empty link text reads as its destination, `[](/url)` as `/url` linked to `/url`, and `[]()`
as nothing. A link text holding only hard breaks reads the same, followed by its hard breaks. as nothing. A link text holding only hard breaks reads the same, followed by its hard breaks.
- An image reads as an image only alone in its paragraph. Anywhere else — beside other text, in - An image reads as an image only alone in its paragraph. Anywhere else — beside other text, in
@@ -253,12 +253,12 @@ Serves Goals 1, 4 and 5.
- An image's title becomes its caption when the image stays an image, and its link's title when - An image's title becomes its caption when the image stays an image, and its link's title when
it becomes linked alt text. Inside another link, the title is dropped. it becomes linked alt text. Inside another link, the title is dropped.
And these, for other reasons: a shortcut reference matching its definition only under Unicode case folding stays And these, for other reasons: a shortcut reference matching its definition only under Unicode case
unresolved, and a link whose text holds an autolink keeps the inner link and leaves the outer folding stays unresolved, and a link whose text holds an autolink keeps the inner link and leaves
brackets literal text, which the spec requires and the reference itself breaks, nesting one `<a>` the outer brackets literal text, which the spec requires and the reference itself breaks, nesting
in the other. `corpus/commonmark-spec/exceptions.json` pins the spellings ADF holds no node for one `<a>` in the other. `corpus/commonmark-spec/exceptions.json` marks each spelling ADF holds no
`node-model` where the suite reaches them, and the case-folded reference `pending`; the suite node for as `node-model` where the suite has an example of it, and the case-folded reference as
holds no example of a link holding an autolink. `pending`; the suite holds no example of a link holding an autolink.
- 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, and the node shapes the `unsupported-node-shape` row lists. Show the refusal and keep the levels, and the node shapes the `unsupported-node-shape` row lists. Show the refusal and keep the
document read-only; saving markdown you could not produce is the loss the round-trip exists to document read-only; saving markdown you could not produce is the loss the round-trip exists to
+2 -2
View File
@@ -248,7 +248,7 @@ function openContainer(walk: Walk, start: ContainerStart): void {
walk.stack.push({ blocks, indentation: start.indentation, kind: 'item', list }) walk.stack.push({ blocks, indentation: start.indentation, kind: 'item', list })
} }
// An item opening after its list's last item closed, as an empty item a blank line ends does, continues that list. // An empty item closes at the blank line after it, yet the next item continues its list unless endList ended it.
function openedList(walk: Walk, start: Extract<ContainerStart, { kind: 'item' }>): ListBlock { function openedList(walk: Walk, start: Extract<ContainerStart, { kind: 'item' }>): ListBlock {
if (!start.fresh) return start.list if (!start.fresh) return start.list
const blocks = currentBlocks(walk) const blocks = currentBlocks(walk)
@@ -258,7 +258,7 @@ function openedList(walk: Walk, start: Extract<ContainerStart, { kind: 'item' }>
return start.list return start.list
} }
// A paragraph of link reference definitions alone leaves no block, yet ends the list before it as any block does. // A paragraph holding only link reference definitions leaves no block, yet ends the list before it as any block does.
function endList(walk: Walk): void { function endList(walk: Walk): void {
const previous = currentBlocks(walk).at(-1) const previous = currentBlocks(walk).at(-1)
if (isList(previous)) walk.endedLists.add(previous) if (isList(previous)) walk.endedLists.add(previous)
+1 -1
View File
@@ -676,7 +676,7 @@ test('reads a bullet list, the marker width setting the continuation', () => {
assert.deepEqual(content(losslessMarkdownToAdf('-\n\n Part.\n')), [bulletList(item()), paragraph('Part.')]) assert.deepEqual(content(losslessMarkdownToAdf('-\n\n Part.\n')), [bulletList(item()), paragraph('Part.')])
}) })
test('reads two lists a link reference definition parts as two lists, in every reader', () => { test('ends a list at a link reference definition, in every reader', () => {
for (const read of [commonMarkToAdf, losslessMarkdownToAdf, portableMarkdownToAdf]) { for (const read of [commonMarkToAdf, losslessMarkdownToAdf, portableMarkdownToAdf]) {
assert.deepEqual(content(read('- a\n\n[r]: /u\n\n- b\n')), [bulletList(item(paragraph('a'))), bulletList(item(paragraph('b')))]) assert.deepEqual(content(read('- a\n\n[r]: /u\n\n- b\n')), [bulletList(item(paragraph('a'))), bulletList(item(paragraph('b')))])
assert.deepEqual(content(read('- a\n\n[r]: /u\n- b\n')), [bulletList(item(paragraph('a'))), bulletList(item(paragraph('b')))]) assert.deepEqual(content(read('- a\n\n[r]: /u\n- b\n')), [bulletList(item(paragraph('a'))), bulletList(item(paragraph('b')))])
+6 -6
View File
@@ -150,8 +150,9 @@ three linear.
each blank line, and `parseBlocks` holds no depth guard: `readBlocks` refuses past 500 levels only each blank line, and `parseBlocks` holds no depth guard: `readBlocks` refuses past 500 levels only
after the walk. `'- '.repeat(n) + 'a\n' + '\n'.repeat(n)` took 675 ms at n = 5000, 2.7 s at 10000 after the walk. `'- '.repeat(n) + 'a\n' + '\n'.repeat(n)` took 675 ms at n = 5000, 2.7 s at 10000
and 10.7 s at 20000 (60 kB) before refusing as `unsupported-nesting-depth`. `docs/decisions.md` and 10.7 s at 20000 (60 kB) before refusing as `unsupported-nesting-depth`. `docs/decisions.md`
§Cost fixes are measured, never timed calls the re-scan bounded by that guard; correct it with the §Cost fixes are measured, never timed says the 500-level guard bounds `continuesContainer`'s
fix. re-scan in depth; the guard runs only after the walk, so it bounds nothing. Correct that entry with
the fix.
### 7. Ship HTML: `adfToHtml`, `htmlToAdf`, and markdown to and from HTML composed through ADF, each call named by its flavour. ### 7. Ship HTML: `adfToHtml`, `htmlToAdf`, and markdown to and from HTML composed through ADF, each call named by its flavour.
@@ -353,10 +354,9 @@ quadratic in a run of blanks inside one leaf: a paragraph of `a`, 80 000 spaces,
### 56. Give each piece of `blocks.ts`'s block-walk state and `inline-content.ts`'s `Scan` one owner that returns what it changes. ### 56. Give each piece of `blocks.ts`'s block-walk state and `inline-content.ts`'s `Scan` one owner that returns what it changes.
Technical principle "One owner per value": the `Walk` record passes through twelve functions that Technical principle "One owner per value": the `Walk` record passes through functions that mutate it
mutate it and return `void`; `walk.leaf` alone is written in seven places, and `openedList` reads and return `void`; `walk.leaf` alone is written in seven places, and `openedList` reads the
the `endedLists` that `closeLeaf` fills. `ContainerStack` in the `endedLists` that `closeLeaf` fills. `ContainerStack` in the same file shows the shape to follow. `inline-content.ts`'s `Scan` has the same shape: about fifteen
same file shows the shape to follow. `inline-content.ts`'s `Scan` has the same shape: about fifteen
functions write `pending`, `pieces`, `deactivatedBefore` and `openingSpellableLink` and return functions write `pending`, `pieces`, `deactivatedBefore` and `openingSpellableLink` and return
`void`, and `parseInlineContent` reads a flag `scanInline` leaves on it. The same shape recurs in `void`, and `parseInlineContent` reads a flag `scanInline` leaves on it. The same shape recurs in
`mintTaskIds` (`portable/task-ids.ts`), which writes `attrs` on the document `readDocument` built; `mintTaskIds` (`portable/task-ids.ts`), which writes `attrs` on the document `readDocument` built;