@rolandjlevy/css-ghost 1.0.4 → 1.1.2

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

@@ -1,16 +1,19 @@
 # 👻 css-ghost
 
-Find orphaned CSS class selectors in your codebase — defined in style files but never referenced in your components.
+Find and remove unused CSS selectors and orphaned CSS custom properties — selectors defined in your style files but never referenced in your components, across React, Vue, Svelte, SCSS, and CSS Modules
 
 ## 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 — 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']`
@@ -18,10 +21,37 @@ Scans one or more directories for style files, extracts every class selector def
 - `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:**
 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.
 
+## How is this different from PurgeCSS?
+
+[PurgeCSS](https://www.npmjs.com/package/purgecss) is a **build-time bundler** — it hooks into webpack, PostCSS, or Gulp to strip unused CSS from your production output. It's designed for removing large framework utility classes (Bootstrap, Tailwind) that you never use.
+
+css-ghost is a **source code auditor** — it finds dead selectors in your actual codebase, with no build step and no config file required. Just point it at a folder:
+
+```bash
+npx @rolandjlevy/css-ghost ./src
+```
+
+| | PurgeCSS | css-ghost |
+|---|---|---|
+| Works on source files | ❌ Build output only | ✅ |
+| Zero config, no build step | ❌ Requires webpack / PostCSS | ✅ |
+| CSS custom property orphans | ❌ | ✅ |
+| Git history per orphan | ❌ | ✅ |
+| Pre-commit hook | ❌ | ✅ |
+| Deletes dead code for you | ❌ | ✅ |
+| MUI / vanilla-extract aware | ❌ | ✅ |
+| Safe with dynamic classes | ❌ Silently removes them | ✅ Flags with ⚠️ |
+
+The two tools are complementary: PurgeCSS for trimming framework output at build time; css-ghost for auditing your own hand-written CSS throughout development.
+
+---
+
 ## 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:
@@ -53,24 +83,177 @@ 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` |
-| `--ai` | Append an AI-generated summary (requires setup) | off |
-| `--setup` | Save your OpenRouter API key for `--ai` | — |
-| `-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
 
@@ -108,9 +291,11 @@ Running `css-ghost ./src` prints a live summary to your terminal:
       }
 
 📁 1 style file scanned
+💾 Potential savings: 3 selectors removed
 ```
 
 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
 
@@ -160,39 +345,58 @@ npm run scan
 npm run scan -- --output ./reports/audit.md
 ```
 
-## No dependencies
+## Troubleshooting
+
+### `css-ghost: command not found` after global install
 
-Built with Node.js built-ins only (`fs`, `path`). No npm packages required.
+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.):
+
+```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
+[MIT](./LICENSE)

package/bin/css-ghost.js

@@ -4,6 +4,7 @@ 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';
 
@@ -15,22 +16,44 @@ if (args.includes('--setup')) {
   process.exit(0);
 }
 
-if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
+// --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)
-  --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
+  --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
 `);
@@ -38,34 +61,41 @@ Examples:
 }
 
 // Parse flags
-const useAi = args.includes('--ai');
-const outputIdx = args.indexOf('--output');
-const outputPath = outputIdx !== -1 ? args[outputIdx + 1] : 'orphan-report.md';
+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 (strip flags and their values)
+// Remaining positional args are directories (strip flags and their values)
 const rawDirs = args.filter((a, i) =>
-  !a.startsWith('--') && (outputIdx === -1 || i !== outputIdx + 1)
+  !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'}...`);
@@ -79,7 +109,40 @@ if (results.length === 0) {
   process.exit(0);
 }
 
+// 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;
 
-generateReport(results, outputPath, aiSummary);
+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,7 +1,7 @@
 {
   "name": "@rolandjlevy/css-ghost",
-  "version": "1.0.4",
-  "description": "Find orphaned CSS class selectors in your codebase",
+  "version": "1.1.2",
+  "description": "Find and remove unused CSS selectors and orphaned CSS custom properties — a CLI linter and auditor for React, Vue, Svelte, SCSS, and CSS Modules",
   "type": "module",
   "bin": {
     "css-ghost": "bin/css-ghost.js"
@@ -9,24 +9,35 @@
   "scripts": {
     "start": "node bin/css-ghost.js",
     "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",
-    "orphan",
     "unused",
+    "orphan",
     "selectors",
+    "dead-code",
+    "cleanup",
     "cli",
     "linter",
+    "audit",
+    "tree-shaking",
+    "custom-properties",
     "react",
+    "vue",
+    "svelte",
     "scss",
-    "stylesheet",
-    "audit"
+    "css-modules",
+    "purgecss"
   ],
   "author": "Roland Levy",
   "license": "MIT",
@@ -37,5 +48,8 @@
   "homepage": "https://github.com/rolandjlevy/css-ghost#readme",
   "engines": {
     "node": ">=18"
+  },
+  "dependencies": {
+    "picocolors": "^1.1.1"
   }
 }