larvit/adf-codec
3
0
Fork 0
Code Pull Requests 1 Actions Activity

3d — the online sandbox, lossy conversion, and @atlaskit/adf-schema evaluation #55

Closed
lilleman wants to merge 1 commits from todo-sandbox-lossy-schema into main
pull from: todo-sandbox-lossy-schema
merge into: larvit:main
Conversation 0 Commits 1 Files Changed 3
+37 -17
3 changed files with 37 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Showing only changes of commit 636fe19e59 - Show all commits
README.md
+2 -2
View File
@@ -3,8 +3,8 @@
Lossless conversion between **Atlassian Document Format** (ADF), an extended markdown flavour, and Lossless conversion between **Atlassian Document Format** (ADF), an extended markdown flavour, and
an HTML dialect. an HTML dialect.
**Status: pre-release — the markdown round-trip (`adfToMarkdown`, `markdownToAdf`); HTML not **Status: published — the markdown round-trip (`adfToMarkdown`, `markdownToAdf`); HTML at
yet.** `0.3.0`.**
Plan: `todo.md`. Decisions: `AGENTS.md`. The flavour's grammar: Plan: `todo.md`. Decisions: `AGENTS.md`. The flavour's grammar:
[`spec/flavour.md`](spec/flavour.md). [`spec/flavour.md`](spec/flavour.md).
todo-history.md
+20
View File
@@ -532,3 +532,23 @@ Under **3 — `markdownToAdf` (`0.1.0`)**:
`instrumentisto/geckodriver`, currency over size — the leg's whole worth is a real `instrumentisto/geckodriver`, currency over size — the leg's whole worth is a real
SpiderMonkey, which decays the moment the pin stops moving, and the smaller image was four SpiderMonkey, which decays the moment the pin stops moving, and the smaller image was four
Firefox majors behind with a publisher that may go quiet while Renovate stays silent. Firefox majors behind with a publisher that may go quiet while Renovate stays silent.
## 5 — Ship `0.1.0`
- [ ] **5 — Ship `0.1.0`.** Only the maintainer's own acts are left (§15): make the Gitea repo
public (§6), create the `NPM_TOKEN` secret, confirm the Actions token may push tags — the
publish succeeds and the tag push then reddens the run, though the next push to `main`
retries the tag alone — and open the bump PR that sets `version` to `0.1.0` and drops
`private: true`, the guard against any earlier publish. The bump and the drop go in one
commit: dropping `private` alone publishes `0.0.0`, which also differs from npm's nothing. `0.1.0` is the
markdown round-trip: both markdown directions, the types, `isAdfDocument`, proved over the
checked-in corpus.
**Settled** (the maintainer, 2026-09-01): the round-trip proved over the checked-in corpus
is what `0.1.0` ships on, and the open-ended proof work follows it rather than gating it —
3k's spec suite and 4's generators and maintainer-supplied payloads are `0.2.0`, 4b's retry
`0.1.1`. A consumer using the library is worth more than a wider proof nobody has needed
yet, and §8's pre-1.0 rules cover what the wider proof then finds.
**Shipped** 2026-09-05: `@larvit/adf-codec@0.1.0` published and `v0.1.0` tagged on `8a847de`. Publishing needed a
bypass-2FA token — the account carrying no write-2FA requirement was not enough, npm demanded an
OTP until the token itself bypassed it.
todo.md
+15 -15
View File
@@ -5,8 +5,8 @@ milestone. A done item shrinks to its title here; its full text moves to `todo-h
## Milestones ## Milestones
Shipping order: 3h, 3i, 3j, 5a, 5b, 5c, 5d, 5 → `0.1.0`; 4b, 4c and 4d → `0.1.1`; 4, 3k → `0.2.0`; Shipping order: 3h, 3i, 3j, 5a, 5b, 5c, 5d, 5 → `0.1.0` (shipped 2026-09-05); 5e before 2027-01; 4b, 4c and 4d → `0.1.1`; 4, 3k → `0.2.0`;
6, 7 → `0.3.0`. 6, 7 → `0.3.0`; 9, 10, 11 → TBD.
The numbering is the order the work was planned in, not the order it ships. The numbering is the order the work was planned in, not the order it ships.
- [x] **0 — Scaffold.** - [x] **0 — Scaffold.**
@@ -126,19 +126,16 @@ The numbering is the order the work was planned in, not the order it ships.
rather than promoting the gate's `dist`, and unmeasured until the log shows them. Per-leg rather than promoting the gate's `dist`, and unmeasured until the log shows them. Per-leg
timing is what turns "slow or hung" from a guess into a reading; the browser leg's own timing is what turns "slow or hung" from a guess into a reading; the browser leg's own
5.4–7.9s against a 17s warm gate is the number that made it obviously cheap. 5.4–7.9s against a 17s warm gate is the number that made it obviously cheap.
- [ ] **5 — Ship `0.1.0`.** Only the maintainer's own acts are left (§15): make the Gitea repo - [x] **5 — Ship `0.1.0`.**
public (§6), create the `NPM_TOKEN` secret, confirm the Actions token may push tags — the - [ ] **5e — The publish token's deadline (before 2027-01).** `0.1.0` published only once the npm
publish succeeds and the tag push then reddens the run, though the next push to `main` token carried **Bypass 2FA**: the account requiring no 2FA on writes was not enough, and npm
retries the tag alone — and open the bump PR that sets `version` to `0.1.0` and drops answered `EOTP` until the token itself bypassed. npm retires bypass-2FA tokens for direct
`private: true`, the guard against any earlier publish. The bump and the drop go in one publishing around January 2027, and its replacement — trusted publishing over OIDC —
commit: dropping `private` alone publishes `0.0.0`, which also differs from npm's nothing. `0.1.0` is the supports GitHub Actions, GitLab CI, CircleCI and Buildkite, not Gitea or self-hosted
markdown round-trip: both markdown directions, the types, `isAdfDocument`, proved over the runners. So the release path has an expiry date and no drop-in successor yet. Revisit before
checked-in corpus. the deadline: whether npm has added Gitea or self-hosted OIDC, and otherwise whether the
**Settled** (the maintainer, 2026-09-01): the round-trip proved over the checked-in corpus release moves to a human-approved staged publish — which fits badly with publish-on-merge,
is what `0.1.0` ships on, and the open-ended proof work follows it rather than gating it — and is the trade to weigh rather than discover on a red release run.
3k's spec suite and 4's generators and maintainer-supplied payloads are `0.2.0`, 4b's retry
`0.1.1`. A consumer using the library is worth more than a wider proof nobody has needed
yet, and §8's pre-1.0 rules cover what the wider proof then finds.
- [x] **5a — Rename to `@larvit/adf-codec`.** - [x] **5a — Rename to `@larvit/adf-codec`.**
- [x] **5b — The consumer's error surface.** - [x] **5b — The consumer's error surface.**
- [x] **5b1 — The error's source position.** - [x] **5b1 — The error's source position.**
@@ -152,6 +149,9 @@ The numbering is the order the work was planned in, not the order it ships.
- [ ] **7 — HTML, ship `0.3.0`.** `adfToHtml`, `htmlToAdf`, the composed `markdownToHtml` / - [ ] **7 — HTML, ship `0.3.0`.** `adfToHtml`, `htmlToAdf`, the composed `markdownToHtml` /
`htmlToMarkdown`. CommonMark spec suite runs against `markdownToHtml` from here (§10). `htmlToMarkdown`. CommonMark spec suite runs against `markdownToHtml` from here (§10).
- [ ] **8 — CLI.** A later goal, shaped around the personas once the library exists. - [ ] **8 — CLI.** A later goal, shaped around the personas once the library exists.
- [ ] **9 — The online sandbox.** A web page with two textboxes converting back and forth between ADF and markdown, powered by the library's browser build.
- [ ] **10 — Lossy conversion.** A direction that only converts what Markdown supports. Data from the ADF is preserved but format, design and other non-markdown constructs are dropped.
- [ ] **11 — Evaluate `@atlaskit/adf-schema`.** Determine whether `@atlaskit/adf-schema` should be added as a dev dependency to serve as truth for the ADF schema.
## The ADF inventory to cover ## The ADF inventory to cover