tonnage 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jeremy Banka
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,38 @@
+# tonnage
+
+Keep exact bundle size tables in a package README and fail CI when the checked-in
+numbers drift.
+
+The tool bundles real public package imports with esbuild, minifies the result,
+and reports JavaScript bytes before and after level-9 gzip. Public-module rows
+retain every runtime export; recipe entry files can select named exports and
+tree-shake the rest. Declarations, source maps, CSS, and other assets are not
+counted. Peer dependencies stay external, and shared modules are counted once
+per bundle.
+
+## Configure
+
+Add the generated-section comments to the target README, then create a config
+beside the package manifest. The complete configuration exhibit is in
+[examples/tonnage.config.ts](./examples/tonnage.config.ts).
+Each recipe points to a reviewable entry file such as
+[examples/recipes/react-app.ts](./examples/recipes/react-app.ts). Use named
+imports in these files to represent the runtime surface a real application uses;
+unused package exports are tree-shaken.
+
+The default generated-section marker is `default`; the example uses `my-package`.
+The opening and closing comments use the forms
+`tonnage:my-package:start` and `tonnage:my-package:end`.
+
+## Run
+
+Run `tonnage write` during development to update the README. Run
+`tonnage check` in CI to recompute the same report without writing and exit
+nonzero when the README is stale. The aliases `make` and `test` are also
+available for manifest-style scripts.
+
+By default the tool reads `package.json`, writes `README.md`, and measures every
+public export except `./package.json`. Paths are resolved relative to the config
+file. Use `exports.include` or `exports.exclude` to select subpaths, recipe entry
+files to describe realistic runtime boundaries, and `external` for non-peer
+imports that the package intentionally leaves to its consumers.

