bunx-ray 0.2.0

package/PUBLISHING.md

@@ -0,0 +1,87 @@
+# Publishing `bunx-ray` to npm
+
+> Quick reference for future releases. Assumes you already ran `npm login` (or `npm adduser`).
+
+---
+
+## 1. Build before publishing
+
+```bash
+npm run build      # compiles TypeScript to dist/
+```
+
+`package.json` already has:
+
+```json
+"prepublishOnly": "npm run build",
+"files": ["dist"]
+```
+
+So running `npm publish` will automatically rebuild and only ship the compiled JS.
+
+---
+
+## 2. Choose a package name & scope
+
+| Package name value        | Default visibility | Can be private? |
+| ------------------------- | ------------------ | --------------- |
+| `"name": "bunx-ray"`      | Public             | **No**          |
+| `"name": "@you/bunx-ray"` | Private            | Yes             |
+
+_Change the `name` field if needed._
+
+---
+
+## 3. Publish commands
+
+### A) Un-scoped, public (most common)
+
+```bash
+npm version patch   # bump 0.1.x → 0.1.(x+1)
+npm publish         # publishes publicly
+```
+
+### B) Scoped & public
+
+```bash
+npm version minor   # or patch / major
+npm publish --access public
+```
+
+### C) Scoped & private (default for scoped)
+
+```bash
+npm version patch
+npm publish --access restricted   # or simply: npm publish
+```
+
+---
+
+## 4. Extras
+
+- **Dry-run** – see what would be published:
+  ```bash
+  npm publish --dry-run
+  ```
+- **Dist-tags** – publish a prerelease:
+  ```bash
+  npm publish --tag next          # install with npm i bunx-ray@next
+  ```
+- **Private registry**:
+  ```bash
+  npm publish --registry https://registry.my-company.com/
+  ```
+
+---
+
+## 5. Verify
+
+```bash
+npm view bunx-ray version      # expect the new version
+npm i -g bunx-ray              # test global install
+bunx-ray --help                # ensure binary runs
+```
+
+---
+
+Happy shipping! 🚀

package/README.md

@@ -0,0 +1,115 @@
+# bunx-ray
+
+**ASCII heat-map bundle viewer** – inspect JavaScript bundle composition right in your terminal (CI-friendly, SSH-friendly, browser-free).
+
+---
+
+## Install & run
+
+```bash
+# global (recommended)
+npm install -g bunx-ray
+
+# or one-off
+npx bunx-ray <stats.json>
+```
+
+## CLI
+
+```
+bunx-ray [stats.json] [flags]
+
+Flags
+  --webpack          Treat input as Webpack stats (default auto-detect)
+  --vite             Treat input as Vite / Rollup stats
+  --esbuild          Treat input as esbuild metafile
+  --cols <n>         Terminal columns  (default 80)
+  --rows <n>         Terminal rows     (default 24)
+  --top  <n>         Show N largest modules (default 10)
+  --grid-only        Only print grid (no legend / summary)
+  --no-legend        Hide legend line
+  --no-summary       Hide bundle summary
+  -h, --help         Show help
+```
+
+### Quick demo (no bundler needed)
+
+```bash
+bunx-ray $(npx bunx-ray demo)             # renders a built-in sample
+```
+
+_(`bunx-ray demo` prints a temp stats file path; handy for first-time tryout.)_
+
+---
+
+## Real-world recipes
+
+### Webpack ≥ 4
+
+```bash
+npx webpack --stats-json            # writes stats.json
+bunx-ray stats.json                 # view heat-map
+```
+
+### Vite v5 / Rollup
+
+```bash
+vite build --stats.writeTo stats.json
+bunx-ray --vite stats.json
+```
+
+### esbuild
+
+```bash
+esbuild src/index.ts --bundle --metafile=meta.json --outfile=/dev/null
+bunx-ray --esbuild meta.json
+```
+
+---
+
+## TypeScript API
+
+Install as a normal dependency and import what you need:
+
+```ts
+import { normalizeWebpack, treemap, draw, Mod } from "bunx-ray";
+
+const mods: Mod[] = normalizeWebpack(
+  JSON.parse(readFileSync("stats.json", "utf8"))
+);
+console.log(draw(treemap(mods, 80, 24)));
+```
+
+All `.d.ts` files ship with the package—no extra `@types` install required.
+
+---
+
+## Why text over HTML?
+
+- Works in CI logs, SSH sessions, Codespaces, headless Docker containers.
+- Diff-friendly → fail PR when a module grows past your budget.
+- Zero browser animations = instant feedback.
+
+---
+
+## Contributing / local playground
+
+Clone the repo and:
+
+```bash
+npm install          # install dev deps
+npm run build        # compile TypeScript → dist/
+
+# sample bundles
+npm run sample:webpack   # outputs dist-webpack/stats.json
+npm run sample:vite      # outputs dist-vite/stats.json
+npm run sample:esbuild   # outputs dist-esbuild/meta.json
+```
+
+Run tests:
+
+```bash
+npm test
+```
+
+Feel free to tweak the `src-*` sample sources to watch the heat-map change.

