From deb639d004f0574bd91b6371265f68772ba1247d Mon Sep 17 00:00:00 2001 From: Lilleman auf Larv Date: Sun, 4 Oct 2026 11:48:47 +0200 Subject: [PATCH 1/4] Record the maintainer's answers for items 49, 50, 55 and 65 --- docs/decisions.md | 2 +- todo.md | 52 ++++++++++++++++++++++++----------------------- 2 files changed, 28 insertions(+), 26 deletions(-) diff --git a/docs/decisions.md b/docs/decisions.md index 2c11f61..540dc4b 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -496,7 +496,7 @@ exits 0 on. while `todo.md` items 59, 60, 61 and 62 are open. A four-seat comprehension panel scored the project under the floor of 7. Its round-5 scores -(2026-10-03) are the baseline: a later panel may not score lower on any dimension. +(2026-10-03) are the score the next chunk starts from. | Seat | Navigation | Locality | Shape | Self-sufficiency | Overall | |---|---|---|---|---|---| diff --git a/todo.md b/todo.md index f4d656c..d00b0db 100644 --- a/todo.md +++ b/todo.md @@ -26,13 +26,13 @@ |---|---|---|---|---|---|---|---|---|---| | 63 | 0.2.0 | defect | **Refuse a cyclic input as `not-an-adf-document`.** | 2 | 2 | 6 | 9 | 1 | 27.5 | | 7 | 0.2.0 | | **Ship HTML: `adfToHtml`, `htmlToAdf`, and `markdownToHtml` / `htmlToMarkdown` composed through ADF.** | 6 | 9 | 9 | 9 | 2, 3 | 25.8 | -| 55 | 0.2.0 | defect | **Spell through the carry every document the emitter refuses today for a carriage return, a NUL, a code-span line start, a newline inside an emoji, mention or status, or a text node whose text is empty or missing, or which holds content.** | 5 | 5 | 7 | 9 | 1 | 25.8 | +| 55 | 0.2.0 | defect | **Spell every document the emitter refuses today for a carriage return, a NUL, a code-span line start, a newline inside an emoji, mention or status, or a text node whose text is empty or missing, or which holds content.** | 5 | 5 | 7 | 9 | 1 | 25.8 | | 45 | 0.2.0 | | **Replace `isAdfDocument` with a reader returning `Result`.** | 2 | 3 | 6 | 8 | 1 | 25.2 | | 6 | 0.2.0 | decision | **Specify the HTML dialect.** | 2 | 6 | 7 | 8 | 2, 3 | 24.7 | | 64 | 0.2.0 | defect | **Read back unchanged on V8 every JSON key the emitter writes, with a fixture whose key holds `\`, `"` or a control character.** | 4 | 4 | 6 | 8 | 1, 7 | 23.0 | | 43 | 0.2.0 | decision | **Give each markdown input its own reader, strict to its own standard.** | 6 | 7 | 8 | 9 | 3, 4 | 22.3 | -| 65 | 0.2.0 | defect | **Read a mid-text or titled CommonMark image as Goal 6 allows.** | 5 | 5 | 7 | 7 | 3, 4, 6 | 18.7 | -| 49 | 0.2.0 | | **Read a list whose bullet or ordered delimiter changes as two lists in the CommonMark reader.** | 4 | 5 | 5 | 8 | 3, 4 | 17.2 | +| 65 | 0.2.0 | defect | **Read a mid-text CommonMark image as a link to it, and a titled one on its own line as an image captioned with its title.** | 5 | 5 | 7 | 7 | 3, 4, 6 | 18.7 | +| 49 | 0.2.0 | | **Read a list whose bullet or ordered delimiter changes as two lists, in both readers, and retire `!adf:listBreak`.** | 4 | 5 | 5 | 8 | 3, 4 | 17.2 | | 61 | 0.2.0 | decision | **Have the emitter ask the inline reader how a line reads back, in place of `line-escaping.ts` predicting it.** | 6 | 8 | 3 | 8 | 1 | 14.0 | | 52 | 0.2.0 | | **Spell `colwidth` as a comma list, `colwidth="340,420"`.** | 3 | 3 | 5 | 6 | 5 | 13.0 | | 51 | 0.2.0 | | **Match a reference label to its definition under Unicode case folding.** | 2 | 2 | 2 | 7 | 3, 4 | 12.4 | @@ -70,16 +70,17 @@ Lands after items 6, 59, 60, 61 and 62. The CommonMark spec suite also runs agai `markdownToHtml`. The README documents HTML as it documents markdown, and its tagline and `package.json`'s `description` regain HTML. -### 55. Spell through the carry every document the emitter refuses today for a carriage return, a NUL, a code-span line start, a newline inside an emoji, mention or status, or a text node whose text is empty or missing, or which holds content. +### 55. Spell every document the emitter refuses today for a carriage return, a NUL, a code-span line start, a newline inside an emoji, mention or status, or a text node whose text is empty or missing, or which holds content. +The maintainer approved on 2026-10-04 revising §Which code a cause takes and §Markdown in is a +canonical fixpoint so these convert, and retiring every code nothing then raises. Today `inline-line.ts` refuses a carriage return or NUL in text (`unspellable-character`) and a paragraph opening with a code-span run (`unspellable-line-start`); `fencedTexts` refuses the same characters in a code block; `directive-syntax.ts` refuses a newline in an emoji, mention or status -(`unspellable-whitespace`). The inline carry's JSON escapes all of them, so a lossless spelling -exists, and §The code list says a cause the carry answers gets no code. Fixing it revises §Which -code a cause takes and §Markdown in is a canonical fixpoint, which the maintainer decides. Also a -text node whose `text` is empty or missing, which `inline-line.ts` and `fencedTexts` refuse, or -which holds `content`, which `inline-line.ts` refuses. Found by the README-goals audit, 2026-10-03. +(`unspellable-whitespace`); `inline-line.ts` and `fencedTexts` refuse a text node whose `text` is +empty or missing, and `inline-line.ts` one holding `content`. The inline carry spells all of them; +a carriage return or NUL could ride `!adf:text{text="…"}` instead, which keeps the text readable — +a writer panel picks. Found by the README-goals audit, 2026-10-03. ### 45. Replace `isAdfDocument` with a reader returning `Result`. @@ -110,23 +111,24 @@ a code fence whose info string opens `adf:` becomes the block carry where Common caller names the markdown it hands in: CommonMark, read as its spec says, or the lossless flavour, read as `spec/flavour.md` says. Breaking: `MIGRATION.md` says which call a caller takes. -### 65. Read a mid-text or titled CommonMark image as Goal 6 allows. +### 65. Read a mid-text CommonMark image as a link to it, and a titled one on its own line as an image captioned with its title. -A mid-text or titled image, such as a bot's `See ![diagram](url) here`, is refused: 14 examples in -`corpus/commonmark-spec/refusals.json`. Settle what such an image builds. Goal 6 drops form and -keeps the target. +Both are refused today with `unmappable-image`: 14 examples in +`corpus/commonmark-spec/refusals.json`, and a bot's `See ![diagram](url) here` among them. ADF's +inline image takes only Atlassian media ids, so a mid-text image reads as its alt text linked to its +URL, its title the link's `title` and an empty alt text the URL itself (item 50). A titled image on +its own line reads as the image with its title as a `caption` (the maintainer, 2026-10-04). -### 49. Read a list whose bullet or ordered delimiter changes as two lists in the CommonMark reader. +### 49. Read a list whose bullet or ordered delimiter changes as two lists, in both readers, and retire `!adf:listBreak`. Lands after item 43. Today `- a` then `+ b`, or `1.` then `1)`, reads as one list; CommonMark reads -two (spec examples 301 and 302), and so must the CommonMark reader. `spec/flavour.md` merges them in -the lossless flavour on purpose and parts two adjacent lists with `!adf:listBreak`. The chunk -settles by Goals 3 and 4 whether the flavour follows, and asks where the Goals do not decide. That -answer also settles what `adfToMarkdown` and `adfToPlainMarkdown` write for two adjacent lists, and -whether `!adf:listBreak` still reads. Breaking, so it ships beside item 43: `MIGRATION.md`'s -Readings table gains its row, and its Spellings table one if `!adf:listBreak` retires. Examples 301 -and 302 lose their `pending` exceptions, and the spelling leaves the README's "Four CommonMark -spellings" bullet, which counts one fewer. +two (spec examples 301 and 302). Goal 4 settles it for the lossless flavour too: CommonMark spells +two adjacent lists by changing the marker, so `adfToMarkdown` and `adfToPlainMarkdown` write the +second of two adjacent bullet lists with `*` (the maintainer, 2026-10-04) and the second of two +ordered lists with `)`, and `!adf:listBreak` retires. Breaking, so it ships beside item 43: +`MIGRATION.md`'s Readings and Spellings tables gain their rows. Examples 301 and 302 lose their +`pending` exceptions, and the spelling leaves the README's "Four CommonMark spellings" bullet, which +counts one fewer. ### 61. Have the emitter ask the inline reader how a line reads back, in place of `line-escaping.ts` predicting it. @@ -167,9 +169,9 @@ mark spellings too, which item 7 moves where it learns what HTML shares. ### 50. Read `[](/url)` and `[]()` as CommonMark's empty link. Both stay literal text today (spec examples 484 and 487). ADF holds no empty text node to carry a -link mark, so the chunk settles what the empty link builds by Goals 3 and 6, and asks where they do -not decide; whatever it builds, both still parse, since a bot relies on plain CommonMark being valid -input. Breaking, so it ships beside item 43: `MIGRATION.md`'s Readings table gains its row. Its +link mark, so a link whose text is empty takes its URL as its text (the maintainer, 2026-10-04): +`[](/url)` reads as `/url` linked to `/url`. `[]()` has no URL to show; the chunk settles it by Goals +3 and 6. Breaking, so it ships beside item 43: `MIGRATION.md`'s Readings table gains its row. Its `pending` exceptions go, and its spelling leaves the README's "Four CommonMark spellings" bullet, which counts one fewer. -- 2.52.0 From 7217b75a1de96e2eaec17300d045ad14b7bc34eb Mon Sep 17 00:00:00 2001 From: Lilleman auf Larv Date: Sun, 4 Oct 2026 11:52:59 +0200 Subject: [PATCH 2/4] Answer the prose review's first round --- docs/decisions.md | 3 ++- todo.md | 46 ++++++++++++++++++++++++++-------------------- 2 files changed, 28 insertions(+), 21 deletions(-) diff --git a/docs/decisions.md b/docs/decisions.md index 540dc4b..94fb36c 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -496,7 +496,8 @@ exits 0 on. while `todo.md` items 59, 60, 61 and 62 are open. A four-seat comprehension panel scored the project under the floor of 7. Its round-5 scores -(2026-10-03) are the score the next chunk starts from. +(2026-10-03) are the baseline: a chunk whose panel scores any dimension lower improves what the +readers named and scores again, and after three such rounds asks the maintainer. | Seat | Navigation | Locality | Shape | Self-sufficiency | Overall | |---|---|---|---|---|---| diff --git a/todo.md b/todo.md index d00b0db..56501b8 100644 --- a/todo.md +++ b/todo.md @@ -31,7 +31,7 @@ | 6 | 0.2.0 | decision | **Specify the HTML dialect.** | 2 | 6 | 7 | 8 | 2, 3 | 24.7 | | 64 | 0.2.0 | defect | **Read back unchanged on V8 every JSON key the emitter writes, with a fixture whose key holds `\`, `"` or a control character.** | 4 | 4 | 6 | 8 | 1, 7 | 23.0 | | 43 | 0.2.0 | decision | **Give each markdown input its own reader, strict to its own standard.** | 6 | 7 | 8 | 9 | 3, 4 | 22.3 | -| 65 | 0.2.0 | defect | **Read a mid-text CommonMark image as a link to it, and a titled one on its own line as an image captioned with its title.** | 5 | 5 | 7 | 7 | 3, 4, 6 | 18.7 | +| 65 | 0.2.0 | defect | **Read an image not alone in its paragraph as its alt text linked to its URL, and a titled image alone in its paragraph as the image captioned with its title, in both readers.** | 5 | 5 | 7 | 7 | 3, 4, 6 | 18.7 | | 49 | 0.2.0 | | **Read a list whose bullet or ordered delimiter changes as two lists, in both readers, and retire `!adf:listBreak`.** | 4 | 5 | 5 | 8 | 3, 4 | 17.2 | | 61 | 0.2.0 | decision | **Have the emitter ask the inline reader how a line reads back, in place of `line-escaping.ts` predicting it.** | 6 | 8 | 3 | 8 | 1 | 14.0 | | 52 | 0.2.0 | | **Spell `colwidth` as a comma list, `colwidth="340,420"`.** | 3 | 3 | 5 | 6 | 5 | 13.0 | @@ -72,15 +72,19 @@ Lands after items 6, 59, 60, 61 and 62. The CommonMark spec suite also runs agai ### 55. Spell every document the emitter refuses today for a carriage return, a NUL, a code-span line start, a newline inside an emoji, mention or status, or a text node whose text is empty or missing, or which holds content. -The maintainer approved on 2026-10-04 revising §Which code a cause takes and §Markdown in is a -canonical fixpoint so these convert, and retiring every code nothing then raises. Today -`inline-line.ts` refuses a carriage return or NUL in text (`unspellable-character`) and a paragraph -opening with a code-span run (`unspellable-line-start`); `fencedTexts` refuses the same characters -in a code block; `directive-syntax.ts` refuses a newline in an emoji, mention or status +Today `inline-line.ts` refuses a carriage return or NUL in text (`unspellable-character`) and a +paragraph opening with a code-span run (`unspellable-line-start`); `fencedTexts` refuses the same +characters in a code block; `inline-line.ts` refuses a newline in an emoji, mention or status (`unspellable-whitespace`); `inline-line.ts` and `fencedTexts` refuse a text node whose `text` is -empty or missing, and `inline-line.ts` one holding `content`. The inline carry spells all of them; -a carriage return or NUL could ride `!adf:text{text="…"}` instead, which keeps the text readable — -a writer panel picks. Found by the README-goals audit, 2026-10-03. +empty or missing, and `inline-line.ts` one holding `content`. The carries spell all of them: the +inline carry in a paragraph, the block carry in a code block. Inline, a carriage return or NUL +could ride `!adf:text{text="…"}` instead, which keeps the text readable — a writer panel picks. + +The maintainer approved on 2026-10-04: §Markdown in is a canonical fixpoint drops its code-span +exception, §Which code a cause takes drops `unspellable-character` and `unspellable-whitespace` as +emitter causes, and `unspellable-character` and `unspellable-line-start` retire. +`unspellable-whitespace` stays, since the reader raises it for a content slot spanning a newline. +Found by the README-goals audit, 2026-10-03. ### 45. Replace `isAdfDocument` with a reader returning `Result`. @@ -111,24 +115,26 @@ a code fence whose info string opens `adf:` becomes the block carry where Common caller names the markdown it hands in: CommonMark, read as its spec says, or the lossless flavour, read as `spec/flavour.md` says. Breaking: `MIGRATION.md` says which call a caller takes. -### 65. Read a mid-text CommonMark image as a link to it, and a titled one on its own line as an image captioned with its title. +### 65. Read an image not alone in its paragraph as its alt text linked to its URL, and a titled image alone in its paragraph as the image captioned with its title, in both readers. Both are refused today with `unmappable-image`: 14 examples in -`corpus/commonmark-spec/refusals.json`, and a bot's `See ![diagram](url) here` among them. ADF's -inline image takes only Atlassian media ids, so a mid-text image reads as its alt text linked to its -URL, its title the link's `title` and an empty alt text the URL itself (item 50). A titled image on -its own line reads as the image with its title as a `caption` (the maintainer, 2026-10-04). +`corpus/commonmark-spec/refusals.json`, a bot's `See ![diagram](url) here` among them. `mediaInline` +takes only Atlassian media ids, never a URL. An image not alone in its paragraph reads as its alt +text, linked to its URL. Its title becomes the link's `title`. An empty alt text reads as the URL, +as item 50 reads an empty link. A titled image alone in its paragraph reads as the image, with its +title as a `caption` (the maintainer, 2026-10-04). Goal 4 puts both readers on it. An image inside +a link, `[![moon](moon.jpg)](/uri)` (spec example 517), would need two links on one text node: the +chunk settles which link the alt text keeps by Goal 6, and asks where it does not decide. ### 49. Read a list whose bullet or ordered delimiter changes as two lists, in both readers, and retire `!adf:listBreak`. Lands after item 43. Today `- a` then `+ b`, or `1.` then `1)`, reads as one list; CommonMark reads two (spec examples 301 and 302). Goal 4 settles it for the lossless flavour too: CommonMark spells -two adjacent lists by changing the marker, so `adfToMarkdown` and `adfToPlainMarkdown` write the -second of two adjacent bullet lists with `*` (the maintainer, 2026-10-04) and the second of two -ordered lists with `)`, and `!adf:listBreak` retires. Breaking, so it ships beside item 43: -`MIGRATION.md`'s Readings and Spellings tables gain their rows. Examples 301 and 302 lose their -`pending` exceptions, and the spelling leaves the README's "Four CommonMark spellings" bullet, which -counts one fewer. +adjacent lists by changing the marker, so `adfToMarkdown` and `adfToPlainMarkdown` alternate `-` +and `*` between adjacent bullet lists (the maintainer, 2026-10-04) and `.` and `)` between adjacent +ordered lists, and `!adf:listBreak` retires. Breaking, so it ships beside item 43: `MIGRATION.md`'s +Readings and Spellings tables gain their rows. Examples 301 and 302 lose their `pending` exceptions, +and the spelling leaves the README's "Four CommonMark spellings" bullet, which counts one fewer. ### 61. Have the emitter ask the inline reader how a line reads back, in place of `line-escaping.ts` predicting it. -- 2.52.0 From 5e5e123ff748e383a7cd619bb71224ec900ad342 Mon Sep 17 00:00:00 2001 From: Lilleman auf Larv Date: Sun, 4 Oct 2026 11:54:31 +0200 Subject: [PATCH 3/4] Answer the prose review's second round --- docs/decisions.md | 2 +- todo.md | 18 +++++++++--------- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/decisions.md b/docs/decisions.md index 94fb36c..20a6525 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -497,7 +497,7 @@ while `todo.md` items 59, 60, 61 and 62 are open. A four-seat comprehension panel scored the project under the floor of 7. Its round-5 scores (2026-10-03) are the baseline: a chunk whose panel scores any dimension lower improves what the -readers named and scores again, and after three such rounds asks the maintainer. +seats named and scores again, and after three such rounds asks the maintainer (2026-10-04). | Seat | Navigation | Locality | Shape | Self-sufficiency | Overall | |---|---|---|---|---|---| diff --git a/todo.md b/todo.md index 56501b8..4b75794 100644 --- a/todo.md +++ b/todo.md @@ -31,7 +31,7 @@ | 6 | 0.2.0 | decision | **Specify the HTML dialect.** | 2 | 6 | 7 | 8 | 2, 3 | 24.7 | | 64 | 0.2.0 | defect | **Read back unchanged on V8 every JSON key the emitter writes, with a fixture whose key holds `\`, `"` or a control character.** | 4 | 4 | 6 | 8 | 1, 7 | 23.0 | | 43 | 0.2.0 | decision | **Give each markdown input its own reader, strict to its own standard.** | 6 | 7 | 8 | 9 | 3, 4 | 22.3 | -| 65 | 0.2.0 | defect | **Read an image not alone in its paragraph as its alt text linked to its URL, and a titled image alone in its paragraph as the image captioned with its title, in both readers.** | 5 | 5 | 7 | 7 | 3, 4, 6 | 18.7 | +| 65 | 0.2.0 | defect | **Read an image not alone in its paragraph as its alt text linked to its URL, and a titled image alone in its paragraph as the image captioned with its title.** | 5 | 5 | 7 | 7 | 3, 4, 6 | 18.7 | | 49 | 0.2.0 | | **Read a list whose bullet or ordered delimiter changes as two lists, in both readers, and retire `!adf:listBreak`.** | 4 | 5 | 5 | 8 | 3, 4 | 17.2 | | 61 | 0.2.0 | decision | **Have the emitter ask the inline reader how a line reads back, in place of `line-escaping.ts` predicting it.** | 6 | 8 | 3 | 8 | 1 | 14.0 | | 52 | 0.2.0 | | **Spell `colwidth` as a comma list, `colwidth="340,420"`.** | 3 | 3 | 5 | 6 | 5 | 13.0 | @@ -72,8 +72,8 @@ Lands after items 6, 59, 60, 61 and 62. The CommonMark spec suite also runs agai ### 55. Spell every document the emitter refuses today for a carriage return, a NUL, a code-span line start, a newline inside an emoji, mention or status, or a text node whose text is empty or missing, or which holds content. -Today `inline-line.ts` refuses a carriage return or NUL in text (`unspellable-character`) and a -paragraph opening with a code-span run (`unspellable-line-start`); `fencedTexts` refuses the same +Today `inline-line.ts` refuses a carriage return or NUL in text, and a NUL in an emoji, mention or +status (`unspellable-character`), and a paragraph opening with a code-span run (`unspellable-line-start`); `fencedTexts` refuses the same characters in a code block; `inline-line.ts` refuses a newline in an emoji, mention or status (`unspellable-whitespace`); `inline-line.ts` and `fencedTexts` refuse a text node whose `text` is empty or missing, and `inline-line.ts` one holding `content`. The carries spell all of them: the @@ -81,8 +81,8 @@ inline carry in a paragraph, the block carry in a code block. Inline, a carriage could ride `!adf:text{text="…"}` instead, which keeps the text readable — a writer panel picks. The maintainer approved on 2026-10-04: §Markdown in is a canonical fixpoint drops its code-span -exception, §Which code a cause takes drops `unspellable-character` and `unspellable-whitespace` as -emitter causes, and `unspellable-character` and `unspellable-line-start` retire. +exception, §Which code a cause takes drops `unspellable-character`, and drops `unspellable-whitespace` as an +emitter cause, and `unspellable-character` and `unspellable-line-start` retire. `unspellable-whitespace` stays, since the reader raises it for a content slot spanning a newline. Found by the README-goals audit, 2026-10-03. @@ -115,14 +115,14 @@ a code fence whose info string opens `adf:` becomes the block carry where Common caller names the markdown it hands in: CommonMark, read as its spec says, or the lossless flavour, read as `spec/flavour.md` says. Breaking: `MIGRATION.md` says which call a caller takes. -### 65. Read an image not alone in its paragraph as its alt text linked to its URL, and a titled image alone in its paragraph as the image captioned with its title, in both readers. +### 65. Read an image not alone in its paragraph as its alt text linked to its URL, and a titled image alone in its paragraph as the image captioned with its title. Both are refused today with `unmappable-image`: 14 examples in `corpus/commonmark-spec/refusals.json`, a bot's `See ![diagram](url) here` among them. `mediaInline` takes only Atlassian media ids, never a URL. An image not alone in its paragraph reads as its alt text, linked to its URL. Its title becomes the link's `title`. An empty alt text reads as the URL, as item 50 reads an empty link. A titled image alone in its paragraph reads as the image, with its -title as a `caption` (the maintainer, 2026-10-04). Goal 4 puts both readers on it. An image inside +title as a `caption` (the maintainer, 2026-10-04). By Goal 4, the lossless flavour reads both the same way. An image inside a link, `[![moon](moon.jpg)](/uri)` (spec example 517), would need two links on one text node: the chunk settles which link the alt text keeps by Goal 6, and asks where it does not decide. @@ -131,8 +131,8 @@ chunk settles which link the alt text keeps by Goal 6, and asks where it does no Lands after item 43. Today `- a` then `+ b`, or `1.` then `1)`, reads as one list; CommonMark reads two (spec examples 301 and 302). Goal 4 settles it for the lossless flavour too: CommonMark spells adjacent lists by changing the marker, so `adfToMarkdown` and `adfToPlainMarkdown` alternate `-` -and `*` between adjacent bullet lists (the maintainer, 2026-10-04) and `.` and `)` between adjacent -ordered lists, and `!adf:listBreak` retires. Breaking, so it ships beside item 43: `MIGRATION.md`'s +and `*` between adjacent bullet lists and `.` and `)` between adjacent ordered lists, and +`!adf:listBreak` retires. `*` is the maintainer's pick (2026-10-04); ordered lists have only `)`. Breaking, so it ships beside item 43: `MIGRATION.md`'s Readings and Spellings tables gain their rows. Examples 301 and 302 lose their `pending` exceptions, and the spelling leaves the README's "Four CommonMark spellings" bullet, which counts one fewer. -- 2.52.0 From 19a70e0e18a7929ca3a76ed3ba08e7065b1a817d Mon Sep 17 00:00:00 2001 From: Lilleman auf Larv Date: Sun, 4 Oct 2026 11:55:40 +0200 Subject: [PATCH 4/4] Answer the prose review's third round --- docs/decisions.md | 4 ++-- todo.md | 50 ++++++++++++++++++++++++----------------------- 2 files changed, 28 insertions(+), 26 deletions(-) diff --git a/docs/decisions.md b/docs/decisions.md index 20a6525..1f0c535 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -496,8 +496,8 @@ exits 0 on. while `todo.md` items 59, 60, 61 and 62 are open. A four-seat comprehension panel scored the project under the floor of 7. Its round-5 scores -(2026-10-03) are the baseline: a chunk whose panel scores any dimension lower improves what the -seats named and scores again, and after three such rounds asks the maintainer (2026-10-04). +(2026-10-03) are the baseline. Since 2026-10-04, a chunk whose panel scores any dimension lower +improves what the seats named and scores again, and after three such rounds asks the maintainer. | Seat | Navigation | Locality | Shape | Self-sufficiency | Overall | |---|---|---|---|---|---| diff --git a/todo.md b/todo.md index 4b75794..1ccb774 100644 --- a/todo.md +++ b/todo.md @@ -73,18 +73,19 @@ Lands after items 6, 59, 60, 61 and 62. The CommonMark spec suite also runs agai ### 55. Spell every document the emitter refuses today for a carriage return, a NUL, a code-span line start, a newline inside an emoji, mention or status, or a text node whose text is empty or missing, or which holds content. Today `inline-line.ts` refuses a carriage return or NUL in text, and a NUL in an emoji, mention or -status (`unspellable-character`), and a paragraph opening with a code-span run (`unspellable-line-start`); `fencedTexts` refuses the same -characters in a code block; `inline-line.ts` refuses a newline in an emoji, mention or status -(`unspellable-whitespace`); `inline-line.ts` and `fencedTexts` refuse a text node whose `text` is -empty or missing, and `inline-line.ts` one holding `content`. The carries spell all of them: the -inline carry in a paragraph, the block carry in a code block. Inline, a carriage return or NUL -could ride `!adf:text{text="…"}` instead, which keeps the text readable — a writer panel picks. +status (`unspellable-character`); and a paragraph opening with a code-span run +(`unspellable-line-start`); `fencedTexts` refuses the same characters in a code block; +`inline-line.ts` refuses a newline in an emoji, mention or status (`unspellable-whitespace`); +`inline-line.ts` and `fencedTexts` refuse a text node whose `text` is empty or missing, and +`inline-line.ts` one holding `content`. The carries spell all of them: the inline carry in a +paragraph, the block carry in a code block. Inline, a carriage return or NUL could ride +`!adf:text{text="…"}` instead, which keeps the text readable — a writer panel picks. The maintainer approved on 2026-10-04: §Markdown in is a canonical fixpoint drops its code-span -exception, §Which code a cause takes drops `unspellable-character`, and drops `unspellable-whitespace` as an -emitter cause, and `unspellable-character` and `unspellable-line-start` retire. -`unspellable-whitespace` stays, since the reader raises it for a content slot spanning a newline. -Found by the README-goals audit, 2026-10-03. +exception, §Which code a cause takes drops `unspellable-whitespace` as an emitter cause; +`unspellable-character` and `unspellable-line-start` retire. `unspellable-whitespace` stays, since +the reader raises it for a content slot spanning a newline. Found by the README-goals audit, +2026-10-03. ### 45. Replace `isAdfDocument` with a reader returning `Result`. @@ -122,19 +123,21 @@ Both are refused today with `unmappable-image`: 14 examples in takes only Atlassian media ids, never a URL. An image not alone in its paragraph reads as its alt text, linked to its URL. Its title becomes the link's `title`. An empty alt text reads as the URL, as item 50 reads an empty link. A titled image alone in its paragraph reads as the image, with its -title as a `caption` (the maintainer, 2026-10-04). By Goal 4, the lossless flavour reads both the same way. An image inside -a link, `[![moon](moon.jpg)](/uri)` (spec example 517), would need two links on one text node: the -chunk settles which link the alt text keeps by Goal 6, and asks where it does not decide. +title as a `caption` (the maintainer, 2026-10-04). By Goal 4, the lossless flavour reads both as +CommonMark does. An image inside a link, `[![moon](moon.jpg)](/uri)` (spec example 517), would need +two links on one text node: the chunk settles which link the alt text keeps by Goal 6, and asks +where it does not decide. ### 49. Read a list whose bullet or ordered delimiter changes as two lists, in both readers, and retire `!adf:listBreak`. Lands after item 43. Today `- a` then `+ b`, or `1.` then `1)`, reads as one list; CommonMark reads two (spec examples 301 and 302). Goal 4 settles it for the lossless flavour too: CommonMark spells -adjacent lists by changing the marker, so `adfToMarkdown` and `adfToPlainMarkdown` alternate `-` -and `*` between adjacent bullet lists and `.` and `)` between adjacent ordered lists, and -`!adf:listBreak` retires. `*` is the maintainer's pick (2026-10-04); ordered lists have only `)`. Breaking, so it ships beside item 43: `MIGRATION.md`'s -Readings and Spellings tables gain their rows. Examples 301 and 302 lose their `pending` exceptions, -and the spelling leaves the README's "Four CommonMark spellings" bullet, which counts one fewer. +adjacent lists by changing the marker, so `adfToMarkdown` and `adfToPlainMarkdown` alternate `-` and +`*` between adjacent bullet lists and `.` and `)` between adjacent ordered lists, and +`!adf:listBreak` retires. `*` is the maintainer's pick (2026-10-04). Breaking, so it ships beside +item 43: `MIGRATION.md`'s Readings and Spellings tables gain their rows. Examples 301 and 302 lose +their `pending` exceptions, and the spelling leaves the README's "Four CommonMark spellings" bullet, +which counts one fewer. ### 61. Have the emitter ask the inline reader how a line reads back, in place of `line-escaping.ts` predicting it. @@ -186,8 +189,8 @@ which counts one fewer. Reading: the alert and task-marker reads in `parse/markdown-to-adf.ts`, the `mintTaskIds` call and the `inlineLeaves` use. Writing: `spellPlainBlock`, `quotedUnder`, `tryTaskList` and `taskBlocks` in `emit/adf-to-markdown.ts`. And `highlightDelimiter` and `highlightFlanking` move out of -`plain/conventions.ts`, which `emit/` imports them from; item 59 moves `Flavour`. Every comprehension reader on 2026-10-03 -named the plain flavour's spread across three directories. +`plain/conventions.ts`, which `emit/` imports them from; item 59 moves `Flavour`. Every +comprehension reader on 2026-10-03 named the plain flavour's spread across three directories. ### 38. Spell a lone surrogate in a text node so it survives a UTF-8 encode. @@ -260,10 +263,9 @@ kB. 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. `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. +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. ### 57. Make each `ci.sh` leg build what it reads, so one leg run alone tests the current tree. -- 2.52.0