package/bin/tonnage.bin.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import "../dist/cli.js"

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/cli.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+import { t as runTonnage } from "./run-DIk7L56w.js";
+import path from "node:path";
+import fs from "node:fs/promises";
+import { pathToFileURL } from "node:url";
+//#region src/cli.ts
+const DEFAULT_CONFIG_FILES = [
+	`tonnage.config.ts`,
+	`tonnage.config.mjs`,
+	`tonnage.config.js`
+];
+async function main() {
+	const command = process.argv[2];
+	const mode = parseMode(command);
+	const configPath = await findConfig(process.argv[3]);
+	const config = await loadConfig(configPath);
+	const result = await runTonnage(config, {
+		configDirectory: path.dirname(configPath),
+		mode
+	});
+	if (mode === `check` && result.changed) {
+		process.stderr.write(`${path.relative(process.cwd(), result.readmePath)} is out of date. Run tonnage write.\n`);
+		process.exitCode = 1;
+		return;
+	}
+	const readme = path.relative(process.cwd(), result.readmePath);
+	process.stdout.write(result.changed ? `Updated ${readme}.\n` : `${readme} is already up to date.\n`);
+}
+function parseMode(command) {
+	switch (command) {
+		case `check`:
+		case `test`: return `check`;
+		case `make`:
+		case `write`: return `write`;
+		case void 0:
+		default: throw new Error(`Usage: tonnage <write|check> [tonnage.config.ts]`);
+	}
+}
+async function findConfig(configArgument) {
+	if (configArgument) return path.resolve(configArgument);
+	for (const filename of DEFAULT_CONFIG_FILES) {
+		const candidate = path.resolve(filename);
+		try {
+			await fs.access(candidate);
+			return candidate;
+		} catch {}
+	}
+	throw new Error(`Could not find a tonnage config (${DEFAULT_CONFIG_FILES.join(`, `)}).`);
+}
+async function loadConfig(configPath) {
+	const imported = await import(pathToFileURL(configPath).href);
+	if (!imported.default || typeof imported.default !== `object`) throw new Error(`${configPath} must default-export a tonnage config.`);
+	return imported.default;
+}
+main().catch((error) => {
+	process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+	process.exitCode = 1;
+});
+//#endregion
+export {};
+
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","names":[],"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\n\nimport fs from \"node:fs/promises\"\nimport path from \"node:path\"\nimport { pathToFileURL } from \"node:url\"\n\nimport { runTonnage } from \"./run.ts\"\nimport type { TonnageConfig, TonnageMode } from \"./types.ts\"\n\nconst DEFAULT_CONFIG_FILES = [\n\t`tonnage.config.ts`,\n\t`tonnage.config.mjs`,\n\t`tonnage.config.js`,\n]\n\nasync function main(): Promise<void> {\n\tconst command = process.argv[2]\n\tconst mode = parseMode(command)\n\tconst configPath = await findConfig(process.argv[3])\n\tconst config = await loadConfig(configPath)\n\tconst result = await runTonnage(config, {\n\t\tconfigDirectory: path.dirname(configPath),\n\t\tmode,\n\t})\n\n\tif (mode === `check` && result.changed) {\n\t\tprocess.stderr.write(\n\t\t\t`${path.relative(process.cwd(), result.readmePath)} is out of date. Run tonnage write.\\n`,\n\t\t)\n\t\tprocess.exitCode = 1\n\t\treturn\n\t}\n\n\tconst readme = path.relative(process.cwd(), result.readmePath)\n\tprocess.stdout.write(\n\t\tresult.changed\n\t\t\t? `Updated ${readme}.\\n`\n\t\t\t: `${readme} is already up to date.\\n`,\n\t)\n}\n\nfunction parseMode(command: string | undefined): TonnageMode {\n\tswitch (command) {\n\t\tcase `check`:\n\t\tcase `test`:\n\t\t\treturn `check`\n\t\tcase `make`:\n\t\tcase `write`:\n\t\t\treturn `write`\n\t\tcase undefined:\n\t\tdefault:\n\t\t\tthrow new Error(`Usage: tonnage <write|check> [tonnage.config.ts]`)\n\t}\n}\n\nasync function findConfig(configArgument: string | undefined): Promise<string> {\n\tif (configArgument) {\n\t\treturn path.resolve(configArgument)\n\t}\n\n\tfor (const filename of DEFAULT_CONFIG_FILES) {\n\t\tconst candidate = path.resolve(filename)\n\t\ttry {\n\t\t\tawait fs.access(candidate)\n\t\t\treturn candidate\n\t\t} catch {\n\t\t\t// Keep looking for the next supported config filename.\n\t\t}\n\t}\n\n\tthrow new Error(\n\t\t`Could not find a tonnage config (${DEFAULT_CONFIG_FILES.join(`, `)}).`,\n\t)\n}\n\nasync function loadConfig(configPath: string): Promise<TonnageConfig> {\n\tconst imported = (await import(pathToFileURL(configPath).href)) as {\n\t\tdefault?: unknown\n\t}\n\tif (!imported.default || typeof imported.default !== `object`) {\n\t\tthrow new Error(`${configPath} must default-export a tonnage config.`)\n\t}\n\treturn imported.default\n}\n\nmain().catch((error: unknown) => {\n\tprocess.stderr.write(\n\t\t`${error instanceof Error ? error.message : String(error)}\\n`,\n\t)\n\tprocess.exitCode = 1\n})\n"],"mappings":";;;;;;AASA,MAAM,uBAAuB;CAC5B;CACA;CACA;AACD;AAEA,eAAe,OAAsB;CACpC,MAAM,UAAU,QAAQ,KAAK;CAC7B,MAAM,OAAO,UAAU,OAAO;CAC9B,MAAM,aAAa,MAAM,WAAW,QAAQ,KAAK,EAAE;CACnD,MAAM,SAAS,MAAM,WAAW,UAAU;CAC1C,MAAM,SAAS,MAAM,WAAW,QAAQ;EACvC,iBAAiB,KAAK,QAAQ,UAAU;EACxC;CACD,CAAC;CAED,IAAI,SAAS,WAAW,OAAO,SAAS;EACvC,QAAQ,OAAO,MACd,GAAG,KAAK,SAAS,QAAQ,IAAI,GAAG,OAAO,UAAU,EAAE,sCACpD;EACA,QAAQ,WAAW;EACnB;CACD;CAEA,MAAM,SAAS,KAAK,SAAS,QAAQ,IAAI,GAAG,OAAO,UAAU;CAC7D,QAAQ,OAAO,MACd,OAAO,UACJ,WAAW,OAAO,OAClB,GAAG,OAAO,0BACd;AACD;AAEA,SAAS,UAAU,SAA0C;CAC5D,QAAQ,SAAR;EACC,KAAK;EACL,KAAK,QACJ,OAAO;EACR,KAAK;EACL,KAAK,SACJ,OAAO;EACR,KAAK,KAAA;EACL,SACC,MAAM,IAAI,MAAM,kDAAkD;CACpE;AACD;AAEA,eAAe,WAAW,gBAAqD;CAC9E,IAAI,gBACH,OAAO,KAAK,QAAQ,cAAc;CAGnC,KAAK,MAAM,YAAY,sBAAsB;EAC5C,MAAM,YAAY,KAAK,QAAQ,QAAQ;EACvC,IAAI;GACH,MAAM,GAAG,OAAO,SAAS;GACzB,OAAO;EACR,QAAQ,CAER;CACD;CAEA,MAAM,IAAI,MACT,oCAAoC,qBAAqB,KAAK,IAAI,EAAE,GACrE;AACD;AAEA,eAAe,WAAW,YAA4C;CACrE,MAAM,WAAY,MAAM,OAAO,cAAc,UAAU,CAAC,CAAC;CAGzD,IAAI,CAAC,SAAS,WAAW,OAAO,SAAS,YAAY,UACpD,MAAM,IAAI,MAAM,GAAG,WAAW,uCAAuC;CAEtE,OAAO,SAAS;AACjB;AAEA,KAAK,CAAC,CAAC,OAAO,UAAmB;CAChC,QAAQ,OAAO,MACd,GAAG,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,EAAE,GAC3D;CACA,QAAQ,WAAW;AACpB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,80 @@
+//#region src/types.d.ts
+type BundlePlatform = `browser` | `neutral` | `node`;
+type TonnageExports = {
+  exclude?: readonly string[];
+  include?: readonly string[];
+};
+type TonnageRecipe = {
+  entry: string;
+  external?: readonly string[];
+  name: string;
+  platform?: BundlePlatform;
+};
+type TonnageConfig = {
+  exports?: boolean | TonnageExports;
+  external?: readonly string[];
+  heading?: string;
+  marker?: string;
+  packageJson?: string;
+  platform?: BundlePlatform;
+  readme?: string;
+  recipes?: readonly TonnageRecipe[];
+  target?: string;
+};
+type BundleMeasurement = {
+  gzipBytes: number;
+  rawBytes: number;
+};
+type TonnageRow = BundleMeasurement & {
+  imports: readonly string[];
+  name: string;
+};
+type TonnageRecipeRow = BundleMeasurement & {
+  entry: string;
+  name: string;
+};
+type TonnageReport = {
+  exports: readonly TonnageRow[];
+  packageName: string;
+  recipes: readonly TonnageRecipeRow[];
+};
+type TonnageMode = `check` | `write`;
+type TonnageRunResult = {
+  changed: boolean;
+  readmePath: string;
+  report: TonnageReport;
+};
+//#endregion
+//#region src/define-config.d.ts
+declare function defineConfig(config: TonnageConfig): TonnageConfig;
+//#endregion
+//#region src/measure.d.ts
+type MeasureImportsOptions = {
+  external?: readonly string[] | undefined;
+  platform?: BundlePlatform | undefined;
+  resolveDirectory: string;
+  target?: string | undefined;
+};
+type MeasureEntryOptions = MeasureImportsOptions;
+declare function measureEntry(entry: string, options: MeasureEntryOptions): Promise<BundleMeasurement>;
+declare function measureImports(imports: readonly string[], options: MeasureImportsOptions): Promise<BundleMeasurement>;
+//#endregion
+//#region src/readme.d.ts
+declare function tonnageMarkers(marker?: string): {
+  end: string;
+  start: string;
+};
+declare function updateGeneratedSection(readme: string, markdown: string, marker?: string): string;
+//#endregion
+//#region src/report.d.ts
+declare function createTonnageReport(config: TonnageConfig, configDirectory: string): Promise<TonnageReport>;
+declare function renderTonnageMarkdown(report: TonnageReport, config?: TonnageConfig): string;
+//#endregion
+//#region src/run.d.ts
+declare function runTonnage(config: TonnageConfig, options: {
+  configDirectory?: string;
+  mode: TonnageMode;
+}): Promise<TonnageRunResult>;
+//#endregion
+export { type BundleMeasurement, type BundlePlatform, type MeasureEntryOptions, type MeasureImportsOptions, type TonnageConfig, type TonnageExports, type TonnageMode, type TonnageRecipe, type TonnageRecipeRow, type TonnageReport, type TonnageRow, type TonnageRunResult, createTonnageReport, defineConfig, measureEntry, measureImports, renderTonnageMarkdown, runTonnage, tonnageMarkers, updateGeneratedSection };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/types.ts","../src/define-config.ts","../src/measure.ts","../src/readme.ts","../src/report.ts","../src/run.ts"],"mappings":";KAAY;KAEA;EACX;EACA;;KAGW;EACX;EACA;EACA;EACA,WAAW;;KAGA;EACX,oBAAoB;EACpB;EACA;EACA;EACA;EACA,WAAW;EACX;EACA,mBAAmB;EACnB;;KAGW;EACX;EACA;;KAGW,aAAa;EACxB;EACA;;KAGW,mBAAmB;EAC9B;EACA;;KAGW;EACX,kBAAkB;EAClB;EACA,kBAAkB;;KAGP;KAEA;EACX;EACA;EACA,QAAQ;;;;iBClDO,aAAa,QAAQ,gBAAgB;;;KCKzC;EACX;EACA,WAAW;EACX;EACA;;KAGW,sBAAsB;iBAEZ,aACrB,eACA,SAAS,sBACP,QAAQ;iBAOW,eACrB,4BACA,SAAS,wBACP,QAAQ;;;iBC7BK,eAAe;EAC9B;EACA;;iBASe,uBACf,gBACA,kBACA;;;iBCGqB,oBACrB,QAAQ,eACR,0BACE,QAAQ;iBAqDK,sBACf,QAAQ,eACR,SAAQ;;;iBCpEa,WACrB,QAAQ,eACR;EACC;EACA,MAAM;IAEL,QAAQ"}

package/dist/index.js

