bundle-cost-cli 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,110 @@
+/** A small set of ANSI color helpers. When disabled, every helper is the identity. */
+interface Colors {
+    green(text: string): string;
+    red(text: string): string;
+    dim(text: string): string;
+    cyan(text: string): string;
+    bold(text: string): string;
+}
+/**
+ * Build a {@link Colors} palette. Pass `false` (no TTY, `NO_COLOR`, `--no-color`)
+ * to get a palette where every helper returns its input untouched.
+ */
+declare function createColors(enabled: boolean): Colors;
+
+/**
+ * Render a non-negative byte count as a human-friendly string.
+ * Bytes are shown whole; everything larger gets two decimals.
+ */
+declare function formatBytes(bytes: number): string;
+/**
+ * Render a signed delta, e.g. `+1.20 KB`, `-512 B`, or `0 B` for no change.
+ */
+declare function formatDelta(bytes: number): string;
+/**
+ * Parse a human size budget like `50kb`, `1.5mb`, or a raw byte count.
+ * Throws on anything it can't make sense of.
+ */
+declare function parseSize(input: string): number;
+
+/** The three sizes we report for a file or a total. */
+interface SizeSet {
+    /** Uncompressed bytes on disk. */
+    raw: number;
+    /** Bytes after gzip — what most CDNs serve. */
+    gzip: number;
+    /** Bytes after brotli — what modern CDNs serve when the client supports it. */
+    brotli: number;
+}
+/** A single measured file, keyed by the path the user typed. */
+interface FileMeasurement {
+    path: string;
+    size: SizeSet;
+}
+/** One row of a report: a file, its sizes, and the delta vs. the last run (if any). */
+interface ReportRow {
+    path: string;
+    size: SizeSet;
+    /** `null` when there is no previous measurement to compare against. */
+    delta: SizeSet | null;
+}
+/** A full report: every file plus a summed total. */
+interface Report {
+    rows: ReportRow[];
+    total: {
+        size: SizeSet;
+        delta: SizeSet | null;
+    };
+}
+
+/** Measure raw, gzip, and brotli sizes of an in-memory buffer. */
+declare function measureBuffer(buffer: Buffer): SizeSet;
+/** Read a file from disk and measure it. Rejects if the file can't be read. */
+declare function measureFile(path: string): Promise<SizeSet>;
+
+/**
+ * Combine a set of measurements into a report. Pass the `previous` sizes (keyed
+ * by path) to compute per-file and total deltas; omit it for a first run.
+ */
+declare function buildReport(measurements: FileMeasurement[], previous?: Map<string, SizeSet>): Report;
+
+interface RenderOptions {
+    /** Show the gzip column (and base the delta on gzip). */
+    gzip: boolean;
+    /** Show an extra brotli column. */
+    brotli: boolean;
+    /** Emit JSON instead of a table. */
+    json: boolean;
+    /** The color palette to paint with. */
+    colors: Colors;
+}
+/** Render a report as either an aligned table or a JSON document. */
+declare function renderReport(report: Report, options: RenderOptions): string;
+
+/** A close handle returned by a watcher. */
+interface Closeable {
+    close(): void;
+}
+/** How a single path gets watched. Swappable so the orchestration is testable. */
+type WatchImpl = (path: string, onChange: () => void) => Closeable;
+/**
+ * Watch every path and call `onChange` whenever any of them changes.
+ * Returns a function that stops every watcher.
+ */
+declare function watchPaths(paths: string[], onChange: () => void, impl?: WatchImpl): () => void;
+
+/** Hooks the test suite swaps in; production code falls back to real I/O. */
+interface RunDeps {
+    log?: (message: string) => void;
+    error?: (message: string) => void;
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+    watch?: typeof watchPaths;
+}
+/**
+ * Parse `argv` (user args, without `node` and the script path) and run the CLI.
+ * Returns the process exit code. All I/O is injectable via {@link RunDeps}.
+ */
+declare function run(argv: string[], deps?: RunDeps): Promise<number>;
+
+export { type Closeable, type Colors, type FileMeasurement, type RenderOptions, type Report, type ReportRow, type RunDeps, type SizeSet, type WatchImpl, buildReport, createColors, formatBytes, formatDelta, measureBuffer, measureFile, parseSize, renderReport, run, watchPaths };

package/dist/index.d.ts

