diff --git a/AGENTS.md b/AGENTS.md index 331038d..0997569 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 diff --git a/CHANGELOG.md b/CHANGELOG.md index 6f90c17..d21c9bd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 `
` holding an `` and a `
`, and as `
` of `` files, where `0.3.1` wrote the carry element, and `htmlToAdf` reads them back. A link around the image is the media's link diff --git a/README.md b/README.md index 2fa491b..10090a7 100644 --- a/README.md +++ b/README.md @@ -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 []` mutation-tests the lines changed since ``, `origin/main` diff --git a/bundle-size/figures.mjs b/bundle-size/figures.mjs new file mode 100644 index 0000000..01851c8 --- /dev/null +++ b/bundle-size/figures.mjs @@ -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`] : []; + })(), +]; diff --git a/bundle-size/figures.test.mjs b/bundle-size/figures.test.mjs new file mode 100644 index 0000000..cbd1e79 --- /dev/null +++ b/bundle-size/figures.test.mjs @@ -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", + ]); +}); diff --git a/bundle-size/package-lock.json b/bundle-size/package-lock.json new file mode 100644 index 0000000..b3acee8 --- /dev/null +++ b/bundle-size/package-lock.json @@ -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" + } + } + } +} diff --git a/bundle-size/package.json b/bundle-size/package.json new file mode 100644 index 0000000..da78b36 --- /dev/null +++ b/bundle-size/package.json @@ -0,0 +1,6 @@ +{ + "private": true, + "devDependencies": { + "esbuild": "0.28.2" + } +} diff --git a/bundle-size/run.mjs b/bundle-size/run.mjs new file mode 100644 index 0000000..6118153 --- /dev/null +++ b/bundle-size/run.mjs @@ -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); +} diff --git a/ci.sh b/ci.sh index bdb8f2f..86afeb7 100755 --- a/ci.sh +++ b/ci.sh @@ -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 diff --git a/converter-comparison/compare.mjs b/converter-comparison/compare.mjs index 802f77e..55b76d3 100644 --- a/converter-comparison/compare.mjs +++ b/converter-comparison/compare.mjs @@ -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)); diff --git a/converter-comparison/run.sh b/converter-comparison/run.sh index 4e7bb9c..76ff0a5 100755 --- a/converter-comparison/run.sh +++ b/converter-comparison/run.sh @@ -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' diff --git a/docs/decisions.md b/docs/decisions.md index d0547ea..1536f0a 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -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. diff --git a/docs/reading-cost.md b/docs/reading-cost.md index d913977..a931ec0 100644 --- a/docs/reading-cost.md +++ b/docs/reading-cost.md @@ -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 diff --git a/todo.md b/todo.md index 3d36481..1d18af9 100644 --- a/todo.md +++ b/todo.md @@ -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.