diff --git a/README.md b/README.md index 50770a7..6345f54 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ products store as ADF. - **Runs anywhere:** pure functions with no runtime dependencies, in Node, Deno, Bun and browsers. - **HTML at `0.2.0`:** `adfToHtml`, `htmlToAdf`, `markdownToHtml`, `htmlToMarkdown`. -[Goals](#goals) · [Audience](#audience) · [The shape](#the-shape) · +[The shape](#the-shape) · [Goals](#goals) · [Audience](#audience) · [Plain markdown](#plain-markdown) · [The errors](#the-errors) · [The guarantees](#the-guarantees) · [The package](#the-package) · [Grammar](https://github.com/larvit/adf-codec/blob/main/spec/flavour.md) · @@ -30,40 +30,6 @@ products store as ADF. [Plan](https://github.com/larvit/adf-codec/blob/main/todo.md) · [Decisions](https://github.com/larvit/adf-codec/blob/main/docs/decisions.md) -## Goals - -The most useful ADF conversion library available, judged by these goals, in priority order: - -1. **Lossless, and every call returns a result, never a throw.** -2. **ADF is the hub.** -3. **Easy to find, and clear at a glance what it does.** -4. **Each format reads and writes as its standard says.** -5. **Our markdown is CommonMark, extended only where CommonMark has no spelling.** -6. **No surprises: output reads and edits the way its audience expects.** -7. **Lossy conversion drops form, never content.** -8. **Runs in any JavaScript engine, with no runtime dependencies and nothing to configure or connect.** -9. **Fast, and linear in the document's size as JSON.** - -## Audience - -Application developers embedding the library, in four personas. All four rely on the guarantees -below and on an error's `code` being a closed list; none may rely on an error message's wording, -which is free text. - -- **Viewer/editor app** — shows a document, lets a human edit, posts it back. Relies on the - round-trip holding for whatever the site's editor wrote, unknown node types included, and on a - refusal arriving before the save rather than after. -- **Bot posting content** — turns generated markdown into ADF. Relies on plain CommonMark being - valid input, so nothing upstream has to learn a flavour. -- **Export/indexing tool** — converts ADF to markdown or HTML in bulk. Relies on readable output - and on every refusal being deterministic, so a document that fails fails the same way next run. -- **LLM/agent pipeline** — hands documents to a model as markdown and writes the edits back. - Relies on the round-trip and on markdown a reader half-knowing the lossless flavour can still edit. - -Behind those apps, the people who read and write the markdown, and later the HTML: product -managers, engineers and support agents working in Atlassian products through a plugin or another -UI. They know markdown and not ADF, and rely on every spelling saying what it means to them. - ## The shape ```sh @@ -102,6 +68,40 @@ htmlToMarkdown(html: string): Result // 0.2.0 `Result` is `{ ok: true; value: T } | { ok: false; error: ConvertError }` — nothing throws. +## Goals + +The most useful ADF conversion library available, judged by these goals, in priority order: + +1. **Lossless, and every call returns a result, never a throw.** +2. **ADF is the hub.** +3. **Easy to find, and clear at a glance what it does.** +4. **Each format reads and writes as its standard says.** +5. **Our markdown is CommonMark, extended only where CommonMark has no spelling.** +6. **No surprises: output reads and edits the way its audience expects.** +7. **Lossy conversion drops form, never content.** +8. **Runs in any JavaScript engine, with no runtime dependencies and nothing to configure or connect.** +9. **Fast, and linear in the document's size as JSON.** + +## Audience + +Application developers embedding the library, in four personas. All four rely on the guarantees +below and on an error's `code` being a closed list; none may rely on an error message's wording, +which is free text. + +- **Viewer/editor app** — shows a document, lets a human edit, posts it back. Relies on the + round-trip holding for whatever the site's editor wrote, unknown node types included, and on a + refusal arriving before the save rather than after. +- **Bot posting content** — turns generated markdown into ADF. Relies on plain CommonMark being + valid input, so nothing upstream has to learn a flavour. +- **Export/indexing tool** — converts ADF to markdown or HTML in bulk. Relies on readable output + and on every refusal being deterministic, so a document that fails fails the same way next run. +- **LLM/agent pipeline** — hands documents to a model as markdown and writes the edits back. + Relies on the round-trip and on markdown a reader half-knowing the lossless flavour can still edit. + +Behind those apps, the people who read and write the markdown, and later the HTML: product +managers, engineers and support agents working in Atlassian products through a plugin or another +UI. They know markdown and not ADF, and rely on every spelling saying what it means to them. + ## Plain markdown Serves Goal 7. Plain markdown is a second flavour of the same grammar. `adfToPlainMarkdown` writes diff --git a/todo.md b/todo.md index a779001..7d22981 100644 --- a/todo.md +++ b/todo.md @@ -36,7 +36,6 @@ | 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 | | 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 `## The shape`.** | 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 | | 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 | @@ -113,9 +112,11 @@ document once inside one tight `try/catch`, reading property descriptors so no g accessor property, or a Proxy trap that throws, is `not-an-adf-document`. The copy keeps own enumerable keys, as `JSON.stringify` does, so an inherited or non-enumerable key drops. The reader reads arrays by index, so no custom iterator runs. Every later step works on the copy. A Proxy can -still claim unbounded width, which the 500-level limit does not cover, so the copy needs a cap on -the values it reads. No standard sets that number: the chunk asks the maintainer for it first. Found -by the technical-principles audit, 2026-10-04. +still claim unbounded width, which the 500-level limit does not cover, so the copy reads at most 10 +million values (the maintainer, 2026-10-05): roughly 50 to 100 MB of JSON, far past any real page, +where 10 000 would refuse a 500-row table. Before reading an array, the reader checks its `length` +against the values left, so a Proxy claiming 2³² elements is refused at once. Found by the +technical-principles audit, 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. @@ -173,11 +174,6 @@ 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 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 `## The shape`. - -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`. Lands after item 43. Today `- a` then `+ b`, or `1.` then `1)`, reads as one list; CommonMark reads @@ -209,8 +205,8 @@ of one character from each of its characters. ### 72. 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. -Lands after the maintainer confirms the GitHub repository's settings, history, CI gate and -publishing. The maintainer does this. Gitea cannot convert an existing repository to a mirror, so +Lands when `0.2.0` is getting ready to be cut (the maintainer, 2026-10-05). The maintainer does +this. Gitea cannot convert an existing repository to a mirror, so the copy is deleted and re-created. That drops the copy's commit hashes from before the 2026-10-04 history rewrite, and its Actions secrets. The Gitea copy holds no issues or releases to move. Actions stay off on the mirror: Gitea runs `.github/workflows/` when `.gitea/workflows/` is absent,