@@ -0,0 +1,9 @@
+import { a as updateGeneratedSection, i as tonnageMarkers, n as createTonnageReport, o as measureEntry, r as renderTonnageMarkdown, s as measureImports, t as runTonnage } from "./run-DIk7L56w.js";
+//#region src/define-config.ts
+function defineConfig(config) {
+	return config;
+}
+//#endregion
+export { createTonnageReport, defineConfig, measureEntry, measureImports, renderTonnageMarkdown, runTonnage, tonnageMarkers, updateGeneratedSection };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/define-config.ts"],"sourcesContent":["import type { TonnageConfig } from \"./types.ts\"\n\nexport function defineConfig(config: TonnageConfig): TonnageConfig {\n\treturn config\n}\n"],"mappings":";;AAEA,SAAgB,aAAa,QAAsC;CAClE,OAAO;AACR"}

package/dist/run-DIk7L56w.js

@@ -0,0 +1,199 @@
+import path from "node:path";
+import { gzipSync } from "node:zlib";
+import { build } from "esbuild";
+import fs from "node:fs/promises";
+//#region src/measure.ts
+async function measureEntry(entry, options) {
+	return measureBuild({ entryPoints: [path.resolve(options.resolveDirectory, entry)] }, options);
+}
+async function measureImports(imports, options) {
+	if (imports.length === 0) throw new Error(`A tonnage entry must import at least one module.`);
+	return measureBuild({ stdin: {
+		contents: imports.map((specifier, index) => `export * as entry${index} from ${JSON.stringify(specifier)}`).join(`\n`),
+		loader: `js`,
+		resolveDir: options.resolveDirectory,
+		sourcefile: `tonnage-entry.js`
+	} }, options);
+}
+async function measureBuild(entry, options) {
+	const platform = options.platform ?? `neutral`;
+	const outputFiles = [...(await build({
+		bundle: true,
+		charset: `utf8`,
+		external: [...options.external ?? [], ...platform === `browser` ? [] : [`node:*`]],
+		format: `esm`,
+		legalComments: `none`,
+		logLevel: `silent`,
+		minify: true,
+		outdir: `out`,
+		platform,
+		...entry,
+		target: options.target ?? `es2022`,
+		treeShaking: true,
+		write: false
+	})).outputFiles ?? []].filter((output) => output.path.endsWith(`.js`)).sort((left, right) => left.path.localeCompare(right.path));
+	if (outputFiles.length === 0) throw new Error(`The tonnage entry did not emit any runtime JavaScript.`);
+	const rawBytes = outputFiles.reduce((total, output) => total + output.contents.byteLength, 0);
+	return {
+		gzipBytes: outputFiles.reduce((total, output) => total + gzipSync(output.contents, { level: 9 }).byteLength, 0),
+		rawBytes
+	};
+}
+//#endregion
+//#region src/readme.ts
+function tonnageMarkers(marker = `default`) {
+	validateMarker(marker);
+	return {
+		end: `<!-- tonnage:${marker}:end -->`,
+		start: `<!-- tonnage:${marker}:start -->`
+	};
+}
+function updateGeneratedSection(readme, markdown, marker) {
+	const { end, start } = tonnageMarkers(marker);
+	const startIndex = readme.indexOf(start);
+	const endIndex = readme.indexOf(end);
+	if (startIndex === -1 || endIndex === -1) throw new Error(`README must contain exactly one ${start} and one ${end} marker.`);
+	if (readme.slice(startIndex + start.length).includes(start) || readme.slice(endIndex + end.length).includes(end)) throw new Error(`README must contain exactly one ${start} and one ${end} marker.`);
+	if (endIndex < startIndex) throw new Error(`${end} must appear after ${start}.`);
+	const contentStart = startIndex + start.length;
+	return `${readme.slice(0, contentStart)}\n\n${markdown.trim()}\n\n${readme.slice(endIndex)}`;
+}
+function validateMarker(marker) {
+	if (!/^[a-z0-9][a-z0-9._-]*$/i.test(marker)) throw new Error(`Tonnage marker names may contain letters, numbers, dots, underscores, and hyphens.`);
+}
+//#endregion
+//#region src/report.ts
+async function createTonnageReport(config, configDirectory) {
+	const packageJsonPath = path.resolve(configDirectory, config.packageJson ?? `package.json`);
+	const packageJson = JSON.parse(await fs.readFile(packageJsonPath, `utf8`));
+	if (!packageJson.name) throw new Error(`${packageJsonPath} does not declare a package name.`);
+	const resolveDirectory = path.dirname(packageJsonPath);
+	const external = unique([...Object.keys(packageJson.peerDependencies ?? {}), ...config.external ?? []]);
+	const exportImports = selectExportImports(packageJson.name, packageJson.exports, config.exports);
+	const exportRows = await Promise.all(exportImports.map(async (specifier) => ({
+		...await measureImports([specifier], {
+			external,
+			platform: config.platform,
+			resolveDirectory,
+			target: config.target
+		}),
+		imports: [specifier],
+		name: specifier
+	})));
+	const recipeRows = await Promise.all((config.recipes ?? []).map(async (recipe) => ({
+		...await measureEntry(recipe.entry, {
+			external: unique([...external, ...recipe.external ?? []]),
+			platform: recipe.platform ?? config.platform,
+			resolveDirectory,
+			target: config.target
+		}),
+		entry: recipe.entry,
+		name: recipe.name
+	})));
+	return {
+		exports: exportRows,
+		packageName: packageJson.name,
+		recipes: recipeRows
+	};
+}
+function renderTonnageMarkdown(report, config = {}) {
+	const lines = [
+		`## ${config.heading ?? `Bundle size`}`,
+		``,
+		`Public-module rows retain complete runtime export surfaces. Recipe rows bundle their reviewable entry files and tree-shake unused exports. Both report exact minified and level-9 gzip JavaScript byte counts; declarations, source maps, CSS, and other assets are excluded. Peer dependencies stay external, and shared modules are counted once per bundle.`
+	];
+	if (report.exports.length > 0) lines.push(``, `### Public modules (whole export surface)`, ``, ...markdownTable([
+		`Import`,
+		`Minified JS`,
+		`Gzip JS`
+	], report.exports.map((row) => [
+		code(row.name),
+		formatBytes(row.rawBytes),
+		formatBytes(row.gzipBytes)
+	]), [
+		`left`,
+		`right`,
+		`right`
+	]));
+	if (report.recipes.length > 0) lines.push(``, `### Representative runtimes (tree-shaken)`, ``, ...markdownTable([
+		`Recipe`,
+		`Entry`,
+		`Minified JS`,
+		`Gzip JS`
+	], report.recipes.map((row) => [
+		escapeCell(row.name),
+		code(row.entry),
+		formatBytes(row.rawBytes),
+		formatBytes(row.gzipBytes)
+	]), [
+		`left`,
+		`left`,
+		`right`,
+		`right`
+	]));
+	return lines.join(`\n`);
+}
+function selectExportImports(packageName, exportsValue, selection) {
+	if (selection === false) return [];
+	const exportKeys = getExportKeys(exportsValue);
+	const options = typeof selection === `object` ? selection : {};
+	const included = options.include ? [...options.include] : exportKeys.filter((exportKey) => exportKey !== `./package.json`);
+	const excluded = new Set(options.exclude ?? []);
+	return included.filter((exportKey) => !excluded.has(exportKey)).map((exportKey) => toPackageImport(packageName, exportKey));
+}
+function getExportKeys(exportsValue) {
+	if (typeof exportsValue === `string` || Array.isArray(exportsValue)) return [`.`];
+	if (!exportsValue || typeof exportsValue !== `object`) return [`.`];
+	const keys = Object.keys(exportsValue);
+	return keys.some((key) => key.startsWith(`.`)) ? keys : [`.`];
+}
+function toPackageImport(packageName, exportKey) {
+	if (exportKey === `.`) return packageName;
+	if (!exportKey.startsWith(`./`)) throw new Error(`Invalid package export key: ${exportKey}`);
+	return `${packageName}/${exportKey.slice(2)}`;
+}
+function formatBytes(bytes) {
+	return `${new Intl.NumberFormat(`en-US`).format(bytes)} B`;
+}
+function code(value) {
+	return `<code>${escapeCell(value)}</code>`;
+}
+function escapeCell(value) {
+	return value.replaceAll(`&`, `&amp;`).replaceAll(`|`, `&#124;`);
+}
+function unique(values) {
+	return [...new Set(values)];
+}
+function markdownTable(headings, rows, alignments) {
+	const widths = headings.map((heading, column) => Math.max(heading.length, ...rows.map((row) => row[column]?.length ?? 0), 3));
+	const renderRow = (cells) => `| ${cells.map((cell, column) => padCell(cell, widths[column] ?? 3, alignments[column] ?? `left`)).join(` | `)} |`;
+	const separator = widths.map((width, column) => alignments[column] === `right` ? `${`-`.repeat(width - 1)}:` : `-`.repeat(width));
+	return [
+		renderRow(headings),
+		renderRow(separator),
+		...rows.map(renderRow)
+	];
+}
+function padCell(cell, width, alignment) {
+	return alignment === `right` ? cell.padStart(width) : cell.padEnd(width);
+}
+//#endregion
+//#region src/run.ts
+async function runTonnage(config, options) {
+	const configDirectory = path.resolve(options.configDirectory ?? process.cwd());
+	const readmePath = path.resolve(configDirectory, config.readme ?? `README.md`);
+	const oldReadme = await fs.readFile(readmePath, `utf8`);
+	const report = await createTonnageReport(config, configDirectory);
+	const newReadme = updateGeneratedSection(oldReadme, renderTonnageMarkdown(report, config), config.marker);
+	const changed = oldReadme !== newReadme;
+	if (options.mode === `write` && changed) await fs.writeFile(readmePath, newReadme);
+	return {
+		changed,
+		readmePath,
+		report
+	};
+}
+//#endregion
+export { updateGeneratedSection as a, tonnageMarkers as i, createTonnageReport as n, measureEntry as o, renderTonnageMarkdown as r, measureImports as s, runTonnage as t };
+
+//# sourceMappingURL=run-DIk7L56w.js.map

