3
0
mirror of https://github.com/larvit/adf-codec.git synced 2026-11-18 22:25:44 +01:00

Answer prose round 1: 0 🔴, 7 🟡; the guarantee splits per reader, the spec's portable sentence follows the named errors, item 112 names rows holding no pipe

This commit is contained in:
2026-10-14 00:52:05 +02:00
committed by Lillem4n
parent 40afc48567
commit 5f1c64b371
7 changed files with 34 additions and 30 deletions
+1 -1
View File
@@ -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
+13 -11
View File
@@ -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`.
+6 -6
View File
@@ -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,
+10 -8
View File
@@ -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:
+1 -1
View File
@@ -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
+1 -1
View File
@@ -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
+2 -2
View File
@@ -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.