feat(build): add hole-punch tool to reduce compressed binary size (#245)

## Summary

- Adds `script/hole-punch.ts` — a post-compile tool that zeros unused
ICU data entries inside Bun-compiled binaries, making zeroed regions
compress to nearly nothing
- Reduces gzip download size by ~24% (37 MB -> 28 MB) across all
platforms
- Runs automatically in CI after build, before smoke test

## How it works

The Bun runtime embeds a 29 MB ICU data blob for international locale
support. Most entries (legacy charset converters, CJK dictionaries,
non-English locale data) are unused by a CLI tool. The tool scans for
the ICU blob via magic bytes, parses its TOC, and zeros safe-to-remove
entries while preserving root-level data, normalization files, and
English locale data that Bun accesses at startup/shutdown.

## Changes

- `script/hole-punch.ts` — hole-punch tool with modular exports for
testing
- `test/lib/hole-punch.test.ts` — 22 unit tests with synthetic ICU blob
builder
- `.github/workflows/ci.yml` — added hole-punch step after build
- `package.json` — added `hole-punch` script

Author: BYK

package.json

@@ -13,6 +13,7 @@
     "dev": "bun run src/bin.ts",
     "build": "bun run script/build.ts --single",
     "build:all": "bun run script/build.ts",
+    "hole-punch": "bun run script/hole-punch.ts",
     "bundle": "bun run script/bundle.ts",
     "typecheck": "tsc --noEmit",
     "lint": "bunx ultracite check",

script/build.ts

@@ -24,6 +24,7 @@ import { promisify } from "node:util";
 import { gzip } from "node:zlib";
 import { $ } from "bun";
 import pkg from "../package.json";
+import { processBinary } from "./hole-punch.js";
 
 const gzipAsync = promisify(gzip);
 
@@ -98,8 +99,17 @@ async function buildTarget(target: BuildTarget): Promise<boolean> {
 
   console.log(`    -> ${outfile}`);
 
+  // Hole-punch: zero unused ICU data entries so they compress to nearly nothing.
+  // Must run before gzip so the compressed output benefits from zeroed regions.
+  const hpStats = processBinary(outfile);
+  if (hpStats && hpStats.removedEntries > 0) {
+    console.log(
+      `    -> hole-punched ${hpStats.removedEntries}/${hpStats.totalEntries} ICU entries`
+    );
+  }
+
   // In CI, create gzip-compressed copies for release downloads.
-  // Reduces download size by ~60% (99 MB → 37 MB).
+  // With hole-punch, reduces download size by ~70% (99 MB → 28 MB).
   if (process.env.CI) {
     const binary = await Bun.file(outfile).arrayBuffer();
     const compressed = await gzipAsync(Buffer.from(binary), { level: 6 });