package/dist/run-DIk7L56w.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-DIk7L56w.js","names":[],"sources":["../src/measure.ts","../src/readme.ts","../src/report.ts","../src/run.ts"],"sourcesContent":["import path from \"node:path\"\nimport { gzipSync } from \"node:zlib\"\n\nimport { build, type BuildOptions } from \"esbuild\"\n\nimport type { BundleMeasurement, BundlePlatform } from \"./types.ts\"\n\nexport type MeasureImportsOptions = {\n\texternal?: readonly string[] | undefined\n\tplatform?: BundlePlatform | undefined\n\tresolveDirectory: string\n\ttarget?: string | undefined\n}\n\nexport type MeasureEntryOptions = MeasureImportsOptions\n\nexport async function measureEntry(\n\tentry: string,\n\toptions: MeasureEntryOptions,\n): Promise<BundleMeasurement> {\n\treturn measureBuild(\n\t\t{ entryPoints: [path.resolve(options.resolveDirectory, entry)] },\n\t\toptions,\n\t)\n}\n\nexport async function measureImports(\n\timports: readonly string[],\n\toptions: MeasureImportsOptions,\n): Promise<BundleMeasurement> {\n\tif (imports.length === 0) {\n\t\tthrow new Error(`A tonnage entry must import at least one module.`)\n\t}\n\n\tconst entry = imports\n\t\t.map(\n\t\t\t(specifier, index) =>\n\t\t\t\t`export * as entry${index} from ${JSON.stringify(specifier)}`,\n\t\t)\n\t\t.join(`\\n`)\n\treturn measureBuild(\n\t\t{\n\t\t\tstdin: {\n\t\t\t\tcontents: entry,\n\t\t\t\tloader: `js`,\n\t\t\t\tresolveDir: options.resolveDirectory,\n\t\t\t\tsourcefile: `tonnage-entry.js`,\n\t\t\t},\n\t\t},\n\t\toptions,\n\t)\n}\n\nasync function measureBuild(\n\tentry: Pick<BuildOptions, `entryPoints` | `stdin`>,\n\toptions: MeasureEntryOptions,\n): Promise<BundleMeasurement> {\n\tconst platform = options.platform ?? `neutral`\n\n\tconst result = await build({\n\t\tbundle: true,\n\t\tcharset: `utf8`,\n\t\texternal: [\n\t\t\t...(options.external ?? []),\n\t\t\t...(platform === `browser` ? [] : [`node:*`]),\n\t\t],\n\t\tformat: `esm`,\n\t\tlegalComments: `none`,\n\t\tlogLevel: `silent`,\n\t\tminify: true,\n\t\toutdir: `out`,\n\t\tplatform,\n\t\t...entry,\n\t\ttarget: options.target ?? `es2022`,\n\t\ttreeShaking: true,\n\t\twrite: false,\n\t})\n\n\tconst outputFiles = [...(result.outputFiles ?? [])]\n\t\t.filter((output) => output.path.endsWith(`.js`))\n\t\t.sort((left, right) => left.path.localeCompare(right.path))\n\tif (outputFiles.length === 0) {\n\t\tthrow new Error(`The tonnage entry did not emit any runtime JavaScript.`)\n\t}\n\tconst rawBytes = outputFiles.reduce(\n\t\t(total, output) => total + output.contents.byteLength,\n\t\t0,\n\t)\n\tconst gzipBytes = outputFiles.reduce(\n\t\t(total, output) =>\n\t\t\ttotal + gzipSync(output.contents, { level: 9 }).byteLength,\n\t\t0,\n\t)\n\n\treturn { gzipBytes, rawBytes }\n}\n","export function tonnageMarkers(marker = `default`): {\n\tend: string\n\tstart: string\n} {\n\tvalidateMarker(marker)\n\treturn {\n\t\tend: `<!-- tonnage:${marker}:end -->`,\n\t\tstart: `<!-- tonnage:${marker}:start -->`,\n\t}\n}\n\nexport function updateGeneratedSection(\n\treadme: string,\n\tmarkdown: string,\n\tmarker?: string,\n): string {\n\tconst { end, start } = tonnageMarkers(marker)\n\tconst startIndex = readme.indexOf(start)\n\tconst endIndex = readme.indexOf(end)\n\n\tif (startIndex === -1 || endIndex === -1) {\n\t\tthrow new Error(\n\t\t\t`README must contain exactly one ${start} and one ${end} marker.`,\n\t\t)\n\t}\n\tif (\n\t\treadme.slice(startIndex + start.length).includes(start) ||\n\t\treadme.slice(endIndex + end.length).includes(end)\n\t) {\n\t\tthrow new Error(\n\t\t\t`README must contain exactly one ${start} and one ${end} marker.`,\n\t\t)\n\t}\n\tif (endIndex < startIndex) {\n\t\tthrow new Error(`${end} must appear after ${start}.`)\n\t}\n\n\tconst contentStart = startIndex + start.length\n\treturn `${readme.slice(0, contentStart)}\\n\\n${markdown.trim()}\\n\\n${readme.slice(endIndex)}`\n}\n\nfunction validateMarker(marker: string): void {\n\tif (!/^[a-z0-9][a-z0-9._-]*$/i.test(marker)) {\n\t\tthrow new Error(\n\t\t\t`Tonnage marker names may contain letters, numbers, dots, underscores, and hyphens.`,\n\t\t)\n\t}\n}\n","import fs from \"node:fs/promises\"\nimport path from \"node:path\"\n\nimport { measureEntry, measureImports } from \"./measure.ts\"\nimport type {\n\tTonnageConfig,\n\tTonnageExports,\n\tTonnageReport,\n\tTonnageRow,\n} from \"./types.ts\"\n\ntype PackageJson = {\n\texports?: unknown\n\tname?: string\n\tpeerDependencies?: Record<string, string>\n}\n\nexport async function createTonnageReport(\n\tconfig: TonnageConfig,\n\tconfigDirectory: string,\n): Promise<TonnageReport> {\n\tconst packageJsonPath = path.resolve(\n\t\tconfigDirectory,\n\t\tconfig.packageJson ?? `package.json`,\n\t)\n\tconst packageJson = JSON.parse(\n\t\tawait fs.readFile(packageJsonPath, `utf8`),\n\t) as PackageJson\n\tif (!packageJson.name) {\n\t\tthrow new Error(`${packageJsonPath} does not declare a package name.`)\n\t}\n\n\tconst resolveDirectory = path.dirname(packageJsonPath)\n\tconst peerDependencies = Object.keys(packageJson.peerDependencies ?? {})\n\tconst external = unique([...peerDependencies, ...(config.external ?? [])])\n\tconst exportImports = selectExportImports(\n\t\tpackageJson.name,\n\t\tpackageJson.exports,\n\t\tconfig.exports,\n\t)\n\n\tconst exportRows = await Promise.all(\n\t\texportImports.map(async (specifier): Promise<TonnageRow> => ({\n\t\t\t...(await measureImports([specifier], {\n\t\t\t\texternal,\n\t\t\t\tplatform: config.platform,\n\t\t\t\tresolveDirectory,\n\t\t\t\ttarget: config.target,\n\t\t\t})),\n\t\t\timports: [specifier],\n\t\t\tname: specifier,\n\t\t})),\n\t)\n\tconst recipeRows = await Promise.all(\n\t\t(config.recipes ?? []).map(async (recipe) => ({\n\t\t\t...(await measureEntry(recipe.entry, {\n\t\t\t\texternal: unique([...external, ...(recipe.external ?? [])]),\n\t\t\t\tplatform: recipe.platform ?? config.platform,\n\t\t\t\tresolveDirectory,\n\t\t\t\ttarget: config.target,\n\t\t\t})),\n\t\t\tentry: recipe.entry,\n\t\t\tname: recipe.name,\n\t\t})),\n\t)\n\n\treturn {\n\t\texports: exportRows,\n\t\tpackageName: packageJson.name,\n\t\trecipes: recipeRows,\n\t}\n}\n\nexport function renderTonnageMarkdown(\n\treport: TonnageReport,\n\tconfig: TonnageConfig = {},\n): string {\n\tconst lines = [\n\t\t`## ${config.heading ?? `Bundle size`}`,\n\t\t``,\n\t\t`Public-module rows retain complete runtime export surfaces. Recipe rows bundle their reviewable entry files and tree-shake unused exports. Both report exact minified and level-9 gzip JavaScript byte counts; declarations, source maps, CSS, and other assets are excluded. Peer dependencies stay external, and shared modules are counted once per bundle.`,\n\t]\n\n\tif (report.exports.length > 0) {\n\t\tlines.push(\n\t\t\t``,\n\t\t\t`### Public modules (whole export surface)`,\n\t\t\t``,\n\t\t\t...markdownTable(\n\t\t\t\t[`Import`, `Minified JS`, `Gzip JS`],\n\t\t\t\treport.exports.map((row) => [\n\t\t\t\t\tcode(row.name),\n\t\t\t\t\tformatBytes(row.rawBytes),\n\t\t\t\t\tformatBytes(row.gzipBytes),\n\t\t\t\t]),\n\t\t\t\t[`left`, `right`, `right`],\n\t\t\t),\n\t\t)\n\t}\n\n\tif (report.recipes.length > 0) {\n\t\tlines.push(\n\t\t\t``,\n\t\t\t`### Representative runtimes (tree-shaken)`,\n\t\t\t``,\n\t\t\t...markdownTable(\n\t\t\t\t[`Recipe`, `Entry`, `Minified JS`, `Gzip JS`],\n\t\t\t\treport.recipes.map((row) => [\n\t\t\t\t\tescapeCell(row.name),\n\t\t\t\t\tcode(row.entry),\n\t\t\t\t\tformatBytes(row.rawBytes),\n\t\t\t\t\tformatBytes(row.gzipBytes),\n\t\t\t\t]),\n\t\t\t\t[`left`, `left`, `right`, `right`],\n\t\t\t),\n\t\t)\n\t}\n\n\treturn lines.join(`\\n`)\n}\n\nfunction selectExportImports(\n\tpackageName: string,\n\texportsValue: unknown,\n\tselection: TonnageConfig[`exports`],\n): string[] {\n\tif (selection === false) {\n\t\treturn []\n\t}\n\n\tconst exportKeys = getExportKeys(exportsValue)\n\tconst options: TonnageExports = typeof selection === `object` ? selection : {}\n\tconst included = options.include\n\t\t? [...options.include]\n\t\t: exportKeys.filter((exportKey) => exportKey !== `./package.json`)\n\tconst excluded = new Set(options.exclude ?? [])\n\n\treturn included\n\t\t.filter((exportKey) => !excluded.has(exportKey))\n\t\t.map((exportKey) => toPackageImport(packageName, exportKey))\n}\n\nfunction getExportKeys(exportsValue: unknown): string[] {\n\tif (typeof exportsValue === `string` || Array.isArray(exportsValue)) {\n\t\treturn [`.`]\n\t}\n\tif (!exportsValue || typeof exportsValue !== `object`) {\n\t\treturn [`.`]\n\t}\n\n\tconst keys = Object.keys(exportsValue)\n\treturn keys.some((key) => key.startsWith(`.`)) ? keys : [`.`]\n}\n\nfunction toPackageImport(packageName: string, exportKey: string): string {\n\tif (exportKey === `.`) {\n\t\treturn packageName\n\t}\n\tif (!exportKey.startsWith(`./`)) {\n\t\tthrow new Error(`Invalid package export key: ${exportKey}`)\n\t}\n\treturn `${packageName}/${exportKey.slice(2)}`\n}\n\nfunction formatBytes(bytes: number): string {\n\treturn `${new Intl.NumberFormat(`en-US`).format(bytes)} B`\n}\n\nfunction code(value: string): string {\n\treturn `<code>${escapeCell(value)}</code>`\n}\n\nfunction escapeCell(value: string): string {\n\treturn value.replaceAll(`&`, `&amp;`).replaceAll(`|`, `&#124;`)\n}\n\nfunction unique(values: readonly string[]): string[] {\n\treturn [...new Set(values)]\n}\n\nfunction markdownTable(\n\theadings: readonly string[],\n\trows: readonly (readonly string[])[],\n\talignments: readonly (`left` | `right`)[],\n): string[] {\n\tconst widths = headings.map((heading, column) =>\n\t\tMath.max(heading.length, ...rows.map((row) => row[column]?.length ?? 0), 3),\n\t)\n\tconst renderRow = (cells: readonly string[]): string =>\n\t\t`| ${cells.map((cell, column) => padCell(cell, widths[column] ?? 3, alignments[column] ?? `left`)).join(` | `)} |`\n\tconst separator = widths.map((width, column) =>\n\t\talignments[column] === `right`\n\t\t\t? `${`-`.repeat(width - 1)}:`\n\t\t\t: `-`.repeat(width),\n\t)\n\n\treturn [renderRow(headings), renderRow(separator), ...rows.map(renderRow)]\n}\n\nfunction padCell(\n\tcell: string,\n\twidth: number,\n\talignment: `left` | `right`,\n): string {\n\treturn alignment === `right` ? cell.padStart(width) : cell.padEnd(width)\n}\n","import fs from \"node:fs/promises\"\nimport path from \"node:path\"\n\nimport { updateGeneratedSection } from \"./readme.ts\"\nimport { createTonnageReport, renderTonnageMarkdown } from \"./report.ts\"\nimport type { TonnageConfig, TonnageMode, TonnageRunResult } from \"./types.ts\"\n\nexport async function runTonnage(\n\tconfig: TonnageConfig,\n\toptions: {\n\t\tconfigDirectory?: string\n\t\tmode: TonnageMode\n\t},\n): Promise<TonnageRunResult> {\n\tconst configDirectory = path.resolve(options.configDirectory ?? process.cwd())\n\tconst readmePath = path.resolve(configDirectory, config.readme ?? `README.md`)\n\tconst oldReadme = await fs.readFile(readmePath, `utf8`)\n\tconst report = await createTonnageReport(config, configDirectory)\n\tconst markdown = renderTonnageMarkdown(report, config)\n\tconst newReadme = updateGeneratedSection(oldReadme, markdown, config.marker)\n\tconst changed = oldReadme !== newReadme\n\n\tif (options.mode === `write` && changed) {\n\t\tawait fs.writeFile(readmePath, newReadme)\n\t}\n\n\treturn { changed, readmePath, report }\n}\n"],"mappings":"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"}

