@rolandjlevy/css-ghost 1.0.2 → 2.0.0

package/src/picker.js

@@ -0,0 +1,123 @@
+import { readdirSync, statSync } from 'fs';
+import { join } from 'path';
+
+const SKIP = new Set(['node_modules', '.git', 'dist', 'build', '.next', 'out', 'coverage', '.cache']);
+
+function getDirs(dir) {
+  try {
+    return readdirSync(dir)
+      .filter(f => {
+        if (f.startsWith('.') || SKIP.has(f)) return false;
+        try { return statSync(join(dir, f)).isDirectory(); }
+        catch { return false; }
+      })
+      .sort();
+  } catch { return []; }
+}
+
+export async function pickDirectories() {
+  return new Promise((done) => {
+    let cwd    = process.cwd();
+    let dirs   = getDirs(cwd);
+    let cursor = 0;
+    let selected = [];
+
+    // ANSI helpers (raw — no extra dep)
+    const C = {
+      reset:  '\x1b[0m',
+      bold:   '\x1b[1m',
+      dim:    '\x1b[2m',
+      invert: '\x1b[7m',
+      green:  '\x1b[32m',
+      cyan:   '\x1b[36m',
+    };
+
+    function render() {
+      const lines = [
+        '',
+        `${C.bold}📂 Directory picker${C.reset}  — navigate into a folder, then press ${C.cyan}[a]${C.reset} to add it`,
+        '',
+        `${C.dim}📍 ${cwd}${C.reset}`,
+        '',
+      ];
+
+      if (dirs.length === 0) {
+        lines.push(`  ${C.dim}(no subdirectories)${C.reset}`);
+      } else {
+        dirs.forEach((d, i) => {
+          const active = i === cursor;
+          lines.push(active
+            ? `  ${C.invert} 📁 ${d} ${C.reset}`
+            : `    📁 ${d}`);
+        });
+      }
+
+      lines.push('');
+
+      if (selected.length > 0) {
+        lines.push(`${C.green}✅ Added to scan:${C.reset}`);
+        selected.forEach(s => lines.push(`   ${C.green}${s}${C.reset}`));
+        lines.push('');
+      }
+
+      lines.push(
+        `${C.dim}[↑↓/jk] navigate  [↵/→] enter  [←] parent  [a] add current dir  [d] done  [^C] quit${C.reset}`
+      );
+
+      process.stdout.write('\x1b[H\x1b[J' + lines.join('\n') + '\n');
+    }
+
+    function cleanup() {
+      process.stdin.setRawMode(false);
+      process.stdin.pause();
+      process.stdout.write('\x1b[2J\x1b[H');
+    }
+
+    function finish() {
+      cleanup();
+      done(selected.length > 0 ? selected : [cwd]);
+    }
+
+    function goUp() {
+      const parent = join(cwd, '..');
+      if (parent !== cwd) {
+        cwd   = parent;
+        dirs  = getDirs(cwd);
+        cursor = 0;
+      }
+    }
+
+    function goInto() {
+      if (dirs.length > 0) {
+        cwd    = join(cwd, dirs[cursor]);
+        dirs   = getDirs(cwd);
+        cursor = 0;
+      }
+    }
+
+    function toggleAdd() {
+      const idx = selected.indexOf(cwd);
+      if (idx === -1) selected.push(cwd);
+      else selected.splice(idx, 1);
+    }
+
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.setEncoding('utf8');
+    process.stdout.write('\x1b[2J\x1b[H');
+    render();
+
+    process.stdin.on('data', (key) => {
+      if (key === '\x03')                    { cleanup(); process.exit(0); }       // Ctrl+C
+      else if (key === '\x1b[A' || key === 'k') cursor = Math.max(0, cursor - 1); // up
+      else if (key === '\x1b[B' || key === 'j') cursor = Math.min(dirs.length - 1, cursor + 1); // down
+      else if (key === '\x1b[C' || key === '\r') goInto();  // right / Enter
+      else if (key === '\x1b[D' || key === '\x7f') goUp();  // left / backspace
+      else if (key === 'a') toggleAdd();
+      else if (key === 'd') { finish(); return; }
+
+      if (dirs.length === 0) cursor = 0;
+      render();
+    });
+  });
+}

package/src/reporter.js

