chore: command to get package size info (#20)

* meta: command to get package size info

* chore: make pkg-size its own internal package

code quality improved by a factor of roughly 874 quintillion

* doc: add note about building before trying to get size report

Author: cyyynthia

.gitignore

@@ -14,3 +14,5 @@ tsconfig.tsbuildinfo
 
 .idea
 .DS_Store
+
+.pkgsize

README.md

@@ -67,3 +67,37 @@ pnpm run -r build
 pnpm run pull
 pnpm run -r generate
 ```
+
+### checking package sizes
+
+to observe the size of packages (both install size and bundled size), there is a `pkg-size-report`
+tool doing just that. you can also save the package sizes at a given time and inspect the impact of
+changes to the final bundle size. the tool uses `esbuild` to produce a minified bundle to get the
+size of each entrypoint.
+
+<!-- prettier-ignore-start -->
+<!-- Otherwise it wrecks the gfm alertbox ugh -->
+
+> [!WARNING]
+> run `pnpm run -r build` before running the command. otherwise, the command **may not run**, or **give bad measurements**.
+
+<!-- prettier-ignore-end -->
+
+```sh
+# See the size of packages.
+# If package sizes were saved previously, will also show the diff.
+pnpm pkg-size-report
+
+# Save esbuild metafiles and package size information.
+pnpm pkg-size-report --save
+
+# Save just esbuild metafiles.
+pnpm pkg-size-report --save-meta
+
+# Show only the packages whose size have changed.
+pnpm pkg-size-report --compare
+
+# Keep the result bundle produced by esbuild.
+# Will be left in /tmp/[...]--[pkgname]--[random]
+pnpm pkg-size-report --keep-builds
+```

package.json

@@ -1,4 +1,5 @@
 {
+	"private": true,
 	"type": "module",
 	"scripts": {
 		"pull": "node ./scripts/pull-lexicons.js",
@@ -8,6 +9,8 @@
 	},
 	"devDependencies": {
 		"@mary/tar": "npm:@jsr/mary__tar@^0.2.4",
+		"mitata": "^1.0.23",
+		"pkg-size-report": "workspace:^",
 		"prettier": "^3.4.2",
 		"typescript": "5.7.2"
 	}

packages/bluesky/richtext-segmenter/package.json

@@ -30,7 +30,6 @@
 	"devDependencies": {
 		"@atcute/bluesky": "workspace:^",
 		"@atcute/client": "workspace:^",
-		"@types/bun": "^1.1.14",
-		"mitata": "^1.0.23"
+		"@types/bun": "^1.1.14"
 	}
 }

packages/internal/pkg-size-report/cli.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import './dist/index.js';

packages/internal/pkg-size-report/package.json

@@ -0,0 +1,25 @@
+{
+	"private": true,
+	"type": "module",
+	"name": "pkg-size-report",
+	"version": "1.0.1",
+	"description": "cli tool to compute and analyze package sizes",
+	"license": "MIT",
+	"repository": {
+		"url": "https://github.com/mary-ext/atcute",
+		"directory": "packages/internal/pkg-size-report"
+	},
+	"bin": "./cli.mjs",
+	"scripts": {
+		"build": "tsc"
+	},
+	"dependencies": {
+		"esbuild": "^0.24.2",
+		"js-yaml": "^4.1.0",
+		"picocolors": "^1.1.1"
+	},
+	"devDependencies": {
+		"@types/js-yaml": "^4.0.9",
+		"@types/node": "^22.10.2"
+	}
+}

packages/internal/pkg-size-report/src/bundle.ts

@@ -0,0 +1,34 @@
+import * as path from 'node:path';
+import * as os from 'node:os';
+import * as fs from 'node:fs';
+import * as url from 'node:url';
+import * as esbuild from 'esbuild';
+
+import { computeFolderSize } from './fs.js';
+
+export function computeBundleInformation(entry: URL, entryQualifier: string, keepBuild = false) {
+	const tmpDirPrefix = path.join(
+		os.tmpdir(),
+		`atcute-pkg-size-build--${entryQualifier.replaceAll('/', '__')}--`,
+	);
+
+	const tmpDir = fs.mkdtempSync(tmpDirPrefix);
+
+	const { metafile } = esbuild.buildSync({
+		bundle: true,
+		minify: true,
+		outdir: tmpDir,
+		metafile: true,
+		entryPoints: [url.fileURLToPath(entry)],
+	});
+
+	const tmpDirUrl = url.pathToFileURL(tmpDir);
+	const bundledSize = computeFolderSize(tmpDirUrl, true);
+
+	if (!keepBuild) fs.rmSync(tmpDir, { recursive: true });
+
+	return {
+		metafile,
+		...bundledSize,
+	};
+}

packages/internal/pkg-size-report/src/consts.ts

@@ -0,0 +1,3 @@
+export const WORKSPACE_ROOT = new URL('../../../../', import.meta.url);
+
+export const PKGSIZE_FOLDER = new URL('.pkgsize/', WORKSPACE_ROOT);

packages/internal/pkg-size-report/src/data.ts

@@ -0,0 +1,42 @@
+import type { Metafile } from 'esbuild';
+
+import * as fs from 'node:fs';
+import { PKGSIZE_FOLDER } from './consts.js';
+
+const PKGSIZE_DATA = new URL(`data.json`, PKGSIZE_FOLDER);
+
+export interface EntrypointSizeInformation {
+	name: string;
+	size: number;
+	gzip: number;
+	brotli: number;
+	metafile: Metafile;
+}
+
+export interface PackageSizeInformation {
+	name: string;
+	installSize: number;
+	entries: EntrypointSizeInformation[];
+}
+
+export function saveSizeData(data: PackageSizeInformation[]): void {
+	const json = JSON.stringify(data, (k, v) => (k === 'metafile' ? void 0 : v), '\t');
+	fs.writeFileSync(PKGSIZE_DATA, json);
+}
+
+export function readSizeData(): PackageSizeInformation[] | null {
+	if (!fs.existsSync(PKGSIZE_DATA)) return null;
+
+	const json = fs.readFileSync(PKGSIZE_DATA, 'utf8');
+	return JSON.parse(json);
+}
+
+export function saveEsbuildMetafiles(data: PackageSizeInformation[]): void {
+	for (const pkg of data) {
+		for (const { name, metafile } of pkg.entries) {
+			const path = new URL(`${name.replaceAll('/', '__')}-esbuild-metafile.json`, PKGSIZE_FOLDER);
+			const json = JSON.stringify(metafile, null, '\t');
+			fs.writeFileSync(path, json);
+		}
+	}
+}

packages/internal/pkg-size-report/src/diff.ts

@@ -0,0 +1,35 @@
+import type { PackageSizeInformation } from './data.js';
+
+export interface DiffInformation {
+	[key: string]: {
+		diff: number;
+		entries: {
+			[key: string]: { diff: number; gzip: number; brotli: number };
+		};
+	};
+}
+
+export function computeSizeDiff(
+	data: PackageSizeInformation[],
+	old: PackageSizeInformation[],
+): DiffInformation {
+	const diff: DiffInformation = {};
+	for (const pkg of data) {
+		const oldPkg = old.find((p) => p.name == pkg.name);
+		if (!oldPkg) continue;
+
+		diff[pkg.name] = { diff: pkg.installSize - oldPkg.installSize, entries: {} };
+		for (const entry of pkg.entries) {
+			const oldEntry = oldPkg.entries.find((e) => e.name === entry.name);
+			if (!oldEntry) continue;
+
+			diff[pkg.name].entries[entry.name] = {
+				diff: entry.size - oldEntry.size,
+				gzip: entry.gzip - oldEntry.gzip,
+				brotli: entry.brotli - oldEntry.brotli,
+			};
+		}
+	}
+
+	return diff;
+}

packages/internal/pkg-size-report/src/fs.ts

@@ -0,0 +1,32 @@
+import * as fs from 'node:fs';
+import * as zlib from 'node:zlib';
+
+export function computeFolderSize(folder: URL, detailed = false) {
+	folder.pathname += '/';
+	let res = { size: 0, gzip: 0, brotli: 0 };
+
+	for (const entry of fs.readdirSync(folder)) {
+		const path = new URL(entry, folder);
+		const stat = fs.statSync(path);
+
+		if (stat.isDirectory()) {
+			const nested = computeFolderSize(path);
+			res.size += nested.size;
+			res.gzip += nested.gzip;
+			res.brotli += nested.brotli;
+		}
+
+		if (stat.isFile()) {
+			res.size += stat.size;
+			if (detailed) {
+				const buf = fs.readFileSync(path);
+				const gzipBuf = zlib.gzipSync(buf);
+				const brotliBuf = zlib.brotliCompressSync(buf);
+				res.gzip += gzipBuf.length;
+				res.brotli += brotliBuf.length;
+			}
+		}
+	}
+
+	return res;
+}

packages/internal/pkg-size-report/src/index.ts

@@ -0,0 +1,66 @@
+import pc from 'picocolors';
+import { computePackageSizeInformation, getAllWorkspacePackages } from './package.js';
+import { readSizeData, saveEsbuildMetafiles, saveSizeData } from './data.js';
+import { computeSizeDiff } from './diff.js';
+
+const TREE_SYM_HAS_NEXT = '├';
+const TREE_SYM_FINAL = '└';
+
+const FLAG_SAVE = process.argv.includes('--save');
+const FLAG_SAVE_META = process.argv.includes('--save-meta');
+const FLAG_COMPARE = process.argv.includes('--compare');
+const FLAG_KEEP_BUILDS = process.argv.includes('--keep-builds');
+
+function formatSize(size: number) {
+	return `${(size / 1000).toFixed(2)}kB`.padEnd(7, ' ');
+}
+
+function formatDiffSize(size: number) {
+	const str = Math.abs(size) < 1000 ? `${size}B` : `${(size / 1000).toFixed(3)}kB`;
+	return size < 0 ? pc.green(str) : pc.red(`+${str}`);
+}
+
+// Get package info
+const packages = getAllWorkspacePackages();
+const sizeData = packages.map((pkg) => computePackageSizeInformation(pkg, FLAG_KEEP_BUILDS));
+
+// Compute diff if applicable
+const prevData = readSizeData();
+const diff = prevData && computeSizeDiff(sizeData, prevData);
+
+// Save files
+if (FLAG_SAVE) saveSizeData(sizeData);
+if (FLAG_SAVE || FLAG_SAVE_META) saveEsbuildMetafiles(sizeData);
+
+// Print to stdout.
+for (const pkg of sizeData) {
+	const pkgDiff = diff?.[pkg.name];
+	if (FLAG_COMPARE && pkgDiff?.diff === 0) continue;
+
+	let pkgInfo = `${pkg.name.padEnd(34, ' ')}\t${formatSize(pkg.installSize).padEnd(8, ' ')} ${pc.gray('install size')}`;
+	if (pkgDiff?.diff) pkgInfo += `    ${formatDiffSize(pkgDiff.diff)}`;
+
+	console.log(pkgInfo);
+
+	for (let i = 0; i < pkg.entries.length; i++) {
+		const entry = pkg.entries[i];
+		const entryDiff = pkgDiff?.entries[entry.name];
+
+		const size = formatSize(entry.size);
+		const gzip = `${formatSize(entry.gzip)} ${pc.gray('gzip')}`;
+		const brotli = `${formatSize(entry.brotli)} ${pc.gray('brotli')}`;
+
+		const treeSym = i === pkg.entries.length - 1 ? TREE_SYM_FINAL : TREE_SYM_HAS_NEXT;
+		let entryInfo = `${treeSym}── ${entry.name.padEnd(30, ' ')}\t${treeSym}── ${size}\t${gzip}\t${brotli}`;
+		if (entryDiff?.diff) {
+			const size = formatDiffSize(entryDiff.diff);
+			const gzip = formatDiffSize(entryDiff.gzip);
+			const brotli = formatDiffSize(entryDiff.brotli);
+			entryInfo += `    ${size}/${gzip}/${brotli}`;
+		}
+
+		console.log(entryInfo);
+	}
+
+	console.log();
+}

packages/internal/pkg-size-report/src/package.ts

@@ -0,0 +1,70 @@
+import type { PackageSizeInformation } from './data.js';
+
+import * as fs from 'node:fs';
+import { load as parseYaml } from 'js-yaml';
+import { WORKSPACE_ROOT } from './consts.js';
+import { computeFolderSize } from './fs.js';
+import { computeBundleInformation } from './bundle.js';
+
+interface PackageJsonData {
+	folder: URL;
+	relpath: string;
+	name: string;
+	private: boolean;
+	exports: Record<string, string> | null; // let's pretend the export map doesn't exist for now shall we :)
+}
+
+const PNPM_LOCKFILE = new URL('pnpm-lock.yaml', WORKSPACE_ROOT);
+
+export function getAllWorkspacePackages(): PackageJsonData[] {
+	const pnpmLockfileYaml = fs.readFileSync(PNPM_LOCKFILE, 'utf8');
+	const pnpmLockfile = parseYaml(pnpmLockfileYaml) as any;
+	const packages = Object.keys(pnpmLockfile.importers);
+
+	return packages
+		.map((p) => {
+			const packageFolder = new URL(`${p}/`, WORKSPACE_ROOT);
+			const packageJsonFile = new URL('package.json', packageFolder);
+			const packageJson = fs.readFileSync(packageJsonFile, 'utf8');
+			return Object.assign({}, JSON.parse(packageJson), {
+				folder: packageFolder,
+				relpath: p,
+			}) as PackageJsonData;
+		})
+		.filter((p) => !p.private);
+}
+
+export function computePackageSizeInformation(
+	pkg: PackageJsonData,
+	keepBuilds = false,
+): PackageSizeInformation {
+	const dist = new URL('dist/', pkg.folder);
+	const { size: installSize } = computeFolderSize(dist);
+
+	const pkgSizeInformation: PackageSizeInformation = {
+		name: pkg.name,
+		installSize,
+		entries: [],
+	};
+
+	// Those are just declaration packages with no useful payload.
+	if (pkg.relpath.includes('definitions')) return pkgSizeInformation;
+
+	// CLI & what not
+	if (!pkg.exports) return pkgSizeInformation;
+
+	for (const entry in pkg.exports) {
+		if (!Object.hasOwn(pkg.exports, entry)) continue;
+
+		const entryQualifier = pkg.name + entry.slice(1);
+		const entryFile = new URL(pkg.exports[entry], pkg.folder);
+
+		const data = computeBundleInformation(entryFile, entryQualifier, keepBuilds);
+		pkgSizeInformation.entries.push({
+			name: entryQualifier,
+			...data,
+		});
+	}
+
+	return pkgSizeInformation;
+}