@rolandjlevy/css-ghost 1.0.1 → 1.0.4

package/README.md

@@ -4,7 +4,7 @@ Find orphaned CSS class selectors in your codebase — defined in style files bu
 
 ## What it does
 
-Scans one or more directories for style files, extracts every class selector defined, then cross-references them against usages in your component files. Anything defined but never used is reported as an orphan.
+Scans one or more directories for style files, extracts every class selector defined, then cross-references them against usages in your component files. Anything defined but never used is reported as an orphan — with its line number and the actual CSS printed inline.
 
 **Supported style files:**
 - `.css`, `.module.css`, `.scss`, `.sass`, `.less`
@@ -14,21 +14,40 @@ Scans one or more directories for style files, extracts every class selector def
 - `className="foo"`
 - `className={styles.foo}`
 - `styles['foo']`
+- `styles[condition ? 'foo' : 'bar']` — both branches extracted
 - `cx('foo')`, `clsx('foo')`, `classnames('foo')`
+- `cx({ active: isOn, disabled: true })` — object keys extracted
+- `cx(['foo', condition && 'bar'])` — array string literals extracted
 
 **Dynamic class detection:**
-Files containing `styles[variable]` or template literal class names are flagged with a ⚠️ warning — results for those files may be incomplete.
+Patterns where the class name is truly unknowable at parse time — `styles[variable]` or template literals containing `${}` — are flagged with a ⚠️ warning. All statically resolvable patterns (string literals, ternaries, object keys) are analysed without warnings.
+
+## To enable AI features
+
+css-ghost can generate a plain English summary of your orphaned selectors using a free [OpenRouter](https://openrouter.ai) API key. Run the setup wizard once:
+
+```bash
+css-ghost --setup
+```
+
+It will prompt you to paste your key (free at [openrouter.ai/keys](https://openrouter.ai/keys)) and save it to `~/.css-ghost`. Then pass `--ai` to any scan:
+
+```bash
+css-ghost ./src --ai
+```
+
+The AI summary appears in both the terminal output and the markdown report. The core scan always runs without a key — `--ai` is entirely optional.
 
 ## Install
 
 ```bash
-npm install -g css-ghost
+npm install -g @rolandjlevy/css-ghost
 ```
 
-Or run directly without installing:
+Or run without installing:
 
 ```bash
-npx css-ghost ./src
+npx @rolandjlevy/css-ghost ./src
 ```
 
 ## Usage
@@ -42,49 +61,105 @@ css-ghost <directory> [directory2] ... [options]
 | Flag | Description | Default |
 | --- | --- | --- |
 | `--output <file>` | Output report file path | `orphan-report.md` |
+| `--ai` | Append an AI-generated summary (requires setup) | off |
+| `--setup` | Save your OpenRouter API key for `--ai` | — |
 | `-h, --help` | Show help | — |
 
 ## Examples
 
 ```bash
-# Scan a single directory
+# Scan your src folder
 css-ghost ./src
 
 # Scan multiple directories
 css-ghost ./src ./components ./pages
 
-# Custom output path
+# With AI summary
+css-ghost ./src --ai
+
+# Write report to a custom path
 css-ghost ./src --output ./reports/css-audit.md
 ```
 
-## Output
+## CLI output
+
+Running `css-ghost ./src` prints a live summary to your terminal:
+
+```
+✅ Report written to orphan-report.md
+📊 3 orphaned selectors across 1 file
+
+📄 src/components/Button/Button.module.css
+   👻 .iconLeft (line 4)
+      .iconLeft {
+        margin-right: 6px;
+        flex-shrink: 0;
+      }
+
+   👻 .loadingSpinner (line 12)
+      .loadingSpinner {
+        animation: spin 0.8s linear infinite;
+      }
+
+   👻 .disabled (line 18)
+      .disabled {
+        opacity: 0.4;
+        pointer-events: none;
+      }
+
+📁 1 style file scanned
+```
+
+Each orphan shows:
+- the selector name and the **exact line number** where it's defined
+- the **full CSS rule** so you can see what it does before deciding to delete it
+
+## Markdown report
 
-Generates a markdown report (`orphan-report.md` by default):
+A full report is also written to `orphan-report.md` (or your `--output` path):
 
 ---
 
-# 👻 css-ghost — Orphaned Selector Report
+### 👻 Orphaned selectors
 
-## Summary
-| Metric | Value |
-| --- | --- |
-| Style files scanned | 12 |
-| Total selectors defined | 84 |
-| Total orphaned selectors | 7 |
-| Files with orphans | 3 |
-| Overall unused rate | 8% |
+#### `.iconLeft` — line 4
 
-## `src/components/Button/Button.module.css`
-| Defined | Orphaned | Unused % |
-| --- | --- | --- |
-| 6 | 2 | 33% |
+```css
+.iconLeft {
+  margin-right: 6px;
+  flex-shrink: 0;
+}
+```
 
-**Orphaned selectors:**
-- `.iconLeft`
-- `.loadingSpinner`
+#### `.loadingSpinner` — line 12
+
+```css
+.loadingSpinner {
+  animation: spin 0.8s linear infinite;
+}
+```
 
 ---
 
+## Using with npm scripts
+
+If you're working inside the project itself, add a `scan` script to `package.json`:
+
+```json
+"scripts": {
+  "scan": "css-ghost ./src"
+}
+```
+
+Then run:
+
+```bash
+npm run scan
+
+# Pass extra args with --
+npm run scan -- --output ./reports/audit.md
+```
+
 ## No dependencies
 
 Built with Node.js built-ins only (`fs`, `path`). No npm packages required.

package/bin/css-ghost.js

@@ -4,9 +4,17 @@ import { resolve } from 'path';
 import { existsSync as fsExists } from 'fs';
 import { scan } from '../src/scanner.js';
 import { generateReport } from '../src/reporter.js';
+import { runSetup } from '../src/setup.js';
+import { getAiSummary } from '../src/ai.js';
 
 const args = process.argv.slice(2);
 
+// --setup
+if (args.includes('--setup')) {
+  await runSetup();
+  process.exit(0);
+}
+
 if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
   console.log(`
 👻 css-ghost — Find orphaned CSS class selectors
@@ -16,17 +24,21 @@ Usage:
 
 Options:
   --output <file>   Output report file path (default: orphan-report.md)
+  --ai              Append an AI-generated summary to the report
+  --setup           Save your OpenRouter API key for use with --ai
   -h, --help        Show this help message
 
 Examples:
   css-ghost ./src
   css-ghost ./src ./components
+  css-ghost ./src --ai
   css-ghost ./src --output ./reports/css-audit.md
 `);
   process.exit(0);
 }
 
-// Parse --output flag
+// Parse flags
+const useAi = args.includes('--ai');
 const outputIdx = args.indexOf('--output');
 const outputPath = outputIdx !== -1 ? args[outputIdx + 1] : 'orphan-report.md';
 
@@ -35,8 +47,10 @@ if (outputIdx !== -1 && !outputPath) {
   process.exit(1);
 }
 
-// Remaining args are directories
-const rawDirs = args.filter((a, i) => !a.startsWith('--') && (outputIdx === -1 || i !== outputIdx + 1));
+// Remaining args are directories (strip flags and their values)
+const rawDirs = args.filter((a, i) =>
+  !a.startsWith('--') && (outputIdx === -1 || i !== outputIdx + 1)
+);
 
 if (rawDirs.length === 0) {
   console.error('❌ At least one directory is required');
@@ -65,4 +79,7 @@ if (results.length === 0) {
   process.exit(0);
 }
 
-generateReport(results, outputPath);
+// Get AI summary before writing report (so it can be included in the .md)
+const aiSummary = useAi ? await getAiSummary(results) : null;
+
+generateReport(results, outputPath, aiSummary);

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "@rolandjlevy/css-ghost",
-  "version": "1.0.1",
+  "version": "1.0.4",
   "description": "Find orphaned CSS class selectors in your codebase",
   "type": "module",
   "bin": {
     "css-ghost": "bin/css-ghost.js"
   },
   "scripts": {
-    "start": "node bin/css-ghost.js"
+    "start": "node bin/css-ghost.js",
+    "scan": "node bin/css-ghost.js ./test",
+    "setup": "node bin/css-ghost.js --setup"
   },
   "files": [
     "bin",

package/src/ai.js

@@ -0,0 +1,94 @@
+import { relative } from 'path';
+import { loadConfig } from './setup.js';
+
+const OPENROUTER_URL = 'https://openrouter.ai/api/v1/chat/completions';
+// Fallback chain — tried in order until one returns a response
+const FREE_MODELS = [
+  'nvidia/nemotron-3.5-lightning:free',
+  'google/gemma-4-31b-it:free',
+  'qwen/qwen3.8-27b:free',
+  'thinkingmachines/inkling:free',
+  'nvidia/nemotron-3-super-120b-a12b:free',
+];
+
+function getApiKey() {
+  if (process.env.OPENROUTER_API_KEY) return process.env.OPENROUTER_API_KEY;
+  const config = loadConfig();
+  return config.openrouterApiKey || null;
+}
+
+function getModelOverride() {
+  if (process.env.OPENROUTER_MODEL) return process.env.OPENROUTER_MODEL;
+  const config = loadConfig();
+  return config.openrouterModel || null;
+}
+
+async function tryModel(model, key, prompt) {
+  const response = await fetch(OPENROUTER_URL, {
+    method: 'POST',
+    headers: {
+      'Authorization': `Bearer ${key}`,
+      'Content-Type': 'application/json',
+      'HTTP-Referer': 'https://github.com/rolandjlevy/css-ghost',
+      'X-Title': 'css-ghost',
+    },
+    body: JSON.stringify({
+      model,
+      messages: [{ role: 'user', content: prompt }],
+      max_tokens: 300,
+    }),
+  });
+
+  if (!response.ok) return null;
+  const data = await response.json();
+  return data.choices?.[0]?.message?.content?.trim() || null;
+}
+
+function buildPrompt(results) {
+  const totalOrphaned = results.reduce((n, r) => n + r.orphaned.length, 0);
+  const filesWithOrphans = results.filter(r => r.orphaned.length > 0);
+
+  const details = filesWithOrphans.map(r => {
+    const relPath = relative(process.cwd(), r.filePath);
+    const names = r.orphaned.map(o => `.${o.name}`).join(', ');
+    return `- ${relPath}: ${names}`;
+  }).join('\n');
+
+  return `You are a CSS code quality assistant. A static analysis tool found ${totalOrphaned} orphaned CSS selectors (defined but never referenced in any component file) across ${filesWithOrphans.length} file(s):
+
+${details}
+
+Write a short, practical summary (3–5 sentences) for a developer. Cover:
+1. Whether this looks like a significant problem or minor cleanup
+2. Which files or selectors are most worth investigating first
+3. One concrete suggestion for how to approach the cleanup
+
+Be direct and specific. No fluff.`;
+}
+
+export async function getAiSummary(results) {
+  const key = getApiKey();
+
+  if (!key) {
+    console.log('💡 Tip: Run css-ghost --setup to enable AI summaries with --ai\n');
+    return null;
+  }
+
+  const override = getModelOverride();
+  const models = override ? [override] : FREE_MODELS;
+  const prompt = buildPrompt(results);
+
+  console.log('🤖 Generating AI summary...\n');
+
+  for (const model of models) {
+    try {
+      const content = await tryModel(model, key, prompt);
+      if (content) return content;
+    } catch {
+      // try next model
+    }
+  }
+
+  console.warn('⚠️  AI summary unavailable — all free models failed or returned empty responses.\n');
+  return null;
+}

package/src/parser.js

@@ -135,23 +135,42 @@ export function extractUsages(content) {
     used.add(m[1]);
   }
 
-  // styles[variable] — dynamic, flag it
-  if (/styles?\[(?!['"])/.test(content)) {
+  // styles[condition ? 'foo' : 'bar'] — ternary with string literals: extract both branches
+  const ternaryBracketRegex = /styles?\[\s*[^?]+\?\s*['"]([a-zA-Z_$][a-zA-Z0-9_$]*)["']\s*:\s*['"]([a-zA-Z_$][a-zA-Z0-9_$]*)["']\s*\]/g;
+  while ((m = ternaryBracketRegex.exec(content)) !== null) {
+    used.add(m[1]);
+    used.add(m[2]);
+  }
+
+  // styles[variable] — truly dynamic (not a string literal or ternary): flag it
+  const trulyDynamicBracket = /styles?\[(?!['"])(?![^?]+\?\s*['"])/;
+  if (trulyDynamicBracket.test(content)) {
     hasDynamic = true;
   }
 
   // cx('foo', 'bar') / clsx('foo') / classnames('foo')
-  const cxRegex = /(?:cx|clsx|classnames)\s*\(([^)]+)\)/g;
+  // Also handles object syntax: cx({ active: isOn, disabled: true })
+  // and array syntax: cx(['foo', condition && 'bar'])
+  const cxRegex = /(?:cx|clsx|classnames)\s*\(([\s\S]*?)\)/g;
   while ((m = cxRegex.exec(content)) !== null) {
     const inner = m[1];
+
+    // String literals: 'foo' or "foo"
     const strRegex = /['"]([a-zA-Z_-][a-zA-Z0-9_-]*)["']/g;
     let sm;
     while ((sm = strRegex.exec(inner)) !== null) {
       used.add(sm[1]);
     }
+
+    // Object keys: { active: ..., disabled: ... }
+    const objKeyRegex = /^\s*([a-zA-Z_$][a-zA-Z0-9_$]*)\s*:/gm;
+    while ((sm = objKeyRegex.exec(inner)) !== null) {
+      used.add(sm[1]);
+    }
   }
 
-  // Template literal dynamic class names
+  // Template literal dynamic class names — flag only if truly dynamic (has ${})
+  // But first extract any static styles.foo refs inside them (already caught above by dotRegex)
   if (/`[^`]*\$\{[^}]+\}[^`]*`/.test(content)) {
     hasDynamic = true;
   }

package/src/reporter.js

@@ -1,7 +1,7 @@
 import { writeFileSync } from 'fs';
 import { relative } from 'path';
 
-export function generateReport(results, outputPath = 'orphan-report.md') {
+export function generateReport(results, outputPath = 'orphan-report.md', aiSummary = null) {
   let totalDefined = 0;
   let totalOrphaned = 0;
   let filesWithOrphans = 0;
@@ -85,17 +85,25 @@ export function generateReport(results, outputPath = 'orphan-report.md') {
     '',
   ].join('\n');
 
-  const content = summary + sections.join('');
+  const aiBlock = aiSummary
+    ? `## 🤖 AI Summary\n\n${aiSummary}\n\n---\n\n`
+    : '';
+
+  const content = summary + aiBlock + sections.join('');
   writeFileSync(outputPath, content, 'utf-8');
 
   // Console output — also print orphans inline
-  console.log(`✅ Report written to ${outputPath}`);
-  console.log(`📊 ${totalOrphaned} orphaned selector${totalOrphaned !== 1 ? 's' : ''} across ${filesWithOrphans} file${filesWithOrphans !== 1 ? 's' : ''}\n`);
+  console.log(`📊 ${totalOrphaned} orphaned selector${totalOrphaned !== 1 ? 's' : ''} in ${filesWithOrphans} file${filesWithOrphans !== 1 ? 's' : ''}. See: ${outputPath}\n`);
+
+  if (aiSummary) {
+    console.log(`🤖 AI summary\n`);
+    console.log(`   ${aiSummary.split('\n').join('\n   ')}\n`);
+  }
 
   for (const result of results) {
     if (result.orphaned.length === 0) continue;
     const relPath = relative(process.cwd(), result.filePath);
-    console.log(`📄 ${relPath}`);
+    console.log(`✅ ${relPath}\n`);
     result.orphaned.forEach(({ name, line, rule }) => {
       console.log(`   👻 .${name} (line ${line})`);
       if (rule) {
@@ -105,6 +113,4 @@ export function generateReport(results, outputPath = 'orphan-report.md') {
       console.log('');
     });
   }
-
-  console.log(`📁 ${results.length} style file${results.length !== 1 ? 's' : ''} scanned\n`);
 }

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.
+`);
+}