@@ -1,36 +1,94 @@
 import { writeFileSync } from 'fs';
 import { relative } from 'path';
+import pc from 'picocolors';
+
+function minifyCss(css) {
+  return css
+    .replace(/\/\*[\s\S]*?\*\//g, '')   // strip comments
+    .replace(/\s+/g, ' ')               // collapse whitespace
+    .replace(/\s*([{}:;,])\s*/g, '$1') // remove spaces around punctuation
+    .trim();
+}
+
+function calcSavings(rules) {
+  const raw = rules.reduce((n, r) => n + Buffer.byteLength(r || '', 'utf-8'), 0);
+  const min = rules.reduce((n, r) => n + Buffer.byteLength(minifyCss(r || ''), 'utf-8'), 0);
+  return { raw, min };
+}
+
+function formatBytes(n) {
+  if (n === 0) return '0 B';
+  if (n < 1024) return `${n} B`;
+  return `${(n / 1024).toFixed(1)} kB`;
+}
+
+/** Format a ghost-trail entry for markdown. */
+function trailMd(trail) {
+  if (!trail) return '';
+  return `> 🕵️  Last git activity: \`${trail.hash}\` by ${trail.author} · ${trail.when} — *"${trail.subject}"*\n`;
+}
+
+/** Format a ghost-trail entry for console. */
+function trailConsole(trail) {
+  if (!trail) return '';
+  return `      ${pc.dim(`🕵️  ${trail.hash} · ${trail.author} · ${trail.when}`)} ${pc.dim(`"${trail.subject}"`)}\n`;
+}
 
-export function generateReport(results, outputPath = 'orphan-report.md') {
-  let totalDefined = 0;
-  let totalOrphaned = 0;
-  let filesWithOrphans = 0;
+export function generateReport(results, outputPath = 'orphan-report.md', aiSummary = null) {
+  let totalDefined    = 0;
+  let totalOrphaned   = 0;
+  let totalVarsDefined  = 0;
+  let totalVarsOrphaned = 0;
+  let filesWithOrphans  = 0;
+  let totalRaw = 0;
+  let totalMin = 0;
 
   const sections = [];
 
   for (const result of results) {
-    const { filePath, orphaned, total, hasDynamic, dynamicFiles } = result;
-    totalDefined += total;
-    totalOrphaned += orphaned.length;
+    const { filePath, orphaned, orphanedVars = [], total, totalVars = 0,
+            hasDynamic, dynamicFiles, trails, varTrails } = result;
 
-    const hasOrphans = orphaned.length > 0;
-    if (hasOrphans) filesWithOrphans++;
+    totalDefined      += total;
+    totalOrphaned     += orphaned.length;
+    totalVarsDefined  += totalVars;
+    totalVarsOrphaned += orphanedVars.length;
 
-    // Skip files with nothing to report
-    if (!hasOrphans && !hasDynamic) continue;
+    const hasOrphans    = orphaned.length > 0;
+    const hasVarOrphans = orphanedVars.length > 0;
+    if (hasOrphans || hasVarOrphans) filesWithOrphans++;
+
+    if (!hasOrphans && !hasVarOrphans && !hasDynamic) continue;
 
     const relPath = relative(process.cwd(), filePath);
     const pct = total > 0 ? Math.round((orphaned.length / total) * 100) : 0;
 
+    const savings = hasOrphans
+      ? calcSavings(orphaned.map(o => o.rule).filter(Boolean))
+      : { raw: 0, min: 0 };
+    totalRaw += savings.raw;
+    totalMin += savings.min;
+
+    const savingsStr = hasOrphans
+      ? `${formatBytes(savings.raw)} raw · ${formatBytes(savings.min)} minified`
+      : '—';
+
     const lines = [
       `## \`${relPath}\``,
       '',
-      `| Defined | Orphaned | Unused % |`,
-      `| --- | --- | --- |`,
-      `| ${total} | ${orphaned.length} | ${pct}% |`,
+      `| Defined | Orphaned | Unused % | Potential savings |`,
+      `| --- | --- | --- | --- |`,
+      `| ${total} | ${orphaned.length} | ${pct}% | ${savingsStr} |`,
       '',
     ];
 
+    if (totalVars > 0) {
+      lines.push(`| CSS variables defined | CSS variables orphaned |`);
+      lines.push(`| --- | --- |`);
+      lines.push(`| ${totalVars} | ${orphanedVars.length} |`);
+      lines.push('');
+    }
+
     if (hasDynamic) {
       lines.push(`> ⚠️ **Dynamic class references detected** — results may be incomplete.`);
       if (dynamicFiles?.length > 0) {
@@ -48,6 +106,26 @@ export function generateReport(results, outputPath = 'orphan-report.md') {
       orphaned.forEach(({ name, line, rule }) => {
         lines.push(`#### \`.${name}\` — line ${line}`);
         lines.push('');
+        const trail = trails?.[name];
+        if (trail) lines.push(trailMd(trail));
+        if (rule) {
+          lines.push('```css');
+          lines.push(rule);
+          lines.push('```');
+        }
+        lines.push('');
+      });
+    }
+
+    if (hasVarOrphans) {
+      lines.push('### 🔮 Orphaned CSS variables\n');
+      lines.push('> These custom properties are defined but never referenced via `var()`.\n');
+
+      orphanedVars.forEach(({ name, line, rule }) => {
+        lines.push(`#### \`${name}\` — line ${line}`);
+        lines.push('');
+        const trail = varTrails?.[name];
+        if (trail) lines.push(trailMd(trail));
         if (rule) {
           lines.push('```css');
           lines.push(rule);
@@ -66,6 +144,19 @@ export function generateReport(results, outputPath = 'orphan-report.md') {
     ? Math.round((totalOrphaned / totalDefined) * 100)
     : 0;
 
+  const summaryRows = [
+    `| Style files scanned | ${results.length} |`,
+    `| Total selectors defined | ${totalDefined} |`,
+    `| Total orphaned selectors | ${totalOrphaned} |`,
+  ];
+  if (totalVarsDefined > 0) {
+    summaryRows.push(`| CSS variables defined | ${totalVarsDefined} |`);
+    summaryRows.push(`| CSS variables orphaned | ${totalVarsOrphaned} |`);
+  }
+  summaryRows.push(`| Files with orphans | ${filesWithOrphans} |`);
+  summaryRows.push(`| Overall unused rate | ${unusedPct}% |`);
+  summaryRows.push(`| Potential savings | ${formatBytes(totalRaw)} raw · ${formatBytes(totalMin)} minified |`);
+
   const summary = [
     '# 👻 css-ghost — Orphaned Selector Report',
     '',
@@ -75,33 +166,72 @@ export function generateReport(results, outputPath = 'orphan-report.md') {
     '',
     `| Metric | Value |`,
     `| --- | --- |`,
-    `| Style files scanned | ${results.length} |`,
-    `| Total selectors defined | ${totalDefined} |`,
-    `| Total orphaned selectors | ${totalOrphaned} |`,
-    `| Files with orphans | ${filesWithOrphans} |`,
-    `| Overall unused rate | ${unusedPct}% |`,
+    ...summaryRows,
     '',
     '---',
     '',
   ].join('\n');
 
-  const content = summary + sections.join('');
-  writeFileSync(outputPath, content, 'utf-8');
+  const aiBlock = aiSummary
+    ? `## 🤖 AI Summary\n\n${aiSummary}\n\n---\n\n`
+    : '';
 
-  // Console output — also print orphans inline
-  console.log(`📊 ${totalOrphaned} orphaned selector${totalOrphaned !== 1 ? 's' : ''} in ${filesWithOrphans} file${filesWithOrphans !== 1 ? 's' : ''}. See: ${outputPath}\n`);
+  const mdContent = summary + aiBlock + sections.join('');
+  writeFileSync(outputPath, mdContent, 'utf-8');
+
+  // ── Console output ─────────────────────────────────────────────────────────
+  const totalAllOrphans = totalOrphaned + totalVarsOrphaned;
+  const orphanCount = `${pc.bold(pc.yellow(totalOrphaned))} orphaned selector${totalOrphaned !== 1 ? 's' : ''}`;
+  const varOrphanCount = totalVarsOrphaned > 0
+    ? ` · ${pc.bold(pc.magenta(totalVarsOrphaned))} orphaned CSS variable${totalVarsOrphaned !== 1 ? 's' : ''}`
+    : '';
+  const fileCount = `${pc.bold(filesWithOrphans)} file${filesWithOrphans !== 1 ? 's' : ''}`;
+
+  console.log(`📊 ${orphanCount}${varOrphanCount} in ${fileCount}. See: ${pc.cyan(outputPath)}`);
+  if (totalMin > 0) console.log(`💾 Potential savings: ${pc.green(formatBytes(totalMin))} minified\n`);
+  else console.log('');
+
+  if (aiSummary) {
+    console.log(`🤖 ${pc.bold('AI summary')}\n`);
+    console.log(`   ${aiSummary.split('\n').join('\n   ')}\n`);
+  }
 
   for (const result of results) {
-    if (result.orphaned.length === 0) continue;
+    const { orphaned, orphanedVars = [], trails, varTrails } = result;
+    if (orphaned.length === 0 && orphanedVars.length === 0) continue;
+
     const relPath = relative(process.cwd(), result.filePath);
-    console.log(`✅ ${relPath}\n`);
-    result.orphaned.forEach(({ name, line, rule }) => {
-      console.log(`   👻 .${name} (line ${line})`);
+    const s = calcSavings(orphaned.map(o => o.rule).filter(Boolean));
+    const savingsSuffix = s.raw > 0
+      ? pc.dim(` — saves ~${formatBytes(s.raw)} (${formatBytes(s.min)} minified)`)
+      : '';
+    console.log(`✅ ${pc.bold(relPath)}${savingsSuffix}\n`);
+
+    orphaned.forEach(({ name, line, rule }) => {
+      console.log(`   👻 ${pc.yellow('.' + name)} ${pc.dim(`(line ${line})`)}`);
+      const trail = trails?.[name];
+      if (trail) process.stdout.write(trailConsole(trail));
       if (rule) {
         const preview = rule.split('\n').slice(0, 4).join('\n');
-        console.log(preview.split('\n').map(l => `      ${l}`).join('\n'));
+        console.log(preview.split('\n').map(l => `      ${pc.dim(l)}`).join('\n'));
       }
       console.log('');
     });
+
+    if (orphanedVars.length > 0) {
+      console.log(`   ${pc.magenta('🔮 Orphaned CSS variables:')}\n`);
+      orphanedVars.forEach(({ name, line, rule }) => {
+        console.log(`   🔮 ${pc.magenta(name)} ${pc.dim(`(line ${line})`)}`);
+        const trail = varTrails?.[name];
+        if (trail) process.stdout.write(trailConsole(trail));
+        if (rule) {
+          console.log(`      ${pc.dim(rule)}`);
+        }
+        console.log('');
+      });
+    }
   }
+
+  // Return totals so callers can check orphan counts (e.g. for --strict)
+  return { totalOrphaned, totalVarsOrphaned, totalAllOrphans };
 }

package/src/scanner.js

@@ -13,7 +13,9 @@ export function scan(dirs) {
     allJsCandidates.push(...componentFiles);
   }
 
-  // Split JS/TS files into style files vs component files
+  // Split JS/TS files into style files vs component files.
+  // makeStyles files are dual-role: they define style keys AND may reference
+  // those classes in the same file, so they go into both lists.
   const jsStyleFiles = [];
   const componentFiles = [];
 
@@ -24,6 +26,8 @@ export function scan(dirs) {
         const content = readFileSync(file, 'utf-8');
         if (isJsStyleFile(content, file)) {
           jsStyleFiles.push(file);
+          // makeStyles files may also consume their own classes in the same file
+          if (/makeStyles\s*\(/.test(content)) componentFiles.push(file);
           continue;
         }
       } catch {
@@ -35,41 +39,71 @@ export function scan(dirs) {
 
   const styleFiles = [...allStyleFiles, ...jsStyleFiles];
 
-  // Build global usage map from all component files
+  // ── PASS 1: Parse all style files once and cache results ─────────────────
+  // This avoids double-reading and gives us cssVars / varUsages in one shot.
+  const parsedStyleFiles = new Map(); // filePath → parseStyleFile result
+
+  const globalUsedVars = new Set(); // CSS var usages collected from ALL files
+
+  for (const styleFile of styleFiles) {
+    try {
+      const parsed = parseStyleFile(styleFile);
+      parsedStyleFiles.set(styleFile, parsed);
+      // Count var usages defined within style files themselves
+      // (e.g. one CSS file using a var defined in another)
+      if (parsed.varUsages) {
+        for (const v of parsed.varUsages) globalUsedVars.add(v);
+      }
+    } catch (e) {
+      console.warn(`⚠️  Could not parse ${styleFile}: ${e.message}`);
+    }
+  }
+
+  // ── PASS 2: Parse component files — collect class usages + var usages ─────
   const globalUsed = new Set();
   const dynamicComponentFiles = [];
 
   for (const file of componentFiles) {
     try {
-      const { used, hasDynamic } = parseComponentFile(file);
+      const { used, usedVars, hasDynamic } = parseComponentFile(file);
       for (const cls of used) globalUsed.add(cls);
+      if (usedVars) for (const v of usedVars) globalUsedVars.add(v);
       if (hasDynamic) dynamicComponentFiles.push(file);
     } catch {
       // skip unreadable files
     }
   }
 
-  // Analyse each style file
+  // ── PASS 3: Cross-reference and build results ─────────────────────────────
   const results = [];
 
   for (const styleFile of styleFiles) {
-    try {
-      const { selectors, hasDynamic } = parseStyleFile(styleFile);
-      // selectors is now a Map: name → { line, rule }
-      const orphaned = [...selectors.entries()]
-        .filter(([name]) => !globalUsed.has(name))
-        .map(([name, meta]) => ({ name, ...meta }));
-
-      results.push({
-        filePath: styleFile,
-        total: selectors.size,
-        orphaned,
-        hasDynamic: hasDynamic || dynamicComponentFiles.length > 0,
-        dynamicFiles: dynamicComponentFiles,
-      });
-    } catch (e) {
-      console.warn(`⚠️  Could not parse ${styleFile}: ${e.message}`);
-    }
+    const parsed = parsedStyleFiles.get(styleFile);
+    if (!parsed) continue;
+
+    const { selectors, cssVars, hasDynamic } = parsed;
+
+    // Orphaned class selectors
+    const orphaned = [...selectors.entries()]
+      .filter(([name]) => !globalUsed.has(name))
+      .map(([name, meta]) => ({ name, ...meta }));
+
+    // Orphaned CSS custom properties
+    const orphanedVars = cssVars
+      ? [...cssVars.entries()]
+          .filter(([name]) => !globalUsedVars.has(name))
+          .map(([name, meta]) => ({ name, ...meta }))
+      : [];
+
+    results.push({
+      filePath: styleFile,
+      total: selectors.size,
+      orphaned,
+      orphanedVars,
+      totalVars: cssVars?.size ?? 0,
+      hasDynamic: hasDynamic || dynamicComponentFiles.length > 0,
+      dynamicFiles: dynamicComponentFiles,
+    });
   }
 
   return results;

package/src/setup.js

@@ -0,0 +1,60 @@
+import { createInterface } from 'readline';
+import { writeFileSync, readFileSync, existsSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+
+export const CONFIG_PATH = join(homedir(), '.css-ghost');
+
+export function loadConfig() {
+  if (!existsSync(CONFIG_PATH)) return {};
+  try {
+    return JSON.parse(readFileSync(CONFIG_PATH, 'utf-8'));
+  } catch {
+    return {};
+  }
+}
+
+export function saveConfig(config) {
+  writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2), 'utf-8');
+}
+
+export async function runSetup() {
+  console.log(`
+👻 css-ghost — AI setup
+
+To enable AI summaries, you need a free OpenRouter API key.
+
+  1. Go to https://openrouter.ai/keys
+  2. Sign up (free) and create a key
+  3. Paste it below — it will be saved to ${CONFIG_PATH}
+
+`);
+
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+
+  const key = await new Promise(resolve => {
+    rl.question('Paste your OpenRouter API key: ', answer => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+
+  if (!key) {
+    console.log('\n❌ No key entered. Setup cancelled.\n');
+    process.exit(1);
+  }
+
+  if (!key.startsWith('sk-or-')) {
+    console.log('\n⚠️  That doesn\'t look like an OpenRouter key (should start with sk-or-).');
+    console.log('   Saving anyway — double-check at https://openrouter.ai/keys if --ai fails.\n');
+  }
+
+  const existing = loadConfig();
+  saveConfig({ ...existing, openrouterApiKey: key });
+
+  console.log(`
+✅ Key saved to ${CONFIG_PATH}
+
+Run css-ghost ./src --ai to get an AI summary alongside your report.
+`);
+}