@rolandjlevy/css-ghost 1.0.2 → 2.0.0

package/LICENSE

@@ -0,0 +1,24 @@
+MIT License
+
+Copyright (c) 2026 Roland Levy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+Standard MIT License text sourced from https://choosealicense.com/licenses/mit/

package/README.md

@@ -7,17 +7,41 @@ Find orphaned CSS class selectors in your codebase — defined in style files bu
 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`
-- `.js` / `.ts` files using `StyleSheet.create({})` or named style objects
+- `.js` / `.ts` files using `StyleSheet.create({})`, `makeStyles({})` (MUI), or named style objects
+- `.css.ts` / `.css.js` files using `style()` or `styleVariants()` (vanilla-extract)
 
 **Detected usage patterns:**
+
 - `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
+- `classes.foo` — MUI `makeStyles` / `useStyles` convention
+- `import { foo } from './styles.css'` — vanilla-extract named imports
 
 **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
 
@@ -34,25 +58,183 @@ npx @rolandjlevy/css-ghost ./src
 ## Usage
 
 ```bash
-css-ghost <directory> [directory2] ... [options]
+css-ghost [directory] [directory2] ... [options]
 ```
 
 **Options:**
 
-| Flag | Description | Default |
-| --- | --- | --- |
-| `--output <file>` | Output report file path | `orphan-report.md` |
-| `-h, --help` | Show help | — |
+| Flag              | Description                                          | Default            |
+| ----------------- | ---------------------------------------------------- | ------------------ |
+| `--output <file>` | Output report file path                              | `orphan-report.md` |
+| `--delete`        | Delete all orphaned selectors from source files      | off                |
+| `--yes`           | Skip the deletion confirmation prompt                | off                |
+| `--strict`        | Exit with code 1 when any orphans are found (CI use) | off                |
+| `--ghost-trail`   | Show the last git commit that touched each orphan    | off                |
+| `--install-hook`  | Write a pre-commit hook to `.git/hooks/pre-commit`   | —                  |
+| `--ai`            | Append an AI-generated summary (requires setup)      | off                |
+| `--setup`         | Save your OpenRouter API key for `--ai`              | —                  |
+| `-h, --help`      | Show help                                            | —                  |
+
+## CSS variable orphan detection
+
+css-ghost also catches **orphaned CSS custom properties** — variables defined with `--my-token: value` but never consumed anywhere via `var(--my-token)`.
+
+Usages are detected across all file types: CSS, SCSS, JS, TS, JSX, TSX, Vue, Svelte, HTML. A variable defined in `variables.css` and used in a React component is correctly seen as _used_.
+
+```
+   🔮 --colour-danger-hover (line 8)
+      --colour-danger-hover: #dc2626;
+
+   🔮 --spacing-xl (line 26)
+      --spacing-xl: 64px;
+```
+
+Orphaned variables appear under a separate **🔮 Orphaned CSS variables** section in both the terminal output and the markdown report.
+
+---
+
+## Ghost trail — git history for orphans
+
+Pass `--ghost-trail` to fetch the last git commit that changed each orphan's occurrence count in the codebase. For class-name orphans the search is limited to component file types (`.tsx`, `.jsx`, `.ts`, `.js`, etc.) so the result reflects _usage_ history rather than the style-file definition.
+
+```bash
+css-ghost ./src --ghost-trail
+```
+
+```
+   👻 .iconRight (line 28)
+      🕵️  b5c6efb · Roland Levy · 3 weeks ago — "Refactor Button component"
+      .iconRight {
+        margin-left: 6px;
+      }
+```
+
+For CSS variables the search looks for `var(--name` across all file types.
+
+> **Note:** ghost trail runs one `git log -S` per orphan in parallel. On large histories with many orphans it may take a few seconds.
+
+---
+
+## Pre-commit hook
+
+Install a hook that blocks commits when orphaned selectors are present:
+
+```bash
+css-ghost --install-hook ./src
+```
+
+This writes `.git/hooks/pre-commit` (executable, `chmod 755`) containing:
+
+```sh
+#!/bin/sh
+echo "👻  css-ghost — checking for orphaned CSS selectors..."
+npx --yes @rolandjlevy/css-ghost ./src --strict --output /tmp/css-ghost-hook-report.md
+
+if [ $? -ne 0 ]; then
+  echo "❌  Commit blocked: orphaned CSS selectors found"
+  echo "    Run 'css-ghost ./src --delete' to remove them"
+  echo "    Or skip: git commit --no-verify"
+  exit 1
+fi
+```
+
+Pass multiple directories to the hook installer the same way you would to a normal scan:
+
+```bash
+css-ghost --install-hook ./src ./components ./pages
+```
+
+To uninstall: `rm .git/hooks/pre-commit`
+
+### `--strict` flag
+
+`--strict` makes css-ghost exit with code 1 when any orphans are found — the mechanism the hook depends on, but also useful in CI workflows independently:
+
+```bash
+# In CI: fail the build if orphans exist
+css-ghost ./src --strict
+```
+
+---
+
+## Interactive folder picker
+
+Run `css-ghost` with no arguments and an arrow-key picker opens in your terminal:
+
+```
+📂 Directory picker  — navigate into a folder, then press [a] to add it
+
+📍 /home/user/my-project
+
+    📁 components
+  ▶  📁 src
+    📁 styles
+
+✅ Added to scan:
+   /home/user/my-project/src
+
+[↑↓/jk] navigate  [↵/→] enter  [←] parent  [a] add current dir  [d] done  [^C] quit
+```
+
+| Key                    | Action                                  |
+| ---------------------- | --------------------------------------- |
+| `↑` / `↓` or `k` / `j` | Move up and down the folder list        |
+| `↵` or `→`             | Enter the highlighted folder            |
+| `←` or Backspace       | Go up to the parent folder              |
+| `a`                    | Add the current folder to the scan list |
+| `d`                    | Done — start the scan                   |
+| `Ctrl+C`               | Quit without scanning                   |
+
+You can add **multiple folders** before pressing `d` — just navigate to each one and press `a`. If you press `d` without adding anything, the folder you're currently browsing is used.
+
+## Deleting orphans
+
+Pass `--delete` after a scan to remove every flagged selector directly from its source file:
+
+```bash
+css-ghost ./src --delete
+```
+
+css-ghost prints the full report first, then lists what will be deleted and asks for confirmation before touching anything. Pass `--yes` to skip the prompt (useful in CI or scripts):
+
+```bash
+css-ghost ./src --delete --yes
+```
+
+Works across all supported file types — `.css`, `.scss`, `.less`, MUI `makeStyles`, and vanilla-extract exports.
+
+> **Tip:** commit or stash your work before running `--delete`. There is no undo.
 
 ## Examples
 
 ```bash
+# Interactive folder picker (no args)
+css-ghost
+
 # Scan your src folder
 css-ghost ./src
 
+# Show git history for each orphan
+css-ghost ./src --ghost-trail
+
+# Fail with exit code 1 when orphans exist (CI)
+css-ghost ./src --strict
+
+# Install a pre-commit hook that scans ./src
+css-ghost --install-hook ./src
+
+# Scan and delete all orphans (with confirmation prompt)
+css-ghost ./src --delete
+
+# Scan and delete without prompting
+css-ghost ./src --delete --yes
+
 # Scan multiple directories
 css-ghost ./src ./components ./pages
 
+# With AI summary
+css-ghost ./src --ai
+
 # Write report to a custom path
 css-ghost ./src --output ./reports/css-audit.md
 ```
