tonnage 0.0.0 → 0.1.1

package/dist/{run-DIk7L56w.js → run-P2rhqYM3.mjs}

@@ -1,12 +1,41 @@
+import fs from "node:fs/promises";
 import path from "node:path";
 import { gzipSync } from "node:zlib";
 import { build } from "esbuild";
-import fs from "node:fs/promises";
+import os from "node:os";
+//#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/measure.ts
 async function measureEntry(entry, options) {
+	return measureEntryWithPlugins(entry, options);
+}
+async function measureEntryWithPlugins(entry, options) {
 	return measureBuild({ entryPoints: [path.resolve(options.resolveDirectory, entry)] }, options);
 }
 async function measureImports(imports, options) {
+	return measureImportsWithPlugins(imports, options);
+}
+async function measureImportsWithPlugins(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`),
@@ -24,9 +53,11 @@ async function measureBuild(entry, options) {
 		format: `esm`,
 		legalComments: `none`,
 		logLevel: `silent`,
+		...platform === `neutral` ? { mainFields: [`module`, `main`] } : {},
 		minify: true,
 		outdir: `out`,
 		platform,
+		plugins: [...options.plugins ?? []],
 		...entry,
 		target: options.target ?? `es2022`,
 		treeShaking: true,
@@ -40,26 +71,40 @@ async function measureBuild(entry, options) {
 	};
 }
 //#endregion
-//#region src/readme.ts
-function tonnageMarkers(marker = `default`) {
-	validateMarker(marker);
-	return {
-		end: `<!-- tonnage:${marker}:end -->`,
-		start: `<!-- tonnage:${marker}:start -->`
-	};
+//#region src/package-resolution.ts
+async function withPackageResolver(packageName, packageDirectory, useResolver) {
+	const temporaryDirectory = await fs.mkdtemp(path.join(os.tmpdir(), `tonnage-package-`));
+	try {
+		const nodeModulesDirectory = path.join(temporaryDirectory, `node_modules`);
+		const packageLinkPath = path.resolve(nodeModulesDirectory, packageName);
+		if (!packageLinkPath.startsWith(`${nodeModulesDirectory}${path.sep}`)) throw new Error(`Invalid package name: ${packageName}`);
+		await fs.mkdir(path.dirname(packageLinkPath), { recursive: true });
+		await fs.symlink(packageDirectory, packageLinkPath, process.platform === `win32` ? `junction` : `dir`);
+		const filter = new RegExp(`^${escapeRegExp(packageName)}(?:/.*)?$`);
+		return await useResolver({
+			name: `tonnage-package-resolution`,
+			setup(build) {
+				build.onResolve({ filter }, async (args) => {
+					if (args.resolveDir === temporaryDirectory) return;
+					return build.resolve(args.path, {
+						importer: args.importer,
+						kind: args.kind,
+						namespace: args.namespace,
+						resolveDir: temporaryDirectory,
+						with: args.with
+					});
+				});
+			}
+		});
+	} finally {
+		await fs.rm(temporaryDirectory, {
+			force: true,
+			recursive: true
+		});
+	}
 }
-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.`);
+function escapeRegExp(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, `\\$&`);
 }
 //#endregion
 //#region src/report.ts