package/examples/recipes/my-package.d.ts

@@ -0,0 +1,9 @@
+// eslint-disable-next-line quotes
+declare module "my-package" {
+	export const atom: unknown
+}
+
+// eslint-disable-next-line quotes
+declare module "my-package/react" {
+	export const useO: unknown
+}

package/examples/recipes/react-app.ts

@@ -0,0 +1,4 @@
+// @exhibit-region start recipe
+export { atom } from "my-package"
+export { useO } from "my-package/react"
+// @exhibit-region end recipe

package/examples/tonnage.config.ts

@@ -0,0 +1,19 @@
+import { defineConfig, type TonnageConfig } from "tonnage"
+
+// @exhibit-region start config
+const config: TonnageConfig = defineConfig({
+	exports: {
+		exclude: [`./package.json`],
+	},
+	marker: `my-package`,
+	recipes: [
+		{
+			entry: `examples/recipes/react-app.ts`,
+			name: `React app`,
+			platform: `browser`,
+		},
+	],
+})
+
+export default config
+// @exhibit-region end config

package/package.json

@@ -0,0 +1,53 @@
+{
+	"name": "tonnage",
+	"version": "0.0.0",
+	"description": "Keep deterministic bundle size reports in README files and CI.",
+	"type": "module",
+	"license": "MIT",
+	"author": "Jeremy Banka",
+	"engines": {
+		"node": ">=22.18.0"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/jeremybanka/tonnage.git"
+	},
+	"files": [
+		"bin",
+		"dist",
+		"src",
+		"examples",
+		"README.md"
+	],
+	"bin": {
+		"tonnage": "bin/tonnage.bin.js"
+	},
+	"exports": {
+		".": {
+			"import": "./dist/index.js",
+			"types": "./dist/index.d.ts"
+		}
+	},
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"scripts": {
+		"build": "tsdown",
+		"lint:eslint": "eslint",
+		"lint:oxlint": "oxlint",
+		"lint:types": "tsc",
+		"test:once": "vitest run"
+	},
+	"dependencies": {
+		"esbuild": "0.28.1"
+	},
+	"devDependencies": {
+		"@types/node": "26.4.0",
+		"eslint": "10.9.1",
+		"tsdown": "0.22.14",
+		"typescript": "7.0.2",
+		"vitest": "4.1.11"
+	}
+}

