@rolandjlevy/css-ghost 1.1.3 → 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+All notable changes to `@rolandjlevy/css-ghost` are documented here.
+
+---
+
+## [1.2.0] — 2026-10-17
+
+### Fixed
+
+- **SASS indented syntax** (`src/parser.js`) — `.sass` files previously returned 0 selectors because the parser required `{` to open a rule block. A new `extractSassIndentedSelectors()` branch parses the indentation-based syntax correctly, detecting top-level class selectors and collecting their rule bodies from the indented lines that follow.
+
+- **Vue and Svelte components not scanned** (`src/walker.js`) — `.vue` and `.svelte` files were excluded from the component walk, causing all selectors used only in Vue SFCs or Svelte components to appear as false positives. Both extensions are now included in `COMPONENT_EXTENSIONS`.
+
+- **`hasDynamic` flag contaminating unrelated files** (`src/scanner.js`) — when any component anywhere in the scan used `styles[variable]` or a template literal, every style file in the entire scan was tagged `hasDynamic: true`. The flag and the `dynamicFiles` list are now scoped to style files that share a directory with the dynamic component.
+
+- **Terminal output missing dynamic warning** (`src/reporter.js`) — the `⚠️ Dynamic class references detected` message appeared in the Markdown report but not in the terminal output. The warning now appears inline per file in the terminal, matching the Markdown behaviour.
+
+### Added
+
+- Comprehensive CLI test fixtures under `test/` covering all documented use-cases: SCSS, LESS, SASS indented syntax, React Native `StyleSheet.create()`, dynamic class access, hyphenated selectors, `clsx` (strings/objects/arrays), Vue SFC `:class` bindings, and Svelte `class:name` directives.
+
+---
+
+## [1.1.3] — 2026-10-16
+
+- Internal release; no public changelog entry.
+
+---
+
+## [1.1.0] — 2026-10-01
+
+### Added
+
+- `--ghost-trail` flag: shows the last git commit that touched each orphaned selector
+- `--ai` flag: appends an AI-generated summary via OpenRouter (run `--setup` once to save your key)
+- CSS custom property orphan detection (`--my-token` defined but never consumed via `var(--my-token)`)
+- `--install-hook` flag: writes a pre-commit hook that blocks commits when orphans are present
+
+---
+
+## [1.0.0] — 2026-09-01
+
+### Initial release
+
+- CSS selector orphan detection across `.css`, `.module.css`, `.scss`, `.sass`, `.less`, and JS style files (`StyleSheet.create`, `makeStyles`, vanilla-extract)
+- `--delete` / `--delete --yes` to remove orphaned selectors from source files
+- `--strict` flag for CI (exit code 1 when any orphans found)
+- `--output <file>` for custom Markdown report paths
+- Interactive folder picker when run with no arguments

package/README.md

@@ -8,9 +8,27 @@ Scans one or more directories for style files, extracts every class selector def
 
 **Supported style files:** `.css`, `.module.css`, `.scss`, `.sass`, `.less`, `.js`/`.ts` using `StyleSheet.create({})` / `makeStyles({})` (MUI), `.css.ts`/`.css.js` using `style()` or `styleVariants()` (vanilla-extract)
 
-**Detected usage patterns:** `className="foo"`, `className={styles.foo}`, `styles['foo']`, ternary patterns, `cx()` / `clsx()` / `classnames()` (strings, objects and arrays), `classes.foo` (MUI), vanilla-extract named imports
+**Detected usage patterns:** `className="foo"`, `className={styles.foo}`, `styles['foo']`, ternary patterns, `cx()` / `clsx()` / `classnames()` (strings, objects and arrays), `classes.foo` (MUI), vanilla-extract named imports, Vue `:class` bindings, Svelte `class:name` directives
 
