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

Answer stability round 1: 0 🔴, 2 🟡 (0 misread); read foreign HTML best effort, never refused, and scope the htmlToAdf decision to item 137 with the dialect read first

This commit is contained in:
2026-11-15 23:03:16 +01:00
committed by Lillem4n
parent 2dcb03369b
commit 856035533e
6 changed files with 56 additions and 49 deletions
+2 -2
View File
@@ -21,7 +21,7 @@ In `docs/decisions.md`:
- Unknown nodes ride the carry
- The carry fence names the node type
- A code block is a fence per text node
- Foreign HTML sorts three ways
- Foreign HTML reads best effort and is never refused
- Names stay text
- Directives under `!adf:`
- CommonMark is a subset
@@ -94,7 +94,7 @@ In `docs/decisions.md`:
- The real-world corpus holds anonymized documents from sites whose licence it records
- The feature table is a section per corpus example, led by a summary table
- Plain text is blocks a blank line apart, with `• ` and `1.` markers and nesting indented
- Jira wiki markup carries what it cannot spell in Jira's `{adf}` macro, and a lossy writer drops it instead
- Jira wiki markup carries what it cannot spell in Jira's `{adf}` macro, and a lossy writer keeps only its content
- `htmlToAdf` reads any HTML, with no option and no second call
## 1. Nothing about any consumer in the library
+3 -3
View File
@@ -286,9 +286,9 @@ which is free text.
- **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 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.
Behind those apps, the people who read and write the markdown, the HTML and the Jira wiki markup:
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.
Also behind them, the people who read a document's plain text as they read an email, whether it
arrives in an email, a notification or a search hit. They see no markup, and rely on text that
+26 -22
View File
@@ -161,25 +161,23 @@ node, so each node keeps its own text. The fences carry one info string, since A
language, and none is empty beside another, since a text node holds text. The grammar:
`spec/flavour.md` §The CommonMark blocks, the `codeBlock` bullet.
## Foreign HTML sorts three ways
## Foreign HTML reads best effort and is never refused
2026-08-23, the sort 2026-09-20, the maintainer. Goals 1 and 5. Valid while ADF holds no node
for a bare container, a comment or a script. Lands with `todo.md` item 137.
2026-08-23, the sort 2026-09-20, best effort 2026-11-15, the maintainer. Goals 7 and 12. Valid while
ADF holds no node for a bare container, a comment or a script. Lands with `todo.md` item 137.
Every foreign element `htmlToAdf` and the markdown readers read sorts one of three ways, never a
silent drop of content:
HTML from emails, CMSs and editors guarantees nothing, so no foreign element is refused. Each reads
one of two ways:
- A container around document content that ADF has no node for unwraps to its children, its own
attributes dropped: `<div align="center">text</div>` keeps `text`, losing the alignment.
- Content ADF cannot hold is an error result naming it. A comment is one: a person wrote those
words, and neither of Atlassian's schemas holds them — `annotation`'s `inlineComment` carries an
id, `placeholder` is the editor's own hint, `extension` names a vendor app.
- What is not document content drops whole: `<script>` and `<style>`, their text with them.
- What no reader sees drops whole: `<script>` and `<style>` with their text, and a comment, since a
browser shows none of it and an email's conditional comments are markup.
`<details><summary>Title</summary>…</details>` is an `expand` titled by its summary, a
`nestedExpand` inside another; an empty one is refused, since `expand` requires content. A `style`
attribute is not read at `0.4.0`: the `textColor` and `backgroundColor` it could reach cost more
than they buy.
`nestedExpand` inside another; an empty one holds an empty paragraph, since `expand` requires
content. A `style` attribute is not read at `0.4.0`: the `textColor` and `backgroundColor` it could
reach cost more than they buy.
The three markdown readers share one parser, so they take the same set.
## Names stay text
@@ -1448,22 +1446,28 @@ alt text.
extension or a synced block holding no text adds no note in its place.
- An expand's title on a line, a blank line above its body.
## Jira wiki markup carries what it cannot spell in Jira's `{adf}` macro, and a lossy writer drops it instead
## Jira wiki markup carries what it cannot spell in Jira's `{adf}` macro, and a lossy writer keeps only its content
2026-11-15, the maintainer. Goals 1, 7 and 11. Valid while Jira's renderer reads the `{adf}` macro.
Lands with `todo.md` items 192 to 196.
The lossless wiki writer spells a node or mark wiki markup has no spelling for as Jira's own
`{adf:display=block}` or `{adf:display=inline}` macro around the node's ADF JSON, so the round-trip
holds and Jira still renders the document. The lossy wiki writer ships beside it for consumers who
want wiki markup alone: it drops the form of what wiki markup cannot spell and keeps its content.
Wiki markup has no spelling for some nodes and marks, a layout among them. The lossless wiki
writer wraps each such node's ADF JSON in Jira's own `{adf}` macro: `{adf:display=block}` for a
block node, `{adf:display=inline}` for an inline node or a marked run. The round-trip holds, and
Jira still renders the document. The lossy wiki writer ships beside it for consumers who want wiki
markup alone: it drops the form of what wiki markup cannot spell and keeps its content.
## `htmlToAdf` reads any HTML, with no option and no second call
2026-11-15, a developer panel. Goals 6, 8 and 12. Valid while the dialect and foreign HTML read
without ambiguity in one reader.
without ambiguity in one reader. Lands with `todo.md` item 137, which ends "Other HTML stays
refused" in §`htmlToAdf` also reads the dialect as a browser serializes it.
HTML from an email, a CMS or an editor reads through `htmlToAdf(html)`, as the dialect does; foreign
elements sort as §Foreign HTML sorts three ways says. The bot, viewer/editor and LLM-pipeline
readers each picked it 3 of 3 over `htmlToAdf(html, { foreign: true })` and `anyHtmlToAdf(html)`:
none of them knows up front whether HTML is foreign, and a flag or a second name makes them guess.
HTML from an email, a CMS or an editor will read through `htmlToAdf(html)`. An element that claims
the dialect, by a `data-adf` attribute or an `adf-` class, reads only as the dialect, and stays
refused where that reading fails, so an edited carry element is still `unmappable-html`. Every other
element sorts as §Foreign HTML reads best effort and is never refused says.
A panel of three developers, one each for the bot, the viewer/editor app and the LLM pipeline, all
picked this over `htmlToAdf(html, { foreign: true })` and `anyHtmlToAdf(html)`. None of them knows
up front whether HTML is foreign, so a flag or a second name makes them guess.
+2 -2
View File
@@ -50,8 +50,8 @@ diagrams drawn into images.
Our directives written to `mark` come out as text: every `!adf:` line of the 14 fixtures is
published as a paragraph holding it. `commonMarkToAdf` refuses a `mark` document that opens with
`<!-- Space: DOCS -->` as `unmappable-html`, and refuses `<!-- Include: -->` the same way, because
a comment is content ADF cannot hold (`docs/decisions.md` §Foreign HTML sorts three ways). Both
refusals follow that entry.
the markdown readers refuse raw HTML today. Once `todo.md` item 138 reads it through `htmlToAdf`,
both comments drop (`docs/decisions.md` §Foreign HTML reads best effort and is never refused).
## What the audience would expect
+1 -1
View File
@@ -192,7 +192,7 @@ is the fence.
## Raw HTML in input
CommonMark input may contain raw HTML. Every markdown reader routes each construct through the
foreign HTML element mapping (`docs/decisions.md` §Foreign HTML sorts three ways) — ADF has no
foreign HTML element mapping (`docs/decisions.md` §Foreign HTML reads best effort and is never refused) — ADF has no
raw-HTML node, so a construct without a mapping, comments and processing instructions included, is
an error result naming it. The flavour never emits raw HTML.
+22 -19
View File
@@ -15,9 +15,9 @@
| 192 | 0.4.0 | | owner | **Spec each ADF node's and mark's Jira wiki spelling in `spec/wiki.md`, sourced from Atlassian's text formatting notation help, with the wiki calls' names a developer panel picks.** | 2 | 2 | 1 | 3 | 3 | 11 by 3 | 2.5 |
| 193 | 0.4.0 | 192 | owner | **Write ADF as Jira wiki markup, carrying in Jira's `{adf}` macro each node and mark wiki markup cannot spell.** | 3 | 1 | 2 | 4 | 7 | 11 by 4 | 0.4 |
| 194 | 0.4.0 | 193 | owner | **Write ADF as Jira wiki markup alone, dropping the form and keeping the content of what wiki markup cannot spell.** | 2 | 2 | 2 | 4 | 4 | 11 by 2 | 1.1 |
| 195 | 0.4.0 | 193 | owner | **Read Jira wiki markup into ADF, `{adf}` carries included, as `spec/wiki.md` says.** | 4 | 1 | 2 | 5 | 8 | 11 by 5 | 0.3 |
| 195 | 0.4.0 | 193 | owner | **Read Jira wiki markup into ADF, `{adf}` macros included, as `spec/wiki.md` says.** | 4 | 1 | 2 | 5 | 8 | 11 by 5 | 0.3 |
| 196 | 0.4.0 | 194, 195 | owner | **Document the wiki calls in the README, with a row comparing them with Atlassian's `WikiMarkupTransformer`.** | 1 | 2 | 1 | 2 | 2 | 3 by 2, 11 by 1 | 3.6 |
| 137 | 0.4.0 | | decision | **Read foreign HTML in `htmlToAdf` the three ways `docs/decisions.md` §Foreign HTML sorts three ways states.** | 2 | 1 | 2 | 3 | 4 | 12 by 6 | 3.3 |
| 137 | 0.4.0 | | decision | **Read foreign HTML in `htmlToAdf` best effort, never refusing it, as `docs/decisions.md` §Foreign HTML reads best effort and is never refused states.** | 2 | 1 | 2 | 3 | 4 | 12 by 6 | 3.3 |
| 172 | 0.4.0 | | principle | **Build one test per reader or case in place of a loop inside a test body, in the 26 test files that loop.** | 3 | 1 | 1 | 3 | 8 | code health by 2 | 0.5 |
| 107 | 0.4.0 | | decision | **Spell the block carry's JSON so its length stays linear in the node's JSON.** | 3 | 1 | 3 | 5 | 5 | | 0.0 |
| 170 | 0.4.0 | | owner | **Bundle the packed tarball with webpack, esbuild, Rollup and Bun in the gate, failing on any bundler warning, and run each bundle's round-trip in Node.** | 3 | 1 | 1 | 3 | 5 | | 0.0 |
@@ -49,13 +49,16 @@
### 192. Spec each ADF node's and mark's Jira wiki spelling in `spec/wiki.md`, sourced from Atlassian's text formatting notation help, with the wiki calls' names a developer panel picks.
First of the items splitting item 148, under README goal 11. Confirm against a real Jira site that
the renderer reads `{adf:display=block}` and `{adf:display=inline}` around ADF JSON, the carry
docs/decisions.md §Jira wiki markup carries what it cannot spell names; where it does not, ask
before building the writers. The spec names, per node and mark, the lossless writer's spelling, the
lossy writer's, and what the reader reads. A developer panel picks the names of the reader and both
writers, and whether the lossy writer is a call or an option (Goal 6.1, Goal 8's "nothing to
configure"); a writer panel of wiki-markup authors benches each spelling Jira's help leaves open.
Goal 11. The lossless writer carries what wiki markup cannot spell in Jira's `{adf}` macro, as
`docs/decisions.md` records. First confirm on a real Jira site that the renderer reads that macro
around ADF JSON; where it does not, ask before building the writers.
The spec names, per node and mark, the lossless writer's spelling, the lossy writer's, and what the
reader reads. A developer panel picks the names of the reader and both writers, and whether the
lossy writer is a call or an option, under Goals 6.1 and 8. Its brief names the trap a wrong pick
sets: an app that saves through the lossy writer loses form on every save, with no refusal. A writer
panel of the wiki-markup authors in the README's `## Audience` settles each spelling Jira's help
leaves open.
### 193. Write ADF as Jira wiki markup, carrying in Jira's `{adf}` macro each node and mark wiki markup cannot spell.
@@ -64,25 +67,25 @@ mark; item 195's reader adds the round-trip property.
### 194. Write ADF as Jira wiki markup alone, dropping the form and keeping the content of what wiki markup cannot spell.
The lossy wiki writer the maintainer asked for beside the lossless one, 2026-11-15, under Goal 7.
It shares the lossless writer's spellings and differs only where that writer would carry.
Goal 7. The maintainer asked for it beside the lossless writer, 2026-11-15. It spells as the
lossless writer does, except where that writer would use the `{adf}` macro.
### 195. Read Jira wiki markup into ADF, `{adf}` carries included, as `spec/wiki.md` says.
### 195. Read Jira wiki markup into ADF, `{adf}` macros included, as `spec/wiki.md` says.
A hand-written reader, as `htmlToAdf` is. Ships with the property that what the lossless writer of
item 193 writes reads back deep-equal, and with refusals whose codes come from the closed list.
### 196. Document the wiki calls in the README, with a row comparing them with Atlassian's `WikiMarkupTransformer`.
Last of the items splitting item 148: a Quick start section per direction, the calls table, the
guarantees, and a row in the comparison tables per docs/decisions.md §The comparison tables list
every ADF converter that starts and converts.
A Quick start section per direction, the calls table and the guarantees. The comparison tables
gain a row, as the decision "The comparison tables list every ADF converter that starts and
converts" asks.
### 137. Read foreign HTML in `htmlToAdf` the three ways `docs/decisions.md` §Foreign HTML sorts three ways states.
### 137. Read foreign HTML in `htmlToAdf` best effort, never refusing it, as `docs/decisions.md` §Foreign HTML reads best effort and is never refused states.
HTML from emails, CMSs and editors into ADF is the most asked need on the Atlassian developer
community, README goal 12. It reads through `htmlToAdf` alone, with no option, as docs/decisions.md
§`htmlToAdf` reads any HTML, with no option and no second call records.
Reading HTML from emails, CMSs and editors is the most asked need on the Atlassian developer
community. A developer panel picked `htmlToAdf` itself, with no option, as `docs/decisions.md`
records.
### 172. Build one test per reader or case in place of a loop inside a test body, in the 26 test files that loop.