package/dist/bundle.d.ts

@@ -0,0 +1,21 @@
+export type Mod = {
+    path: string;
+    size: number;
+};
+export interface Cell {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    mod: Mod;
+}
+export declare function treemap(mods: Mod[], W?: number, H?: number): Cell[];
+export declare function draw(cells: Cell[], W?: number, H?: number): string;
+export declare function normalizeWebpack(stats: any): Mod[];
+export declare function normalizeVite(stats: any): Mod[];
+export declare function normalizeEsbuild(meta: any): Mod[];
+export declare const SIZE_THRESHOLDS: number[];
+export declare function formatSize(bytes: number): string;
+export declare function totalSize(mods: Mod[]): number;
+export declare function topModules(mods: Mod[], n?: number): Mod[];
+//# sourceMappingURL=bundle.d.ts.map

package/dist/bundle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundle.d.ts","sourceRoot":"","sources":["../src/bundle.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,GAAG,GAAG;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,WAAW,IAAI;IACnB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,GAAG,EAAE,GAAG,CAAC;CACV;AAGD,wBAAgB,OAAO,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,CAAC,SAAK,EAAE,CAAC,SAAK,GAAG,IAAI,EAAE,CAiB3D;AAED,wBAAgB,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,SAAK,EAAE,CAAC,SAAK,GAAG,MAAM,CAe1D;AAGD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,GAAG,GAAG,GAAG,EAAE,CAalD;AAGD,wBAAgB,aAAa,CAAC,KAAK,EAAE,GAAG,GAAG,GAAG,EAAE,CAa/C;AAGD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,GAAG,GAAG,GAAG,EAAE,CAUjD;AAID,eAAO,MAAM,eAAe,UAAqC,CAAC;AAElE,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAIhD;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,GAAG,EAAE,GAAG,MAAM,CAE7C;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,CAAC,SAAK,GAAG,GAAG,EAAE,CAErD"}

package/dist/bundle.js