@@ -87,6 +269,7 @@ Running `css-ghost ./src` prints a live summary to your terminal:
 ```
 
 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
 
@@ -136,39 +319,65 @@ npm run scan
 npm run scan -- --output ./reports/audit.md
 ```
 
-## No dependencies
+## Troubleshooting
+
+### `css-ghost: command not found` after global install
+
+Your npm global bin directory may not be on your PATH. Run:
+
+```bash
+npm bin -g
+```
+
+Then add that path to your shell config (`~/.zshrc`, `~/.bashrc`, etc.):
 
-Built with Node.js built-ins only (`fs`, `path`). No npm packages required.
+```bash
+export PATH="$(npm bin -g):$PATH"
+```
+
+Reload with `source ~/.zshrc`. This is a one-time fix — it won't be needed again after that.
+
+> This is common when Node was installed via the official installer rather than nvm or Homebrew.
+
+## Dependencies
+
+One runtime dependency: [`picocolors`](https://github.com/alexeyraspopov/picocolors) for terminal colours. Everything else uses Node.js built-ins (`fs`, `path`, `readline`).
 
 ## Origin — built with OpenRouter free models via Claude Code
 
 This tool was created as a test project to explore [using OpenRouter's free model tier with Claude Code](https://www.mindstudio.ai/blog/open-router-free-models-claude-code-cost-reduction) as a way to cut AI development costs.
 
-Claude Code normally calls Anthropic's API directly. By overriding two environment variables you can route it through OpenRouter's free tier instead — meaning you can run agentic coding sessions at no cost using models like Llama 3.3 70B or Deepseek R1.
-
-### Setup
+Claude Code normally calls Anthropic's API directly. By overriding two environment variables you can route it through OpenRouter's free tier instead — meaning you can run agentic coding sessions at no cost.
 
-Get a free API key at [openrouter.ai/keys](https://openrouter.ai/keys), then add these aliases to your `~/.zshrc`:
+If you've already run `css-ghost --setup`, you have an OpenRouter key. You can also export it as an environment variable — css-ghost picks it up automatically, so you don't even need `--setup`:
 
 ```bash
-# Store your key once
 export OPENROUTER_API_KEY="sk-or-v1-YOUR_KEY"
+```
+
+And you can reuse the same key with Claude Code by adding these aliases to your `~/.zshrc`:
 
-# Llama 3.3 70B — fast, capable, free
+```bash
 alias claude-free='ANTHROPIC_BASE_URL="https://openrouter.ai/api/v1" \
   ANTHROPIC_API_KEY="$OPENROUTER_API_KEY" \
-  claude --model "meta-llama/llama-3.3-70b-instruct:free"'
+  claude --model "nvidia/nemotron-3.5-lightning:free"'
 
-# Deepseek R1 — strongest free option for reasoning and debugging
 alias claude-r1='ANTHROPIC_BASE_URL="https://openrouter.ai/api/v1" \
   ANTHROPIC_API_KEY="$OPENROUTER_API_KEY" \
-  claude --model "deepseek/deepseek-r1:free"'
+  claude --model "qwen/qwen3.8-27b:free"'
 ```
 
 Then `source ~/.zshrc`. Use `claude-free` or `claude-r1` in place of `claude` to start a free session.
 
-> **Note:** Free tier models handle Claude Code's tool call format well in practice, but run a quick agentic task first to confirm file read/edit/bash loops work end to end in your environment before committing to it for serious work.
+> **Note:** Free model availability changes frequently. Browse current options at [openrouter.ai/models](https://openrouter.ai/models?q=free) — filter by `:free`.
 
 ## License
 
 MIT
+
+```bash
+  .-.
+ (o o)
+ | O |
+ '~~~'
+```

package/bin/css-ghost.js

@@ -4,54 +4,98 @@ import { resolve } from 'path';
 import { existsSync as fsExists } from 'fs';
 import { scan } from '../src/scanner.js';
 import { generateReport } from '../src/reporter.js';
+import { deleteOrphans } from '../src/deleter.js';
+import { runSetup } from '../src/setup.js';
+import { getAiSummary } from '../src/ai.js';
 
 const args = process.argv.slice(2);
 
-if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
+// --setup
+if (args.includes('--setup')) {
+  await runSetup();
+  process.exit(0);
+}
+
+// --install-hook [dirs...]
+if (args.includes('--install-hook')) {
+  const { installHook } = await import('../src/hook.js');
+  // Any positional args become the directories the hook will scan
+  const hookDirs = args.filter(a => !a.startsWith('-'));
+  installHook(hookDirs, process.cwd());
+  process.exit(0);
+}
+
+if (args.includes('--help') || args.includes('-h')) {
   console.log(`
-👻 css-ghost — Find orphaned CSS class selectors
+👻 css-ghost — Find orphaned CSS class selectors and custom properties
 
 Usage:
-  css-ghost <directory> [directory2] ... [options]
+  css-ghost [directory] [directory2] ... [options]
+
+  When no directory is given, an interactive folder picker opens.
 
 Options:
-  --output <file>   Output report file path (default: orphan-report.md)
-  -h, --help        Show this help message
+  --output <file>    Output report file path (default: orphan-report.md)
+  --delete           Delete all orphaned selectors from source files (prompts first)
+  --yes              Skip the deletion confirmation prompt (use with --delete)
+  --strict           Exit with code 1 when orphans are found (useful in CI)
+  --ghost-trail      Show the last git commit that touched each orphan
+  --install-hook     Write a pre-commit hook to .git/hooks/pre-commit
+  --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                          # interactive folder picker
   css-ghost ./src
   css-ghost ./src ./components
+  css-ghost ./src --ghost-trail      # show git history for each orphan
+  css-ghost ./src --strict           # exit 1 when orphans found (CI mode)
+  css-ghost ./src --delete
+  css-ghost ./src --delete --yes
+  css-ghost --install-hook ./src     # install pre-commit hook for ./src
+  css-ghost ./src --ai
   css-ghost ./src --output ./reports/css-audit.md
 `);
   process.exit(0);
 }
 
-// Parse --output flag
-const outputIdx = args.indexOf('--output');
-const outputPath = outputIdx !== -1 ? args[outputIdx + 1] : 'orphan-report.md';
+// Parse flags
+const useAi       = args.includes('--ai');
+const doDelete    = args.includes('--delete');
+const skipConfirm = args.includes('--yes') || args.includes('-y');
+const strict      = args.includes('--strict');
+const ghostTrail  = args.includes('--ghost-trail');
+const outputIdx   = args.indexOf('--output');
+const outputPath  = outputIdx !== -1 ? args[outputIdx + 1] : 'orphan-report.md';
 
 if (outputIdx !== -1 && !outputPath) {
   console.error('❌ --output requires a file path');
   process.exit(1);
 }
 
-// Remaining args are directories
-const rawDirs = args.filter((a, i) => !a.startsWith('--') && (outputIdx === -1 || i !== outputIdx + 1));
+// Remaining positional args are directories (strip flags and their values)
+const rawDirs = args.filter((a, i) =>
+  !a.startsWith('-') && (outputIdx === -1 || i !== outputIdx + 1)
+);
 
+// No directories given → launch interactive picker
+let dirs;
 if (rawDirs.length === 0) {
-  console.error('❌ At least one directory is required');
-  process.exit(1);
-}
-
-// Validate directories exist
-const dirs = [];
-for (const d of rawDirs) {
-  const resolved = resolve(d);
-  if (!fsExists(resolved)) {
-    console.error(`❌ Directory not found: ${d}`);
-    process.exit(1);
+  const { pickDirectories } = await import('../src/picker.js');
+  dirs = await pickDirectories();
+  console.log('');
+} else {
+  // Validate provided directories exist
+  dirs = [];
+  for (const d of rawDirs) {
+    const resolved = resolve(d);
+    if (!fsExists(resolved)) {
+      console.error(`❌ Directory not found: ${d}`);
+      process.exit(1);
+    }
+    dirs.push(resolved);
   }
-  dirs.push(resolved);
 }
 
 console.log(`\n👻 css-ghost scanning ${dirs.length} director${dirs.length === 1 ? 'y' : 'ies'}...`);
@@ -65,4 +109,40 @@ if (results.length === 0) {
   process.exit(0);
 }
 
-generateReport(results, outputPath);
+// Ghost trail — fetch git history for each orphan (opt-in, runs before report)
+if (ghostTrail) {
+  const { isGitRepo, getGhostTrails } = await import('../src/git.js');
+  if (!isGitRepo(process.cwd())) {
+    console.warn('⚠️  --ghost-trail: not a git repository — skipping git history.\n');
+  } else {
+    const totalOrphans = results.reduce(
+      (n, r) => n + r.orphaned.length + (r.orphanedVars?.length ?? 0), 0
+    );
+    if (totalOrphans > 0) {
+      process.stdout.write(`🔍 Fetching git history for ${totalOrphans} orphan${totalOrphans !== 1 ? 's' : ''}...`);
+      for (const result of results) {
+        if (result.orphaned.length > 0) {
+          result.trails = await getGhostTrails(result.orphaned, process.cwd());
+        }
+        if ((result.orphanedVars?.length ?? 0) > 0) {
+          result.varTrails = await getGhostTrails(result.orphanedVars, process.cwd(), { isVar: true });
+        }
+      }
+      process.stdout.write(' done\n\n');
+    }
+  }
+}
+
+// Get AI summary before writing report (so it can be included in the .md)
+const aiSummary = useAi ? await getAiSummary(results) : null;
+
+const { totalAllOrphans } = generateReport(results, outputPath, aiSummary);
+
+if (doDelete) {
+  await deleteOrphans(results, { yes: skipConfirm });
+}
+
+// --strict: exit 1 if any orphans were found (for CI / pre-commit hooks)
+if (strict && totalAllOrphans > 0) {
+  process.exit(1);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rolandjlevy/css-ghost",
-  "version": "1.0.2",
+  "version": "2.0.0",
   "description": "Find orphaned CSS class selectors in your codebase",
   "type": "module",
   "bin": {
@@ -8,12 +8,17 @@
   },
   "scripts": {
     "start": "node bin/css-ghost.js",
-    "scan": "node bin/css-ghost.js ./test"
+    "scan": "node bin/css-ghost.js ./test",
+    "scan:trail": "node bin/css-ghost.js ./test --ghost-trail",
+    "delete": "node bin/css-ghost.js ./test --delete",
+    "delete:yes": "node bin/css-ghost.js ./test --delete --yes",
+    "setup": "node bin/css-ghost.js --setup"
   },
   "files": [
     "bin",
     "src",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   "keywords": [
     "css",
@@ -36,5 +41,8 @@
   "homepage": "https://github.com/rolandjlevy/css-ghost#readme",
   "engines": {
     "node": ">=18"
+  },
+  "dependencies": {
+    "picocolors": "^1.1.1"
   }
 }

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;
+}