3
0
mirror of https://github.com/larvit/adf-codec.git synced 2026-11-18 22:25:44 +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
- **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
+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`).
- 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 `<a>`
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 `<a>` 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
+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 })
}
// 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 {
if (!start.fresh) return start.list
const blocks = currentBlocks(walk)
@@ -258,7 +258,7 @@ function openedList(walk: Walk, start: Extract<ContainerStart, { kind: 'item' }>
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)
+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.')])
})
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')))])
+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
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;