@@ -0,0 +1,94 @@
+// simple slice-and-dice treemap mapped to character grid
+export function treemap(mods, W = 80, H = 24) {
+    const cells = [];
+    let x = 0, y = 0, rowH = H;
+    const total = mods.reduce((a, m) => a + m.size, 0);
+    for (const m of mods) {
+        const frac = m.size / total;
+        const w = Math.max(1, Math.round((frac * W * H) / rowH));
+        if (x + w > W) {
+            y += rowH;
+            x = 0;
+        }
+        cells.push({ x, y, w, h: rowH, mod: m });
+        x += w;
+    }
+    return cells;
+}
+export function draw(cells, W = 80, H = 24) {
+    const grid = Array.from({ length: H }, () => Array(W).fill(' '));
+    const shades = ['░', '▒', '▓', '█'];
+    const max = Math.max(...cells.map((c) => c.mod.size));
+    for (const c of cells) {
+        const shade = shades[Math.floor((c.mod.size / max) * (shades.length - 1))];
+        for (let i = 0; i < c.h; i++) {
+            for (let j = 0; j < c.w; j++) {
+                if (c.y + i < H && c.x + j < W) {
+                    grid[c.y + i][c.x + j] = shade;
+                }
+            }
+        }
+    }
+    return grid.map((r) => r.join('')).join('\n');
+}
+// Normalize Webpack stats → Mod[]
+export function normalizeWebpack(stats) {
+    const mods = [];
+    if (Array.isArray(stats.modules)) {
+        for (const m of stats.modules) {
+            const size = m.size ?? m.parsedSize ?? 0;
+            const name = m.name ?? m.identifier ?? '';
+            if (size && name)
+                mods.push({ path: name, size });
+        }
+    }
+    else if (Array.isArray(stats.children)) {
+        for (const child of stats.children)
+            mods.push(...normalizeWebpack(child));
+    }
+    mods.sort((a, b) => b.size - a.size);
+    return mods;
+}
+// Vite / Rollup stats (array of outputs with modules)
+export function normalizeVite(stats) {
+    const mods = [];
+    const outputs = Array.isArray(stats.output) ? stats.output : [stats.output ?? stats];
+    for (const out of outputs) {
+        if (!out || !out.modules)
+            continue;
+        const modulesObj = out.modules;
+        for (const [p, m] of Object.entries(modulesObj)) {
+            const size = m.renderedLength ?? m.renderedSize ?? m.originalLength ?? m.size ?? 0;
+            mods.push({ path: p, size });
+        }
+    }
+    mods.sort((a, b) => b.size - a.size);
+    return mods;
+}
+// esbuild metafile JSON
+export function normalizeEsbuild(meta) {
+    const mods = [];
+    if (meta.inputs && typeof meta.inputs === 'object') {
+        for (const [p, info] of Object.entries(meta.inputs)) {
+            const size = info.bytes ?? 0;
+            mods.push({ path: p, size });
+        }
+    }
+    mods.sort((a, b) => b.size - a.size);
+    return mods;
+}
+// ---------------- Utilities ------------------
+export const SIZE_THRESHOLDS = [10 * 1024, 50 * 1024, 100 * 1024]; // bytes
+export function formatSize(bytes) {
+    if (bytes >= 1024 * 1024)
+        return (bytes / (1024 * 1024)).toFixed(1) + ' MB';
+    if (bytes >= 1024)
+        return (bytes / 1024).toFixed(1) + ' KB';
+    return bytes + ' B';
+}
+export function totalSize(mods) {
+    return mods.reduce((a, m) => a + m.size, 0);
+}
+export function topModules(mods, n = 10) {
+    return [...mods].sort((a, b) => b.size - a.size).slice(0, n);
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,85 @@
+// ---- CLI -----------------------------------------------------------------
+import { Command } from 'commander';
+import chalk from 'chalk';
+import fs from 'fs';
+import path from 'path';
+import { normalizeWebpack, normalizeVite, normalizeEsbuild } from './bundle.js';
+import { renderReport } from './report.js';
+function main() {
+    const program = new Command();
+    program
+        .name('bunx-ray')
+        .description('ASCII heat-map bundle viewer')
+        .argument('<stats>', 'Build stats JSON file')
+        .option('--webpack', 'Input is Webpack stats (default)')
+        .option('--vite', 'Input is Vite/Rollup stats')
+        .option('--esbuild', 'Input is esbuild metafile')
+        .option('--cols <number>', 'Terminal columns (default 80)', '80')
+        .option('--rows <number>', 'Terminal rows (default 24)', '24')
+        .option('--top <number>', 'Show N largest modules (default 10)', '10')
+        .option('--no-legend', 'Hide legend line')
+        .option('--no-summary', 'Hide summary line')
+        .option('--grid-only', 'Only print grid (implies --no-legend --no-summary)')
+        .option('--demo', 'Render built-in demo heat-map')
+        .parse(process.argv);
+    const opts = program.opts();
+    const file = program.args[0];
+    const cols = Number(opts.cols);
+    const rows = Number(opts.rows);
+    if (!Number.isFinite(cols) || !Number.isFinite(rows)) {
+        console.error(chalk.red('Error: --cols and --rows must be numbers'));
+        process.exit(1);
+    }
+    const raw = fs.readFileSync(path.resolve(process.cwd(), file), 'utf8');
+    let stats;
+    try {
+        stats = JSON.parse(raw);
+    }
+    catch (e) {
+        console.error(chalk.red(`Failed to parse JSON from ${file}`));
+        process.exit(1);
+    }
+    // Choose adapter based on flags or auto-detect.
+    let mods = [];
+    if (opts.webpack) {
+        mods = normalizeWebpack(stats);
+    }
+    else if (opts.vite) {
+        mods = normalizeVite(stats);
+    }
+    else if (opts.esbuild) {
+        mods = normalizeEsbuild(stats);
+    }
+    else {
+        // auto-detect simple heuristics
+        if (stats.inputs && stats.outputs)
+            mods = normalizeEsbuild(stats);
+        else if (stats.modules || stats.children)
+            mods = normalizeWebpack(stats);
+        else if (stats.output)
+            mods = normalizeVite(stats);
+        else {
+            console.error(chalk.red('Unable to detect stats format; please pass --webpack | --vite | --esbuild'));
+            process.exit(1);
+        }
+    }
+    if (mods.length === 0) {
+        console.error(chalk.yellow('No modules found in stats file.'));
+        process.exit(1);
+    }
+    const report = renderReport(mods, {
+        cols,
+        rows,
+        top: Number(opts.top ?? 10),
+        legend: opts.legend !== false && !opts.gridOnly,
+        summary: opts.summary !== false && !opts.gridOnly,
+        color: true,
+    });
+    if (report.legendLine)
+        console.log(report.legendLine);
+    if (report.summaryLine)
+        console.log(report.summaryLine);
+    console.log('\n' + report.grid + '\n');
+    report.tableLines.forEach((l) => console.log(l));
+}
+main();

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export type { Mod, Cell } from './bundle.js';
+export { normalizeWebpack, normalizeVite, normalizeEsbuild, treemap, draw, formatSize, totalSize, topModules, } from './bundle.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,gBAAgB,EAChB,OAAO,EACP,IAAI,EACJ,UAAU,EACV,SAAS,EACT,UAAU,GACX,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1 @@
+export { normalizeWebpack, normalizeVite, normalizeEsbuild, treemap, draw, formatSize, totalSize, topModules, } from './bundle.js';

package/dist/report.d.ts

@@ -0,0 +1,17 @@
+import { Mod } from './bundle.js';
+export interface ReportOptions {
+    cols: number;
+    rows: number;
+    top: number;
+    legend: boolean;
+    summary: boolean;
+    color: boolean;
+}
+export interface RenderedReport {
+    legendLine?: string;
+    summaryLine?: string;
+    grid: string;
+    tableLines: string[];
+}
+export declare function renderReport(mods: Mod[], opts: ReportOptions): RenderedReport;
+//# sourceMappingURL=report.d.ts.map

package/dist/report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../src/report.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAoD,MAAM,aAAa,CAAC;AAEpF,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;CAChB;AAaD,MAAM,WAAW,cAAc;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,IAAI,EAAE,aAAa,GAAG,cAAc,CAsC7E"}

package/dist/report.js

@@ -0,0 +1,43 @@
+import { treemap, draw, formatSize, totalSize, topModules } from './bundle.js';
+const SHADES = ['░', '▒', '▓', '█'];
+function calcThresholds(max) {
+    return [0.25, 0.5, 0.75].map((p) => max * p);
+}
+function shadeForSize(size, max) {
+    const idx = Math.floor((size / max) * (SHADES.length - 1));
+    return SHADES[idx];
+}
+export function renderReport(mods, opts) {
+    const { cols, rows, top, legend, summary } = opts;
+    const max = Math.max(...mods.map((m) => m.size));
+    const thresholds = calcThresholds(max);
+    // grid
+    const grid = draw(treemap(mods, cols, rows), cols, rows);
+    // legend
+    let legendLine;
+    if (legend) {
+        legendLine =
+            'Legend  ' +
+                [
+                    `${SHADES[3]} >${formatSize(thresholds[2])}`,
+                    `${SHADES[2]} ${formatSize(thresholds[1])}-${formatSize(thresholds[2])}`,
+                    `${SHADES[1]} ${formatSize(thresholds[0])}-${formatSize(thresholds[1])}`,
+                    `${SHADES[0]} <${formatSize(thresholds[0])}`,
+                ].join('  ');
+    }
+    // summary
+    let summaryLine;
+    if (summary) {
+        summaryLine = `Total bundle: ${formatSize(totalSize(mods))} | modules: ${mods.length}`;
+    }
+    // table
+    const list = topModules(mods, top);
+    const tableLines = [`Top ${list.length} modules`];
+    list.forEach((m, idx) => {
+        const shade = shadeForSize(m.size, max);
+        const pct = ((m.size / totalSize(mods)) * 100).toFixed(1).padStart(4);
+        const name = m.path.length > 28 ? '…' + m.path.slice(-27) : m.path.padEnd(28);
+        tableLines.push(`${(idx + 1).toString().padStart(2)} ${shade} ${name} ${formatSize(m.size).padStart(8)} (${pct}%)`);
+    });
+    return { legendLine, summaryLine, grid, tableLines };
+}

package/meta.json

@@ -0,0 +1,36 @@
+{
+  "inputs": {
+    "src-esbuild/math.ts": {
+      "bytes": 60,
+      "imports": [],
+      "format": "esm"
+    },
+    "src-esbuild/index.ts": {
+      "bytes": 71,
+      "imports": [
+        {
+          "path": "src-esbuild/math.ts",
+          "kind": "import-statement",
+          "original": "./math"
+        }
+      ],
+      "format": "esm"
+    }
+  },
+  "outputs": {
+    "../../../../../dev/null": {
+      "imports": [],
+      "exports": [],
+      "entryPoint": "src-esbuild/index.ts",
+      "inputs": {
+        "src-esbuild/math.ts": {
+          "bytesInOutput": 29
+        },
+        "src-esbuild/index.ts": {
+          "bytesInOutput": 43
+        }
+      },
+      "bytes": 153
+    }
+  }
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "bunx-ray",
+  "version": "0.2.0",
+  "description": "ASCII heat-map bundle viewer",
+  "type": "module",
+  "bin": {
+    "bunx-ray": "dist/cli.js"
+  },
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "prepublishOnly": "npm run build",
+    "build": "tsc",
+    "start": "node dist/cli.js",
+    "test": "npm run build && vitest run",
+    "sample:webpack": "webpack --config webpack.sample.js --mode production --json > dist-webpack/stats.json",
+    "sample:vite": "vite build --config vite.sample.js",
+    "sample:esbuild": "esbuild src-esbuild/index.ts --bundle --outfile=dist-esbuild/bundle.js --metafile=dist-esbuild/meta.json"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0",
+    "@types/node": "^20.8.10",
+    "vitest": "^3.0.0",
+    "execa": "^8.0.0",
+    "webpack": "^5.91.0",
+    "webpack-cli": "^5.1.4",
+    "vite": "^5.0.0",
+    "rollup-plugin-analyzer": "^4.0.0",
+    "esbuild": "^0.21.0"
+  }
+}

