@ozsarman/clarityjs 0.6.0

package/src/analyze.js

@@ -0,0 +1,534 @@
+/**
+ * Clarity.js — Bundle Analyzer
+ *
+ * Reads a Vite/Rollup build output directory and the emitted stats
+ * (stats.json or the route manifest) to generate:
+ *   - An interactive HTML sunburst/treemap chart
+ *   - A JSON report
+ *   - A terminal summary
+ *
+ * Usage (programmatic):
+ *   import { analyzeBundle } from '@ozsarman/clarityjs/analyze';
+ *   const report = await analyzeBundle({ distDir: 'dist', open: true });
+ *
+ * Usage (CLI — called from cli.js):
+ *   clarity analyze [dist-dir] [--json] [--open] [--out path]
+ *
+ * Author: Claude (Anthropic) + Özdemir Sarman
+ */
+
+import { readFileSync, existsSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { resolve, relative, extname, basename, join } from 'node:path';
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Analyse a Vite/Rollup dist directory.
+ *
+ * @param {object} opts
+ * @param {string}  opts.distDir  - Path to the dist folder (default: 'dist')
+ * @param {string}  [opts.outDir] - Where to write the HTML report (default: distDir)
+ * @param {string}  [opts.outFile]- Report filename (default: 'clarity-analyze.html')
+ * @param {boolean} [opts.open]   - Open in browser after generation (default: false)
+ * @param {boolean} [opts.json]   - Also write a .json report
+ * @param {boolean} [opts.verbose]
+ * @returns {Promise<BundleReport>}
+ */
+export async function analyzeBundle({
+  distDir  = 'dist',
+  outDir,
+  outFile  = 'clarity-analyze.html',
+  open     = false,
+  json     = false,
+  verbose  = false,
+} = {}) {
+  const distAbs = resolve(distDir);
+
+  if (!existsSync(distAbs)) {
+    throw new Error(`[clarity analyze] dist directory not found: ${distAbs}\nRun "clarity build" first.`);
+  }
+
+  // ── Scan all .js files in dist ──────────────────────────────────────────────
+  const files = _scanFiles(distAbs);
+
+  if (files.length === 0) {
+    throw new Error(`[clarity analyze] No .js files found in ${distAbs}`);
+  }
+
+  // ── Build tree ──────────────────────────────────────────────────────────────
+  const tree = _buildTree(files, distAbs);
+  const report = _buildReport(tree, files, distAbs);
+
+  if (verbose) {
+    _printSummary(report);
+  }
+
+  // ── Write JSON ──────────────────────────────────────────────────────────────
+  const outBase = resolve(outDir ?? distAbs);
+
+  if (json) {
+    const jsonPath = join(outBase, outFile.replace(/\.html?$/, '.json'));
+    writeFileSync(jsonPath, JSON.stringify(report, null, 2), 'utf8');
+    if (verbose) console.log(`[clarity analyze] JSON → ${jsonPath}`);
+  }
+
+  // ── Write HTML chart ────────────────────────────────────────────────────────
+  const html = _renderHTML(report);
+  const htmlPath = join(outBase, outFile);
+  writeFileSync(htmlPath, html, 'utf8');
+
+  if (verbose) console.log(`[clarity analyze] Report → ${htmlPath}`);
+
+  // ── Open in browser ─────────────────────────────────────────────────────────
+  if (open) {
+    await _openBrowser(htmlPath);
+  }
+
+  return report;
+}
+
+// ─── File scanning ────────────────────────────────────────────────────────────
+
+function _scanFiles(dir) {
+  const results = [];
+  const IGNORE = new Set(['node_modules', '.git']);
+
+  function walk(d) {
+    for (const name of readdirSync(d)) {
+      if (IGNORE.has(name)) continue;
+      const full = join(d, name);
+      const st = statSync(full);
+      if (st.isDirectory()) {
+        walk(full);
+      } else if (st.isFile()) {
+        const ext = extname(name).toLowerCase();
+        if (ext === '.js' || ext === '.mjs' || ext === '.css') {
+          results.push({ path: full, size: st.size, ext });
+        }
+      }
+    }
+  }
+
+  walk(dir);
+  return results;
+}
+
+// ─── Tree builder ─────────────────────────────────────────────────────────────
+
+function _buildTree(files, root) {
+  const tree = { name: basename(root), children: [], size: 0 };
+
+  for (const file of files) {
+    const rel = relative(root, file.path);
+    const parts = rel.split(/[\\/]/);
+    let node = tree;
+
+    for (let i = 0; i < parts.length - 1; i++) {
+      let child = node.children.find(c => c.name === parts[i] && c.children);
+      if (!child) {
+        child = { name: parts[i], children: [], size: 0 };
+        node.children.push(child);
+      }
+      node = child;
+    }
+
+    const leaf = {
+      name:    parts[parts.length - 1],
+      size:    file.size,
+      ext:     file.ext,
+      path:    rel,
+      children: null,
+    };
+    node.children.push(leaf);
+  }
+
+  // Roll up sizes
+  function rollup(n) {
+    if (n.children === null) return n.size;
+    n.size = n.children.reduce((sum, c) => sum + rollup(c), 0);
+    return n.size;
+  }
+  rollup(tree);
+
+  return tree;
+}
+
+// ─── Report builder ───────────────────────────────────────────────────────────
+
+/**
+ * @typedef {{ total: number, files: FileEntry[], tree: object, chunks: ChunkGroup[] }} BundleReport
+ */
+function _buildReport(tree, files, root) {
+  const jsFiles  = files.filter(f => f.ext === '.js' || f.ext === '.mjs');
+  const cssFiles = files.filter(f => f.ext === '.css');
+
+  const totalJS  = jsFiles.reduce((s, f) => s + f.size, 0);
+  const totalCSS = cssFiles.reduce((s, f) => s + f.size, 0);
+  const total    = files.reduce((s, f) => s + f.size, 0);
+
+  // Identify chunk types by naming convention
+  function chunkType(name) {
+    if (name.startsWith('route-'))    return 'route';
+    if (name.includes('vendor'))      return 'vendor';
+    if (name.includes('clarity'))     return 'framework';
+    if (name.includes('index'))       return 'entry';
+    return 'chunk';
+  }
+
+  const chunks = jsFiles
+    .map(f => ({
+      name: basename(f.path, extname(f.path)),
+      path: relative(root, f.path),
+      size: f.size,
+      type: chunkType(basename(f.path)),
+    }))
+    .sort((a, b) => b.size - a.size);
+
+  return {
+    generatedAt: new Date().toISOString(),
+    distDir:     root,
+    total,
+    totalJS,
+    totalCSS,
+    fileCount:   files.length,
+    chunks,
+    tree,
+  };
+}
+
+// ─── Terminal summary ─────────────────────────────────────────────────────────
+
+function _printSummary(report) {
+  const fmt = n => `${(n / 1024).toFixed(1)} KB`;
+  console.log(`\n  Bundle Analysis`);
+  console.log(`  ──────────────────────────────────`);
+  console.log(`  Total:  ${fmt(report.total)}   (JS: ${fmt(report.totalJS)}, CSS: ${fmt(report.totalCSS)})`);
+  console.log(`  Files:  ${report.fileCount}`);
+  console.log(`\n  Largest chunks:`);
+  for (const c of report.chunks.slice(0, 8)) {
+    const bar = '█'.repeat(Math.max(1, Math.round((c.size / (report.chunks[0]?.size || 1)) * 20)));
+    console.log(`  ${bar.padEnd(20)}  ${fmt(c.size).padStart(9)}  ${c.name}`);
+  }
+  console.log();
+}
+
+// ─── HTML report renderer ─────────────────────────────────────────────────────
+
+function _renderHTML(report) {
+  const dataJson = JSON.stringify(report);
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>Clarity Bundle Analyzer</title>
+<style>
+  *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+  :root {
+    --bg: #1e1e2e; --surface: #181825; --border: #313244;
+    --text: #cdd6f4; --muted: #6c7086; --accent: #7c3aed;
+    --blue: #89b4fa; --green: #a6e3a1; --yellow: #f9e2af;
+    --red: #f38ba8; --pink: #cba6f7; --teal: #94e2d5;
+    --orange: #fab387;
+  }
+  body { background: var(--bg); color: var(--text); font-family: system-ui, sans-serif; font-size: 14px; min-height: 100vh; }
+
+  .header { background: var(--surface); border-bottom: 1px solid var(--border); padding: 16px 24px; display: flex; align-items: center; gap: 16px; }
+  .header h1 { font-size: 18px; color: var(--green); font-weight: 700; }
+  .header .meta { color: var(--muted); font-size: 12px; }
+  .header .total { margin-left: auto; font-weight: 700; color: var(--blue); }
+
+  .stats { display: flex; gap: 12px; padding: 16px 24px; flex-wrap: wrap; }
+  .stat { background: var(--surface); border: 1px solid var(--border); border-radius: 8px; padding: 12px 16px; min-width: 140px; }
+  .stat-label { color: var(--muted); font-size: 11px; text-transform: uppercase; letter-spacing: .05em; }
+  .stat-value { font-size: 20px; font-weight: 700; color: var(--blue); margin-top: 4px; }
+
+  .main { display: grid; grid-template-columns: 1fr 360px; gap: 0; height: calc(100vh - 160px); }
+
+  /* Sunburst/Treemap */
+  .chart-panel { padding: 16px 24px; overflow: hidden; display: flex; flex-direction: column; gap: 12px; }
+  .chart-title { font-size: 13px; color: var(--muted); text-transform: uppercase; letter-spacing: .05em; }
+  #chart-svg { flex: 1; width: 100%; }
+  .tooltip {
+    position: fixed; background: var(--surface); border: 1px solid var(--border);
+    border-radius: 8px; padding: 10px 14px; font-size: 12px; pointer-events: none;
+    box-shadow: 0 4px 20px rgba(0,0,0,.4); z-index: 9999; max-width: 280px;
+  }
+  .tooltip .tt-name { font-weight: 700; color: var(--text); margin-bottom: 4px; word-break: break-all; }
+  .tooltip .tt-size { color: var(--blue); }
+  .tooltip .tt-pct  { color: var(--muted); }
+
+  /* Chunks list */
+  .list-panel { background: var(--surface); border-left: 1px solid var(--border); overflow-y: auto; padding: 12px 16px; }
+  .list-panel h2 { font-size: 12px; color: var(--muted); text-transform: uppercase; margin-bottom: 12px; letter-spacing: .05em; }
+  .chunk-item { display: flex; align-items: center; gap: 8px; padding: 7px 0; border-bottom: 1px solid var(--border); }
+  .chunk-item:last-child { border-bottom: none; }
+  .chunk-dot { width: 8px; height: 8px; border-radius: 50%; flex-shrink: 0; }
+  .chunk-name { flex: 1; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-size: 12px; }
+  .chunk-type { font-size: 10px; color: var(--muted); padding: 1px 6px; border-radius: 10px; background: var(--border); flex-shrink: 0; }
+  .chunk-size { font-size: 11px; color: var(--blue); font-weight: 600; flex-shrink: 0; }
+  .chunk-bar { display: block; height: 3px; background: var(--accent); border-radius: 2px; margin-top: 3px; }
+
+  .filter-row { display: flex; gap: 8px; margin-bottom: 12px; flex-wrap: wrap; }
+  .filter-btn {
+    padding: 3px 10px; border-radius: 10px; border: 1px solid var(--border);
+    background: none; color: var(--muted); font-size: 11px; cursor: pointer;
+  }
+  .filter-btn.active { background: var(--accent); color: #fff; border-color: var(--accent); }
+</style>
+</head>
+<body>
+<div class="header">
+  <h1>⚡ Clarity Bundle Analyzer</h1>
+  <div class="meta">Generated ${new Date(report.generatedAt).toLocaleString()}</div>
+  <div class="total">Total: ${_fmtKB(report.total)}</div>
+</div>
+
+<div class="stats">
+  <div class="stat"><div class="stat-label">JavaScript</div><div class="stat-value">${_fmtKB(report.totalJS)}</div></div>
+  <div class="stat"><div class="stat-label">CSS</div><div class="stat-value">${_fmtKB(report.totalCSS)}</div></div>
+  <div class="stat"><div class="stat-label">Files</div><div class="stat-value">${report.fileCount}</div></div>
+  <div class="stat"><div class="stat-label">Chunks</div><div class="stat-value">${report.chunks.length}</div></div>
+</div>
+
+<div class="main">
+  <div class="chart-panel">
+    <div class="chart-title">Treemap — click to drill down</div>
+    <svg id="chart-svg"></svg>
+  </div>
+
+  <div class="list-panel">
+    <h2>Chunks</h2>
+    <div class="filter-row" id="filters"></div>
+    <div id="chunk-list"></div>
+  </div>
+</div>
+
+<div class="tooltip" id="tooltip" style="display:none"></div>
+
+<script>
+const DATA = ${dataJson};
+
+// ── Palette ──
+const PALETTE = {
+  route:     '#7c3aed',
+  vendor:    '#89b4fa',
+  framework: '#a6e3a1',
+  entry:     '#fab387',
+  chunk:     '#6c7086',
+  css:       '#94e2d5',
+};
+function colourFor(type) { return PALETTE[type] || PALETTE.chunk; }
+function fmtKB(n) { return n >= 1024 ? (n/1024).toFixed(1)+' KB' : n+' B'; }
+function fmtPct(n, total) { return (n/total*100).toFixed(1)+'%'; }
+
+// ── Chunk list ──────────────────────────────────────────────────────────────
+let _activeFilter = 'all';
+const maxSize = DATA.chunks[0]?.size || 1;
+
+function renderChunkList(filter) {
+  const list = document.getElementById('chunk-list');
+  const items = filter === 'all' ? DATA.chunks : DATA.chunks.filter(c => c.type === filter);
+  list.innerHTML = items.map(c => \`
+    <div class="chunk-item">
+      <span class="chunk-dot" style="background:\${colourFor(c.type)}"></span>
+      <div style="flex:1;overflow:hidden">
+        <div class="chunk-name" title="\${c.path}">\${c.name}</div>
+        <span class="chunk-bar" style="width:\${Math.max(2, Math.round(c.size/maxSize*200))}px"></span>
+      </div>
+      <span class="chunk-type">\${c.type}</span>
+      <span class="chunk-size">\${fmtKB(c.size)}</span>
+    </div>
+  \`).join('');
+}
+
+function renderFilters() {
+  const types = ['all', ...new Set(DATA.chunks.map(c => c.type))];
+  const el = document.getElementById('filters');
+  el.innerHTML = types.map(t => \`
+    <button class="filter-btn\${t === _activeFilter ? ' active' : ''}" data-type="\${t}">\${t}</button>
+  \`).join('');
+  el.querySelectorAll('.filter-btn').forEach(btn => {
+    btn.addEventListener('click', () => {
+      _activeFilter = btn.dataset.type;
+      renderFilters();
+      renderChunkList(_activeFilter);
+    });
+  });
+}
+
+renderFilters();
+renderChunkList('all');
+
+// ── Treemap (squarified) ────────────────────────────────────────────────────
+const svg = document.getElementById('chart-svg');
+const tt  = document.getElementById('tooltip');
+
+function getRect() {
+  const r = svg.getBoundingClientRect();
+  return { x: 0, y: 0, w: r.width || 800, h: r.height || 500 };
+}
+
+// Squarified treemap algorithm
+function squarify(items, rect) {
+  if (!items.length) return [];
+  items = [...items].sort((a, b) => b.size - a.size);
+
+  const totalSize = items.reduce((s, i) => s + i.size, 0);
+  const rects = [];
+  let remaining = [...items];
+  let { x, y, w, h } = rect;
+
+  while (remaining.length) {
+    const row = [];
+    let rowSize = 0;
+    let i = 0;
+
+    while (i < remaining.length) {
+      row.push(remaining[i]);
+      rowSize += remaining[i].size;
+      const ratio = _worstRatio(row, rowSize, w, h, totalSize);
+      if (i > 0 && ratio > _worstRatio(row.slice(0, -1), rowSize - remaining[i].size, w, h, totalSize)) {
+        row.pop();
+        rowSize -= remaining[i].size;
+        break;
+      }
+      i++;
+    }
+
+    const rowFrac = rowSize / totalSize;
+    const shorter = Math.min(w, h);
+    const longer  = (w <= h ? w : h) * (rowFrac / (shorter / Math.max(w, h)));
+
+    let off = w <= h ? x : y;
+    for (const item of row) {
+      const frac = item.size / rowSize;
+      const len  = shorter * (rowFrac * (w <= h ? w : h) / shorter) * frac;
+      if (w <= h) {
+        rects.push({ item, x: off, y, w: len, h: shorter * rowFrac });
+        off += len;
+      } else {
+        rects.push({ item, x, y: off, w: shorter * rowFrac, h: len });
+        off += len;
+      }
+    }
+
+    if (w <= h) { y += shorter * rowFrac; h -= shorter * rowFrac; }
+    else        { x += shorter * rowFrac; w -= shorter * rowFrac; }
+
+    totalSize && (totalSize - rowSize);
+    remaining = remaining.filter(r => !row.includes(r));
+  }
+
+  return rects;
+}
+
+function _worstRatio(row, rowSize, w, h, total) {
+  if (!row.length) return Infinity;
+  const shorter = Math.min(w, h);
+  const rowW = Math.max(w, h) * (rowSize / total);
+  let worst = 0;
+  for (const item of row) {
+    const cellH = shorter * (rowSize / total) * (item.size / rowSize);
+    const r = Math.max(rowW / cellH, cellH / rowW);
+    if (r > worst) worst = r;
+  }
+  return worst;
+}
+
+function renderTreemap() {
+  svg.innerHTML = '';
+  const { w, h } = getRect();
+  svg.setAttribute('viewBox', \`0 0 \${w} \${h}\`);
+
+  const leaves = DATA.chunks.map(c => ({ ...c, size: c.size }));
+  const rects  = squarify(leaves, { x: 0, y: 0, w, h });
+
+  const ns = 'http://www.w3.org/2000/svg';
+  const PAD = 2;
+
+  for (const { item, x, y, w: rw, h: rh } of rects) {
+    if (rw < 2 || rh < 2) continue;
+
+    const g = document.createElementNS(ns, 'g');
+
+    const rect = document.createElementNS(ns, 'rect');
+    rect.setAttribute('x',      x + PAD);
+    rect.setAttribute('y',      y + PAD);
+    rect.setAttribute('width',  Math.max(0, rw - PAD * 2));
+    rect.setAttribute('height', Math.max(0, rh - PAD * 2));
+    rect.setAttribute('rx', 4);
+    rect.setAttribute('fill',   colourFor(item.type));
+    rect.setAttribute('fill-opacity', '0.85');
+    rect.setAttribute('stroke', '#1e1e2e');
+    rect.setAttribute('stroke-width', '1');
+    rect.style.cursor = 'pointer';
+    g.appendChild(rect);
+
+    if (rw > 50 && rh > 24) {
+      const label = document.createElementNS(ns, 'text');
+      label.setAttribute('x',           x + PAD + 6);
+      label.setAttribute('y',           y + PAD + 15);
+      label.setAttribute('font-size',   Math.min(13, rw / 7));
+      label.setAttribute('fill',        '#fff');
+      label.setAttribute('font-family', 'monospace');
+      label.setAttribute('font-weight', '600');
+      label.setAttribute('clip-path',   \`url(#clip-\${item.name})\`);
+      label.textContent = item.name;
+      g.appendChild(label);
+
+      if (rh > 38) {
+        const sub = document.createElementNS(ns, 'text');
+        sub.setAttribute('x',           x + PAD + 6);
+        sub.setAttribute('y',           y + PAD + 30);
+        sub.setAttribute('font-size',   10);
+        sub.setAttribute('fill',        'rgba(255,255,255,0.7)');
+        sub.setAttribute('font-family', 'system-ui');
+        sub.textContent = fmtKB(item.size);
+        g.appendChild(sub);
+      }
+    }
+
+    // Tooltip events
+    g.addEventListener('mouseenter', (e) => {
+      tt.style.display = 'block';
+      tt.innerHTML = \`
+        <div class="tt-name">\${item.name}</div>
+        <div class="tt-size">\${fmtKB(item.size)}</div>
+        <div class="tt-pct">\${fmtPct(item.size, DATA.totalJS)} of JS</div>
+        <div style="color:#6c7086;font-size:10px;margin-top:4px">\${item.path}</div>
+      \`;
+    });
+    g.addEventListener('mousemove', (e) => {
+      tt.style.left = (e.clientX + 16) + 'px';
+      tt.style.top  = (e.clientY - 10) + 'px';
+    });
+    g.addEventListener('mouseleave', () => { tt.style.display = 'none'; });
+
+    svg.appendChild(g);
+  }
+}
+
+renderTreemap();
+window.addEventListener('resize', renderTreemap);
+</script>
+</body>
+</html>`;
+}
+
+function _fmtKB(n) {
+  if (n >= 1024 * 1024) return `${(n / (1024 * 1024)).toFixed(2)} MB`;
+  if (n >= 1024) return `${(n / 1024).toFixed(1)} KB`;
+  return `${n} B`;
+}
+
+async function _openBrowser(filePath) {
+  const { platform } = process;
+  const url = `file://${filePath}`;
+  const cmd = platform === 'darwin' ? 'open'
+             : platform === 'win32' ? 'start'
+             : 'xdg-open';
+  const { exec } = await import('node:child_process');
+  exec(`${cmd} "${url}"`);
+}