package/src/cli.ts

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+
+import fs from "node:fs/promises"
+import path from "node:path"
+import { pathToFileURL } from "node:url"
+
+import { runTonnage } from "./run.ts"
+import type { TonnageConfig, TonnageMode } from "./types.ts"
+
+const DEFAULT_CONFIG_FILES = [
+	`tonnage.config.ts`,
+	`tonnage.config.mjs`,
+	`tonnage.config.js`,
+]
+
+async function main(): Promise<void> {
+	const command = process.argv[2]
+	const mode = parseMode(command)
+	const configPath = await findConfig(process.argv[3])
+	const config = await loadConfig(configPath)
+	const result = await runTonnage(config, {
+		configDirectory: path.dirname(configPath),
+		mode,
+	})
+
+	if (mode === `check` && result.changed) {
+		process.stderr.write(
+			`${path.relative(process.cwd(), result.readmePath)} is out of date. Run tonnage write.\n`,
+		)
+		process.exitCode = 1
+		return
+	}
+
+	const readme = path.relative(process.cwd(), result.readmePath)
+	process.stdout.write(
+		result.changed
+			? `Updated ${readme}.\n`
+			: `${readme} is already up to date.\n`,
+	)
+}
+
+function parseMode(command: string | undefined): TonnageMode {
+	switch (command) {
+		case `check`:
+		case `test`:
+			return `check`
+		case `make`:
+		case `write`:
+			return `write`
+		case undefined:
+		default:
+			throw new Error(`Usage: tonnage <write|check> [tonnage.config.ts]`)
+	}
+}
+
+async function findConfig(configArgument: string | undefined): Promise<string> {
+	if (configArgument) {
+		return path.resolve(configArgument)
+	}
+
+	for (const filename of DEFAULT_CONFIG_FILES) {
+		const candidate = path.resolve(filename)
+		try {
+			await fs.access(candidate)
+			return candidate
+		} catch {
+			// Keep looking for the next supported config filename.
+		}
+	}
+
+	throw new Error(
+		`Could not find a tonnage config (${DEFAULT_CONFIG_FILES.join(`, `)}).`,
+	)
+}
+
+async function loadConfig(configPath: string): Promise<TonnageConfig> {
+	const imported = (await import(pathToFileURL(configPath).href)) as {
+		default?: unknown
+	}
+	if (!imported.default || typeof imported.default !== `object`) {
+		throw new Error(`${configPath} must default-export a tonnage config.`)
+	}
+	return imported.default
+}
+
+main().catch((error: unknown) => {
+	process.stderr.write(
+		`${error instanceof Error ? error.message : String(error)}\n`,
+	)
+	process.exitCode = 1
+})