package/src/bundle.ts

@@ -0,0 +1,115 @@
+// Core functions for bunx-ray MVP
+import chalk from 'chalk';
+
+export type Mod = {
+  path: string;
+  size: number; // bytes
+};
+
+export interface Cell {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+  mod: Mod;
+}
+
+// simple slice-and-dice treemap mapped to character grid
+export function treemap(mods: Mod[], W = 80, H = 24): Cell[] {
+  const cells: Cell[] = [];
+  let x = 0,
+    y = 0,
+    rowH = H;
+  const total = mods.reduce((a, m) => a + m.size, 0);
+  for (const m of mods) {
+    const frac = m.size / total;
+    const w = Math.max(1, Math.round((frac * W * H) / rowH));
+    if (x + w > W) {
+      y += rowH;
+      x = 0;
+    }
+    cells.push({ x, y, w, h: rowH, mod: m });
+    x += w;
+  }
+  return cells;
+}
+
+export function draw(cells: Cell[], W = 80, H = 24): string {
+  const grid: string[][] = Array.from({ length: H }, () => Array(W).fill(' '));
+  const shades = ['░', '▒', '▓', '█'];
+  const max = Math.max(...cells.map((c) => c.mod.size));
+  for (const c of cells) {
+    const shade = shades[Math.floor((c.mod.size / max) * (shades.length - 1))];
+    for (let i = 0; i < c.h; i++) {
+      for (let j = 0; j < c.w; j++) {
+        if (c.y + i < H && c.x + j < W) {
+          grid[c.y + i][c.x + j] = shade;
+        }
+      }
+    }
+  }
+  return grid.map((r) => r.join('')).join('\n');
+}
+
+// Normalize Webpack stats → Mod[]
+export function normalizeWebpack(stats: any): Mod[] {
+  const mods: Mod[] = [];
+  if (Array.isArray(stats.modules)) {
+    for (const m of stats.modules) {
+      const size = m.size ?? m.parsedSize ?? 0;
+      const name = m.name ?? m.identifier ?? '';
+      if (size && name) mods.push({ path: name, size });
+    }
+  } else if (Array.isArray(stats.children)) {
+    for (const child of stats.children) mods.push(...normalizeWebpack(child));
+  }
+  mods.sort((a, b) => b.size - a.size);
+  return mods;
+}
+
+// Vite / Rollup stats (array of outputs with modules)
+export function normalizeVite(stats: any): Mod[] {
+  const mods: Mod[] = [];
+  const outputs = Array.isArray(stats.output) ? stats.output : [stats.output ?? stats];
+  for (const out of outputs) {
+    if (!out || !out.modules) continue;
+    const modulesObj = out.modules;
+    for (const [p, m] of Object.entries<any>(modulesObj)) {
+      const size = (m as any).renderedLength ?? (m as any).renderedSize ?? (m as any).originalLength ?? (m as any).size ?? 0;
+      mods.push({ path: p, size });
+    }
+  }
+  mods.sort((a, b) => b.size - a.size);
+  return mods;
+}
+
+// esbuild metafile JSON
+export function normalizeEsbuild(meta: any): Mod[] {
+  const mods: Mod[] = [];
+  if (meta.inputs && typeof meta.inputs === 'object') {
+    for (const [p, info] of Object.entries<any>(meta.inputs)) {
+      const size = info.bytes ?? 0;
+      mods.push({ path: p, size });
+    }
+  }
+  mods.sort((a, b) => b.size - a.size);
+  return mods;
+}
+
+// ---------------- Utilities ------------------
+
+export const SIZE_THRESHOLDS = [10 * 1024, 50 * 1024, 100 * 1024]; // bytes
+
+export function formatSize(bytes: number): string {
+  if (bytes >= 1024 * 1024) return (bytes / (1024 * 1024)).toFixed(1) + ' MB';
+  if (bytes >= 1024) return (bytes / 1024).toFixed(1) + ' KB';
+  return bytes + ' B';
+}
+
+export function totalSize(mods: Mod[]): number {
+  return mods.reduce((a, m) => a + m.size, 0);
+}
+
+export function topModules(mods: Mod[], n = 10): Mod[] {
+  return [...mods].sort((a, b) => b.size - a.size).slice(0, n);
+} 