-**Dynamic class detection:** Patterns where the class name can't be resolved statically — `styles[variable]` or template literals with `${}` — are flagged with a ⚠️ warning instead of being reported as orphans.
+**Dynamic class detection:** Patterns where the class name can't be resolved statically — `styles[variable]` or template literals with `${}` — are flagged with a ⚠️ warning per file in both the terminal output and the Markdown report.
+
+## Example output
+
+![css-ghost demo](./docs/demo.gif)
+
+When a component uses dynamic class access (`styles[variant]`), the file is flagged rather than reporting false positives:
+
+```
+✅ src/components/alert.module.css
+
+   ⚠️  Dynamic class references detected — results may be incomplete.
+   Dynamic references in: src/components/Alert.jsx
+
+   👻 .hidden (line 30)
+      .hidden { display: none; }
+```
+
+---
 
 ## How is this different from PurgeCSS?
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rolandjlevy/css-ghost",
-  "version": "1.1.3",
+  "version": "1.2.0",
   "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": {
@@ -18,6 +18,7 @@
     "bin",
     "src",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "keywords": [

package/src/deleter.js

@@ -36,10 +36,42 @@ function findBlockEnd(lines, startIdx) {
 
 // ─── CSS / SCSS / LESS ───────────────────────────────────────────────────────
 
-function deleteFromCssFile(filePath, orphans) {
+// Return the start index of a comment block (/* ... */) that sits immediately
+// before `idx` in `content` (separated only by whitespace/newlines), or -1.
+function findPrecedingComment(content, idx) {
+  // Walk backwards over whitespace
+  let i = idx - 1;
+  while (i >= 0 && /[\s]/.test(content[i])) i--;
+
+  if (i < 1 || content[i] !== '/' || content[i - 1] !== '*') return -1;
+
+  // Found the end of a block comment — now find its start
+  const closePos = i - 1; // position of '*/'  second char
+  const openPos = content.lastIndexOf('/*', closePos);
+  return openPos === -1 ? -1 : openPos;
+}
+
+// Delete individual CSS declarations (e.g. `  --token: value;\n`) from content.
+function deleteCssDeclarations(content, varNames) {
+  let removed = 0;
+  for (const name of varNames) {
+    // Match `  --name: anything up to semicolon;\n?` including leading whitespace
+    const re = new RegExp(`[ \\t]*${escapeRegex(name)}\\s*:[^;]*;[ \\t]*\\n?`, 'g');
+    const next = content.replace(re, () => { removed++; return ''; });
+    if (next !== content) content = next;
+  }
+  return { content, removed };
+}
+
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function deleteFromCssFile(filePath, orphans, orphanedVarNames = []) {
   let content = readFileSync(filePath, 'utf-8');
   let removed = 0;
 
+  // ── 1. Delete orphaned class/selector rules ────────────────────────────────
   // Sort longest rules first so that nested/contained rules don't mis-match.
   const sorted = [...orphans].sort((a, b) => (b.rule?.length ?? 0) - (a.rule?.length ?? 0));
 
@@ -48,13 +80,24 @@ function deleteFromCssFile(filePath, orphans) {
     const idx = content.indexOf(rule);
     if (idx === -1) continue;
 
-    const before = content.slice(0, idx);
+    // Bug fix: also remove a comment block immediately preceding the rule.
+    const commentStart = findPrecedingComment(content, idx);
+    const deleteFrom   = commentStart !== -1 ? commentStart : idx;
+
+    const before = content.slice(0, deleteFrom);
     const after  = content.slice(idx + rule.length);
     // Eat one trailing newline so we don't leave double-blank-lines everywhere.
     content = before + after.replace(/^\n/, '');
     removed++;
   }
 
+  // ── 2. Delete orphaned CSS variable declarations ───────────────────────────
+  if (orphanedVarNames.length > 0) {
+    const { content: next, removed: varRemoved } = deleteCssDeclarations(content, orphanedVarNames);
+    content = next;
+    removed += varRemoved;
+  }
+
   writeFileSync(filePath, normalise(content), 'utf-8');
   return removed;
 }
@@ -110,23 +153,27 @@ function deleteFromVeFile(filePath, orphans) {
 // ─── Public API ──────────────────────────────────────────────────────────────
 
 export async function deleteOrphans(results, { yes = false } = {}) {
-  const toDelete = results.filter(r => r.orphaned.length > 0);
+  // A file is eligible for deletion if it has orphaned selectors OR orphaned vars.
+  const toDelete = results.filter(r => r.orphaned.length > 0 || (r.orphanedVars?.length ?? 0) > 0);
 
   if (toDelete.length === 0) {
     console.log('Nothing to delete.\n');
     return 0;
   }
 
-  const totalCount = toDelete.reduce((n, r) => n + r.orphaned.length, 0);
-
   console.log(
-    `\n${pc.bold('🗑️  The following orphaned selectors will be permanently deleted:')}\n`
+    `\n${pc.bold('🗑️  The following orphaned selectors and CSS variables will be permanently deleted:')}\n`
   );
 
-  for (const { filePath, orphaned } of toDelete) {
+  for (const { filePath, orphaned, orphanedVars } of toDelete) {
     const rel = relative(process.cwd(), filePath);
     console.log(`  ${pc.bold(rel)}`);
-    orphaned.forEach(o => console.log(`    ${pc.yellow('•')} .${o.name} ${pc.dim(`(line ${o.line})`)}`));
+    orphaned.forEach(o =>
+      console.log(`    ${pc.yellow('•')} .${o.name} ${pc.dim(`(line ${o.line})`)}`)
+    );
+    (orphanedVars ?? []).forEach(o =>
+      console.log(`    ${pc.magenta('•')} ${o.name} ${pc.dim(`(line ${o.line})`)}`)
+    );
   }
 
   if (!yes) {
@@ -142,25 +189,27 @@ export async function deleteOrphans(results, { yes = false } = {}) {
   console.log('');
   let totalRemoved = 0;
 
-  for (const { filePath, orphaned } of toDelete) {
-    const ext    = extname(filePath);
-    const rel    = relative(process.cwd(), filePath);
+  for (const { filePath, orphaned, orphanedVars } of toDelete) {
+    const ext         = extname(filePath);
+    const rel         = relative(process.cwd(), filePath);
+    const varNames    = (orphanedVars ?? []).map(v => v.name);
+    const totalExpected = orphaned.length + varNames.length;
     let removed;
 
     try {
       if (['.css', '.scss', '.sass', '.less'].includes(ext)) {
-        removed = deleteFromCssFile(filePath, orphaned);
+        removed = deleteFromCssFile(filePath, orphaned, varNames);
       } else if (/\.css\.(ts|js)x?$/.test(filePath)) {
         removed = deleteFromVeFile(filePath, orphaned);
       } else {
         removed = deleteFromJsFile(filePath, orphaned);
       }
 
-      const label = removed === orphaned.length
+      const label = removed === totalExpected
         ? pc.green(`✂️  ${rel}`)
         : pc.yellow(`✂️  ${rel}`);
-      const note  = removed < orphaned.length
-        ? pc.dim(` (${orphaned.length - removed} could not be located — check manually)`)
+      const note  = removed < totalExpected
+        ? pc.dim(` (${totalExpected - removed} could not be located — check manually)`)
         : '';
       console.log(`${label} — removed ${removed}${note}`);
       totalRemoved += removed;
@@ -169,8 +218,9 @@ export async function deleteOrphans(results, { yes = false } = {}) {
     }
   }
 
+  const noun = totalRemoved === 1 ? 'item' : 'items';
   console.log(
-    `\n${pc.green(pc.bold(`✅ Done.`))} Removed ${totalRemoved} orphaned selector${totalRemoved !== 1 ? 's' : ''}.\n`
+    `\n${pc.green(pc.bold(`✅ Done.`))} Removed ${totalRemoved} orphaned ${noun}.\n`
   );
 
   return totalRemoved;

package/src/parser.js

@@ -53,6 +53,58 @@ export function extractVarUsages(content) {
 
 // ─── CSS / SCSS selector extraction ────────────────────────────────────────
 
+/**
+ * Parse SASS indented syntax (.sass) — no braces, indentation defines blocks.
+ * Class selectors appear at the start of a line (after optional whitespace),
+ * followed by indented property lines.
+ */
+function extractSassIndentedSelectors(content) {
+  const selectors = new Map();
+  const lines = content.split('\n');
+
+  // Strip // single-line comments (SASS uses // as well as /* */)
+  const stripped = content
+    .replace(/\/\*[\s\S]*?\*\//g, m => m.replace(/[^\n]/g, ' '))
+    .split('\n')
+    .map(l => l.replace(/\/\/.*$/, ''));
+
+  let i = 0;
+  while (i < stripped.length) {
+    const raw = stripped[i];
+    const trimmed = raw.trimStart();
+    const indent = raw.length - trimmed.length;
+
+    // A class selector: zero or shallow indent, starts with "."
+    if (indent === 0 && trimmed.startsWith('.')) {
+      const m = trimmed.match(/^\.([a-zA-Z_-][a-zA-Z0-9_-]*)/);
+      if (m) {
+        const name = m[1];
+        const lineNum = i + 1;
+        // Collect the rule block: this line + indented lines that follow
+        const ruleLines = [lines[i]];
+        let j = i + 1;
+        while (j < lines.length) {
+          const nextRaw = stripped[j];
+          if (nextRaw.trim() === '') { j++; continue; }
+          const nextIndent = nextRaw.length - nextRaw.trimStart().length;
+          if (nextIndent > indent) {
+            ruleLines.push(lines[j]);
+            j++;
+          } else {
+            break;
+          }
+        }
+        if (!selectors.has(name)) {
+          selectors.set(name, { line: lineNum, rule: ruleLines.join('\n').trim() });
+        }
+      }
+    }
+    i++;
+  }
+
+  return selectors;
+}
+
 function extractCssSelectors(content) {
   const selectors = new Map(); // name → { line, rule }
   const lines = content.split('\n');
@@ -324,7 +376,7 @@ export function parseStyleFile(filePath) {
   const content = readFileSync(filePath, 'utf-8');
   const ext = extname(filePath);
 
-  if (['.css', '.scss', '.sass', '.less'].includes(ext)) {
+  if (['.css', '.scss', '.less'].includes(ext)) {
     return {
       selectors: extractCssSelectors(content),
       cssVars:   extractCssVarDefinitions(content),
@@ -333,6 +385,16 @@ export function parseStyleFile(filePath) {
     };
   }
 
+  // SASS indented syntax — no braces; needs its own parser branch
+  if (ext === '.sass') {
+    return {
+      selectors: extractSassIndentedSelectors(content),
+      cssVars:   extractCssVarDefinitions(content),
+      varUsages: extractVarUsages(content),
+      hasDynamic: false,
+    };
+  }
+
   // JS/TS style file — CSS custom properties are not typically defined here
   const selectors = extractJsStyleKeys(content);
   return { selectors, cssVars: new Map(), varUsages: new Set(), hasDynamic: false };

package/src/reporter.js

@@ -197,7 +197,7 @@ export function generateReport(results, outputPath = 'orphan-report.md', aiSumma
   }
 
   for (const result of results) {
-    const { orphaned, orphanedVars = [], trails, varTrails } = result;
+    const { orphaned, orphanedVars = [], trails, varTrails, hasDynamic, dynamicFiles } = result;
     if (orphaned.length === 0 && orphanedVars.length === 0) continue;
 
     const relPath = relative(process.cwd(), result.filePath);
@@ -207,6 +207,17 @@ export function generateReport(results, outputPath = 'orphan-report.md', aiSumma
       : '';
     console.log(`✅ ${pc.bold(relPath)}${savingsSuffix}\n`);
 
+    if (hasDynamic) {
+      console.log(`   ${pc.yellow('⚠️  Dynamic class references detected — results may be incomplete.')}`);
+      if (dynamicFiles?.length > 0) {
+        const relDynamic = dynamicFiles
+          .map(f => `${relative(process.cwd(), f)}`)
+          .join(', ');
+        console.log(pc.dim(`   Dynamic references in: ${relDynamic}`));
+      }
+      console.log('');
+    }
+
     orphaned.forEach(({ name, line, rule }) => {
       console.log(`   👻 ${pc.yellow('.' + name)} ${pc.dim(`(line ${line})`)}`);
       const trail = trails?.[name];

package/src/scanner.js

@@ -1,5 +1,5 @@
 import { readFileSync } from 'fs';
-import { extname } from 'path';
+import { extname, dirname } from 'path';
 import { walkDir } from './walker.js';
 import { parseStyleFile, parseComponentFile, isJsStyleFile } from './parser.js';
 
@@ -75,6 +75,12 @@ export function scan(dirs) {
   }
 
   // ── PASS 3: Cross-reference and build results ─────────────────────────────
+  // Build a Set of directories that contain dynamic components, so we can
+  // scope the hasDynamic flag to style files that share a directory — rather
+  // than tagging every style file in the entire scan when just one component
+  // anywhere uses dynamic class access.
+  const dynamicDirs = new Set(dynamicComponentFiles.map(f => dirname(f)));
+
   const results = [];
 
   for (const styleFile of styleFiles) {
@@ -82,6 +88,13 @@ export function scan(dirs) {
     if (!parsed) continue;
 
     const { selectors, cssVars, hasDynamic } = parsed;
+    const styleDir = dirname(styleFile);
+
+    // Only the dynamic components co-located with this style file are relevant
+    const localDynamicFiles = dynamicComponentFiles.filter(
+      f => dirname(f) === styleDir
+    );
+    const localHasDynamic = hasDynamic || dynamicDirs.has(styleDir);
 
     // Orphaned class selectors
     const orphaned = [...selectors.entries()]
@@ -101,8 +114,8 @@ export function scan(dirs) {
       orphaned,
       orphanedVars,
       totalVars: cssVars?.size ?? 0,
-      hasDynamic: hasDynamic || dynamicComponentFiles.length > 0,
-      dynamicFiles: dynamicComponentFiles,
+      hasDynamic: localHasDynamic,
+      dynamicFiles: localDynamicFiles,
     });
   }
 

package/src/walker.js

@@ -2,7 +2,7 @@ import { readdirSync } from 'fs';
 import { join, extname, basename } from 'path';
 
 const STYLE_EXTENSIONS = ['.css', '.scss', '.sass', '.less'];
-const COMPONENT_EXTENSIONS = new Set(['.js', '.jsx', '.ts', '.tsx']);
+const COMPONENT_EXTENSIONS = new Set(['.js', '.jsx', '.ts', '.tsx', '.vue', '.svelte']);
 const IGNORE_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.next', 'out', 'coverage', '.cache']);
 
 export function walkDir(dir) {