From dbc8b91f91bfc623b1bb51fb02ea9ad6bf384d9e Mon Sep 17 00:00:00 2001 From: Lilleman auf Larv Date: Mon, 5 Oct 2026 09:38:39 +0200 Subject: [PATCH] Answer product-owner round 1: list each input the new code takes in MIGRATION's table, a String object among them, and give htmlToAdf the code --- CHANGELOG.md | 7 ++++--- MIGRATION.md | 7 ++++--- README.md | 2 +- docs/decisions.md | 6 +++--- todo.md | 3 ++- 5 files changed, 14 insertions(+), 11 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d976265..41ac55d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,9 +3,10 @@ ## Unreleased - **Breaking:** `markdownToAdf` and `plainMarkdownToAdf` refuse a value that is not a string with - the new code `not-a-string`, at position `{ line: 1, offset: 0 }`. Before, `null` and `undefined` - threw a `TypeError` and a number read as an empty document. A `switch` over `ConvertErrorCode` - naming every code needs the new case. + the new code `not-a-string`, at position `{ line: 1, offset: 0 }`. Before, `null`, `undefined` + and a non-empty array threw a `TypeError`, a `String` object converted its text, and a number + read as an empty document; pass `String(value)` where a boxed string arrives. A `switch` over + `ConvertErrorCode` naming every code needs the new case. - **Breaking:** an attribute value that is not a plain object, array or JSON primitive, such as a `Date`, `Map`, typed array or class instance, makes `isAdfDocument` return `false` and the converters refuse it as `not-an-adf-document`. Before, the converters wrote it as `{}` or its own diff --git a/MIGRATION.md b/MIGRATION.md index 2c47c28..7bdbfeb 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -81,7 +81,8 @@ converts; markdown the parser refused with one of them now refuses with the code | a node with a block body written as a leaf (`panel`) | `unsupported-node-shape` | `malformed-directive` | | an empty node the `::taskItem` spelling row names, written as a leaf | parses | `malformed-directive` | | an empty node the `::taskItem` spelling row names, written with a closer | `unsupported-node-shape` | parses | +| `null`, `undefined` or a non-empty array, on parse | throws a `TypeError` | `not-a-string` | +| a `String` object, on parse | the document its text spells | `not-a-string`; pass `String(value)` | +| a number, a boolean, a plain object or an empty array, on parse | an empty document | `not-a-string` | -`ConvertErrorCode` gains `not-a-string`: a `switch` naming every code needs its case. The markdown -readers return it for a value that is not a string, which threw or read as an empty document -before. +`ConvertErrorCode` gains `not-a-string`: a `switch` naming every code needs its case. diff --git a/README.md b/README.md index 15fef1a..1a81d9d 100644 --- a/README.md +++ b/README.md @@ -187,7 +187,7 @@ Parsing — `markdownToAdf` and `plainMarkdownToAdf`, and `htmlToAdf` at `0.2.0` | --- | --- | --- | | `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 or ragged `---` delimiter row, an alignment colon in it, or a row not opening with a pipe | open every row with a pipe and give the delimiter row the header's cell count; to keep the lines literal text instead, escape the leading pipe of every one — escaping a single row leaves the next to open a fresh table and fail the same way | -| `not-a-string` | the value handed in is not a string: `null`, `undefined`, a number, an object | pass the markdown as a string; the message names the type passed | +| `not-a-string` | the value handed in is not a string: `null`, `undefined`, a number, an object, a `String` object among them | pass the input as a string, `String(value)` for a `String` object; the message names the type passed | | `unknown-directive-name` | a directive whose name is no node or mark this version spells | check the name in `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 an HTML construct the documented element set does not map, a comment and a processing instruction among them — at this version that is every raw HTML construct in markdown, the element set landing at `0.2.0` | remove the construct, or write what it holds in the lossless flavour | | `unmappable-image` | an image sits inside other content that is not another image's description, or carries a title | give the image a paragraph of its own and drop the title | diff --git a/docs/decisions.md b/docs/decisions.md index 1fd4fc5..1ed222b 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -383,9 +383,9 @@ handles one cause alike whichever node, attribute or direction raised it. knows which direction it called and parting them after `0.1.0` is MAJOR (2026-09-23). - A non-finite number takes two codes: `unsupported-node-shape` parsing, `not-an-adf-document` emitting — no document holds one, so no round-trip crosses them (2026-09-23). -- A value handed to a markdown reader that is not a string is `not-a-string`, its position - `{ line: 1, offset: 0 }` and its path empty: no code read true of it, and `not-an-adf-document` - names the other direction's input (2026-10-05). +- A value handed to a reader of markdown or HTML that is not a string is `not-a-string`, its + position `{ line: 1, offset: 0 }` and its path empty: no code read true of it, and + `not-an-adf-document` names the other direction's input (2026-10-05). ## `message` and `path` diff --git a/todo.md b/todo.md index 230fb3e..b4eb752 100644 --- a/todo.md +++ b/todo.md @@ -67,7 +67,8 @@ ### 7. Ship HTML: `adfToHtml`, `htmlToAdf`, and `markdownToHtml` / `htmlToMarkdown` composed through ADF. Lands after items 6, 59, 60, 61 and 62. The CommonMark spec suite also runs against -`markdownToHtml`. The README documents HTML as it documents markdown. +`markdownToHtml`. The README documents HTML as it documents markdown. `htmlToAdf` refuses a value +that is not a string as `not-a-string` (`docs/decisions.md` §Which code a cause takes). ### 45. Replace `isAdfDocument` with a reader returning `Result`.