package/src/cli.ts

@@ -0,0 +1,97 @@
+// ---- CLI -----------------------------------------------------------------
+import { Command } from 'commander';
+import chalk from 'chalk';
+import fs from 'fs';
+import path from 'path';
+
+import {
+  Mod,
+  normalizeWebpack,
+  normalizeVite,
+  normalizeEsbuild,
+  treemap,
+  draw
+} from './bundle.js';
+
+import { renderReport } from './report.js';
+
+function main() {
+  const program = new Command();
+
+  program
+    .name('bunx-ray')
+    .description('ASCII heat-map bundle viewer')
+    .argument('<stats>', 'Build stats JSON file')
+    .option('--webpack', 'Input is Webpack stats (default)')
+    .option('--vite', 'Input is Vite/Rollup stats')
+    .option('--esbuild', 'Input is esbuild metafile')
+    .option('--cols <number>', 'Terminal columns (default 80)', '80')
+    .option('--rows <number>', 'Terminal rows (default 24)', '24')
+    .option('--top <number>', 'Show N largest modules (default 10)', '10')
+    .option('--no-legend', 'Hide legend line')
+    .option('--no-summary', 'Hide summary line')
+    .option('--grid-only', 'Only print grid (implies --no-legend --no-summary)')
+    .option('--demo', 'Render built-in demo heat-map')
+    .parse(process.argv);
+
+  const opts = program.opts();
+  const file = program.args[0];
+
+  const cols = Number(opts.cols);
+  const rows = Number(opts.rows);
+  if (!Number.isFinite(cols) || !Number.isFinite(rows)) {
+    console.error(chalk.red('Error: --cols and --rows must be numbers'));
+    process.exit(1);
+  }
+
+  const raw = fs.readFileSync(path.resolve(process.cwd(), file), 'utf8');
+  let stats: any;
+  try {
+    stats = JSON.parse(raw);
+  } catch (e) {
+    console.error(chalk.red(`Failed to parse JSON from ${file}`));
+    process.exit(1);
+  }
+
+  // Choose adapter based on flags or auto-detect.
+  let mods: Mod[] = [];
+  if (opts.webpack) {
+    mods = normalizeWebpack(stats);
+  } else if (opts.vite) {
+    mods = normalizeVite(stats);
+  } else if (opts.esbuild) {
+    mods = normalizeEsbuild(stats);
+  } else {
+    // auto-detect simple heuristics
+    if (stats.inputs && stats.outputs) mods = normalizeEsbuild(stats);
+    else if (stats.modules || stats.children) mods = normalizeWebpack(stats);
+    else if (stats.output) mods = normalizeVite(stats);
+    else {
+      console.error(chalk.red('Unable to detect stats format; please pass --webpack | --vite | --esbuild'));
+      process.exit(1);
+    }
+  }
+
+  if (mods.length === 0) {
+    console.error(chalk.yellow('No modules found in stats file.'));
+    process.exit(1);
+  }
+
+  const report = renderReport(mods, {
+    cols,
+    rows,
+    top: Number(opts.top ?? 10),
+    legend: opts.legend !== false && !opts.gridOnly,
+    summary: opts.summary !== false && !opts.gridOnly,
+    color: true,
+  });
+
+  if (report.legendLine) console.log(report.legendLine);
+  if (report.summaryLine) console.log(report.summaryLine);
+
+  console.log('\n' + report.grid + '\n');
+
+  report.tableLines.forEach((l) => console.log(l));
+}
+
+main(); 

