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

Publish the bundle size in the README and fail the gate when it drifts a tenth

This commit is contained in:
2026-11-15 13:37:58 +01:00
committed by Lillem4n
parent 0a6522aa62
commit 6b7a8e691b
14 changed files with 698 additions and 36 deletions
+1
View File
@@ -66,6 +66,7 @@ In `docs/decisions.md`:
- Firefox reads the build
- The coverage floors
- The size ratchet
- The published size is a bundler's output, checked within a tenth
- Properties on a fixed seed
- The CommonMark suite checks three ways
- The flavour spec is read as a source
+1
View File
@@ -2,6 +2,7 @@
## Unreleased
- The README states the package's size: 71 kB minified and gzipped as a bundler ships it, 161 kB packed and 601 kB unpacked, and a size column in the comparison table; the release pipeline fails where a figure is a tenth off.
- `adfToHtml` writes a media single, a media group and a caption as `<figure class="adf-media-single">` holding an
`<img>` and a `<figcaption>`, and as `<div class="adf-media-group">` of `<span class="adf-file">` files, where
`0.3.1` wrote the carry element, and `htmlToAdf` reads them back. A link around the image is the media's link
+25 -21
View File
@@ -301,27 +301,29 @@ On 2026-11-05, [`converter-comparison/`](https://github.com/larvit/adf-codec/tre
ran each other package's published code at the version the table names, and this package's latest
release, with default options. A package writing markdown got a document holding marks, a link, a mention, a status, a panel and a
list, and a document holding a node type it cannot know. A package reading markdown got markdown
holding the same marks and link.
holding the same marks and link. The last column is what a bundler ships for the package: esbuild 0.28.2
bundles the package and its dependencies for Node, minifies the bundle and gzips it at level 9. The figure
for this package is the current source's.
| Package | Converts | ADF to markdown to ADF | A node type it does not know | Formats | Direct runtime dependencies |
| --- | --- | --- | --- | --- | --- |
| `@larvit/adf-codec` | both ways | the same document | kept | markdown: lossless, portable; CommonMark in; HTML out; its own HTML in | 0 |
| `@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 |
| `@faulander/md2adf` 1.0.0 | both ways | a different document: the status is gone, the mention's `id` becomes its text and the panel a quote | dropped with its text | markdown | 2 |
| `@nthings.dev/adf4j-wasm` 1.0.2 | ADF to markdown | – | replaced by the text `[Unsupported: futureThing]` | GitHub Flavored Markdown, from WebAssembly | 0 |
| `@wrtnlabs/markdown-to-adf` 1.0.2 | markdown to a list of blocks, not a document; fails ordinary input: `***bold italic***` comes out as italic text holding asterisks, and a paragraph holding a hard break stands between blocks | – | – | markdown | 2 |
| `adf-converter` 0.1.0 | ADF to markdown; writes a mention as `@@Ann` | – | its text kept, with a console message | markdown | 0 |
| `adf-md` 0.2.0 | both ways | a different document: the status without its `localId`, the marks in the other order | dropped with its text | markdown with MDX tags for panels, mentions and statuses | 6 |
| `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 |
| `extended-markdown-adf-parser` 2.4.0 | both ways | a different document: the mention comes back as linked text, the status without its `localId` | written as JSON, read back as a paragraph of that JSON's text | markdown | 9 |
| `github-markdown-adf` 1.3.0 | both ways | a different document: the mention comes back as text, the status as inline code, the marks in the other order | dropped with its text | markdown | 3 |
| `markdown-to-adf` 0.2.20 | markdown to ADF; fails ordinary input: a quote is written as the node type `blockQuote`, which ADF spells `blockquote` | – | – | markdown | 3 |
| `marklassian` 1.2.1 | markdown to ADF | – | – | markdown | 1 |
| `md-adf` 0.2.2 | both ways, with a warning for each fallback | a different document: the mention and the status come back as text, the marks in the other order, the panel as a quote | dropped with its text, with a warning | markdown | 5 |
| `md-to-adf` 0.6.4 | markdown to ADF; fails ordinary input: each list item is written as a list of its own | – | – | markdown | 2 |
| `mdast-util-from-adf` 2.3.0 | ADF to an mdast tree, which `mdast-util-to-markdown` 2.2.2 writes as markdown; throws on a status | – | throws | markdown | 3 |
| Package | Converts | ADF to markdown to ADF | A node type it does not know | Formats | Direct runtime dependencies | Minified and gzipped, with its dependencies |
| --- | --- | --- | --- | --- | --- | --- |
| `@larvit/adf-codec` | both ways | the same document | kept | markdown: lossless, portable; CommonMark in; HTML out; its own HTML in | 0 | 71 kB |
| `@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 | 177 kB |
| `@faulander/md2adf` 1.0.0 | both ways | a different document: the status is gone, the mention's `id` becomes its text and the panel a quote | dropped with its text | markdown | 2 | 99 kB |
| `@nthings.dev/adf4j-wasm` 1.0.2 | ADF to markdown | – | replaced by the text `[Unsupported: futureThing]` | GitHub Flavored Markdown, from WebAssembly | 0 | 0.8 kB, and a WebAssembly module of 6.8 MB gzipped |
| `@wrtnlabs/markdown-to-adf` 1.0.2 | markdown to a list of blocks, not a document; fails ordinary input: `***bold italic***` comes out as italic text holding asterisks, and a paragraph holding a hard break stands between blocks | – | – | markdown | 2 | 21 kB |
| `adf-converter` 0.1.0 | ADF to markdown; writes a mention as `@@Ann` | – | its text kept, with a console message | markdown | 0 | 1.8 kB |
| `adf-md` 0.2.0 | both ways | a different document: the status without its `localId`, the marks in the other order | dropped with its text | markdown with MDX tags for panels, mentions and statuses | 6 | 137 kB |
| `adf-to-markdown` 1.0.1 | ADF to markdown | – | dropped with its text | markdown | 0 | 2.4 kB |
| `adf-to-md` 1.2.1 | ADF to markdown | – | dropped with its text, as are mentions, statuses and panels | markdown | 1 | 1.2 kB |
| `adf2markdown` 1.2.0 | ADF to markdown | – | its text kept | markdown | 0 | 1.1 kB |
| `extended-markdown-adf-parser` 2.4.0 | both ways | a different document: the mention comes back as linked text, the status without its `localId` | written as JSON, read back as a paragraph of that JSON's text | markdown | 9 | 131 kB |
| `github-markdown-adf` 1.3.0 | both ways | a different document: the mention comes back as text, the status as inline code, the marks in the other order | dropped with its text | markdown | 3 | 40 kB |
| `markdown-to-adf` 0.2.20 | markdown to ADF; fails ordinary input: a quote is written as the node type `blockQuote`, which ADF spells `blockquote` | – | – | markdown | 3 | 58 kB |
| `marklassian` 1.2.1 | markdown to ADF | – | – | markdown | 1 | 13 kB |
| `md-adf` 0.2.2 | both ways, with a warning for each fallback | a different document: the mention and the status come back as text, the marks in the other order, the panel as a quote | dropped with its text, with a warning | markdown | 5 | 54 kB |
| `md-to-adf` 0.6.4 | markdown to ADF; fails ordinary input: each list item is written as a list of its own | – | – | markdown | 2 | 6.8 kB |
| `mdast-util-from-adf` 2.3.0 | ADF to an mdast tree, which `mdast-util-to-markdown` 2.2.2 writes as markdown; throws on a status | – | throws | markdown | 3 | 1.3 kB, or 24 kB with `mdast-util-to-markdown` |
The next table lists converters this comparison does not run: other ecosystems' libraries,
Atlassian's own paths, and one npm package that needs a browser. Each row is what the project's
@@ -806,6 +808,7 @@ Serves [Goals](#goals) 8.
| Host APIs | none: pure ECMAScript, no DOM, no `node:` import |
| Module format | ESM only, one entrypoint |
| Registry | public npm, `@larvit/adf-codec` |
| Size | 71 kB minified and gzipped, as a bundler ships it; 161 kB tarball, 601 kB unpacked. The gate fails when a figure is more than a tenth off |
| Types | built JavaScript with `.d.ts` beside it |
Contract: [`docs/decisions.md`](https://github.com/larvit/adf-codec/blob/main/docs/decisions.md#any-es2022-engine),
@@ -840,7 +843,8 @@ Contract: [`docs/decisions.md`](https://github.com/larvit/adf-codec/blob/main/do
All three commands need only Docker, git and bash 5.
- `./ci.sh` runs every check CI runs.
- `./ci.sh` runs every check CI runs. It fails where the size figures in [The package](#the-package) and the
comparison table are more than a tenth off the build's, and names the measured figures.
- `./feature-table/write.sh` rewrites `docs/feature-table.md` from `feature-table/examples.json` and
the build. `./ci.sh` fails where a change leaves that page stale.
- `./mutation-tests/run.sh [<base>]` mutation-tests the lines changed since `<base>`, `origin/main`
+51
View File
@@ -0,0 +1,51 @@
import { build } from "esbuild";
import { execFileSync } from "node:child_process";
import { gzipSync } from "node:zlib";
const bytesPerKilobyte = 1000;
// A published figure stays true while it is within this share of the measure.
const tolerance = 0.1;
// What a consumer's bundler ships for the package: its code and its dependencies, minified, gzipped.
export const minifiedGzippedBytes = async (resolveDir, specifier) => {
const { outputFiles } = await build({
bundle: true,
format: "esm",
logLevel: "silent",
minify: true,
platform: "node",
stdin: { contents: `export * from ${JSON.stringify(specifier)};`, resolveDir },
write: false,
});
return gzipSync(outputFiles[0].contents, { level: 9 }).length;
};
export const packedBytes = (packageDir) => {
const [{ size, unpackedSize }] = JSON.parse(execFileSync("npm", ["pack", "--dry-run", "--json"], { cwd: packageDir, encoding: "utf8", env: { ...process.env, npm_config_update_notifier: "false" } }));
return { tarball: size, unpacked: unpackedSize };
};
const number = "(\\d+(?:\\.\\d+)?)";
const published = [
["minified", "minified and gzipped", new RegExp(`^\\| Size \\|.*?${number} kB minified and gzipped`, "m")],
["tarball", "tarball", new RegExp(`^\\| Size \\|.*?${number} kB tarball`, "m")],
["unpacked", "unpacked", new RegExp(`^\\| Size \\|.*?${number} kB unpacked`, "m")],
];
const tableCell = new RegExp(`^\\| \`@larvit/adf-codec\` \\|.*\\| ${number} kB \\|$`, "m");
const offBy = (claimed, bytes) => Math.abs(Number(claimed) - bytes / bytesPerKilobyte) > tolerance * bytes / bytesPerKilobyte;
const kilobytes = (bytes) => (bytes / bytesPerKilobyte).toFixed(1);
// The README's size claims that no longer match the measure, each as a sentence.
export const drift = (readme, measured) => [
...published.flatMap(([key, label, pattern]) => {
const found = pattern.exec(readme);
if (!found) return [`README has no ${label} figure in its Size row`];
return offBy(found[1], measured[key]) ? [`README says ${found[1]} kB ${label}; measured ${kilobytes(measured[key])} kB`] : [];
}),
...(() => {
const found = tableCell.exec(readme);
if (!found) return ["README's comparison table has no size for @larvit/adf-codec"];
return offBy(found[1], measured.minified) ? [`README's comparison table says ${found[1]} kB for @larvit/adf-codec; measured ${kilobytes(measured.minified)} kB`] : [];
})(),
];
+60
View File
@@ -0,0 +1,60 @@
import assert from "node:assert/strict";
import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { test } from "node:test";
import { drift, minifiedGzippedBytes } from "./figures.mjs";
const fixture = (files) => {
const dir = mkdtempSync(join(tmpdir(), "bundle-size-"));
for (const [path, contents] of Object.entries(files)) {
mkdirSync(join(dir, path, ".."), { recursive: true });
writeFileSync(join(dir, path), contents);
}
return dir;
};
const readmeSaying = (minified, tarball, unpacked, tableCell) =>
`| Size | ${minified} kB minified and gzipped; ${tarball} kB tarball, ${unpacked} kB unpacked |\n` +
`| \`@larvit/adf-codec\` | both ways | a | b | c | 0 | ${tableCell} kB |\n`;
const measured = { minified: 13000, tarball: 60000, unpacked: 220000 };
test("minified size ignores comments and whitespace", async () => {
const bare = fixture({ "entry.js": "export const answer=40+2;" });
const padded = fixture({ "entry.js": "// a comment\nexport const answer = 40 + 2;\n\n\n" });
assert.equal(await minifiedGzippedBytes(padded, "./entry.js"), await minifiedGzippedBytes(bare, "./entry.js"));
});
test("minified size counts the dependencies a bundler pulls in", async () => {
const alone = fixture({ "entry.js": "export const a = 1;" });
const withDependency = fixture({
"entry.js": "export * from 'dep'; export const a = 1;",
"node_modules/dep/index.js": `export const words = ${JSON.stringify(Array.from({ length: 200 }, (_, i) => (i * 2654435761 % 4294967296).toString(36)))};`,
"node_modules/dep/package.json": '{"name":"dep","type":"module","main":"index.js"}',
});
assert.ok(await minifiedGzippedBytes(withDependency, "./entry.js") > await minifiedGzippedBytes(alone, "./entry.js") + 500);
});
test("a README within a tenth of every measure has no drift", () => {
assert.deepEqual(drift(readmeSaying(13, 60, 220, 13), measured), []);
assert.deepEqual(drift(readmeSaying(14, 65, 240, 14), measured), []);
});
test("a figure more than a tenth off is named with its measure", () => {
assert.deepEqual(drift(readmeSaying(13, 60, 220, 11), measured), [
"README's comparison table says 11 kB for @larvit/adf-codec; measured 13.0 kB",
]);
assert.deepEqual(drift(readmeSaying(13, 53, 220, 13), measured), [
"README says 53 kB tarball; measured 60.0 kB",
]);
});
test("a README missing a figure names it", () => {
assert.deepEqual(drift("| Dependencies | none |\n", measured), [
"README has no minified and gzipped figure in its Size row",
"README has no tarball figure in its Size row",
"README has no unpacked figure in its Size row",
"README's comparison table has no size for @larvit/adf-codec",
]);
});
+496
View File
@@ -0,0 +1,496 @@
{
"name": "bundle-size",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"devDependencies": {
"esbuild": "0.28.2"
}
},
"node_modules/@esbuild/aix-ppc64": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.28.2.tgz",
"integrity": "sha512-XExcO+dvLKvVtNTibSTBej1NCAbaGhWn9Ww1ZPx80qsahhPFe/8jgWP0IchNe0F3HwkU7n8ejhH8bjonqht8mQ==",
"cpu": [
"ppc64"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"aix"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/android-arm": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.28.2.tgz",
"integrity": "sha512-kXXoiPVVGQcnIYGOeaovwOURpniDBpSq4A03qkQ+BMQqtGG6HYap3xne9C1O1yo4TR3qxlCX5IqqmX6fFo2Lqg==",
"cpu": [
"arm"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"android"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/android-arm64": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.28.2.tgz",
"integrity": "sha512-5YfKeeI8qWfBZIX+u2xZC3Zlb3Os/gLS2sbEKM+I4ZOcsWmHS2WLysCcQZDAFRslDUU5Oiq44gf6PYN1vGwG5A==",
"cpu": [
"arm64"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"android"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/android-x64": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.28.2.tgz",
"integrity": "sha512-O387ite7SzUyCcy3JQX4P4bLtEA7bLLkx+esve5JHnyYfNTxcVpXZo9jhdB0lTKN44gztELTdU7nS8Nr16Fs1Q==",
"cpu": [
"x64"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"android"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/darwin-arm64": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.28.2.tgz",
"integrity": "sha512-n4KqkOQrraxHJcgjM1RvwbigfQKIKJVpM7xp+KsxiyUSrRdIXnt73VhrPAx0fV44hgfmIVKjxMN9J1t5jySVkw==",
"cpu": [
"arm64"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"darwin"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/darwin-x64": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.28.2.tgz",
"integrity": "sha512-uq6suIWYP37qzGddBKPw5QEQPi6HiLGsO7UmkpfyaYNQ3D+rN6w6WfwH+nuqcGXWvawGwxOEroO4YGnFh95azw==",
"cpu": [
"x64"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"darwin"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/freebsd-arm64": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.28.2.tgz",
"integrity": "sha512-n+I0BTSRIoy+d6RPKnEVwql5UwBJolytvY4mAOIEJorKlqgPII8ix6slVVrfZ5Tnj7glIZvloylbB/EJPMWEXw==",
"cpu": [
"arm64"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"freebsd"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/freebsd-x64": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.28.2.tgz",
"integrity": "sha512-78XJTJkvPs0kz2w61301PJjXl4g7q3JqiYMZ/M/yVI73EHBrCRTgkhu9oqG7vPqq+a/yadEW8aD+agKlk5xrmg==",
"cpu": [
"x64"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"freebsd"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/linux-arm": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.28.2.tgz",
"integrity": "sha512-XlDnu2q5yoqems+xay6wSAcg9DDD7K9RLKZEBOMZm3ckNpJBvOX20tSfby8KfrrhINDyv9V2YVZKY/SpoGJI8w==",
"cpu": [
"arm"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"linux"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/linux-arm64": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.28.2.tgz",
"integrity": "sha512-pW4AC0P3it8c7do9MVM4p51FzHzdM/TZrerurgRcHJ2WTa1VQ1CIq18xncfpBJw4ojkiZZrKW2yIBWBP92j6Ug==",
"cpu": [
"arm64"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"linux"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/linux-ia32": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.28.2.tgz",
"integrity": "sha512-CYbnj78HsIeA+DhgUKgFCfvNsTHFhMMrinUrMZpDXJXKN8T3XViTZ/+wtHeVxEWY8ewSzTFN+nRmSwO2tZaLUQ==",
"cpu": [
"ia32"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"linux"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/linux-loong64": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.28.2.tgz",
"integrity": "sha512-buwkd8nsph4R+ajRvw0qM5Hja/TXQow3ptzWO2EbG/cqcIkHloRrdlBtQlshyYGTNFvfkfJ5tpPLVkY4DtsPfQ==",
"cpu": [
"loong64"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"linux"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/linux-mips64el": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.28.2.tgz",
"integrity": "sha512-ZVykbDyk7519VwiNb9Lcj9m8XM6v5V9uKPvrEMkkEedVewf+0itkhahp4HDpgERXhwLRpWFypsGbG/J8s0QjJA==",
"cpu": [
"mips64el"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"linux"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/linux-ppc64": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.28.2.tgz",
"integrity": "sha512-CAXl+Dtd9UUuJd8pKKdwh6MLm3MUMiqMPmhZ3tTSXPqfyQ3vDl6R5hZdZ/kYojK4ofXtdfSv1tFq8XzWx3heNQ==",
"cpu": [
"ppc64"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"linux"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/linux-riscv64": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.28.2.tgz",
"integrity": "sha512-GeXCej4IQtU1B+QlDV8W/RRvbzI3O/Stss+/bCXv4lZls5WGRtu2a+3JkA3i4qIUlMXpcHebWpF8AkJhATowuA==",
"cpu": [
"riscv64"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"linux"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/linux-s390x": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.28.2.tgz",
"integrity": "sha512-3H1weTYZPxt/WOhByszQZybS9w5lKzUn1FDMsgEChbHWQwHYQQRfBxgCcZvPhjHfKyJjIievvMmEUawJrdY9Dg==",
"cpu": [
"s390x"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"linux"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/linux-x64": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.28.2.tgz",
"integrity": "sha512-4xTZr1FUmSoQW4XIWmit3tzQrUTZM+N3P0XV8xROKYF50XfI7xeO90+1bZvNwxIufQ9hDQVRJH5YhgPVF8A/HQ==",
"cpu": [
"x64"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"linux"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/netbsd-arm64": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.28.2.tgz",
"integrity": "sha512-sSATRjPeDBg3pdgHoQfoYBob11Kk1FGa9lui5RIHZCoCkJa9QKlvl3/vKz2usCmYYjs7ymJR/2Nnsqe+Hjt5nw==",
"cpu": [
"arm64"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"netbsd"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/netbsd-x64": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.28.2.tgz",
"integrity": "sha512-lqnzCV+mM0gIADaKihiCg6ifgfU2L3h5E33rNQBN1Y4MaVGnzryzmvvf7UHxprpQdE8hpqLolJ9Rl+SkIRDpyw==",
"cpu": [
"x64"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"netbsd"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/openbsd-arm64": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.28.2.tgz",
"integrity": "sha512-AL2qJILH7lNjrDmCQDvdxMfAUIv8KMNZOvrwAQ8i8//ntL9FflhOyMJ8OZSMBb8/AWXe3/5v5S20y3zCoZWKoQ==",
"cpu": [
"arm64"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"openbsd"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/openbsd-x64": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.28.2.tgz",
"integrity": "sha512-QtiuPytchRyC4rwUKhexJdQKvDuZ6hWloi3igqPQNUJCS1/v9EiO3UTOXR6A3FoMo4fnAKbWJdqaIwhOzh8qEw==",
"cpu": [
"x64"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"openbsd"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/openharmony-arm64": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.28.2.tgz",
"integrity": "sha512-WkhYDmpTjLvGlScA1rwjRUmhl4k8oXR3cIbtqWmELgU/dFeHHlEllxDvdWcNJV9rbzCexB5vz8gtNewWLgCT7Q==",
"cpu": [
"arm64"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"openharmony"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/sunos-x64": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.28.2.tgz",
"integrity": "sha512-GPMSkTOtMnv2U2F8gxe4Io6qmVs+YKyp832Etqqxr0hFngmXQ3rzwytelm3GIn7T4VviRUlf3sOgBOiTdvaf7g==",
"cpu": [
"x64"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"sunos"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/win32-arm64": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.28.2.tgz",
"integrity": "sha512-PIhhEkE9uPBleRBrQEJpUn7MBnibZzbGzYWPmY3x+YoVg/95zbjB4CxPPOQ8l5tYYM4mMaCthF8/1DIfBQQyWQ==",
"cpu": [
"arm64"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"win32"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/win32-ia32": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.28.2.tgz",
"integrity": "sha512-YmJbfTlvU7Sdn9BB+4PRES4oB6pxgS37MAONj+hBr/cpXS1aBPKXxNnDbu+QCWPj0o9dgyxeq79g6c5P8KeuYA==",
"cpu": [
"ia32"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"win32"
],
"engines": {
"node": ">=18"
}
},
"node_modules/@esbuild/win32-x64": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.28.2.tgz",
"integrity": "sha512-5ebpxr3nWMzrL/rnUI755Jkuee0bHL/Gq0WTF9lvcpv73wAp5eu8MfBUgWK9bhWvZjj7yX8etf/8tI8Ney695g==",
"cpu": [
"x64"
],
"dev": true,
"license": "MIT",
"optional": true,
"os": [
"win32"
],
"engines": {
"node": ">=18"
}
},
"node_modules/esbuild": {
"version": "0.28.2",
"resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.28.2.tgz",
"integrity": "sha512-HKVLS8dvII+xoKW9kmqxbRKrnWEXfJJr/FZhhJmiqIB0e053QNYFqOBouTMO/k5sID4MvCiUCvv8b9M4h32wIA==",
"dev": true,
"hasInstallScript": true,
"license": "MIT",
"bin": {
"esbuild": "bin/esbuild"
},
"engines": {
"node": ">=18"
},
"optionalDependencies": {
"@esbuild/aix-ppc64": "0.28.2",
"@esbuild/android-arm": "0.28.2",
"@esbuild/android-arm64": "0.28.2",
"@esbuild/android-x64": "0.28.2",
"@esbuild/darwin-arm64": "0.28.2",
"@esbuild/darwin-x64": "0.28.2",
"@esbuild/freebsd-arm64": "0.28.2",
"@esbuild/freebsd-x64": "0.28.2",
"@esbuild/linux-arm": "0.28.2",
"@esbuild/linux-arm64": "0.28.2",
"@esbuild/linux-ia32": "0.28.2",
"@esbuild/linux-loong64": "0.28.2",
"@esbuild/linux-mips64el": "0.28.2",
"@esbuild/linux-ppc64": "0.28.2",
"@esbuild/linux-riscv64": "0.28.2",
"@esbuild/linux-s390x": "0.28.2",
"@esbuild/linux-x64": "0.28.2",
"@esbuild/netbsd-arm64": "0.28.2",
"@esbuild/netbsd-x64": "0.28.2",
"@esbuild/openbsd-arm64": "0.28.2",
"@esbuild/openbsd-x64": "0.28.2",
"@esbuild/openharmony-arm64": "0.28.2",
"@esbuild/sunos-x64": "0.28.2",
"@esbuild/win32-arm64": "0.28.2",
"@esbuild/win32-ia32": "0.28.2",
"@esbuild/win32-x64": "0.28.2"
}
}
}
}
+6
View File
@@ -0,0 +1,6 @@
{
"private": true,
"devDependencies": {
"esbuild": "0.28.2"
}
}
+12
View File
@@ -0,0 +1,12 @@
import { readFileSync } from "node:fs";
import { resolve } from "node:path";
import { drift, minifiedGzippedBytes, packedBytes } from "./figures.mjs";
const root = resolve(import.meta.dirname, "..");
const measured = { minified: await minifiedGzippedBytes(root, "./dist/index.js"), ...packedBytes(root) };
console.log(`${(measured.minified / 1000).toFixed(1)} kB minified and gzipped; ${(measured.tarball / 1000).toFixed(1)} kB tarball, ${(measured.unpacked / 1000).toFixed(1)} kB unpacked`);
if (process.argv.includes("--check")) {
const problems = drift(readFileSync(resolve(root, "README.md"), "utf8"), measured);
for (const problem of problems) console.error(problem);
process.exit(problems.length === 0 ? 0 : 1);
}
+3
View File
@@ -102,6 +102,9 @@ in_image_memory=1g leg "release tooling tests ($node_image)" in_image "$node_ima
leg "build ($node_image)" in_image "$node_image" npm run build
leg "feature table is current ($node_image)" in_image "$node_image" node feature-table/build.mjs --check
leg "install the bundle size tool ($node_image)" in_image "$node_image" npm ci --no-audit --no-fund --prefix bundle-size
leg "bundle size tests ($node_image)" in_image "$node_image" node --test bundle-size/
leg "README's size figures are current ($node_image)" in_image "$node_image" node bundle-size/run.mjs --check
leg "pack and install the tarball ($node_image)" in_image "$node_image" sh -c 'set -e
rm -rf package-tests/node_modules
npm pack --pack-destination /tmp
+6
View File
@@ -19,6 +19,7 @@ import * as marklassian from "marklassian";
import * as mdAdf from "md-adf";
import mdToAdf from "md-to-adf";
import { toMarkdown as mdastToMarkdown } from "mdast-util-to-markdown";
import { minifiedGzippedBytes } from "./figures.mjs";
import { readFileSync } from "node:fs";
const { defaultSchema } = createRequire(import.meta.url)("@atlaskit/adf-schema/schema-default");
@@ -116,6 +117,11 @@ for (const [name, { toAdf, toMarkdown }] of Object.entries(converters)) {
const manifest = JSON.parse(readFileSync(`node_modules/${name}/package.json`, "utf8"));
console.log(`\n## ${name} ${manifest.version}`);
console.log("direct runtime dependencies:", Object.keys(manifest.dependencies ?? {}).length);
try {
console.log("minified and gzipped bytes:", await minifiedGzippedBytes(process.cwd(), name));
} catch (error) {
console.log("minified and gzipped bytes failed:", error.message.split("\n")[0]);
}
const written = toMarkdown && show("ADF to markdown", () => toMarkdown(roundTripDoc));
if (written !== undefined && toAdf) {
const readBack = show("read back", () => toAdf(written));
+4 -3
View File
@@ -1,10 +1,10 @@
#!/bin/sh
# Keep these versions and --before in step with the README's comparison table.
# Keep these versions and --before in step with the README's comparison table, and esbuild's with ../bundle-size/package.json.
# --before reads a bare date as midnight UTC, so the day after the run date includes that day's publishes.
set -eu
here=$(cd "$(dirname "$0")" && pwd)
node_image=node:26.13.1-alpine3.24
docker run --rm --memory 2g --memory-swap 2g --ulimit core=0 -u "$(id -u):$(id -g)" -e HOME=/tmp -v "$here:/comparison:ro" -w /tmp \
docker run --rm --memory 2g --memory-swap 2g --ulimit core=0 -u "$(id -u):$(id -g)" -e HOME=/tmp -v "$here:/comparison:ro" -v "$here/../bundle-size:/bundle-size:ro" -w /tmp \
"$node_image" sh -c '
npm install --before=2026-11-06 --ignore-scripts --no-audit --no-fund --silent \
@atlaskit/editor-json-transformer@10.0.0 \
@@ -18,6 +18,7 @@ docker run --rm --memory 2g --memory-swap 2g --ulimit core=0 -u "$(id -u):$(id -
adf-to-markdown@1.0.1 \
adf-to-md@1.2.1 \
adf2markdown@1.2.0 \
esbuild@0.28.2 \
extended-markdown-adf-parser@2.4.0 \
github-markdown-adf@1.3.0 \
markdown-to-adf@0.2.20 \
@@ -26,4 +27,4 @@ docker run --rm --memory 2g --memory-swap 2g --ulimit core=0 -u "$(id -u):$(id -
md-to-adf@0.6.4 \
mdast-util-from-adf@2.3.0 \
mdast-util-to-markdown@2.2.2 &&
cp /comparison/compare.mjs . && node compare.mjs'
cp /comparison/compare.mjs /bundle-size/figures.mjs . && node compare.mjs'
+15
View File
@@ -924,6 +924,21 @@ config gone missing fails the leg instead of falling back to oxlint's own defaul
`--deny-warnings`, since a rule from a category this config never names arrives as a warning it
exits 0 on.
## The published size is a bundler's output, checked within a tenth
2026-11-15, the implementer's recommendation, open to the maintainer. Goal 3. Valid while competitors advertise a minified and gzipped figure.
The README states the package's size as what a bundler ships, minified and gzipped, beside the tarball
and the unpacked size, and in a column of the comparison table. That is the figure the other packages
advertise (marklassian's "12kb" measures 13 kB here). `bundle-size/` measures it with esbuild, in its own
package as §Stryker in its own package has it: the bundle of `export * from` the entry, dependencies
included, for Node. The comparison measures every package with the same call.
The build stays tsc's unminified output, since goal 8 asks nothing of a consumer, and a minified build
leaves their debugger and stack traces nothing to read. The gate fails where a README figure is more than
a tenth off the measure: a tighter bound fails most pull requests, and a tenth still catches a feature
that doubles a part of the package. The release job needs the gate, so a stale figure stops a release.
## Properties on a fixed seed
2026-09-14, the maintainer. Goal 1. Valid while a red gate must reproduce.
+17
View File
@@ -1163,3 +1163,20 @@ Read most (opens and searches):
- `src/html/mark-elements.ts` 3
## Reading cost reset, 2026-11-15T12:26:57Z
## Reading cost, chunk 1cf1c505f613, finished 2026-11-15T12:33:26Z
63411 new input tokens before the first commit.
Read most (opens and searches):
- `docs/decisions.md` 5
- `README.md` 4
- `ci.sh` 4
- `AGENTS.md` 2
- `spec/html.md` 2
- `src/html/emit/adf-to-html.test.ts` 2
- `CHANGELOG.md` 1
- `docs/reading-cost.md` 1
- `package.json` 1
- `todo.md` 1
+1 -12
View File
@@ -12,7 +12,6 @@
| ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score |
|---|---|---|---|---|---|---|---|---|---|---|---|
| 46 | 0.4.0 | | | **Publish the bundle size in the README, failing the release pipeline when it drifts.** | 2 | 2 | 1 | 3 | 4 | 3 by 3 | 2.6 |
| 174 | 0.4.0 | | defect | **Bound the passes `trimmedEdges` takes by a constant, so a line of alternating code and emphasized blanks trims in linear time.** | 3 | 1 | 2 | 4 | 7 | 9 by 3 | 1.9 |
| 51 | 0.4.0 | | | **Match a reference label to its definition under Unicode case folding.** | 2 | 1 | 2 | 3 | 4 | 4 by 2 | 1.7 |
| 148 | 0.4.0 | | | **Ship conversion between ADF and Jira wiki markup both ways, under a README goal for wiki markup.** | 3 | 2 | 2 | 5 | 7 | 3 by 5 | 0.8 |
@@ -46,16 +45,6 @@
## Details
### 46. Publish the bundle size in the README, failing the release pipeline when it drifts.
The HTML items change the size. The quantity is what a consumer downloads and loads: the
tarball `npm pack` produces, its unpacked `dist`, and the built JavaScript minified + gzipped — the
figure the competitors advertise (marklassian's "12kb") and the only apples-to-apples one, since
ours ships tsc's unminified output and no minifier yet (decide here whether to minify for the build
or report the unminified gzip). The figure lands in README §The package beside the "no runtime
dependencies" claim, and in a size column of the comparison table. Measured today,
unminified: tarball 60.4 kB, unpacked 221.5 kB, JS gzipped 45.6 kB.
### 174. Bound the passes `trimmedEdges` takes by a constant, so a line of alternating code and emphasized blanks trims in linear time.
`trimmedEdges` (`src/markdown/portable/inline-reduction.ts`) repeats a pass until nothing changes, and
@@ -133,7 +122,7 @@ package, as Stryker does (§Stryker in its own package), with pinned versions. B
image the gate already pulls. No leg needs an account or a network beyond the install.
Once the leg holds, the README may say the package bundles with those four; it says nothing about
Forge's runtime, which no leg tests. Item 46 may take its bundle size from this leg.
Forge's runtime, which no leg tests. The bundlers join esbuild in `bundle-size/`'s package.
### 42. Trim a text leaf's trailing blanks in linear time.