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;