package/src/index.ts

@@ -0,0 +1,11 @@
+export type { Mod, Cell } from './bundle.js';
+export {
+  normalizeWebpack,
+  normalizeVite,
+  normalizeEsbuild,
+  treemap,
+  draw,
+  formatSize,
+  totalSize,
+  topModules,
+} from './bundle.js'; 

package/src/report.ts

@@ -0,0 +1,68 @@
+import { Mod, treemap, draw, formatSize, totalSize, topModules } from './bundle.js';
+
+export interface ReportOptions {
+  cols: number;
+  rows: number;
+  top: number;
+  legend: boolean;
+  summary: boolean;
+  color: boolean; // reserved – color disabled for now
+}
+
+const SHADES = ['░', '▒', '▓', '█'] as const;
+
+function calcThresholds(max: number): number[] {
+  return [0.25, 0.5, 0.75].map((p) => max * p);
+}
+
+function shadeForSize(size: number, max: number): string {
+  const idx = Math.floor((size / max) * (SHADES.length - 1));
+  return SHADES[idx];
+}
+
+export interface RenderedReport {
+  legendLine?: string;
+  summaryLine?: string;
+  grid: string;
+  tableLines: string[];
+}
+
+export function renderReport(mods: Mod[], opts: ReportOptions): RenderedReport {
+  const { cols, rows, top, legend, summary } = opts;
+  const max = Math.max(...mods.map((m) => m.size));
+  const thresholds = calcThresholds(max);
+
+  // grid
+  const grid = draw(treemap(mods, cols, rows), cols, rows);
+
+  // legend
+  let legendLine: string | undefined;
+  if (legend) {
+    legendLine =
+      'Legend  ' +
+      [
+        `${SHADES[3]} >${formatSize(thresholds[2])}`,
+        `${SHADES[2]} ${formatSize(thresholds[1])}-${formatSize(thresholds[2])}`,
+        `${SHADES[1]} ${formatSize(thresholds[0])}-${formatSize(thresholds[1])}`,
+        `${SHADES[0]} <${formatSize(thresholds[0])}`,
+      ].join('  ');
+  }
+
+  // summary
+  let summaryLine: string | undefined;
+  if (summary) {
+    summaryLine = `Total bundle: ${formatSize(totalSize(mods))} | modules: ${mods.length}`;
+  }
+
+  // table
+  const list = topModules(mods, top);
+  const tableLines: string[] = [`Top ${list.length} modules`];
+  list.forEach((m, idx) => {
+    const shade = shadeForSize(m.size, max);
+    const pct = ((m.size / totalSize(mods)) * 100).toFixed(1).padStart(4);
+    const name = m.path.length > 28 ? '…' + m.path.slice(-27) : m.path.padEnd(28);
+    tableLines.push(`${(idx + 1).toString().padStart(2)} ${shade} ${name} ${formatSize(m.size).padStart(8)} (${pct}%)`);
+  });
+
+  return { legendLine, summaryLine, grid, tableLines };
+} 