@@ -70,26 +115,32 @@ async function createTonnageReport(config, configDirectory) {
 	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
-	})));
+	const { exportRows, recipeRows } = await withPackageResolver(packageJson.name, resolveDirectory, async (packageResolver) => {
+		return {
+			exportRows: await Promise.all(exportImports.map(async (specifier) => ({
+				...await measureImportsWithPlugins([specifier], {
+					external,
+					platform: config.platform,
+					plugins: [packageResolver],
+					resolveDirectory,
+					target: config.target
+				}),
+				imports: [specifier],
+				name: specifier
+			}))),
+			recipeRows: await Promise.all((config.recipes ?? []).map(async (recipe) => ({
+				...await measureEntryWithPlugins(recipe.entry, {
+					external: unique([...external, ...recipe.external ?? []]),
+					platform: recipe.platform ?? config.platform,
+					plugins: [packageResolver],
+					resolveDirectory,
+					target: config.target
+				}),
+				entry: recipe.entry,
+				name: recipe.name
+			})))
+		};
+	});
 	return {
 		exports: exportRows,
 		packageName: packageJson.name,
@@ -97,12 +148,18 @@ async function createTonnageReport(config, configDirectory) {
 	};
 }
 function renderTonnageMarkdown(report, config = {}) {
+	const hasExports = report.exports.length > 0;
+	const hasRecipes = report.recipes.length > 0;
+	const hasMultipleSections = hasExports && hasRecipes;
 	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.`
+		...methodologyLines({
+			hasExports,
+			hasRecipes
+		})
 	];
-	if (report.exports.length > 0) lines.push(``, `### Public modules (whole export surface)`, ``, ...markdownTable([
+	if (hasExports) lines.push(``, ...hasMultipleSections ? [`### Package exports`, ``] : [], ...markdownTable([
 		`Import`,
 		`Minified JS`,
 		`Gzip JS`
@@ -115,7 +172,7 @@ function renderTonnageMarkdown(report, config = {}) {
 		`right`,
 		`right`
 	]));
-	if (report.recipes.length > 0) lines.push(``, `### Representative runtimes (tree-shaken)`, ``, ...markdownTable([
+	if (hasRecipes) lines.push(``, ...hasMultipleSections ? [`### Usage examples`, ``] : [], ...markdownTable([
 		`Recipe`,
 		`Entry`,
 		`Minified JS`,
@@ -133,6 +190,13 @@ function renderTonnageMarkdown(report, config = {}) {
 	]));
 	return lines.join(`\n`);
 }
+function methodologyLines({ hasExports, hasRecipes }) {
+	const lines = [];
+	if (hasExports) lines.push(`Package export sizes include complete runtime export surfaces.`);
+	if (hasRecipes) lines.push(`Usage example sizes bundle their entry files and tree-shake unused exports.`);
+	lines.push(`Sizes are 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.`);
+	return lines;
+}
 function selectExportImports(packageName, exportsValue, selection) {
 	if (selection === false) return [];
 	const exportKeys = getExportKeys(exportsValue);
@@ -194,6 +258,6 @@ async function runTonnage(config, options) {
 	};
 }
 //#endregion
-export { updateGeneratedSection as a, tonnageMarkers as i, createTonnageReport as n, measureEntry as o, renderTonnageMarkdown as r, measureImports as s, runTonnage as t };
+export { measureImports as a, measureEntry as i, createTonnageReport as n, tonnageMarkers as o, renderTonnageMarkdown as r, updateGeneratedSection as s, runTonnage as t };
 
-//# sourceMappingURL=run-DIk7L56w.js.map
+//# sourceMappingURL=run-P2rhqYM3.mjs.map

package/dist/run-P2rhqYM3.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-P2rhqYM3.mjs","names":[],"sources":["../src/readme.ts","../src/measure.ts","../src/package-resolution.ts","../src/report.ts","../src/run.ts"],"sourcesContent":["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 path from \"node:path\"\nimport { gzipSync } from \"node:zlib\"\n\nimport { build, type BuildOptions, type Plugin } 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\ntype InternalMeasureOptions = MeasureImportsOptions & {\n\tplugins?: readonly Plugin[]\n}\n\nexport async function measureEntry(\n\tentry: string,\n\toptions: MeasureEntryOptions,\n): Promise<BundleMeasurement> {\n\treturn measureEntryWithPlugins(entry, options)\n}\n\nexport async function measureEntryWithPlugins(\n\tentry: string,\n\toptions: InternalMeasureOptions,\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\treturn measureImportsWithPlugins(imports, options)\n}\n\nexport async function measureImportsWithPlugins(\n\timports: readonly string[],\n\toptions: InternalMeasureOptions,\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: InternalMeasureOptions,\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\t...(platform === `neutral` ? { mainFields: [`module`, `main`] } : {}),\n\t\tminify: true,\n\t\toutdir: `out`,\n\t\tplatform,\n\t\tplugins: [...(options.plugins ?? [])],\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","import fs from \"node:fs/promises\"\nimport os from \"node:os\"\nimport path from \"node:path\"\n\nimport type { Plugin } from \"esbuild\"\n\nexport async function withPackageResolver<Result>(\n\tpackageName: string,\n\tpackageDirectory: string,\n\tuseResolver: (plugin: Plugin) => Promise<Result>,\n): Promise<Result> {\n\tconst temporaryDirectory = await fs.mkdtemp(\n\t\tpath.join(os.tmpdir(), `tonnage-package-`),\n\t)\n\ttry {\n\t\tconst nodeModulesDirectory = path.join(temporaryDirectory, `node_modules`)\n\t\tconst packageLinkPath = path.resolve(nodeModulesDirectory, packageName)\n\t\tif (!packageLinkPath.startsWith(`${nodeModulesDirectory}${path.sep}`)) {\n\t\t\tthrow new Error(`Invalid package name: ${packageName}`)\n\t\t}\n\n\t\tawait fs.mkdir(path.dirname(packageLinkPath), { recursive: true })\n\t\tawait fs.symlink(\n\t\t\tpackageDirectory,\n\t\t\tpackageLinkPath,\n\t\t\tprocess.platform === `win32` ? `junction` : `dir`,\n\t\t)\n\n\t\tconst filter = new RegExp(`^${escapeRegExp(packageName)}(?:/.*)?$`)\n\t\tconst plugin: Plugin = {\n\t\t\tname: `tonnage-package-resolution`,\n\t\t\tsetup(build) {\n\t\t\t\tbuild.onResolve({ filter }, async (args) => {\n\t\t\t\t\tif (args.resolveDir === temporaryDirectory) {\n\t\t\t\t\t\treturn\n\t\t\t\t\t}\n\n\t\t\t\t\treturn build.resolve(args.path, {\n\t\t\t\t\t\timporter: args.importer,\n\t\t\t\t\t\tkind: args.kind,\n\t\t\t\t\t\tnamespace: args.namespace,\n\t\t\t\t\t\tresolveDir: temporaryDirectory,\n\t\t\t\t\t\twith: args.with,\n\t\t\t\t\t})\n\t\t\t\t})\n\t\t\t},\n\t\t}\n\n\t\treturn await useResolver(plugin)\n\t} finally {\n\t\tawait fs.rm(temporaryDirectory, { force: true, recursive: true })\n\t}\n}\n\nfunction escapeRegExp(value: string): string {\n\treturn value.replace(/[.*+?^${}()|[\\]\\\\]/g, `\\\\$&`)\n}\n","import fs from \"node:fs/promises\"\nimport path from \"node:path\"\n\nimport {\n\tmeasureEntryWithPlugins,\n\tmeasureImportsWithPlugins,\n} from \"./measure.ts\"\nimport { withPackageResolver } from \"./package-resolution.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, recipeRows } = await withPackageResolver(\n\t\tpackageJson.name,\n\t\tresolveDirectory,\n\t\tasync (packageResolver) => {\n\t\t\tconst exportRows = await Promise.all(\n\t\t\t\texportImports.map(async (specifier): Promise<TonnageRow> => ({\n\t\t\t\t\t...(await measureImportsWithPlugins([specifier], {\n\t\t\t\t\t\texternal,\n\t\t\t\t\t\tplatform: config.platform,\n\t\t\t\t\t\tplugins: [packageResolver],\n\t\t\t\t\t\tresolveDirectory,\n\t\t\t\t\t\ttarget: config.target,\n\t\t\t\t\t})),\n\t\t\t\t\timports: [specifier],\n\t\t\t\t\tname: specifier,\n\t\t\t\t})),\n\t\t\t)\n\t\t\tconst recipeRows = await Promise.all(\n\t\t\t\t(config.recipes ?? []).map(async (recipe) => ({\n\t\t\t\t\t...(await measureEntryWithPlugins(recipe.entry, {\n\t\t\t\t\t\texternal: unique([...external, ...(recipe.external ?? [])]),\n\t\t\t\t\t\tplatform: recipe.platform ?? config.platform,\n\t\t\t\t\t\tplugins: [packageResolver],\n\t\t\t\t\t\tresolveDirectory,\n\t\t\t\t\t\ttarget: config.target,\n\t\t\t\t\t})),\n\t\t\t\t\tentry: recipe.entry,\n\t\t\t\t\tname: recipe.name,\n\t\t\t\t})),\n\t\t\t)\n\n\t\t\treturn { exportRows, recipeRows }\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 hasExports = report.exports.length > 0\n\tconst hasRecipes = report.recipes.length > 0\n\tconst hasMultipleSections = hasExports && hasRecipes\n\tconst lines = [\n\t\t`## ${config.heading ?? `Bundle size`}`,\n\t\t``,\n\t\t...methodologyLines({ hasExports, hasRecipes }),\n\t]\n\n\tif (hasExports) {\n\t\tlines.push(\n\t\t\t``,\n\t\t\t...(hasMultipleSections ? [`### Package exports`, ``] : []),\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 (hasRecipes) {\n\t\tlines.push(\n\t\t\t``,\n\t\t\t...(hasMultipleSections ? [`### Usage examples`, ``] : []),\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 methodologyLines({\n\thasExports,\n\thasRecipes,\n}: {\n\thasExports: boolean\n\thasRecipes: boolean\n}): string[] {\n\tconst lines: string[] = []\n\tif (hasExports) {\n\t\tlines.push(`Package export sizes include complete runtime export surfaces.`)\n\t}\n\tif (hasRecipes) {\n\t\tlines.push(\n\t\t\t`Usage example sizes bundle their entry files and tree-shake unused exports.`,\n\t\t)\n\t}\n\tlines.push(\n\t\t`Sizes are 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\treturn lines\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":";;;;;;AAAA,SAAgB,eAAe,SAAS,WAGtC;CACD,eAAe,MAAM;CACrB,OAAO;EACN,KAAK,gBAAgB,OAAO;EAC5B,OAAO,gBAAgB,OAAO;CAC/B;AACD;AAEA,SAAgB,uBACf,QACA,UACA,QACS;CACT,MAAM,EAAE,KAAK,UAAU,eAAe,MAAM;CAC5C,MAAM,aAAa,OAAO,QAAQ,KAAK;CACvC,MAAM,WAAW,OAAO,QAAQ,GAAG;CAEnC,IAAI,eAAe,MAAM,aAAa,IACrC,MAAM,IAAI,MACT,mCAAmC,MAAM,WAAW,IAAI,SACzD;CAED,IACC,OAAO,MAAM,aAAa,MAAM,MAAM,CAAC,CAAC,SAAS,KAAK,KACtD,OAAO,MAAM,WAAW,IAAI,MAAM,CAAC,CAAC,SAAS,GAAG,GAEhD,MAAM,IAAI,MACT,mCAAmC,MAAM,WAAW,IAAI,SACzD;CAED,IAAI,WAAW,YACd,MAAM,IAAI,MAAM,GAAG,IAAI,qBAAqB,MAAM,EAAE;CAGrD,MAAM,eAAe,aAAa,MAAM;CACxC,OAAO,GAAG,OAAO,MAAM,GAAG,YAAY,EAAE,MAAM,SAAS,KAAK,EAAE,MAAM,OAAO,MAAM,QAAQ;AAC1F;AAEA,SAAS,eAAe,QAAsB;CAC7C,IAAI,CAAC,0BAA0B,KAAK,MAAM,GACzC,MAAM,IAAI,MACT,oFACD;AAEF;;;AC3BA,eAAsB,aACrB,OACA,SAC6B;CAC7B,OAAO,wBAAwB,OAAO,OAAO;AAC9C;AAEA,eAAsB,wBACrB,OACA,SAC6B;CAC7B,OAAO,aACN,EAAE,aAAa,CAAC,KAAK,QAAQ,QAAQ,kBAAkB,KAAK,CAAC,EAAE,GAC/D,OACD;AACD;AAEA,eAAsB,eACrB,SACA,SAC6B;CAC7B,OAAO,0BAA0B,SAAS,OAAO;AAClD;AAEA,eAAsB,0BACrB,SACA,SAC6B;CAC7B,IAAI,QAAQ,WAAW,GACtB,MAAM,IAAI,MAAM,kDAAkD;CASnE,OAAO,aACN,EACC,OAAO;EACN,UATW,QACZ,KACC,WAAW,UACX,oBAAoB,MAAM,QAAQ,KAAK,UAAU,SAAS,GAC5D,CAAC,CACA,KAAK,IAIU;EACd,QAAQ;EACR,YAAY,QAAQ;EACpB,YAAY;CACb,EACD,GACA,OACD;AACD;AAEA,eAAe,aACd,OACA,SAC6B;CAC7B,MAAM,WAAW,QAAQ,YAAY;CAuBrC,MAAM,cAAc,CAAC,IAAI,MArBJ,MAAM;EAC1B,QAAQ;EACR,SAAS;EACT,UAAU,CACT,GAAI,QAAQ,YAAY,CAAC,GACzB,GAAI,aAAa,YAAY,CAAC,IAAI,CAAC,QAAQ,CAC5C;EACA,QAAQ;EACR,eAAe;EACf,UAAU;EACV,GAAI,aAAa,YAAY,EAAE,YAAY,CAAC,UAAU,MAAM,EAAE,IAAI,CAAC;EACnE,QAAQ;EACR,QAAQ;EACR;EACA,SAAS,CAAC,GAAI,QAAQ,WAAW,CAAC,CAAE;EACpC,GAAG;EACH,QAAQ,QAAQ,UAAU;EAC1B,aAAa;EACb,OAAO;CACR,CAAC,EAAA,CAE+B,eAAe,CAAC,CAAE,CAAC,CACjD,QAAQ,WAAW,OAAO,KAAK,SAAS,KAAK,CAAC,CAAC,CAC/C,MAAM,MAAM,UAAU,KAAK,KAAK,cAAc,MAAM,IAAI,CAAC;CAC3D,IAAI,YAAY,WAAW,GAC1B,MAAM,IAAI,MAAM,wDAAwD;CAEzE,MAAM,WAAW,YAAY,QAC3B,OAAO,WAAW,QAAQ,OAAO,SAAS,YAC3C,CACD;CAOA,OAAO;EAAE,WANS,YAAY,QAC5B,OAAO,WACP,QAAQ,SAAS,OAAO,UAAU,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,YACjD,CAGgB;EAAG;CAAS;AAC9B;;;AC7GA,eAAsB,oBACrB,aACA,kBACA,aACkB;CAClB,MAAM,qBAAqB,MAAM,GAAG,QACnC,KAAK,KAAK,GAAG,OAAO,GAAG,kBAAkB,CAC1C;CACA,IAAI;EACH,MAAM,uBAAuB,KAAK,KAAK,oBAAoB,cAAc;EACzE,MAAM,kBAAkB,KAAK,QAAQ,sBAAsB,WAAW;EACtE,IAAI,CAAC,gBAAgB,WAAW,GAAG,uBAAuB,KAAK,KAAK,GACnE,MAAM,IAAI,MAAM,yBAAyB,aAAa;EAGvD,MAAM,GAAG,MAAM,KAAK,QAAQ,eAAe,GAAG,EAAE,WAAW,KAAK,CAAC;EACjE,MAAM,GAAG,QACR,kBACA,iBACA,QAAQ,aAAa,UAAU,aAAa,KAC7C;EAEA,MAAM,SAAS,IAAI,OAAO,IAAI,aAAa,WAAW,EAAE,UAAU;EAoBlE,OAAO,MAAM,YAAY;GAlBxB,MAAM;GACN,MAAM,OAAO;IACZ,MAAM,UAAU,EAAE,OAAO,GAAG,OAAO,SAAS;KAC3C,IAAI,KAAK,eAAe,oBACvB;KAGD,OAAO,MAAM,QAAQ,KAAK,MAAM;MAC/B,UAAU,KAAK;MACf,MAAM,KAAK;MACX,WAAW,KAAK;MAChB,YAAY;MACZ,MAAM,KAAK;KACZ,CAAC;IACF,CAAC;GACF;EAG6B,CAAC;CAChC,UAAU;EACT,MAAM,GAAG,GAAG,oBAAoB;GAAE,OAAO;GAAM,WAAW;EAAK,CAAC;CACjE;AACD;AAEA,SAAS,aAAa,OAAuB;CAC5C,OAAO,MAAM,QAAQ,uBAAuB,MAAM;AACnD;;;ACnCA,eAAsB,oBACrB,QACA,iBACyB;CACzB,MAAM,kBAAkB,KAAK,QAC5B,iBACA,OAAO,eAAe,cACvB;CACA,MAAM,cAAc,KAAK,MACxB,MAAM,GAAG,SAAS,iBAAiB,MAAM,CAC1C;CACA,IAAI,CAAC,YAAY,MAChB,MAAM,IAAI,MAAM,GAAG,gBAAgB,kCAAkC;CAGtE,MAAM,mBAAmB,KAAK,QAAQ,eAAe;CAErD,MAAM,WAAW,OAAO,CAAC,GADA,OAAO,KAAK,YAAY,oBAAoB,CAAC,CAC3B,GAAG,GAAI,OAAO,YAAY,CAAC,CAAE,CAAC;CACzE,MAAM,gBAAgB,oBACrB,YAAY,MACZ,YAAY,SACZ,OAAO,OACR;CAEA,MAAM,EAAE,YAAY,eAAe,MAAM,oBACxC,YAAY,MACZ,kBACA,OAAO,oBAAoB;EA4B1B,OAAO;GAAE,YAAA,MA3BgB,QAAQ,IAChC,cAAc,IAAI,OAAO,eAAoC;IAC5D,GAAI,MAAM,0BAA0B,CAAC,SAAS,GAAG;KAChD;KACA,UAAU,OAAO;KACjB,SAAS,CAAC,eAAe;KACzB;KACA,QAAQ,OAAO;IAChB,CAAC;IACD,SAAS,CAAC,SAAS;IACnB,MAAM;GACP,EAAE,CACH;GAeqB,YAAA,MAdI,QAAQ,KAC/B,OAAO,WAAW,CAAC,EAAA,CAAG,IAAI,OAAO,YAAY;IAC7C,GAAI,MAAM,wBAAwB,OAAO,OAAO;KAC/C,UAAU,OAAO,CAAC,GAAG,UAAU,GAAI,OAAO,YAAY,CAAC,CAAE,CAAC;KAC1D,UAAU,OAAO,YAAY,OAAO;KACpC,SAAS,CAAC,eAAe;KACzB;KACA,QAAQ,OAAO;IAChB,CAAC;IACD,OAAO,OAAO;IACd,MAAM,OAAO;GACd,EAAE,CACH;EAEgC;CACjC,CACD;CAEA,OAAO;EACN,SAAS;EACT,aAAa,YAAY;EACzB,SAAS;CACV;AACD;AAEA,SAAgB,sBACf,QACA,SAAwB,CAAC,GAChB;CACT,MAAM,aAAa,OAAO,QAAQ,SAAS;CAC3C,MAAM,aAAa,OAAO,QAAQ,SAAS;CAC3C,MAAM,sBAAsB,cAAc;CAC1C,MAAM,QAAQ;EACb,MAAM,OAAO,WAAW;EACxB;EACA,GAAG,iBAAiB;GAAE;GAAY;EAAW,CAAC;CAC/C;CAEA,IAAI,YACH,MAAM,KACL,IACA,GAAI,sBAAsB,CAAC,uBAAuB,EAAE,IAAI,CAAC,GACzD,GAAG,cACF;EAAC;EAAU;EAAe;CAAS,GACnC,OAAO,QAAQ,KAAK,QAAQ;EAC3B,KAAK,IAAI,IAAI;EACb,YAAY,IAAI,QAAQ;EACxB,YAAY,IAAI,SAAS;CAC1B,CAAC,GACD;EAAC;EAAQ;EAAS;CAAO,CAC1B,CACD;CAGD,IAAI,YACH,MAAM,KACL,IACA,GAAI,sBAAsB,CAAC,sBAAsB,EAAE,IAAI,CAAC,GACxD,GAAG,cACF;EAAC;EAAU;EAAS;EAAe;CAAS,GAC5C,OAAO,QAAQ,KAAK,QAAQ;EAC3B,WAAW,IAAI,IAAI;EACnB,KAAK,IAAI,KAAK;EACd,YAAY,IAAI,QAAQ;EACxB,YAAY,IAAI,SAAS;CAC1B,CAAC,GACD;EAAC;EAAQ;EAAQ;EAAS;CAAO,CAClC,CACD;CAGD,OAAO,MAAM,KAAK,IAAI;AACvB;AAEA,SAAS,iBAAiB,EACzB,YACA,cAIY;CACZ,MAAM,QAAkB,CAAC;CACzB,IAAI,YACH,MAAM,KAAK,gEAAgE;CAE5E,IAAI,YACH,MAAM,KACL,6EACD;CAED,MAAM,KACL,mNACD;CACA,OAAO;AACR;AAEA,SAAS,oBACR,aACA,cACA,WACW;CACX,IAAI,cAAc,OACjB,OAAO,CAAC;CAGT,MAAM,aAAa,cAAc,YAAY;CAC7C,MAAM,UAA0B,OAAO,cAAc,WAAW,YAAY,CAAC;CAC7E,MAAM,WAAW,QAAQ,UACtB,CAAC,GAAG,QAAQ,OAAO,IACnB,WAAW,QAAQ,cAAc,cAAc,gBAAgB;CAClE,MAAM,WAAW,IAAI,IAAI,QAAQ,WAAW,CAAC,CAAC;CAE9C,OAAO,SACL,QAAQ,cAAc,CAAC,SAAS,IAAI,SAAS,CAAC,CAAC,CAC/C,KAAK,cAAc,gBAAgB,aAAa,SAAS,CAAC;AAC7D;AAEA,SAAS,cAAc,cAAiC;CACvD,IAAI,OAAO,iBAAiB,YAAY,MAAM,QAAQ,YAAY,GACjE,OAAO,CAAC,GAAG;CAEZ,IAAI,CAAC,gBAAgB,OAAO,iBAAiB,UAC5C,OAAO,CAAC,GAAG;CAGZ,MAAM,OAAO,OAAO,KAAK,YAAY;CACrC,OAAO,KAAK,MAAM,QAAQ,IAAI,WAAW,GAAG,CAAC,IAAI,OAAO,CAAC,GAAG;AAC7D;AAEA,SAAS,gBAAgB,aAAqB,WAA2B;CACxE,IAAI,cAAc,KACjB,OAAO;CAER,IAAI,CAAC,UAAU,WAAW,IAAI,GAC7B,MAAM,IAAI,MAAM,+BAA+B,WAAW;CAE3D,OAAO,GAAG,YAAY,GAAG,UAAU,MAAM,CAAC;AAC3C;AAEA,SAAS,YAAY,OAAuB;CAC3C,OAAO,GAAG,IAAI,KAAK,aAAa,OAAO,CAAC,CAAC,OAAO,KAAK,EAAE;AACxD;AAEA,SAAS,KAAK,OAAuB;CACpC,OAAO,SAAS,WAAW,KAAK,EAAE;AACnC;AAEA,SAAS,WAAW,OAAuB;CAC1C,OAAO,MAAM,WAAW,KAAK,OAAO,CAAC,CAAC,WAAW,KAAK,QAAQ;AAC/D;AAEA,SAAS,OAAO,QAAqC;CACpD,OAAO,CAAC,GAAG,IAAI,IAAI,MAAM,CAAC;AAC3B;AAEA,SAAS,cACR,UACA,MACA,YACW;CACX,MAAM,SAAS,SAAS,KAAK,SAAS,WACrC,KAAK,IAAI,QAAQ,QAAQ,GAAG,KAAK,KAAK,QAAQ,IAAI,OAAO,EAAE,UAAU,CAAC,GAAG,CAAC,CAC3E;CACA,MAAM,aAAa,UAClB,KAAK,MAAM,KAAK,MAAM,WAAW,QAAQ,MAAM,OAAO,WAAW,GAAG,WAAW,WAAW,MAAM,CAAC,CAAC,CAAC,KAAK,KAAK,EAAE;CAChH,MAAM,YAAY,OAAO,KAAK,OAAO,WACpC,WAAW,YAAY,UACpB,GAAG,IAAI,OAAO,QAAQ,CAAC,EAAE,KACzB,IAAI,OAAO,KAAK,CACpB;CAEA,OAAO;EAAC,UAAU,QAAQ;EAAG,UAAU,SAAS;EAAG,GAAG,KAAK,IAAI,SAAS;CAAC;AAC1E;AAEA,SAAS,QACR,MACA,OACA,WACS;CACT,OAAO,cAAc,UAAU,KAAK,SAAS,KAAK,IAAI,KAAK,OAAO,KAAK;AACxE;;;AC3OA,eAAsB,WACrB,QACA,SAI4B;CAC5B,MAAM,kBAAkB,KAAK,QAAQ,QAAQ,mBAAmB,QAAQ,IAAI,CAAC;CAC7E,MAAM,aAAa,KAAK,QAAQ,iBAAiB,OAAO,UAAU,WAAW;CAC7E,MAAM,YAAY,MAAM,GAAG,SAAS,YAAY,MAAM;CACtD,MAAM,SAAS,MAAM,oBAAoB,QAAQ,eAAe;CAEhE,MAAM,YAAY,uBAAuB,WADxB,sBAAsB,QAAQ,MACK,GAAU,OAAO,MAAM;CAC3E,MAAM,UAAU,cAAc;CAE9B,IAAI,QAAQ,SAAS,WAAW,SAC/B,MAAM,GAAG,UAAU,YAAY,SAAS;CAGzC,OAAO;EAAE;EAAS;EAAY;CAAO;AACtC"}

package/package.json

@@ -1,53 +1,51 @@
 {
-	"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"
-	}
-}
+  "name": "tonnage",
+  "version": "0.1.1",
+  "description": "Keep deterministic bundle size reports in README files and CI.",
+  "type": "module",
+  "license": "MPL-2.0",
+  "author": "Jeremy Banka",
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jeremybanka/tonnage.git"
+  },
+  "files": [
+    "AGENTS.md",
+    "CHANGELOG.md",
+    "dist",
+    "src",
+    "examples",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "tonnage": "dist/cli.mjs"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "types": "./dist/index.d.mts"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "dependencies": {
+    "comline": "0.5.2",
+    "esbuild": "0.28.2"
+  },
+  "devDependencies": {
+    "@types/node": "26.4.0",
+    "vitest": "npm:@voidzero-dev/vite-plus-test@0.1.24"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "test": "vp test"
+  }
+}

package/src/cli.ts

@@ -4,8 +4,9 @@ import fs from "node:fs/promises"
 import path from "node:path"
 import { pathToFileURL } from "node:url"
 
+import { parseTonnageCli, renderTonnageCliHelp } from "./command-line.ts"
 import { runTonnage } from "./run.ts"
-import type { TonnageConfig, TonnageMode } from "./types.ts"
+import type { TonnageConfig } from "./types.ts"
 
 const DEFAULT_CONFIG_FILES = [
 	`tonnage.config.ts`,
@@ -14,9 +15,14 @@ const DEFAULT_CONFIG_FILES = [
 ]
 
 async function main(): Promise<void> {
-	const command = process.argv[2]
-	const mode = parseMode(command)
-	const configPath = await findConfig(process.argv[3])
+	const invocation = parseTonnageCli([`tonnage`, ...process.argv.slice(2)])
+	if (invocation.kind === `help`) {
+		process.stdout.write(renderTonnageCliHelp())
+		return
+	}
+
+	const { configArgument, mode } = invocation
+	const configPath = await findConfig(configArgument)
 	const config = await loadConfig(configPath)
 	const result = await runTonnage(config, {
 		configDirectory: path.dirname(configPath),
@@ -39,20 +45,6 @@ async function main(): Promise<void> {
 	)
 }
 
-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)

package/src/command-line.ts

@@ -0,0 +1,52 @@
+import { cli, help, helpOption, optional } from "comline"
+
+import type { TonnageMode } from "./types.ts"
+
+const ROOT_MANUAL = helpOption(`Show help for the tonnage command line.`)
+const WRITE_MANUAL = helpOption(`Update the configured README report.`)
+const CHECK_MANUAL = helpOption(
+	`Check that the configured README report is up to date.`,
+)
+
+const tonnageCli = cli({
+	cliName: `tonnage`,
+	cliDescription: `Keep deterministic bundle size reports in README files and CI.`,
+	routes: optional({
+		check: optional({ $configPath: null }),
+		write: optional({ $configPath: null }),
+	}),
+	routeOptions: {
+		"": ROOT_MANUAL,
+		check: CHECK_MANUAL,
+		"check/$configPath": CHECK_MANUAL,
+		write: WRITE_MANUAL,
+		"write/$configPath": WRITE_MANUAL,
+	},
+	discoverConfigPath: () => undefined,
+})
+
+export type TonnageCliInvocation =
+	| { kind: `help` }
+	| { configArgument?: string; kind: `run`; mode: TonnageMode }
+
+export function parseTonnageCli(args: string[]): TonnageCliInvocation {
+	const { inputs } = tonnageCli(args)
+
+	if (inputs.case === `` || inputs.opts.help) {
+		return { kind: `help` }
+	}
+
+	const mode =
+		inputs.case === `write` || inputs.case === `write/$configPath`
+			? `write`
+			: `check`
+	const configArgument = inputs.path[1]
+
+	return configArgument === undefined
+		? { kind: `run`, mode }
+		: { configArgument, kind: `run`, mode }
+}
+
+export function renderTonnageCliHelp(): string {
+	return help(tonnageCli.definition)
+}

package/src/measure.ts

@@ -1,7 +1,7 @@
 import path from "node:path"
 import { gzipSync } from "node:zlib"
 
-import { build, type BuildOptions } from "esbuild"
+import { build, type BuildOptions, type Plugin } from "esbuild"
 
 import type { BundleMeasurement, BundlePlatform } from "./types.ts"
 
@@ -14,9 +14,20 @@ export type MeasureImportsOptions = {
 
 export type MeasureEntryOptions = MeasureImportsOptions
 
+type InternalMeasureOptions = MeasureImportsOptions & {
+	plugins?: readonly Plugin[]
+}
+
 export async function measureEntry(
 	entry: string,
 	options: MeasureEntryOptions,
+): Promise<BundleMeasurement> {
+	return measureEntryWithPlugins(entry, options)
+}
+
+export async function measureEntryWithPlugins(
+	entry: string,
+	options: InternalMeasureOptions,
 ): Promise<BundleMeasurement> {
 	return measureBuild(
 		{ entryPoints: [path.resolve(options.resolveDirectory, entry)] },
@@ -27,6 +38,13 @@ export async function measureEntry(
 export async function measureImports(
 	imports: readonly string[],
 	options: MeasureImportsOptions,
+): Promise<BundleMeasurement> {
+	return measureImportsWithPlugins(imports, options)
+}
+
+export async function measureImportsWithPlugins(
+	imports: readonly string[],
+	options: InternalMeasureOptions,
 ): Promise<BundleMeasurement> {
 	if (imports.length === 0) {
 		throw new Error(`A tonnage entry must import at least one module.`)
@@ -53,7 +71,7 @@ export async function measureImports(
 
 async function measureBuild(
 	entry: Pick<BuildOptions, `entryPoints` | `stdin`>,
-	options: MeasureEntryOptions,
+	options: InternalMeasureOptions,
 ): Promise<BundleMeasurement> {
 	const platform = options.platform ?? `neutral`
 
@@ -67,9 +85,11 @@ async function measureBuild(
 		format: `esm`,
 		legalComments: `none`,
 		logLevel: `silent`,
+		...(platform === `neutral` ? { mainFields: [`module`, `main`] } : {}),
 		minify: true,
 		outdir: `out`,
 		platform,
+		plugins: [...(options.plugins ?? [])],
 		...entry,
 		target: options.target ?? `es2022`,
 		treeShaking: true,

package/src/package-resolution.ts

@@ -0,0 +1,57 @@
+import fs from "node:fs/promises"
+import os from "node:os"
+import path from "node:path"
+
+import type { Plugin } from "esbuild"
+
+export async function withPackageResolver<Result>(
+	packageName: string,
+	packageDirectory: string,
+	useResolver: (plugin: Plugin) => Promise<Result>,
+): Promise<Result> {
+	const temporaryDirectory = await fs.mkdtemp(
+		path.join(os.tmpdir(), `tonnage-package-`),
+	)
+	try {
+		const nodeModulesDirectory = path.join(temporaryDirectory, `node_modules`)
+		const packageLinkPath = path.resolve(nodeModulesDirectory, packageName)
+		if (!packageLinkPath.startsWith(`${nodeModulesDirectory}${path.sep}`)) {
+			throw new Error(`Invalid package name: ${packageName}`)
+		}
+
+		await fs.mkdir(path.dirname(packageLinkPath), { recursive: true })
+		await fs.symlink(
+			packageDirectory,
+			packageLinkPath,
+			process.platform === `win32` ? `junction` : `dir`,
+		)
+
+		const filter = new RegExp(`^${escapeRegExp(packageName)}(?:/.*)?$`)
+		const plugin: Plugin = {
+			name: `tonnage-package-resolution`,
+			setup(build) {
+				build.onResolve({ filter }, async (args) => {
+					if (args.resolveDir === temporaryDirectory) {
+						return
+					}
+
+					return build.resolve(args.path, {
+						importer: args.importer,
+						kind: args.kind,
+						namespace: args.namespace,
+						resolveDir: temporaryDirectory,
+						with: args.with,
+					})
+				})
+			},
+		}
+
+		return await useResolver(plugin)
+	} finally {
+		await fs.rm(temporaryDirectory, { force: true, recursive: true })
+	}
+}
+
+function escapeRegExp(value: string): string {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, `\\$&`)
+}