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

Answer prose round 1: 4 🔴, 6 🟡 (0 misread); state the shapes moved and what holds today, and drop the mark rule

This commit is contained in:
2026-11-04 20:51:28 +01:00
committed by Lillem4n
parent 5af77d0a5e
commit 7a7b12b6a7
4 changed files with 49 additions and 46 deletions
+1 -1
View File
@@ -59,7 +59,7 @@ In `docs/decisions.md`:
- Posts announcing a release wait for its publish, and their drafts wait for the finished release - Posts announcing a release wait for its publish, and their drafts wait for the finished release
- A chunk ruled worse merges where a plan item of its release already restores that code's reading, and that item takes the ruling's places - A chunk ruled worse merges where a plan item of its release already restores that code's reading, and that item takes the ruling's places
- A chunk ruled worse that restructures the places takes a paired ruling after each restructure, against the same base, and merges once one is not worse - A chunk ruled worse that restructures the places takes a paired ruling after each restructure, against the same base, and merges once one is not worse
- The first step checks the schema, and no converter does - Schema refusals are made in the first step alone
- The gate runs on Deno and Bun - The gate runs on Deno and Bun
- The gate installs the tarball - The gate installs the tarball
- Firefox reads the build - Firefox reads the build
+26 -23
View File
@@ -297,7 +297,7 @@ besides hard breaks but no node that takes a link: the panel refused to have
breaks alone still reads as its destination, then the breaks (§An image reads as an image only alone breaks alone still reads as its destination, then the breaks (§An image reads as an image only alone
in its paragraph). `adfToLosslessMarkdown` writes a node holding a mark its type does not take as in its paragraph). `adfToLosslessMarkdown` writes a node holding a mark its type does not take as
`!adf:carry`, so the round-trip holds, except an inline card a link marks, which is refused `!adf:carry`, so the round-trip holds, except an inline card a link marks, which is refused
(§The first step checks the schema, and no converter does). (§Schema refusals are made in the first step alone).
## A linked image is written `[![alt](url)](href)`, a captioned image as its directive ## A linked image is written `[![alt](url)](href)`, a captioned image as its directive
@@ -442,7 +442,7 @@ it joins the second panel's `<a>` to that portable spelling.
HTML nests no `<a>` in an `<a>`, so no element can hold both a card's URL and the target of a link HTML nests no `<a>` in an `<a>`, so no element can hold both a card's URL and the target of a link
marking it. Every writer refuses such a card, and a carry element holding one, as the maintainer marking it. Every writer refuses such a card, and a carry element holding one, as the maintainer
chose on 2026-11-04 over a new spelling (§The first step checks the schema, and no converter does). chose on 2026-11-04 over a new spelling (§Schema refusals are made in the first step alone).
A fifth panel (2026-11-04, three readers in the same roles, then four more for what the first three A fifth panel (2026-11-04, three readers in the same roles, then four more for what the first three
split on) was asked how to write a mention, emoji, status, date and inline card, which until then split on) was asked how to write a mention, emoji, status, date and inline card, which until then
@@ -749,31 +749,34 @@ stays on `insideRun` alone, since it answers the parted line. A refactor that me
so the chunk's later rulings read against that merge, the commit `larv-review ruling-base` prints. A restructure past a so the chunk's later rulings read against that merge, the commit `larv-review ruling-base` prints. A restructure past a
pass's round cap still goes unreviewed, so the PR summary names it. pass's round cap still goes unreviewed, so the PR summary names it.
## The first step checks the schema, and no converter does ## Schema refusals are made in the first step alone
2026-11-04, the maintainer. Goal 1 and code health. Valid while Atlassian's schema forbids shapes 2026-11-04, replacing §No schema validation of 2026-08-23 (its mark refusal 2026-08-25) and the
a converter would otherwise meet. entry of this date that kept the card refusal alone, the maintainer. Goal 1 and code health. Valid
while Atlassian's schema forbids shapes a converter would otherwise meet.
An Atlassian-schema rule the library applies is checked once, in the first step every call opens A shape Atlassian's schema forbids, and the library refuses, is refused in the first step, where
with: `writableContent` for the writers, `carriedNode` for the carry readers `losslessMarkdownToAdf` the document is checked once: `writableContent` opens every writer, and `carriedNode` opens every
and `htmlToAdf`. A converter checks none, so a document one call refuses every call refuses, at carry reader's node. No converter refuses one. A document one call refuses on a schema rule every
the same path, and what a converter holds is valid ADF. An `inlineCard` with a `link` mark is call refuses alike, with one code, message and path, wherever the shape stands, in a carried node
refused there today, as `unsupported-node-shape` at the card's path, wherever it stands, since the too. The first step refuses an `inlineCard` with a `link` mark as `unsupported-node-shape`: the
schema gives a card the `annotation` mark alone (§The node tables answer to Atlassian's schema) schema gives a card the `annotation` mark alone (§The node tables answer to Atlassian's schema),
and HTML nests no `<a>` in an `<a>`. `todo.md` item 167 moves the other refusals a writer makes on a schema and HTML nests no `<a>` in an `<a>`. `adfToLosslessMarkdown` still refuses two more, on a node not
rule: a node holding a mark type twice, a node holding `text`, or `content` where it takes none, riding the carry: a block or non-text inline node holding `text`, and a leaf block or non-text
and an inline node holding neither. inline node holding `content`. `todo.md` item 167 moves them, and until it ships this entry does
not hold for them.
A rule joins the first step as a refusal only where no format can spell the node whole. A node type, Nothing else joins the first step. Nothing refuses a node type, mark or attribute the schema does
mark or attribute the schema does not name, a known node where no section spells it not name (§Unknown nodes ride the carry), a known node where no section spells it, or a mark a node
(§Unknown nodes ride the carry), and a mark a node cannot hold (§A mark skips a node that cannot cannot hold (§A mark skips a node that cannot hold it), so they ride the carry. A refusal that is
hold it) ride the carry, which keeps the round-trip. A limit of the engine or the flavour is no no schema rule stays where it is met: a node holding one mark type twice, which the schema allows
schema rule and stays where it is met: nesting depth, output length and what a portable line can and no spelling holds; nesting depth; output length; what a portable line can spell; and a
spell. A reader refusing markdown or HTML it cannot read is no check of ADF and stays in the reader. reader's refusal of markdown or HTML it cannot read. A schema refusal a converter gains later is
made in the first step too.
The earlier entry kept the card refusal alone, premising that the site a document is saved to The earlier entries premised that the site a document is saved to validates the rest. A
validates the rest. A hand-built document has not reached the site yet, and the viewer/editor hand-built document has not reached the site yet, and the viewer/editor persona relies on a
persona relies on a refusal arriving before the save. refusal arriving before the save.
## The gate runs on Deno and Bun ## The gate runs on Deno and Bun
+1 -1
View File
@@ -147,7 +147,7 @@ export function nodeMarks(node: { marks?: AdfMark[] }): readonly AdfMark[] {
return node.marks ?? [] return node.marks ?? []
} }
// Walks every node, carried or of an unknown type, so a link-marked card is refused wherever it stands (docs/decisions.md §The first step checks the schema, and no converter does). // Walks every node, carried or of an unknown type, so a link-marked card is refused wherever it stands (docs/decisions.md §Schema refusals are made in the first step alone).
export function refusedShape(content: readonly AdfNode[]): ConvertError | undefined { export function refusedShape(content: readonly AdfNode[]): ConvertError | undefined {
type Step = { index: number; node: AdfNode; parent: Step | undefined } type Step = { index: number; node: AdfNode; parent: Step | undefined }
const pending: Step[] = content.map((node, index) => ({ index, node, parent: undefined })).reverse() const pending: Step[] = content.map((node, index) => ({ index, node, parent: undefined })).reverse()
+21 -21
View File
@@ -17,7 +17,7 @@
| 165 | 0.3.0 | 164 | | **Have a reader panel seated from `## Audience` judge each feature-table row reasonable or not, and file an item for each row it rejects.** | 2 | 2 | 1 | 3 | 3 | 6 by 5 | 7.5 | | 165 | 0.3.0 | 164 | | **Have a reader panel seated from `## Audience` judge each feature-table row reasonable or not, and file an item for each row it rejects.** | 2 | 2 | 1 | 3 | 3 | 6 by 5 | 7.5 |
| 132 | 0.3.0 | | | **Write tables as `<table>` in `adfToHtml` and read them back in `htmlToAdf`, in place of the carry element.** | 2 | 2 | 2 | 4 | 5 | 6 by 4 | 2.4 | | 132 | 0.3.0 | | | **Write tables as `<table>` in `adfToHtml` and read them back in `htmlToAdf`, in place of the carry element.** | 2 | 2 | 2 | 4 | 5 | 6 by 4 | 2.4 |
| 73 | 0.3.0 | 132, 163, 165 | | **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.** | 1 | 2 | 2 | 3 | 2 | 3 by 8 | 16.9 | | 73 | 0.3.0 | 132, 163, 165 | | **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.** | 1 | 2 | 2 | 3 | 2 | 3 by 8 | 16.9 |
| 167 | 0.3.0 | | decision | **Check every Atlassian-schema rule a writer refuses today in `writableContent`, and drop it from the writers.** | 3 | 1 | 2 | 4 | 5 | code health by 5 | 13.1 | | 167 | 0.3.0 | | decision | **Refuse in `refusedShape` the schema-forbidden shapes `adfToLosslessMarkdown` refuses in its walk, and drop them from that writer.** | 3 | 1 | 2 | 4 | 5 | code health by 5 | 13.1 |
| 72 | 0.3.0 | 132 | 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.** | 1 | 2 | 1 | 2 | 1 | 3 by 1 | 2.5 | | 72 | 0.3.0 | 132 | 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.** | 1 | 2 | 1 | 2 | 1 | 3 by 1 | 2.5 |
| 153 | 0.4.0 | | question | **Decide whether `src/markdown/` root may import `emit/`, `parse/` or `portable/`, and hold the answer in `.oxlintrc.json` and §The source parts by ADF and format.** | 1 | 2 | 2 | 3 | 2 | code health by 3 | 26.2 | | 153 | 0.4.0 | | question | **Decide whether `src/markdown/` root may import `emit/`, `parse/` or `portable/`, and hold the answer in `.oxlintrc.json` and §The source parts by ADF and format.** | 1 | 2 | 2 | 3 | 2 | code health by 3 | 26.2 |
| 156 | 0.4.0 | | | **Stop a leg's container when its script is interrupted, so Ctrl-C ends `ci.sh` or `mutation-tests/run.sh` at once.** | 1 | 2 | 1 | 2 | 1 | code health by 2 | 20.9 | | 156 | 0.4.0 | | | **Stop a leg's container when its script is interrupted, so Ctrl-C ends `ci.sh` or `mutation-tests/run.sh` at once.** | 1 | 2 | 1 | 2 | 1 | code health by 2 | 20.9 |
@@ -106,29 +106,29 @@ solves it, then links the GitHub repository, the README's comparison table and t
opening. The maintainer posts them once `0.3.0` is published (`docs/decisions.md` §Posts opening. The maintainer posts them once `0.3.0` is published (`docs/decisions.md` §Posts
announcing a release wait for its publish). Found while planning discoverability, 2026-10-04. announcing a release wait for its publish). Found while planning discoverability, 2026-10-04.
### 167. Check every Atlassian-schema rule a writer refuses today in `writableContent`, and drop it from the writers. ### 167. Refuse in `refusedShape` the schema-forbidden shapes `adfToLosslessMarkdown` refuses in its walk, and drop them from that writer.
The maintainer's call, 2026-11-04 (`docs/decisions.md` §The first step checks the schema, and no The maintainer's call, 2026-11-04 (`docs/decisions.md` §Schema refusals are made in the first step
converter does): the first step holds every schema check, "moved there from wherever else in the alone): the first step holds every schema check, "moved there from wherever else in the code they
code they are". It replaces item 68, which would have carried these shapes: a schema-forbidden are". It replaces item 68, which would have carried these shapes. Move into `refusedShape`:
shape is refused once, with its path, in every writer. Move into `refusedShape`:
- `emitLeaf` in `emit/inline-line.ts`: a node holding one mark type twice, and an inline node - `emitDirectiveBlock` in `emit/adf-to-markdown.ts`: a block holding `text`, and a leaf block
holding neither `content` nor `text`. holding `content`.
- `emitDirectiveBlock` in `emit/adf-to-markdown.ts`: a node holding `text`, and a leaf block holding - `emitLeaf` in `emit/inline-line.ts`: a non-text inline node holding `content` or `text`.
`content`.
- The HTML and portable writers, which today write the first two without refusing: they refuse them
too, which is breaking for a document holding either (`CHANGELOG.md`, `MIGRATION.md`).
- Check `src/html/` and `src/markdown/portable/` for a refusal of this kind the grep of
`unsupported-node-shape` missed, and `carriedNode` for a rule the readers still build.
Stays where it is: a limit of the engine or the flavour (nesting depth, output length, a portable Atlassian's schema gives each such node no `text` or `content` (`additionalProperties` is false).
task list holding what no list item spells) and a reader's refusal of markdown or HTML it cannot Breaking: `adfToHtml` and `adfToPortableMarkdown` refuse these shapes too, and so does
read. A node type, mark or attribute the schema does not name, a known node out of place and a mark `adfToLosslessMarkdown` inside a node that rides the carry, where it writes them today. Say so in
a node cannot hold keep riding the carry. Drop the refused shapes from the README's `CHANGELOG.md` and `MIGRATION.md`. Search the writers for any other refusal of a shape the schema
`unsupported-node-shape` causes under writing and from `spec/flavour.md`; the property generators forbids, and `carriedNode` for one the readers still build.
build none of them. Lands with items 45, 77 and 80 where it can, since their reader walks every
node too, but needs none. Stays where it is: a node holding one mark type twice (the schema allows it, no spelling holds it),
nesting depth, output length, a portable task list holding what no list item spells, and a
reader's refusal of markdown or HTML it cannot read. A node type, mark or attribute the schema does
not name, a known node out of place and a mark a node cannot hold keep riding the carry. Drop the
refused shapes from the README's `unsupported-node-shape` cause under writing in
`adfToLosslessMarkdown` and add them to the cause common to the writers, and from `spec/flavour.md`;
the property generators build none of them.
### 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. ### 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.