package/src-esbuild/index.ts

@@ -0,0 +1,2 @@
+import { add } from './math';
+console.log('Add esbuild', add(10, 15)); 

package/src-esbuild/math.ts

@@ -0,0 +1 @@
+export const add = (a: number, b: number): number => a + b; 

package/src-vite/index.ts

@@ -0,0 +1,2 @@
+import { add } from './math.ts';
+console.log('Add', add(5, 7)); 

package/src-vite/math.ts

@@ -0,0 +1 @@
+export const add = (a: number, b: number): number => a + b; 

package/src-webpack/index.js

@@ -0,0 +1,5 @@
+import _ from 'lodash';
+import { add } from './math.js';
+
+console.log('Sum', add(2, 3));
+console.log(_.chunk([1,2,3,4],2)); 

package/src-webpack/math.js

@@ -0,0 +1 @@
+export const add = (a, b) => a + b; 

package/test/__snapshots__/bundle.test.ts.snap

@@ -0,0 +1,34 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`normalize + draw > esbuild fixture renders 1`] = `
+"███████████████████▓▓▓▓▓▓▓▓▓▓▓▓▓▒▒▒▒▒▒▒▒
+███████████████████▓▓▓▓▓▓▓▓▓▓▓▓▓▒▒▒▒▒▒▒▒
+███████████████████▓▓▓▓▓▓▓▓▓▓▓▓▓▒▒▒▒▒▒▒▒
+███████████████████▓▓▓▓▓▓▓▓▓▓▓▓▓▒▒▒▒▒▒▒▒
+███████████████████▓▓▓▓▓▓▓▓▓▓▓▓▓▒▒▒▒▒▒▒▒
+███████████████████▓▓▓▓▓▓▓▓▓▓▓▓▓▒▒▒▒▒▒▒▒
+███████████████████▓▓▓▓▓▓▓▓▓▓▓▓▓▒▒▒▒▒▒▒▒
+███████████████████▓▓▓▓▓▓▓▓▓▓▓▓▓▒▒▒▒▒▒▒▒"
+`;
+
+exports[`normalize + draw > vite fixture renders 1`] = `
+"███████████████████▓▓▓▓▓▓▓▓▓▓▓▓▓▒▒▒▒▒▒▒▒
+███████████████████▓▓▓▓▓▓▓▓▓▓▓▓▓▒▒▒▒▒▒▒▒
+███████████████████▓▓▓▓▓▓▓▓▓▓▓▓▓▒▒▒▒▒▒▒▒
+███████████████████▓▓▓▓▓▓▓▓▓▓▓▓▓▒▒▒▒▒▒▒▒
+███████████████████▓▓▓▓▓▓▓▓▓▓▓▓▓▒▒▒▒▒▒▒▒
+███████████████████▓▓▓▓▓▓▓▓▓▓▓▓▓▒▒▒▒▒▒▒▒
+███████████████████▓▓▓▓▓▓▓▓▓▓▓▓▓▒▒▒▒▒▒▒▒
+███████████████████▓▓▓▓▓▓▓▓▓▓▓▓▓▒▒▒▒▒▒▒▒"
+`;
+
+exports[`normalize + draw > webpack fixture renders 1`] = `
+"█████████████▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒░░░
+█████████████▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒░░░
+█████████████▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒░░░
+█████████████▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒░░░
+█████████████▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒░░░
+█████████████▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒░░░
+█████████████▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒░░░
+█████████████▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒░░░"
+`;

