bundle-cost-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kea0811
+
+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,143 @@
+# bundle-cost-cli
+
+![tests](https://img.shields.io/badge/tests-passing-brightgreen.svg)
+![coverage](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)
+![license](https://img.shields.io/badge/license-MIT-blue.svg)
+
+**🌐 [Live demo →](https://bundle-cost-cli.vercel.app)**
+
+> Print the real over-the-wire cost of your build output — and the delta on every save.
+
+You already know your bundle is "kinda big." What you don't know, in the moment you add a dependency, is _how much_ bigger it just got. `bundle-cost` answers that in one line: point it at your built files and it prints raw, gzip, and (optionally) brotli sizes. Run it with `--watch` and it reprints a **delta** every time you save — so a stray `import { everything } from 'lodash'` shows up as `+71 KB` before you commit it, not after a user complains.
+
+No bundler plugin, no config file, no telemetry. Just bytes.
+
+## Install
+
+**From GitHub** (always works):
+
+```bash
+pnpm add -g github:kea0811/bundle-cost-cli
+```
+
+**From npm** _(when published to npm)_:
+
+```bash
+pnpm add -g bundle-cost-cli
+```
+
+> Using npm or yarn? `npm install -g bundle-cost-cli` / `yarn global add bundle-cost-cli` work too. Or skip the install entirely and run it once with `pnpm dlx bundle-cost-cli dist/index.js` (`npx` works the same way).
+
+Requires Node 18+.
+
+## Quick start
+
+Point it at one or more files:
+
+```bash
+bundle-cost dist/index.js dist/index.cjs
+```
+
+```text
+File              Raw     Gzip
+dist/index.js   9.89 KB  3.37 KB
+dist/index.cjs  11.87 KB  4.06 KB
+total           21.76 KB  7.43 KB
+```
+
+### Watch mode — a delta on every save
+
+```bash
+bundle-cost dist/index.js --watch
+```
+
+The first render is your baseline. Every save after that adds a `Δ gzip` column, colored green when you shrank it and red when you grew it:
+
+```text
+File              Raw     Gzip   Δ gzip
+dist/index.js   10.4 KB  3.71 KB  +340 B
+total           10.4 KB  3.71 KB  +340 B
+```
+
+Pair it with your bundler's own watch mode in another terminal and you get a live cost readout for free.
+
+### Set a budget (great for CI)
+
+```bash
+bundle-cost dist/index.js --limit 50kb
+```
+
+If the **total gzip** size is over budget, `bundle-cost` prints a red `✗` line and exits with code `1` — so it fails your pipeline instead of silently shipping a regression. Under budget, it exits `0` with a green `✓`.
+
+### Machine-readable output
+
+```bash
+bundle-cost dist/index.js --json
+```
+
+```json
+{
+  "files": [
+    { "path": "dist/index.js", "raw": 10123, "gzip": 3451, "brotli": 3063, "delta": null }
+  ],
+  "total": { "raw": 10123, "gzip": 3451, "brotli": 3063, "delta": null }
+}
+```
+
+Pipe it into `jq`, store it as a build artifact, or diff two runs yourself.
+
+## Options
+
+| Flag | Description |
+| --- | --- |
+| `-w, --watch` | Watch the files and print the size delta on every save. |
+| `-b, --brotli` | Add a brotli column alongside gzip. |
+| `--no-gzip` | Hide the gzip column (show raw bytes only). |
+| `-j, --json` | Print machine-readable JSON instead of a table. |
+| `-l, --limit <size>` | Fail (exit `1`) if total gzip exceeds this budget, e.g. `50kb`, `1.5mb`. |
+| `--no-color` | Disable ANSI colors (also respects `NO_COLOR`). |
+| `-h, --help` | Show usage and examples. |
+
+Sizes accept `b`, `kb`, `mb`, `gb`, `tb` (case-insensitive), or a bare byte count.
+
+## Programmatic API
+
+The same building blocks ship as a typed ESM/CJS module, so you can wire bundle cost into your own scripts:
+
+```ts
+import { measureFile, buildReport, renderReport, formatBytes, createColors } from 'bundle-cost-cli';
+
+const size = await measureFile('dist/index.js');
+console.log(`gzip: ${formatBytes(size.gzip)}`);
+
+const report = buildReport([{ path: 'dist/index.js', size }]);
+console.log(renderReport(report, { gzip: true, brotli: false, json: false, colors: createColors(false) }));
+```
+
+`run(argv, deps)` is exported too — the whole CLI with injectable `log`, `error`, `cwd`, `env`, and `watch`, which is exactly how the test suite drives it.
+
+## How it works
+
+There's no minifier in here and no bundler hook. `bundle-cost` reads each file as-is and runs it through Node's built-in `zlib` — `gzipSync` and `brotliCompressSync` — because gzip and brotli are what a CDN actually serves. That keeps the tool dependency-light and honest: it measures the bytes you ship, not an estimate.
+
+Watch mode keeps the previous measurement in memory and diffs against it, so the delta is always "since the last save in this session." All of the I/O — stdout, the filesystem watcher, the clock — is injected, which is why the test suite hits 100% coverage without touching your real terminal.
+
+## Live demo
+
+See it in action at **[bundle-cost-cli.vercel.app](https://bundle-cost-cli.vercel.app)** — a static landing page with a sample run.
+
+## Contributing
+
+PRs welcome — especially new output formats and budget ergonomics. To hack on it:
+
+```bash
+pnpm install
+pnpm test
+pnpm build
+```
+
+`pnpm test:coverage` enforces 100% coverage, and `pnpm dev` rebuilds on change.
+
+## License
+
+MIT © [kea0811](https://github.com/kea0811)

package/dist/bin.cjs

@@ -0,0 +1,343 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/cli.ts
+var import_node_path = require("path");
+var import_commander = require("commander");
+
+// src/color.ts
+function wrap(open, close) {
+  return (text) => `\x1B[${open}m${text}\x1B[${close}m`;
+}
+var identity = (text) => text;
+function createColors(enabled) {
+  if (!enabled) {
+    return { green: identity, red: identity, dim: identity, cyan: identity, bold: identity };
+  }
+  return {
+    green: wrap(32, 39),
+    red: wrap(31, 39),
+    dim: wrap(2, 22),
+    cyan: wrap(36, 39),
+    bold: wrap(1, 22)
+  };
+}
+
+// src/format.ts
+var UNITS = ["B", "KB", "MB", "GB", "TB"];
+var SIZE_RE = /^(\d+(?:\.\d+)?)\s*(b|kb|mb|gb|tb)?$/i;
+var MULTIPLIERS = {
+  b: 1,
+  kb: 1024,
+  mb: 1024 ** 2,
+  gb: 1024 ** 3,
+  tb: 1024 ** 4
+};
+function formatBytes(bytes) {
+  if (bytes < 1) return "0 B";
+  const exponent = Math.min(
+    Math.floor(Math.log(bytes) / Math.log(1024)),
+    UNITS.length - 1
+  );
+  const value = bytes / 1024 ** exponent;
+  const rendered = exponent === 0 ? String(Math.round(value)) : value.toFixed(2);
+  return `${rendered} ${UNITS[exponent]}`;
+}
+function formatDelta(bytes) {
+  if (bytes === 0) return "0 B";
+  const sign = bytes > 0 ? "+" : "-";
+  return `${sign}${formatBytes(Math.abs(bytes))}`;
+}
+function parseSize(input) {
+  const match = SIZE_RE.exec(input.trim());
+  if (!match) {
+    throw new Error(
+      `Invalid size: "${input}" (try "50kb", "1.5mb", or a raw byte count)`
+    );
+  }
+  const value = Number(match[1]);
+  const unit = (match[2] ?? "b").toLowerCase();
+  return Math.round(value * MULTIPLIERS[unit]);
+}
+
+// src/render.ts
+var plainCell = (text) => ({ plain: text, colored: text });
+function colorDelta(delta, metric, colors) {
+  if (delta === null) return { plain: "new", colored: colors.cyan("new") };
+  const value = delta[metric];
+  const text = formatDelta(value);
+  if (value < 0) return { plain: text, colored: colors.green(text) };
+  if (value > 0) return { plain: text, colored: colors.red(text) };
+  return { plain: text, colored: colors.dim(text) };
+}
+function buildCells(label, size, delta, metric, hasDelta, options, bold) {
+  const cells = [
+    { plain: label, colored: bold ? options.colors.bold(label) : label },
+    plainCell(formatBytes(size.raw))
+  ];
+  if (options.gzip) cells.push(plainCell(formatBytes(size.gzip)));
+  if (options.brotli) cells.push(plainCell(formatBytes(size.brotli)));
+  if (hasDelta) cells.push(colorDelta(delta, metric, options.colors));
+  return cells;
+}
+function renderJson(report) {
+  return JSON.stringify(
+    {
+      files: report.rows.map((row) => ({
+        path: row.path,
+        raw: row.size.raw,
+        gzip: row.size.gzip,
+        brotli: row.size.brotli,
+        delta: row.delta
+      })),
+      total: {
+        raw: report.total.size.raw,
+        gzip: report.total.size.gzip,
+        brotli: report.total.size.brotli,
+        delta: report.total.delta
+      }
+    },
+    null,
+    2
+  );
+}
+function renderTable(report, options) {
+  const metric = options.gzip ? "gzip" : "raw";
+  const hasDelta = report.rows.some((row) => row.delta !== null) || report.total.delta !== null;
+  const headers = ["File", "Raw"];
+  if (options.gzip) headers.push("Gzip");
+  if (options.brotli) headers.push("Brotli");
+  if (hasDelta) headers.push(`\u0394 ${metric}`);
+  const headerCells = headers.map((header) => ({
+    plain: header,
+    colored: options.colors.dim(header)
+  }));
+  const bodyRows = report.rows.map(
+    (row) => buildCells(row.path, row.size, row.delta, metric, hasDelta, options, false)
+  );
+  const totalRow = buildCells(
+    "total",
+    report.total.size,
+    report.total.delta,
+    metric,
+    hasDelta,
+    options,
+    true
+  );
+  const matrix = [headerCells, ...bodyRows, totalRow];
+  const widths = headers.map(
+    (_, column) => Math.max(...matrix.map((row) => row[column].plain.length))
+  );
+  return matrix.map(
+    (row) => row.map((cell, column) => {
+      const padding = " ".repeat(widths[column] - cell.plain.length);
+      return column === 0 ? cell.colored + padding : padding + cell.colored;
+    }).join("  ")
+  ).join("\n");
+}
+function renderReport(report, options) {
+  return options.json ? renderJson(report) : renderTable(report, options);
+}
+
+// src/report.ts
+function subtract(next, prev) {
+  return {
+    raw: next.raw - prev.raw,
+    gzip: next.gzip - prev.gzip,
+    brotli: next.brotli - prev.brotli
+  };
+}
+function sum(sizes) {
+  return sizes.reduce(
+    (acc, size) => ({
+      raw: acc.raw + size.raw,
+      gzip: acc.gzip + size.gzip,
+      brotli: acc.brotli + size.brotli
+    }),
+    { raw: 0, gzip: 0, brotli: 0 }
+  );
+}
+function buildReport(measurements, previous) {
+  const rows = measurements.map((measurement) => {
+    const prev = previous?.get(measurement.path);
+    return {
+      path: measurement.path,
+      size: measurement.size,
+      delta: prev ? subtract(measurement.size, prev) : null
+    };
+  });
+  const totalSize = sum(measurements.map((m) => m.size));
+  const previousTotal = previous ? sum([...previous.values()]) : void 0;
+  return {
+    rows,
+    total: {
+      size: totalSize,
+      delta: previousTotal ? subtract(totalSize, previousTotal) : null
+    }
+  };
+}
+
+// src/sizes.ts
+var import_promises = require("fs/promises");
+var import_node_zlib = require("zlib");
+function measureBuffer(buffer) {
+  return {
+    raw: buffer.byteLength,
+    gzip: (0, import_node_zlib.gzipSync)(buffer).byteLength,
+    brotli: (0, import_node_zlib.brotliCompressSync)(buffer).byteLength
+  };
+}
+async function measureFile(path) {
+  const buffer = await (0, import_promises.readFile)(path);
+  return measureBuffer(buffer);
+}
+
+// src/watch.ts
+var fs = __toESM(require("fs"), 1);
+var defaultImpl = (path, onChange) => {
+  const watcher = fs.watch(path, () => onChange());
+  return { close: () => watcher.close() };
+};
+function watchPaths(paths, onChange, impl = defaultImpl) {
+  const watchers = paths.map((path) => impl(path, onChange));
+  return () => {
+    for (const watcher of watchers) watcher.close();
+  };
+}
+
+// src/cli.ts
+var DESCRIPTION = "Print the gzipped bundle cost of your files \u2014 and the delta on every save.";
+var HELP_EXAMPLES = `
+Examples:
+  $ bundle-cost dist/index.js
+  $ bundle-cost dist/*.js --brotli
+  $ bundle-cost dist/index.js --limit 50kb
+  $ bundle-cost dist/index.js --watch
+  $ bundle-cost dist/index.js --json
+`;
+var trimTrailingNewline = (text) => text.replace(/\n+$/, "");
+async function measureAll(targets) {
+  return Promise.all(
+    targets.map(async (target) => ({ ...target, size: await measureFile(target.path) }))
+  );
+}
+var toMeasurements = (measured) => measured.map((m) => ({ path: m.label, size: m.size }));
+var snapshot = (measured) => new Map(measured.map((m) => [m.label, m.size]));
+function startWatch(targets, renderOptions, initial, ctx) {
+  let previous = snapshot(initial);
+  ctx.log(renderOptions.colors.dim("watching for changes\u2026 (ctrl-c to stop)"));
+  ctx.watch(
+    targets.map((target) => target.path),
+    async () => {
+      let next;
+      try {
+        next = await measureAll(targets);
+      } catch (err) {
+        ctx.error(renderOptions.colors.red(`Could not read file: ${err.message}`));
+        return;
+      }
+      ctx.log(renderReport(buildReport(toMeasurements(next), previous), renderOptions));
+      previous = snapshot(next);
+    }
+  );
+}
+function reportBudget(totalGzip, limit, colors, ctx) {
+  const headline = `${formatBytes(totalGzip)} gzip`;
+  if (totalGzip > limit) {
+    ctx.error(colors.red(`\u2717 ${headline} exceeds the ${formatBytes(limit)} budget`));
+    return 1;
+  }
+  ctx.log(colors.green(`\u2713 ${headline} is within the ${formatBytes(limit)} budget`));
+  return 0;
+}
+async function execute(files, options, ctx) {
+  const colorsEnabled = options.color !== false && !ctx.env.NO_COLOR;
+  const renderOptions = {
+    gzip: options.gzip !== false,
+    brotli: options.brotli === true,
+    json: options.json === true,
+    colors: createColors(colorsEnabled)
+  };
+  let limit;
+  if (options.limit !== void 0) {
+    try {
+      limit = parseSize(options.limit);
+    } catch (err) {
+      ctx.error(renderOptions.colors.red(err.message));
+      return 1;
+    }
+  }
+  const targets = files.map((file) => ({ label: file, path: (0, import_node_path.resolve)(ctx.cwd, file) }));
+  let measured;
+  try {
+    measured = await measureAll(targets);
+  } catch (err) {
+    ctx.error(renderOptions.colors.red(`Could not read file: ${err.message}`));
+    return 1;
+  }
+  const report = buildReport(toMeasurements(measured));
+  ctx.log(renderReport(report, renderOptions));
+  if (options.watch) {
+    startWatch(targets, renderOptions, measured, ctx);
+    return 0;
+  }
+  if (limit !== void 0) {
+    return reportBudget(report.total.size.gzip, limit, renderOptions.colors, ctx);
+  }
+  return 0;
+}
+async function run(argv, deps = {}) {
+  const log = deps.log ?? ((message) => process.stdout.write(`${message}
+`));
+  const error = deps.error ?? ((message) => process.stderr.write(`${message}
+`));
+  const ctx = {
+    log,
+    error,
+    cwd: deps.cwd ?? process.cwd(),
+    env: deps.env ?? process.env,
+    watch: deps.watch ?? watchPaths
+  };
+  const program = new import_commander.Command();
+  program.name("bundle-cost").description(DESCRIPTION).argument("<files...>", "one or more files to measure (e.g. dist/index.js)").option("-w, --watch", "watch the files and print the size delta on every save").option("-b, --brotli", "include a brotli column alongside gzip").option("--no-gzip", "hide the gzip column (show raw bytes only)").option("-j, --json", "print machine-readable JSON instead of a table").option("-l, --limit <size>", "fail if the total gzip size exceeds this budget (e.g. 50kb)").option("--no-color", "disable ANSI colors").addHelpText("after", HELP_EXAMPLES).exitOverride().configureOutput({
+    writeOut: (text) => log(trimTrailingNewline(text)),
+    writeErr: (text) => error(trimTrailingNewline(text))
+  });
+  let exitCode = 0;
+  program.action(async (files, options) => {
+    exitCode = await execute(files, options, ctx);
+  });
+  try {
+    await program.parseAsync(argv, { from: "user" });
+  } catch (err) {
+    return err.exitCode;
+  }
+  return exitCode;
+}
+
+// src/bin.ts
+run(process.argv.slice(2)).then((code) => {
+  if (code !== 0) process.exitCode = code;
+});