@@ -0,0 +1,110 @@
+/** A small set of ANSI color helpers. When disabled, every helper is the identity. */
+interface Colors {
+    green(text: string): string;
+    red(text: string): string;
+    dim(text: string): string;
+    cyan(text: string): string;
+    bold(text: string): string;
+}
+/**
+ * Build a {@link Colors} palette. Pass `false` (no TTY, `NO_COLOR`, `--no-color`)
+ * to get a palette where every helper returns its input untouched.
+ */
+declare function createColors(enabled: boolean): Colors;
+
+/**
+ * Render a non-negative byte count as a human-friendly string.
+ * Bytes are shown whole; everything larger gets two decimals.
+ */
+declare function formatBytes(bytes: number): string;
+/**
+ * Render a signed delta, e.g. `+1.20 KB`, `-512 B`, or `0 B` for no change.
+ */
+declare function formatDelta(bytes: number): string;
+/**
+ * Parse a human size budget like `50kb`, `1.5mb`, or a raw byte count.
+ * Throws on anything it can't make sense of.
+ */
+declare function parseSize(input: string): number;
+
+/** The three sizes we report for a file or a total. */
+interface SizeSet {
+    /** Uncompressed bytes on disk. */
+    raw: number;
+    /** Bytes after gzip — what most CDNs serve. */
+    gzip: number;
+    /** Bytes after brotli — what modern CDNs serve when the client supports it. */
+    brotli: number;
+}
+/** A single measured file, keyed by the path the user typed. */
+interface FileMeasurement {
+    path: string;
+    size: SizeSet;
+}
+/** One row of a report: a file, its sizes, and the delta vs. the last run (if any). */
+interface ReportRow {
+    path: string;
+    size: SizeSet;
+    /** `null` when there is no previous measurement to compare against. */
+    delta: SizeSet | null;
+}
+/** A full report: every file plus a summed total. */
+interface Report {
+    rows: ReportRow[];
+    total: {
+        size: SizeSet;
+        delta: SizeSet | null;
+    };
+}
+
+/** Measure raw, gzip, and brotli sizes of an in-memory buffer. */
+declare function measureBuffer(buffer: Buffer): SizeSet;
+/** Read a file from disk and measure it. Rejects if the file can't be read. */
+declare function measureFile(path: string): Promise<SizeSet>;
+
+/**
+ * Combine a set of measurements into a report. Pass the `previous` sizes (keyed
+ * by path) to compute per-file and total deltas; omit it for a first run.
+ */
+declare function buildReport(measurements: FileMeasurement[], previous?: Map<string, SizeSet>): Report;
+
+interface RenderOptions {
+    /** Show the gzip column (and base the delta on gzip). */
+    gzip: boolean;
+    /** Show an extra brotli column. */
+    brotli: boolean;
+    /** Emit JSON instead of a table. */
+    json: boolean;
+    /** The color palette to paint with. */
+    colors: Colors;
+}
+/** Render a report as either an aligned table or a JSON document. */
+declare function renderReport(report: Report, options: RenderOptions): string;
+
+/** A close handle returned by a watcher. */
+interface Closeable {
+    close(): void;
+}
+/** How a single path gets watched. Swappable so the orchestration is testable. */
+type WatchImpl = (path: string, onChange: () => void) => Closeable;
+/**
+ * Watch every path and call `onChange` whenever any of them changes.
+ * Returns a function that stops every watcher.
+ */
+declare function watchPaths(paths: string[], onChange: () => void, impl?: WatchImpl): () => void;
+
+/** Hooks the test suite swaps in; production code falls back to real I/O. */
+interface RunDeps {
+    log?: (message: string) => void;
+    error?: (message: string) => void;
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+    watch?: typeof watchPaths;
+}
+/**
+ * Parse `argv` (user args, without `node` and the script path) and run the CLI.
+ * Returns the process exit code. All I/O is injectable via {@link RunDeps}.
+ */
+declare function run(argv: string[], deps?: RunDeps): Promise<number>;
+
+export { type Closeable, type Colors, type FileMeasurement, type RenderOptions, type Report, type ReportRow, type RunDeps, type SizeSet, type WatchImpl, buildReport, createColors, formatBytes, formatDelta, measureBuffer, measureFile, parseSize, renderReport, run, watchPaths };

package/dist/index.js

@@ -0,0 +1,323 @@
+// 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/sizes.ts
+import { readFile } from "fs/promises";
+import { brotliCompressSync, gzipSync } from "zlib";
+function measureBuffer(buffer) {
+  return {
+    raw: buffer.byteLength,
+    gzip: gzipSync(buffer).byteLength,
+    brotli: brotliCompressSync(buffer).byteLength
+  };
+}
+async function measureFile(path) {
+  const buffer = await readFile(path);
+  return measureBuffer(buffer);
+}
+
+// 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/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/watch.ts
+import * as fs from "fs";
+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
+import { resolve } from "path";
+import { Command } from "commander";
+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: 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 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;
+}
+export {
+  buildReport,
+  createColors,
+  formatBytes,
+  formatDelta,
+  measureBuffer,
+  measureFile,
+  parseSize,
+  renderReport,
+  run,
+  watchPaths
+};

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "bundle-cost-cli",
+  "version": "0.1.0",
+  "description": "A tiny CLI that prints the gzipped bundle cost of your files — and the delta on every save.",
+  "keywords": [
+    "bundle-size",
+    "bundle-cost",
+    "gzip",
+    "brotli",
+    "cli",
+    "size-limit",
+    "performance",
+    "budget",
+    "watch",
+    "dx"
+  ],
+  "author": "kea0811",
+  "license": "MIT",
+  "homepage": "https://github.com/kea0811/bundle-cost-cli#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kea0811/bundle-cost-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/kea0811/bundle-cost-cli/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "bin": {
+    "bundle-cost": "./dist/bin.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "dev": "tsup --watch",
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.7.5",
+    "@vitest/coverage-v8": "^2.1.2",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.2",
+    "vitest": "^2.1.2"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "packageManager": "pnpm@10.28.1",
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
+  }
+}