package/test/bundle.test.ts

@@ -0,0 +1,31 @@
+/// <reference types="vitest" />
+
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'fs';
+import { normalizeWebpack, normalizeVite, normalizeEsbuild, treemap, draw } from '../src/bundle';
+
+const fixturesDir = new URL('../fixtures/', import.meta.url).pathname;
+
+function load(name: string) {
+  return JSON.parse(readFileSync(`${fixturesDir}${name}`, 'utf8'));
+}
+
+describe('normalize + draw', () => {
+  it('webpack fixture renders', () => {
+    const mods = normalizeWebpack(load('webpack-sample.json'));
+    const ascii = draw(treemap(mods, 40, 8), 40, 8);
+    expect(ascii).toMatchSnapshot();
+  });
+
+  it('vite fixture renders', () => {
+    const mods = normalizeVite(load('vite-sample.json'));
+    const ascii = draw(treemap(mods, 40, 8), 40, 8);
+    expect(ascii).toMatchSnapshot();
+  });
+
+  it('esbuild fixture renders', () => {
+    const mods = normalizeEsbuild(load('esbuild-sample.json'));
+    const ascii = draw(treemap(mods, 40, 8), 40, 8);
+    expect(ascii).toMatchSnapshot();
+  });
+}); 

package/test/cli.test.ts

@@ -0,0 +1,28 @@
+import { describe, it, expect } from 'vitest';
+import { execa } from 'execa';
+import path from 'path';
+
+const cli = path.resolve('dist/cli.js');
+const fixture = path.resolve('fixtures/webpack-sample.json');
+
+describe('CLI smoke tests', () => {
+  it('prints legend and summary by default', async () => {
+    const { stdout } = await execa('node', [cli, fixture, '--cols', '20', '--rows', '6']);
+    expect(stdout).toMatch(/Legend/);
+    expect(stdout).toMatch(/Total bundle/);
+  });
+
+  it('grid-only hides legend and summary', async () => {
+    const { stdout } = await execa('node', [cli, fixture, '--grid-only', '--cols', '20', '--rows', '6']);
+    expect(stdout).not.toMatch(/Legend/);
+    expect(stdout).not.toMatch(/Total bundle/);
+  });
+
+  it('respects top flag', async () => {
+    const { stdout } = await execa('node', [cli, fixture, '--top', '2', '--cols', '20', '--rows', '6']);
+    const lines = stdout.split('\n').filter((l) => l.startsWith(' '));
+    // last section lines start with space digit for table
+    const tableLines = lines.filter((l) => /\d+ [░▒▓█]/.test(l));
+    expect(tableLines.length).toBe(2);
+  });
+}); 

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "dist",
+    "rootDir": "src",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "types": ["node", "vitest"],
+    "declaration": true,
+    "declarationMap": true
+  },
+  "include": ["src"]
+} 

package/vite.sample.js

@@ -0,0 +1,15 @@
+import { resolve } from 'path';
+import analyze from 'rollup-plugin-analyzer';
+
+export default {
+  build: {
+    outDir: 'dist-vite',
+    emptyOutDir: true,
+    rollupOptions: {
+      input: resolve('./src-vite/index.ts'),
+      plugins: [
+        analyze({ summaryOnly: true, json: true, filename: 'dist-vite/stats.json' })
+      ]
+    }
+  }
+}; 

package/webpack.sample.js

@@ -0,0 +1,13 @@
+import path from 'path';
+
+export default {
+  mode: 'production',
+  entry: './src-webpack/index.js',
+  output: {
+    filename: 'bundle.js',
+    path: path.resolve('./dist-webpack'),
+  },
+  stats: {
+    preset: 'normal',
+  },
+};