From 63494c56577cb81d908008c48e22d97dae1abdb0 Mon Sep 17 00:00:00 2001 From: Lilleman auf Larv Date: Wed, 14 Oct 2026 20:00:04 +0200 Subject: [PATCH] =?UTF-8?q?Answer=20stability=20round=201:=200=20?= =?UTF-8?q?=F0=9F=94=B4,=203=20=F0=9F=9F=A1;=20pin=20the=20comparison's=20?= =?UTF-8?q?dependency=20tree=20by=20date,=20print=20what=20reads=20back,?= =?UTF-8?q?=20let=20Renovate=20watch=20its=20image?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CHANGELOG.md | 1 - README.md | 9 +++++---- converter-comparison/compare.mjs | 15 ++++++++------- converter-comparison/run.sh | 5 +++-- renovate.json | 2 +- todo.md | 3 ++- 6 files changed, 19 insertions(+), 16 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b227b2f..a1fce10 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,7 +10,6 @@ cannot take as `!adf:carry{json="…"}`. `MIGRATION.md` says how to convert stored markdown. - `losslessMarkdownToAdf` names the CommonMark spelling to write when it refuses a directive whose node CommonMark spells, such as `[![alt](url)](href)` for a linked `!adf:mediaSingle`. - - The README compares the package with seven other ADF converters, each checked against its published version. diff --git a/README.md b/README.md index 1ee4426..a333776 100644 --- a/README.md +++ b/README.md @@ -194,15 +194,16 @@ UI. They know markdown and not ADF, and rely on every spelling saying what it me ## Other ADF converters -Serves [Goals](#goals) 3. Each package at the version named, checked 2026-10-14 by running its -published code on one document holding marks, a link, a mention, a status, a panel and a list, and +Serves [Goals](#goals) 3. Every npm package converting ADF to or from markdown with over 1,000 +downloads a week, at the version named, checked 2026-10-14 by running its published code with its +default options on one document holding marks, a link, a mention, a status, a panel and a list, and on one holding a node type it cannot know: [`converter-comparison/`](https://github.com/larvit/adf-codec/tree/main/converter-comparison). -| Package | Converts | ADF to markdown to ADF | A node type it does not know | Formats | Runtime dependencies | +| Package | Converts | ADF to markdown to ADF | A node type it does not know | Formats | Direct runtime dependencies | | --- | --- | --- | --- | --- | --- | | `@larvit/adf-codec` 0.2.0 | both ways | the same document | kept | markdown: lossless, portable, CommonMark | 0 | -| `@atlaskit/editor-markdown-transformer` 6.3.1 | markdown to ADF, through `@atlaskit/editor-json-transformer`; ADF to markdown throws "not implemented" | – | – | markdown | 5 | +| `@atlaskit/editor-markdown-transformer` 6.3.1 | markdown to ADF, through `@atlaskit/editor-json-transformer` 10.0.0; ADF to markdown throws "This is not implemented yet" | – | – | markdown | 5 | | `adf-to-markdown` 1.0.1 | ADF to markdown | – | dropped with its text | markdown | 0 | | `adf-to-md` 1.2.1 | ADF to markdown | – | dropped with its text, as are mentions, statuses and panels | markdown | 1 | | `adf2markdown` 1.2.0 | ADF to markdown | – | its text kept | markdown | 0 | diff --git a/converter-comparison/compare.mjs b/converter-comparison/compare.mjs index 66c4e46..f52d6f8 100644 --- a/converter-comparison/compare.mjs +++ b/converter-comparison/compare.mjs @@ -1,15 +1,15 @@ -import { createRequire } from "node:module"; -import { readFileSync } from "node:fs"; -import { isDeepStrictEqual } from "node:util"; -import * as atlaskitJson from "@atlaskit/editor-json-transformer"; -import * as atlaskitMarkdown from "@atlaskit/editor-markdown-transformer"; +import * as adf2markdown from "adf2markdown"; import * as adfCodec from "@larvit/adf-codec"; import * as adfToMarkdown from "adf-to-markdown"; import adfToMd from "adf-to-md"; -import * as adf2markdown from "adf2markdown"; +import * as atlaskitJson from "@atlaskit/editor-json-transformer"; +import * as atlaskitMarkdown from "@atlaskit/editor-markdown-transformer"; +import { createRequire } from "node:module"; import * as extendedParser from "extended-markdown-adf-parser"; +import { isDeepStrictEqual } from "node:util"; import * as marklassian from "marklassian"; import mdToAdf from "md-to-adf"; +import { readFileSync } from "node:fs"; const { defaultSchema } = createRequire(import.meta.url)("@atlaskit/adf-schema/schema-default"); @@ -78,7 +78,8 @@ for (const [name, { toAdf, toMarkdown }] of Object.entries(converters)) { console.log("runtime dependencies:", Object.keys(manifest.dependencies ?? {}).length); const written = toMarkdown && show("ADF to markdown", () => toMarkdown(roundTripDoc)); if (written !== undefined) { - if (toAdf) show("round-trip deep-equal", () => isDeepStrictEqual(toAdf(written), roundTripDoc)); + const readBack = toAdf && show("read back", () => toAdf(written)); + if (readBack !== undefined) console.log("round-trip deep-equal:", isDeepStrictEqual(readBack, roundTripDoc)); const unknown = show("unknown node to markdown", () => toMarkdown(unknownNodeDoc)); if (toAdf && unknown !== undefined) show("unknown node read back", () => toAdf(unknown)); } diff --git a/converter-comparison/run.sh b/converter-comparison/run.sh index 8541913..cd35ab0 100755 --- a/converter-comparison/run.sh +++ b/converter-comparison/run.sh @@ -2,9 +2,10 @@ # Re-checks the README's comparison table against each package's published version. set -eu here=$(cd "$(dirname "$0")" && pwd) +node_image=node:24.21.0-alpine3.24 docker run --rm --ulimit core=0 -u "$(id -u):$(id -g)" -e HOME=/tmp -v "$here:/comparison:ro" -w /tmp \ - node:24.21.0-alpine3.24 sh -c ' - npm install --ignore-scripts --no-audit --no-fund --silent \ + "$node_image" sh -c ' + npm install --before=2026-10-15 --ignore-scripts --no-audit --no-fund --silent \ @atlaskit/editor-json-transformer@10.0.0 \ @atlaskit/editor-markdown-transformer@6.3.1 \ @larvit/adf-codec@0.2.0 \ diff --git a/renovate.json b/renovate.json index c44b383..1d36104 100644 --- a/renovate.json +++ b/renovate.json @@ -16,7 +16,7 @@ "datasourceTemplate": "docker", "depNameTemplate": "node", "description": "Pin the node image the gate runs", - "managerFilePatterns": ["docker-runner.sh"], + "managerFilePatterns": ["converter-comparison/run.sh", "docker-runner.sh"], "matchStrings": ["node_image=node:(?[0-9][^\\s\"']*)"], "versioningTemplate": "docker" }, diff --git a/todo.md b/todo.md index cb9d590..195a9d5 100644 --- a/todo.md +++ b/todo.md @@ -71,7 +71,8 @@ ### 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. Each post links the GitHub repository, the README's comparison table and a README that opens with -what the package is. We draft each post for the place it goes; the maintainer posts them once +what the package is. Before posting, `converter-comparison/run.sh` checks the table again with +`0.3.0` and today's date in `--before`. We draft each post for the place it goes; the maintainer posts them once `0.3.0` is published. Found while planning discoverability, 2026-10-04. ### 114. Build code-marked text holding no mark besides `link` and `annotation`, in every reader, and have `adfToLosslessMarkdown` carry code text holding any other mark.