3
0
mirror of https://github.com/larvit/adf-codec.git synced 2026-11-21 07:32:58 +01:00

Answer stability round 1: item 71 waits on items 7 and 46 again, keywords match the GitHub topics

This commit is contained in:
2026-10-05 00:24:20 +02:00
committed by Lillem4n
parent 3fb21b9766
commit f4022d62c9
4 changed files with 37 additions and 34 deletions
+2 -2
View File
@@ -2,8 +2,8 @@
## Unreleased ## Unreleased
- The README opens with what the package does and for whom, and compares it with the other ADF - The README opens with what the package does and for whom, and `package.json` carries search
converters on npm; `package.json` carries search keywords. keywords.
- The source moves to [github.com/larvit/adf-codec](https://github.com/larvit/adf-codec), where - The source moves to [github.com/larvit/adf-codec](https://github.com/larvit/adf-codec), where
issues and pull requests go. issues and pull requests go.
- **Breaking:** directives, the inline opaque carry among them (now `!adf:carry{json="…"}`), are - **Breaking:** directives, the inline opaque carry among them (now `!adf:carry{json="…"}`), are
+9 -24
View File
@@ -10,17 +10,19 @@ products store as ADF.
- **Lossless:** `adfToMarkdown` and `markdownToAdf` give back the document they started from — - **Lossless:** `adfToMarkdown` and `markdownToAdf` give back the document they started from —
panels, mentions, statuses and node types this version does not know included. panels, mentions, statuses and node types this version does not know included.
- **Plain CommonMark in:** a bot's or a model's markdown is valid input, nothing to learn first. - **Plain CommonMark in:** a bot's or a model's markdown is valid input, apart from raw HTML and
- **Plain markdown out:** `adfToPlainMarkdown` and `plainMarkdownToAdf` convert to and from what the exceptions [The guarantees](#the-guarantees) lists.
GitHub, GitLab and Obsidian render — GitHub Flavored Markdown's alerts and task lists, Obsidian - **Plain markdown, lossy:** `adfToPlainMarkdown` and `plainMarkdownToAdf` convert to and from
Flavored Markdown's callouts, highlights and pipe tables — keeping the content. markdown GitHub, GitLab and Obsidian render — GitHub Flavored Markdown's alerts, task lists and
pipe tables, Obsidian Flavored Markdown's callouts and highlights. They keep the text, images and
link targets and drop the rest; to save edits back, use the lossless pair.
- **No throws:** every call returns a result; a refusal carries a code from a closed list. - **No throws:** every call returns a result; a refusal carries a code from a closed list.
- **Runs anywhere:** pure functions with no runtime dependencies, in Node, Deno, Bun and browsers. - **Runs anywhere:** pure functions with no runtime dependencies, in Node, Deno, Bun and browsers.
- **HTML** at `0.2.0`: `adfToHtml`, `htmlToAdf`, `markdownToHtml`, `htmlToMarkdown`. - **HTML at `0.2.0`:** `adfToHtml`, `htmlToAdf`, `markdownToHtml`, `htmlToMarkdown`.
[Goals](#goals) · [Audience](#audience) · [The shape](#the-shape) · [Goals](#goals) · [Audience](#audience) · [The shape](#the-shape) ·
[Other ADF converters](#other-adf-converters) · [Plain markdown](#plain-markdown) · [Plain markdown](#plain-markdown) · [The errors](#the-errors) · [The guarantees](#the-guarantees) ·
[The errors](#the-errors) · [The guarantees](#the-guarantees) · [The package](#the-package) · [The package](#the-package) ·
[Grammar](https://github.com/larvit/adf-codec/blob/main/spec/flavour.md) · [Grammar](https://github.com/larvit/adf-codec/blob/main/spec/flavour.md) ·
[Changes](https://github.com/larvit/adf-codec/blob/main/CHANGELOG.md) · [Changes](https://github.com/larvit/adf-codec/blob/main/CHANGELOG.md) ·
[Upgrading from `0.1.0`](https://github.com/larvit/adf-codec/blob/main/MIGRATION.md) · [Upgrading from `0.1.0`](https://github.com/larvit/adf-codec/blob/main/MIGRATION.md) ·
@@ -99,23 +101,6 @@ htmlToMarkdown(html: string): Result<string> // 0.2.0
`Result<T>` is `{ ok: true; value: T } | { ok: false; error: ConvertError }` — nothing throws. `Result<T>` is `{ ok: true; value: T } | { ok: false; error: ConvertError }` — nothing throws.
## Other ADF converters
Serves Goal 3. Each package's latest version on npm, checked 2026-10-05 against its docs and by
converting a document holding a paragraph, a mention, a status, an info panel and an unknown node
type to markdown and back.
| Package | ADF to markdown | Markdown to ADF | Round-trip | Invalid ADF | Runtime dependencies |
| --- | --- | --- | --- | --- | --- |
| `@larvit/adf-codec` | yes | yes | deep-equal | returns `not-an-adf-document` | 0 |
| `@atlaskit/editor-markdown-transformer` 6.3.1 | no: `encode` throws | yes, through `@atlaskit/editor-json-transformer` | — | — | 5 |
| `marklassian` 1.2.1 | no | yes | — | — | 1 |
| `adf-to-md` 1.2.1 | yes | no | — | throws | 1 |
| `extended-markdown-adf-parser` 2.4.0 | yes | yes | lossy: the mention reads back as a link, the status loses its `localId`, the unknown node as its JSON in a paragraph | writes empty markdown | 9 |
| `md-to-adf` 0.6.4 | no | yes | — | — | 2 |
| `adf-to-markdown` 1.0.1 | yes | no | — | throws on `null`, writes empty markdown for a `doc` without `content` | 0 |
| `adf2markdown` 1.2.0 | yes | no | — | throws on `null`, writes a newline for a `doc` without `content` | 0 |
## Plain markdown ## Plain markdown
Serves Goal 7. Plain markdown is a second flavour of the same grammar. `adfToPlainMarkdown` writes Serves Goal 7. Plain markdown is a second flavour of the same grammar. `adfToPlainMarkdown` writes
+1 -1
View File
@@ -12,7 +12,7 @@
"html", "html",
"jira", "jira",
"markdown", "markdown",
"prosemirror" "typescript"
], ],
"license": "MIT", "license": "MIT",
"repository": { "repository": {
+25 -7
View File
@@ -6,7 +6,7 @@
`Bar = 9` `Bar = 9`
`Next ID = 79` `Next ID = 80`
| Goal | W | | Goal | W |
|---|---| |---|---|
@@ -32,10 +32,12 @@
| 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, 8 | 23.0 | | 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, 8 | 23.0 |
| 77 | 0.2.0 | decision | **Read the input once into a plain copy, so an accessor property or a throwing Proxy yields `not-an-adf-document` and every call returns a result.** | 4 | 4 | 5 | 9 | 1 | 23.0 | | 77 | 0.2.0 | decision | **Read the input once into a plain copy, so an accessor property or a throwing Proxy yields `not-an-adf-document` and every call returns a result.** | 4 | 4 | 5 | 9 | 1 | 23.0 |
| 66 | 0.2.0 | defect | **Refuse an attribute value that is not a plain object, array or JSON primitive.** | 3 | 2 | 5 | 8 | 1 | 22.5 | | 66 | 0.2.0 | defect | **Refuse an attribute value that is not a plain object, array or JSON primitive.** | 3 | 2 | 5 | 8 | 1 | 22.5 |
| 71 | 0.2.0 | | **Add a README table comparing the package with the other ADF converters, each cell checked against that package's own docs or behaviour.** | 1 | 3 | 6 | 7 | 3 | 21.2 |
| 43 | 0.2.0 | decision | **Give each markdown input its own reader, strict to its own standard.** | 6 | 7 | 8 | 9 | 4, 5 | 20.3 | | 43 | 0.2.0 | decision | **Give each markdown input its own reader, strict to its own standard.** | 6 | 7 | 8 | 9 | 4, 5 | 20.3 |
| 68 | 0.2.0 | | **Carry a non-text inline node holding `content` or `text`, a block holding `text`, and a leaf block holding `content`.** | 3 | 3 | 4 | 7 | 1 | 18.2 | | 68 | 0.2.0 | | **Carry a non-text inline node holding `content` or `text`, a block holding `text`, and a leaf block holding `content`.** | 3 | 3 | 4 | 7 | 1 | 18.2 |
| 75 | 0.2.0 | | **Make the generated-markdown property write block carries as `adf:` fences, canonical and hostile.** | 2 | 2 | 3 | 7 | 1 | 17.5 | | 75 | 0.2.0 | | **Make the generated-markdown property write block carries as `adf:` fences, canonical and hostile.** | 2 | 2 | 3 | 7 | 1 | 17.5 |
| 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 | 4, 5, 7 | 17.1 | | 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 | 4, 5, 7 | 17.1 |
| 79 | 0.2.0 | question | **Decide whether the README's `## Goals` and `## Audience` sit below its quick start.** | 1 | 1 | 4 | 6 | 3 | 16.1 |
| 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 | 4, 5 | 15.5 | | 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 | 4, 5 | 15.5 |
| 46 | 0.2.0 | | **Publish the bundle size in the README, failing the release pipeline when it drifts.** | 2 | 4 | 5 | 5 | 3, 8 | 14.8 | | 46 | 0.2.0 | | **Publish the bundle size in the README, failing the release pipeline when it drifts.** | 2 | 4 | 5 | 5 | 3, 8 | 14.8 |
| 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 | | 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 |
@@ -71,9 +73,9 @@ Lands after items 6, 59, 60, 61 and 62. The CommonMark spec suite also runs agai
### 78. Return a result when `markdownToAdf` or `plainMarkdownToAdf` is handed a value that is not a string. ### 78. Return a result when `markdownToAdf` or `plainMarkdownToAdf` is handed a value that is not a string.
Today `null` and `undefined` throw a `TypeError` reading `length`, and `42` reads as an empty Today `null` and `undefined` throw a `TypeError` reading `length`, and `42` reads as an empty
document. A JavaScript caller, or a TypeScript one past an untyped boundary, reaches both. The code document. A JavaScript caller, or a TypeScript one past an untyped boundary, can pass any of these.
it returns follows `docs/decisions.md` §Which code a cause takes. Found by the competitor probe for The code it returns follows `docs/decisions.md` §The code list. Found while checking the other ADF
the README's comparison table, 2026-10-05. converters for item 71, 2026-10-05.
### 45. Replace `isAdfDocument` with a reader returning `Result<AdfDocument>`. ### 45. Replace `isAdfDocument` with a reader returning `Result<AdfDocument>`.
@@ -125,6 +127,17 @@ typed array in `attrs`, as `structuredClone` keeps it, passes the guard and is w
key per element: `ok: true` with content lost. Accept an object whose prototype is key per element: `ok: true` with content lost. Accept an object whose prototype is
`Object.prototype` or `null`, and an array. Found by the stability review of item 63, 2026-10-04. `Object.prototype` or `null`, and an array. Found by the stability review of item 63, 2026-10-04.
### 71. Add a README table comparing the package with the other ADF converters, each cell checked against that package's own docs or behaviour.
Lands after items 7 and 46: the table names HTML and compares item 46's size figure. Its columns:
which directions each converts, whether the round-trip holds, what an unknown node does, the
formats, runtime dependencies and size. Candidates are the packages an npm search for ADF and
markdown returns, marklassian among them. Every cell cites that package's README or a run against
its published version, and the table names each version and the date it was checked. Found while
planning discoverability, 2026-10-04. Checked 2026-10-05: no other package converts HTML or holds
the round-trip; the candidates are `@atlaskit/editor-markdown-transformer`, `adf-to-markdown`,
`adf-to-md`, `adf2markdown`, `extended-markdown-adf-parser`, `marklassian` and `md-to-adf`.
### 43. Give each markdown input its own reader, strict to its own standard. ### 43. Give each markdown input its own reader, strict to its own standard.
Today `markdownToAdf` reads CommonMark and the lossless flavour as one input: text shaped like a Today `markdownToAdf` reads CommonMark and the lossless flavour as one input: text shaped like a
@@ -162,6 +175,11 @@ its paragraph, it reads as the image with a `link` mark to `/uri`, which ADF's `
alone in its paragraph, the image reads as its alt text linked to `/uri`, and its URL drops. A alone in its paragraph, the image reads as its alt text linked to `/uri`, and its URL drops. A
writer panel chose this reading 3 of 3 (2026-10-04), by Goal 6, which outranks Goal 7. writer panel chose this reading 3 of 3 (2026-10-04), by Goal 6, which outranks Goal 7.
### 79. Decide whether the README's `## Goals` and `## Audience` sit below its quick start.
A reader landing on npm scrolls past nine goals and four personas before `npm install`; the opening
already says who the package is for. Raised by the product-owner review of item 47, 2026-10-05.
### 49. Read a list whose bullet or ordered delimiter changes as two lists, in both readers, and retire `!adf:listBreak`. ### 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 Lands after item 43. Today `- a` then `+ b`, or `1.` then `1)`, reads as one list; CommonMark reads
@@ -250,9 +268,9 @@ which counts one fewer.
### 73. Announce the package where someone needing an ADF converter already reads: JRACLOUD-77436, the Atlassian developer community and Stack Overflow's ADF-to-markdown questions. ### 73. Announce the package where someone needing an ADF converter already reads: JRACLOUD-77436, the Atlassian developer community and Stack Overflow's ADF-to-markdown questions.
Lands after `0.2.0` is published, so each post links the GitHub repository, the comparison and a Lands after `0.2.0` is published with item 71, so each post links the GitHub repository, the
README that opens with what the package is. We draft each post for the place it goes; the README's comparison table and a README that opens with what the package is. We draft each post for
maintainer posts them. Found while planning discoverability, 2026-10-04. the place it goes; the maintainer posts them. Found while planning discoverability, 2026-10-04.
### 38. Spell a lone surrogate in a text node so it survives a UTF-8 encode. ### 38. Spell a lone surrogate in a text node so it survives a UTF-8 encode.