diff --git a/CHANGELOG.md b/CHANGELOG.md index 301010f..9bcd077 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,12 +2,6 @@ ## 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` 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 @@ -58,11 +52,18 @@ `losslessMarkdownToAdf` refuses a directive mark wrapping only hard breaks as `unsupported-node-shape`. `adfToLosslessMarkdown` writes a hard break holding marks as `!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 - `*`, `_`, `~` or backticks, or a heading ending in a long run of `#`: it is linear in the run, and - a run of 20000 `*` takes milliseconds where it took seconds. -- Fix the round-trip: `losslessMarkdownToAdf(adfToLosslessMarkdown(doc))` deep-equals `doc` as - `JSON.parse` builds it: two adjacent text nodes CommonMark would read back as one are parted by + `*`, `_`, `~` or backticks, or a heading ending in a long run of `#`: the time is linear in the + run, and a run of 20000 `*` takes milliseconds where it took seconds. +- 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 `!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 nodes is a fence per node. A `codeBlock` holding other than plain text nodes rides the block diff --git a/README.md b/README.md index 850c255..dafa6fa 100644 --- a/README.md +++ b/README.md @@ -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`). - A document any reader built, written back with `adfToLosslessMarkdown`, takes the library's canonical spelling, which round-trips byte-identically. -- These CommonMark spellings parse without an error and build a document the reference - implementation renders differently, where ADF holds no node for what it renders: +- These CommonMark spellings parse without an error but build a document the reference + 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 `[]()` 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 @@ -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 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 - unresolved, and a link whose text holds an autolink keeps the inner link and leaves the outer - brackets literal text, which the spec requires and the reference itself breaks, nesting one `` - in the other. `corpus/commonmark-spec/exceptions.json` pins the spellings ADF holds no node for - `node-model` where the suite reaches them, and the case-folded reference `pending`; the suite - holds no example of a link holding an autolink. + And these, for other reasons: a shortcut reference matching its definition only under Unicode case + folding stays unresolved, and a link whose text holds an autolink keeps the inner link and leaves + the outer brackets literal text, which the spec requires and the reference itself breaks, nesting + one `` in the other. `corpus/commonmark-spec/exceptions.json` marks each spelling ADF holds no + node for as `node-model` where the suite has an example of it, and the case-folded reference as + `pending`; the suite holds no example of a link holding an autolink. - 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 document read-only; saving markdown you could not produce is the loss the round-trip exists to diff --git a/src/markdown/parse/blocks.ts b/src/markdown/parse/blocks.ts index c98a35d..f9adcea 100644 --- a/src/markdown/parse/blocks.ts +++ b/src/markdown/parse/blocks.ts @@ -248,7 +248,7 @@ function openContainer(walk: Walk, start: ContainerStart): void { 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): ListBlock { if (!start.fresh) return start.list const blocks = currentBlocks(walk) @@ -258,7 +258,7 @@ function openedList(walk: Walk, start: Extract 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 { const previous = currentBlocks(walk).at(-1) if (isList(previous)) walk.endedLists.add(previous) diff --git a/src/markdown/parse/markdown-to-adf.test.ts b/src/markdown/parse/markdown-to-adf.test.ts index d05852d..22d337b 100644 --- a/src/markdown/parse/markdown-to-adf.test.ts +++ b/src/markdown/parse/markdown-to-adf.test.ts @@ -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.')]) }) -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]) { 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')))]) diff --git a/todo.md b/todo.md index 2579703..f4f2161 100644 --- a/todo.md +++ b/todo.md @@ -150,8 +150,9 @@ three linear. 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 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 -fix. +§Cost fixes are measured, never timed says the 500-level guard bounds `continuesContainer`'s +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. @@ -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. -Technical principle "One owner per value": the `Walk` record passes through twelve functions that -mutate it and return `void`; `walk.leaf` alone is written in seven places, and `openedList` reads -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 +Technical principle "One owner per value": the `Walk` record passes through functions that mutate it +and return `void`; `walk.leaf` alone is written in seven places, and `openedList` reads 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 functions write `pending`, `pieces`, `deactivatedBefore` and `openingSpellableLink` and return `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;