From 3b843618724c84ca7f2587a36a538410a0f09819 Mon Sep 17 00:00:00 2001 From: Lilleman auf Larv Date: Wed, 14 Oct 2026 00:52:05 +0200 Subject: [PATCH] =?UTF-8?q?Answer=20prose=20round=201:=200=20=F0=9F=94=B4,?= =?UTF-8?q?=207=20=F0=9F=9F=A1;=20the=20guarantee=20splits=20per=20reader,?= =?UTF-8?q?=20the=20spec's=20portable=20sentence=20follows=20the=20named?= =?UTF-8?q?=20errors,=20item=20112=20names=20rows=20holding=20no=20pipe?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CHANGELOG.md | 2 +- README.md | 24 +++++++++++++----------- docs/decisions.md | 12 ++++++------ spec/flavour.md | 18 ++++++++++-------- src/markdown/parse/blocks.ts | 2 +- src/markdown/portable/conventions.ts | 2 +- todo.md | 4 ++-- 7 files changed, 34 insertions(+), 30 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 574d303..7b36fd6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -106,7 +106,7 @@ markdown GitHub, GitLab and Obsidian render: alerts, callouts, task lists, `==highlights==` and pipe tables. A task item keeps its paragraphs, then its nested task lists; the rest of the item, such as an image or a code block, stands after the task list. `portableMarkdownToAdf` reads GFM's - pipe table without its leading pipes and with alignment colons, dropping the alignment. + pipe table with or without leading pipes, and with alignment colons, dropping the alignment. - Spell `rule`'s `color`, `style` and `weight`, `layoutSection`'s `columnRuleStyle` and a link's `collection`, `id` and `occurrenceKey` directly where they rode the opaque carry. - The README opens with what the package does and for whom, and `package.json` carries search diff --git a/README.md b/README.md index 46e0e5b..fb66328 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ products store as ADF. document they started from — panels, mentions, statuses and node types this version does not know included. - **Markdown in:** `portableMarkdownToAdf` reads a bot's or a model's markdown, including `~~` and - GFM's pipe tables whose rows are as wide as their header, their column alignment dropped. + GFM's pipe tables whose rows hold as many cells as their header, their column alignment dropped. `commonMarkToAdf` reads strict CommonMark as its spec says: nothing becomes a table, task or panel. - **Portable markdown out, lossy:** `adfToPortableMarkdown` writes the markdown that GitHub, GitLab @@ -334,9 +334,10 @@ keeping the content and dropping the rest: attributes, colours, layout, identity reader of the rendered document sees or follows: its text, images and link targets. It writes no directive. -`portableMarkdownToAdf` reads CommonMark and `~~` as `losslessMarkdownToAdf` reads them, GFM's -pipe tables with or without leading pipes, their column alignment dropped, and the conventions below as nodes, taking other tools' spellings too; a directive and an -`adf:` fence read as CommonMark reads them, as text and code. A backslash keeps a marker as text: +`portableMarkdownToAdf` reads CommonMark and `~~` as `losslessMarkdownToAdf` reads them, and the +conventions below as nodes, taking other tools' spellings too. It reads GFM's pipe tables with or +without leading pipes and drops their column alignment. A directive and an `adf:` fence read as +CommonMark reads them, as text and code. A backslash keeps a marker as text: `\==x==`, `> \[!NOTE]`, `- \[x]`. Markdown `adfToPortableMarkdown` wrote reads back and writes again byte for byte; the document it came from does not come back. @@ -425,7 +426,7 @@ Which reader raises which code: [The calls](#the-calls). Codes every direction r | Code | Fires when | What you can do | | --- | --- | --- | | `malformed-directive` | an `!adf:` the grammar cannot read — a prefix completing no directive, an unclosed container, `[content]` or `{attrs}`, a closer with no container of its name open, a leaf given a body, `{attrs}` out of order or duplicated, invalid JSON in an opaque carry | write the spelling the message names, or keep it literal: escape the prefix — `\!adf:`, block and inline alike — or, for a code fence whose info string opens `adf:`, drop the info string and wrap the fence in `!adf:codeBlock {language="adf:…"}` | -| `malformed-pipe-table` | a pipe row that is no pipe table — a missing `---` delimiter row, or a delimiter or body row whose cell count differs from the header's; in `losslessMarkdownToAdf` also an alignment colon or a header or delimiter row not opening with a pipe | add a `---` row under the header and give every row the header's cell count; for `losslessMarkdownToAdf`, also open every row with a pipe and drop the colons. To keep the lines literal text, escape the leading pipe of every one — escaping a single row leaves the next to open a fresh table and fail the same way — or, for a table without leading pipes, a `\|` in its delimiter row | +| `malformed-pipe-table` | a pipe row that is no pipe table — a missing `---` delimiter row, or a delimiter or body row whose cell count differs from the header's; in `losslessMarkdownToAdf` also an alignment colon, and a header or delimiter row not opening with a pipe | add a `---` row under the header and give every row the header's cell count; for `losslessMarkdownToAdf`, also open every row with a pipe and drop the colons. To keep the lines literal text, escape the leading pipe of every one — escaping a single row leaves the next to open a fresh table and fail the same way — or, for a table without leading pipes, write one `|` of its delimiter row as `\|` | | `not-a-string` | the value handed in is not a string, such as `null`, a number or a `String` object | pass the input as a string, `String(value)` for a `String` object; the message names the value's type | | `unknown-directive-name` | a directive whose name is no node or mark this version spells | check the name in [`spec/flavour.md`](https://github.com/larvit/adf-codec/blob/main/spec/flavour.md), or escape the prefix as `\!adf:`; the spelling itself is well formed, so a later minor may give the name meaning | | `unmappable-html` | the input holds raw HTML, a comment and a processing instruction among them | remove the construct, or write what it holds as markdown | @@ -493,12 +494,13 @@ Serves [Goals](#goals) 1, 4 and 5. levels, the node shapes the `unsupported-node-shape` row lists, and a conversion `engine-limit` stops. Show the refusal and keep the document read-only; saving markdown you could not produce is the loss the round-trip exists to stop. -- Both readers narrow GFM's pipe table: a row whose cell count differs from the header's is an - error result where GFM pads or cuts it, and a line holding no `|` ends the table where GFM reads - it as a row. `losslessMarkdownToAdf` narrows it twice more: a header or delimiter row not opening - with a pipe is an error result, and any line not opening with one ends the table; an alignment - colon in the delimiter row is an error too — ADF holds no column alignment. `portableMarkdownToAdf` reads both and drops the alignment. The - trailing pipe is canonical output, optional in input. +- Both readers narrow GFM's pipe table. A body row whose cell count differs from the header's is + an error result, where GFM pads or cuts it. A line holding no `|` ends the table, where GFM reads + it as a row. +- `losslessMarkdownToAdf` also needs a leading `|`: a header or delimiter row without one is an + error result, and a later line without one ends the table. It refuses an alignment colon in the + delimiter row too, since ADF holds no column alignment. `portableMarkdownToAdf` accepts both and + drops the alignment. The trailing pipe is canonical output, optional in input. - Past that and `~~`, `losslessMarkdownToAdf` reads no GFM: an autolink literal and a `- [ ]` marker stay text, and a checklist is the `taskList` directive — `portableMarkdownToAdf` turns the marker into a `taskList`. diff --git a/docs/decisions.md b/docs/decisions.md index a9aece4..69eb058 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -438,12 +438,12 @@ handles one cause alike whichever node, attribute or direction raised it. or across directions, one code covers them all and `path` and `message` say which — `unsupported-nesting-depth` is the 500-level guard whichever direction hits it. - A claim code names the spelling claimed, never the node that spelling would have built: a - malformed `!adf:table` is a `malformed-directive`, and an alignment colon in - `losslessMarkdownToAdf` a `malformed-pipe-table` — the flavour's own delimiter row is `-` runs, so - the grammar refuses the colon rather than ADF's missing column model doing it; - `portableMarkdownToAdf` reads GFM's colon and drops the alignment (2026-10-14). What the grammar itself refuses stays a - claim code, key order among it, and a leaf given a body is refused at its opener, as a container - missing its closer is (2026-09-16). + malformed `!adf:table` is a `malformed-directive`. An alignment colon in `losslessMarkdownToAdf` + is a `malformed-pipe-table`: the flavour's own delimiter row is `-` runs, so the grammar refuses + the colon rather than ADF's missing column model doing it. `portableMarkdownToAdf` reads GFM's + colon and drops the alignment (2026-10-14). What the grammar itself refuses stays a claim code, + key order among it, and a leaf given a body is refused at its opener, as a container missing its + closer is (2026-09-16). - A directive whose name reads back to no node is `unknown-directive-name` rather than a claim code — the spelling is well formed, and telling that apart from a typo is what a consumer switches on when a later MINOR gives the name meaning. A reserved name is a known name, so never that code, diff --git a/spec/flavour.md b/spec/flavour.md index fe705cc..d0f8cac 100644 --- a/spec/flavour.md +++ b/spec/flavour.md @@ -346,18 +346,20 @@ Claiming at block level, symmetric with directives: a line opening with an unesc claimed and must parse as part of a pipe table, else it is a named error — escape the pipe (`\|`) to keep it literal text. The shape a missing leading pipe leaves is claimed too: a line holding an unescaped `|`, followed inside one paragraph by a line whose cells are all `-` runs, -an alignment colon among them, and match it in count — GFM's table without the outer pipes — is -a named error rather than the prose it reads as. `portableMarkdownToAdf` reads that shape as a -table, its body rows with or without the leading `|` until a line holding none or opening another -block, and drops an alignment colon's alignment. A pipe table is a header row, a delimiter row whose cells are runs of -one or more `-` (canonical `---`), and body rows; rows follow code-fence indentation. +alignment colons allowed, and match it in count — GFM's table without the outer pipes — is a +named error rather than the prose it reads as. A pipe table is a header row, a delimiter row whose +cells are runs of one or more `-` (canonical `---`), and body rows; rows follow code-fence +indentation. Cells split on unescaped `|` before inline parsing — `\|` stays in the cell text, and the inline layer's ordinary CommonMark escaping yields the pipe; each cell is the inline content of one paragraph, trimmed; canonical form pads cells with single spaces and ends rows with `|` (optional in input). Named errors: a delimiter or body row whose cell count differs from the -header's, and, outside `portableMarkdownToAdf`, an alignment colon in the delimiter row — ADF holds -no column alignment. In a pipe cell a hard break is `!adf:hardBreak{}` and a literal `|` is `\|`; -a `|` inside a quoted attribute value is already `\u007c`, so the split never reaches it. +header's, and, in `losslessMarkdownToAdf`, an alignment colon in the delimiter row — ADF holds no +column alignment. In a pipe cell a hard break is `!adf:hardBreak{}` and a literal `|` is `\|`; a +`|` inside a quoted attribute value is already `\u007c`, so the split never reaches it. +`portableMarkdownToAdf` reads GFM's table: any row may drop its leading `|`, a body row continues +the table while it holds a `|` and opens no other block, and an alignment colon is read and its +alignment dropped. The directive form nests cells as containers of block content inside `tableRow` containers: diff --git a/src/markdown/parse/blocks.ts b/src/markdown/parse/blocks.ts index c6eedd9..1b3b0a8 100644 --- a/src/markdown/parse/blocks.ts +++ b/src/markdown/parse/blocks.ts @@ -360,7 +360,7 @@ function continuesLazily(walk: Walk, line: Line): boolean { return !opensBlock(walk.claims, opener) } -// Every leaf a line can open but a paragraph, a setext underline and indented code. +// Whether the line opens a block other than a paragraph, a setext underline or indented code. function opensBlock(claims: Claims, opener: string): boolean { if ((claims.directives && readDirectiveLine(opener) !== undefined) || (claims.pipeTables !== false && claimsPipeLine(opener)) || isThematicBreak(opener)) return true return atxHeading(opener) !== undefined || openingCodeFence(opener) !== undefined || openingHtmlBlock(opener, true) !== undefined diff --git a/src/markdown/portable/conventions.ts b/src/markdown/portable/conventions.ts index a02c38e..682f369 100644 --- a/src/markdown/portable/conventions.ts +++ b/src/markdown/portable/conventions.ts @@ -10,7 +10,7 @@ export type Claims = { carryFence: boolean directives: boolean highlights: boolean - // `gfm` reads rows with or without the leading `|`, alignment colons dropped; `flavour` only rows opening with `|` over `-` runs. + // `gfm`: a row may drop its leading `|`, and an alignment colon is read and dropped; `flavour`: every row opens with `|`, the delimiter row `-` runs only. pipeTables: 'flavour' | 'gfm' | false strikethrough: boolean taskMarkers: boolean diff --git a/todo.md b/todo.md index cf7d724..f7488d5 100644 --- a/todo.md +++ b/todo.md @@ -50,7 +50,7 @@ | 68 | 0.3.0 | | **Carry a non-text inline node holding `content` or `text`, a block holding `text`, and a leaf block holding `content`.** | 3 | 3 | 4 | 4 | 7 | 1 | 18.2 | | 75 | 0.3.0 | | **Make the generated-markdown property write block carries as `adf:` fences, canonical and hostile.** | 2 | 2 | 4 | 3 | 7 | 1 | 17.5 | | 81 | 0.3.0 | | **Fail the gate unless the README's error tables list exactly the codes `ConvertErrorCode` holds.** | 1 | 2 | 2 | 5 | 5 | 3 | 16.3 | -| 112 | 0.3.0 | question | **Read a GFM pipe table's ragged and pipe-less body rows, and a one-column table without leading pipes, in `portableMarkdownToAdf` as GFM does, keeping every cell.** | 3 | 3 | 5 | 6 | 6 | 4, 7 | 16.3 | +| 112 | 0.3.0 | question | **Read a GFM pipe table's ragged rows, its body rows holding no pipe, and a one-column table without leading pipes in `portableMarkdownToAdf`.** | 3 | 3 | 5 | 6 | 6 | 4, 7 | 16.3 | | 46 | 0.3.0 | | **Publish the bundle size in the README, failing the release pipeline when it drifts.** | 2 | 4 | 3 | 5 | 5 | 3, 8 | 14.8 | | 72 | 0.3.0 | decision | **Re-create `gitea.larvit.se/larvit/adf-codec` as a read-only pull mirror of GitHub, its issues and Actions off and its description pointing at GitHub.** | 2 | 1 | 1 | 3 | 6 | 3 | 13.1 | | 107 | 0.3.0 | decision | **Spell the block carry's JSON so its length stays linear in the node's JSON.** | 4 | 5 | 7 | 3 | 5 | 1 | 10.8 | @@ -273,7 +273,7 @@ and hostile. Found by the technical-principles audit, 2026-10-04. leaves the README's tables a false contract under a green gate. Assert that the tables list exactly the union. Found by the technical-principles audit of item 78, 2026-10-05. -### 112. Read a GFM pipe table's ragged and pipe-less body rows, and a one-column table without leading pipes, in `portableMarkdownToAdf` as GFM does, keeping every cell. +### 112. Read a GFM pipe table's ragged rows, its body rows holding no pipe, and a one-column table without leading pipes in `portableMarkdownToAdf`. GFM pads a short row with empty cells, cuts a long one to the header's count, reads a line holding no `|` after a table as a row, and reads `a |` over `--- |` as a one-column table.