package/src/define-config.ts

@@ -0,0 +1,5 @@
+import type { TonnageConfig } from "./types.ts"
+
+export function defineConfig(config: TonnageConfig): TonnageConfig {
+	return config
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+export { defineConfig } from "./define-config.ts"
+export type { MeasureEntryOptions, MeasureImportsOptions } from "./measure.ts"
+export { measureEntry, measureImports } from "./measure.ts"
+export { tonnageMarkers, updateGeneratedSection } from "./readme.ts"
+export { createTonnageReport, renderTonnageMarkdown } from "./report.ts"
+export { runTonnage } from "./run.ts"
+export type {
+	BundleMeasurement,
+	BundlePlatform,
+	TonnageConfig,
+	TonnageExports,
+	TonnageMode,
+	TonnageRecipe,
+	TonnageRecipeRow,
+	TonnageReport,
+	TonnageRow,
+	TonnageRunResult,
+} from "./types.ts"

package/src/measure.ts

@@ -0,0 +1,96 @@
+import path from "node:path"
+import { gzipSync } from "node:zlib"
+
+import { build, type BuildOptions } from "esbuild"
+
+import type { BundleMeasurement, BundlePlatform } from "./types.ts"
+
+export type MeasureImportsOptions = {
+	external?: readonly string[] | undefined
+	platform?: BundlePlatform | undefined
+	resolveDirectory: string
+	target?: string | undefined
+}
+
+export type MeasureEntryOptions = MeasureImportsOptions
+
+export async function measureEntry(
+	entry: string,
+	options: MeasureEntryOptions,
+): Promise<BundleMeasurement> {
+	return measureBuild(
+		{ entryPoints: [path.resolve(options.resolveDirectory, entry)] },
+		options,
+	)
+}
+
+export async function measureImports(
+	imports: readonly string[],
+	options: MeasureImportsOptions,
+): Promise<BundleMeasurement> {
+	if (imports.length === 0) {
+		throw new Error(`A tonnage entry must import at least one module.`)
+	}
+
+	const entry = imports
+		.map(
+			(specifier, index) =>
+				`export * as entry${index} from ${JSON.stringify(specifier)}`,
+		)
+		.join(`\n`)
+	return measureBuild(
+		{
+			stdin: {
+				contents: entry,
+				loader: `js`,
+				resolveDir: options.resolveDirectory,
+				sourcefile: `tonnage-entry.js`,
+			},
+		},
+		options,
+	)
+}
+
+async function measureBuild(
+	entry: Pick<BuildOptions, `entryPoints` | `stdin`>,
+	options: MeasureEntryOptions,
+): Promise<BundleMeasurement> {
+	const platform = options.platform ?? `neutral`
+
+	const result = await build({
+		bundle: true,
+		charset: `utf8`,
+		external: [
+			...(options.external ?? []),
+			...(platform === `browser` ? [] : [`node:*`]),
+		],
+		format: `esm`,
+		legalComments: `none`,
+		logLevel: `silent`,
+		minify: true,
+		outdir: `out`,
+		platform,
+		...entry,
+		target: options.target ?? `es2022`,
+		treeShaking: true,
+		write: false,
+	})
+
+	const outputFiles = [...(result.outputFiles ?? [])]
+		.filter((output) => output.path.endsWith(`.js`))
+		.sort((left, right) => left.path.localeCompare(right.path))
+	if (outputFiles.length === 0) {
+		throw new Error(`The tonnage entry did not emit any runtime JavaScript.`)
+	}
+	const rawBytes = outputFiles.reduce(
+		(total, output) => total + output.contents.byteLength,
+		0,
+	)
+	const gzipBytes = outputFiles.reduce(
+		(total, output) =>
+			total + gzipSync(output.contents, { level: 9 }).byteLength,
+		0,
+	)
+
+	return { gzipBytes, rawBytes }
+}

package/src/readme.ts

@@ -0,0 +1,48 @@
+export function tonnageMarkers(marker = `default`): {
+	end: string
+	start: string
+} {
+	validateMarker(marker)
+	return {
+		end: `<!-- tonnage:${marker}:end -->`,
+		start: `<!-- tonnage:${marker}:start -->`,
+	}
+}
+
+export function updateGeneratedSection(
+	readme: string,
+	markdown: string,
+	marker?: string,
+): string {
+	const { end, start } = tonnageMarkers(marker)
+	const startIndex = readme.indexOf(start)
+	const endIndex = readme.indexOf(end)
+
+	if (startIndex === -1 || endIndex === -1) {
+		throw new Error(
+			`README must contain exactly one ${start} and one ${end} marker.`,
+		)
+	}
+	if (
+		readme.slice(startIndex + start.length).includes(start) ||
+		readme.slice(endIndex + end.length).includes(end)
+	) {
+		throw new Error(
+			`README must contain exactly one ${start} and one ${end} marker.`,
+		)
+	}
+	if (endIndex < startIndex) {
+		throw new Error(`${end} must appear after ${start}.`)
+	}
+
+	const contentStart = startIndex + start.length
+	return `${readme.slice(0, contentStart)}\n\n${markdown.trim()}\n\n${readme.slice(endIndex)}`
+}
+
+function validateMarker(marker: string): void {
+	if (!/^[a-z0-9][a-z0-9._-]*$/i.test(marker)) {
+		throw new Error(
+			`Tonnage marker names may contain letters, numbers, dots, underscores, and hyphens.`,
+		)
+	}
+}

package/src/report.ts

@@ -0,0 +1,206 @@
+import fs from "node:fs/promises"
+import path from "node:path"
+
+import { measureEntry, measureImports } from "./measure.ts"
+import type {
+	TonnageConfig,
+	TonnageExports,
+	TonnageReport,
+	TonnageRow,
+} from "./types.ts"
+
+type PackageJson = {
+	exports?: unknown
+	name?: string
+	peerDependencies?: Record<string, string>
+}
+
+export async function createTonnageReport(
+	config: TonnageConfig,
+	configDirectory: string,
+): Promise<TonnageReport> {
+	const packageJsonPath = path.resolve(
+		configDirectory,
+		config.packageJson ?? `package.json`,
+	)
+	const packageJson = JSON.parse(
+		await fs.readFile(packageJsonPath, `utf8`),
+	) as PackageJson
+	if (!packageJson.name) {
+		throw new Error(`${packageJsonPath} does not declare a package name.`)
+	}
+
+	const resolveDirectory = path.dirname(packageJsonPath)
+	const peerDependencies = Object.keys(packageJson.peerDependencies ?? {})
+	const external = unique([...peerDependencies, ...(config.external ?? [])])
+	const exportImports = selectExportImports(
+		packageJson.name,
+		packageJson.exports,
+		config.exports,
+	)
+
+	const exportRows = await Promise.all(
+		exportImports.map(async (specifier): Promise<TonnageRow> => ({
+			...(await measureImports([specifier], {
+				external,
+				platform: config.platform,
+				resolveDirectory,
+				target: config.target,
+			})),
+			imports: [specifier],
+			name: specifier,
+		})),
+	)
+	const recipeRows = await Promise.all(
+		(config.recipes ?? []).map(async (recipe) => ({
+			...(await measureEntry(recipe.entry, {
+				external: unique([...external, ...(recipe.external ?? [])]),
+				platform: recipe.platform ?? config.platform,
+				resolveDirectory,
+				target: config.target,
+			})),
+			entry: recipe.entry,
+			name: recipe.name,
+		})),
+	)
+
+	return {
+		exports: exportRows,
+		packageName: packageJson.name,
+		recipes: recipeRows,
+	}
+}
+
+export function renderTonnageMarkdown(
+	report: TonnageReport,
+	config: TonnageConfig = {},
+): string {
+	const lines = [
+		`## ${config.heading ?? `Bundle size`}`,
+		``,
+		`Public-module rows retain complete runtime export surfaces. Recipe rows bundle their reviewable entry files and tree-shake unused exports. Both report exact minified and level-9 gzip JavaScript byte counts; declarations, source maps, CSS, and other assets are excluded. Peer dependencies stay external, and shared modules are counted once per bundle.`,
+	]
+
+	if (report.exports.length > 0) {
+		lines.push(
+			``,
+			`### Public modules (whole export surface)`,
+			``,
+			...markdownTable(
+				[`Import`, `Minified JS`, `Gzip JS`],
+				report.exports.map((row) => [
+					code(row.name),
+					formatBytes(row.rawBytes),
+					formatBytes(row.gzipBytes),
+				]),
+				[`left`, `right`, `right`],
+			),
+		)
+	}
+
+	if (report.recipes.length > 0) {
+		lines.push(
+			``,
+			`### Representative runtimes (tree-shaken)`,
+			``,
+			...markdownTable(
+				[`Recipe`, `Entry`, `Minified JS`, `Gzip JS`],
+				report.recipes.map((row) => [
+					escapeCell(row.name),
+					code(row.entry),
+					formatBytes(row.rawBytes),
+					formatBytes(row.gzipBytes),
+				]),
+				[`left`, `left`, `right`, `right`],
+			),
+		)
+	}
+
+	return lines.join(`\n`)
+}
+
+function selectExportImports(
+	packageName: string,
+	exportsValue: unknown,
+	selection: TonnageConfig[`exports`],
+): string[] {
+	if (selection === false) {
+		return []
+	}
+
+	const exportKeys = getExportKeys(exportsValue)
+	const options: TonnageExports = typeof selection === `object` ? selection : {}
+	const included = options.include
+		? [...options.include]
+		: exportKeys.filter((exportKey) => exportKey !== `./package.json`)
+	const excluded = new Set(options.exclude ?? [])
+
+	return included
+		.filter((exportKey) => !excluded.has(exportKey))
+		.map((exportKey) => toPackageImport(packageName, exportKey))
+}
+
+function getExportKeys(exportsValue: unknown): string[] {
+	if (typeof exportsValue === `string` || Array.isArray(exportsValue)) {
+		return [`.`]
+	}
+	if (!exportsValue || typeof exportsValue !== `object`) {
+		return [`.`]
+	}
+
+	const keys = Object.keys(exportsValue)
+	return keys.some((key) => key.startsWith(`.`)) ? keys : [`.`]
+}
+
+function toPackageImport(packageName: string, exportKey: string): string {
+	if (exportKey === `.`) {
+		return packageName
+	}
+	if (!exportKey.startsWith(`./`)) {
+		throw new Error(`Invalid package export key: ${exportKey}`)
+	}
+	return `${packageName}/${exportKey.slice(2)}`
+}
+
+function formatBytes(bytes: number): string {
+	return `${new Intl.NumberFormat(`en-US`).format(bytes)} B`
+}
+
+function code(value: string): string {
+	return `<code>${escapeCell(value)}</code>`
+}
+
+function escapeCell(value: string): string {
+	return value.replaceAll(`&`, `&amp;`).replaceAll(`|`, `&#124;`)
+}
+
+function unique(values: readonly string[]): string[] {
+	return [...new Set(values)]
+}
+
+function markdownTable(
+	headings: readonly string[],
+	rows: readonly (readonly string[])[],
+	alignments: readonly (`left` | `right`)[],
+): string[] {
+	const widths = headings.map((heading, column) =>
+		Math.max(heading.length, ...rows.map((row) => row[column]?.length ?? 0), 3),
+	)
+	const renderRow = (cells: readonly string[]): string =>
+		`| ${cells.map((cell, column) => padCell(cell, widths[column] ?? 3, alignments[column] ?? `left`)).join(` | `)} |`
+	const separator = widths.map((width, column) =>
+		alignments[column] === `right`
+			? `${`-`.repeat(width - 1)}:`
+			: `-`.repeat(width),
+	)
+
+	return [renderRow(headings), renderRow(separator), ...rows.map(renderRow)]
+}
+
+function padCell(
+	cell: string,
+	width: number,
+	alignment: `left` | `right`,
+): string {
+	return alignment === `right` ? cell.padStart(width) : cell.padEnd(width)
+}

package/src/run.ts

@@ -0,0 +1,28 @@
+import fs from "node:fs/promises"
+import path from "node:path"
+
+import { updateGeneratedSection } from "./readme.ts"
+import { createTonnageReport, renderTonnageMarkdown } from "./report.ts"
+import type { TonnageConfig, TonnageMode, TonnageRunResult } from "./types.ts"
+
+export async function runTonnage(
+	config: TonnageConfig,
+	options: {
+		configDirectory?: string
+		mode: TonnageMode
+	},
+): Promise<TonnageRunResult> {
+	const configDirectory = path.resolve(options.configDirectory ?? process.cwd())
+	const readmePath = path.resolve(configDirectory, config.readme ?? `README.md`)
+	const oldReadme = await fs.readFile(readmePath, `utf8`)
+	const report = await createTonnageReport(config, configDirectory)
+	const markdown = renderTonnageMarkdown(report, config)
+	const newReadme = updateGeneratedSection(oldReadme, markdown, config.marker)
+	const changed = oldReadme !== newReadme
+
+	if (options.mode === `write` && changed) {
+		await fs.writeFile(readmePath, newReadme)
+	}
+
+	return { changed, readmePath, report }
+}

package/src/types.ts

@@ -0,0 +1,54 @@
+export type BundlePlatform = `browser` | `neutral` | `node`
+
+export type TonnageExports = {
+	exclude?: readonly string[]
+	include?: readonly string[]
+}
+
+export type TonnageRecipe = {
+	entry: string
+	external?: readonly string[]
+	name: string
+	platform?: BundlePlatform
+}
+
+export type TonnageConfig = {
+	exports?: boolean | TonnageExports
+	external?: readonly string[]
+	heading?: string
+	marker?: string
+	packageJson?: string
+	platform?: BundlePlatform
+	readme?: string
+	recipes?: readonly TonnageRecipe[]
+	target?: string
+}
+
+export type BundleMeasurement = {
+	gzipBytes: number
+	rawBytes: number
+}
+
+export type TonnageRow = BundleMeasurement & {
+	imports: readonly string[]
+	name: string
+}
+
+export type TonnageRecipeRow = BundleMeasurement & {
+	entry: string
+	name: string
+}
+
+export type TonnageReport = {
+	exports: readonly TonnageRow[]
+	packageName: string
+	recipes: readonly TonnageRecipeRow[]
+}
+
+export type TonnageMode = `check` | `write`
+
+export type TonnageRunResult = {
+	changed: boolean
+	readmePath: string
+	report: TonnageReport
+}