@rolandjlevy/css-ghost 1.1.3 → 1.3.0

package/CHANGELOG.md

@@ -0,0 +1,64 @@
+# Changelog
+
+All notable changes to `@rolandjlevy/css-ghost` are documented here.
+
+---
+
+## [1.3.0] — 2026-10-17
+
+### Added
+
+- **Programmatic API** (`src/index.js`) — `scan()` and `generateReport()` are now exposed as the package's public entry point via the `exports` field. Other tools and build plugins can now depend on css-ghost directly.
+- **TypeScript types** (`index.d.ts`) — hand-authored declarations for `ScanResult`, `OrphanedItem`, `GhostTrail`, and `ReportTotals`; no `@types/` package needed.
+- **GitHub Actions CI** (`.github/workflows/ci.yml`) — runs the smoke test suite on Node 18, 20 and 22 on every push and pull request.
+- **Smoke test runner** (`test/run.js`) — `npm test` now runs `scan()` against all 13 fixture directories and asserts result shapes; 13/13 pass.
+- **README badges** — npm version, monthly downloads, CI status, Node version and licence badge at the top of the README.
+- **Programmatic API docs** — new README section with install instructions, usage example, and TypeScript note.
+- **Keywords expanded** — added `vite`, `webpack`, `postcss`, `css-variables`, `vanilla-extract`, `orphaned-selectors` for better npm discovery.
+
+---
+
+## [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

@@ -1,5 +1,11 @@
 # 👻 css-ghost
 
+[![npm version](https://img.shields.io/npm/v/@rolandjlevy/css-ghost.svg)](https://www.npmjs.com/package/@rolandjlevy/css-ghost)
+[![npm downloads](https://img.shields.io/npm/dm/@rolandjlevy/css-ghost.svg)](https://www.npmjs.com/package/@rolandjlevy/css-ghost)
+[![CI](https://github.com/rolandjlevy/css-ghost/actions/workflows/ci.yml/badge.svg)](https://github.com/rolandjlevy/css-ghost/actions/workflows/ci.yml)
+[![Node.js >=18](https://img.shields.io/node/v/@rolandjlevy/css-ghost.svg)](https://nodejs.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
 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
@@ -8,9 +14,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 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; }
+```
 
-**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.
+---
 
 ## How is this different from PurgeCSS?
 
@@ -140,6 +164,34 @@ css-ghost ./src --ai                   # with AI summary
 css-ghost ./src --output ./reports/audit.md
 ```
 
+## Programmatic API
+
+Use css-ghost as a library inside your own build tools, Vite plugins, or scripts:
+
+```bash
+npm install @rolandjlevy/css-ghost
+```
+
+```js
+import { scan, generateReport } from '@rolandjlevy/css-ghost';
+import { resolve } from 'path';
+
+// Scan one or more directories
+const results = scan([resolve(process.cwd(), 'src')]);
+
+// Optional: write a Markdown report and get the orphan totals
+const { totalAllOrphans } = generateReport(results, 'orphan-report.md');
+
+// Use in CI: fail the build if any orphans are found
+if (totalAllOrphans > 0) process.exit(1);
+```
+
+TypeScript types are included — no `@types/` package needed.
+
+**`scan(dirs: string[])`** — returns a `ScanResult[]` array, one entry per style file. Each entry includes `filePath`, `orphaned` selectors, `orphanedVars` (CSS custom properties), `hasDynamic` flag, and more.
+
+**`generateReport(results, outputPath?, aiSummary?)`** — writes a Markdown report and prints a colour summary to the terminal. Returns `{ totalOrphaned, totalVarsOrphaned, totalAllOrphans }`.
+
 ## Using with npm scripts
 
 ```json

package/index.d.ts

@@ -0,0 +1,108 @@
+/**
+ * TypeScript declarations for @rolandjlevy/css-ghost
+ * Import from the package root to get `scan` and `generateReport`.
+ */
+
+/** A single orphaned class selector or CSS variable. */
+export interface OrphanedItem {
+  /** The selector name (without leading `.`) or CSS variable name (with `--` prefix). */
+  name: string;
+  /** Line number in the source style file. */
+  line: number;
+  /** The raw CSS rule text, if available. */
+  rule?: string;
+}
+
+/** Git blame info for a single orphaned item (--ghost-trail mode). */
+export interface GhostTrail {
+  /** Short commit hash. */
+  hash: string;
+  /** Commit author name. */
+  author: string;
+  /** Human-readable date/time of the commit. */
+  when: string;
+  /** Commit subject line. */
+  subject: string;
+}
+
+/**
+ * Per-file result returned by `scan()`.
+ * One entry per style file processed.
+ */
+export interface ScanResult {
+  /** Absolute path to the style file. */
+  filePath: string;
+  /** Total number of class selectors defined in the file. */
+  total: number;
+  /** Class selectors that are defined but never referenced in component files. */
+  orphaned: OrphanedItem[];
+  /** CSS custom properties (`--foo`) defined but never used via `var()`. */
+  orphanedVars: OrphanedItem[];
+  /** Total number of CSS custom properties defined in the file. */
+  totalVars: number;
+  /**
+   * `true` when the co-located component files use dynamic class access
+   * (`styles[variable]`, template literals) — results may be incomplete.
+   */
+  hasDynamic: boolean;
+  /** Absolute paths of component files that contain dynamic class references. */
+  dynamicFiles: string[];
+  /**
+   * Ghost-trail git blame data for orphaned selectors, keyed by selector name.
+   * Only present when `--ghost-trail` is active or you call the git module directly.
+   */
+  trails?: Record<string, GhostTrail>;
+  /**
+   * Ghost-trail git blame data for orphaned CSS variables, keyed by variable name.
+   * Only present when `--ghost-trail` is active or you call the git module directly.
+   */
+  varTrails?: Record<string, GhostTrail>;
+}
+
+/** Totals returned by `generateReport()`. Useful for CI / strict-mode checks. */
+export interface ReportTotals {
+  /** Number of orphaned class selectors across all scanned files. */
+  totalOrphaned: number;
+  /** Number of orphaned CSS variables across all scanned files. */
+  totalVarsOrphaned: number;
+  /** Sum of `totalOrphaned` and `totalVarsOrphaned`. */
+  totalAllOrphans: number;
+}
+
+/**
+ * Scan one or more directories for orphaned CSS selectors and CSS custom properties.
+ *
+ * @param dirs - Absolute paths to the directories you want to scan.
+ * @returns An array of per-file results — one entry per style file found.
+ *
+ * @example
+ * import { scan } from '@rolandjlevy/css-ghost';
+ * import { resolve } from 'path';
+ *
+ * const results = scan([resolve(process.cwd(), 'src')]);
+ * const totalOrphans = results.reduce((n, r) => n + r.orphaned.length + r.orphanedVars.length, 0);
+ * console.log(`Found ${totalOrphans} orphan(s).`);
+ */
+export function scan(dirs: string[]): ScanResult[];
+
+/**
+ * Generate a Markdown report file and print a summary to stdout.
+ *
+ * @param results   - Output from `scan()`.
+ * @param outputPath - Where to write the `.md` report. Defaults to `'orphan-report.md'`.
+ * @param aiSummary - Optional AI-generated summary string to embed in the report.
+ * @returns Totals you can use for CI gates or `--strict` mode.
+ *
+ * @example
+ * import { scan, generateReport } from '@rolandjlevy/css-ghost';
+ * import { resolve } from 'path';
+ *
+ * const results = scan([resolve(process.cwd(), 'src')]);
+ * const { totalAllOrphans } = generateReport(results, 'orphan-report.md');
+ * if (totalAllOrphans > 0) process.exit(1);
+ */
+export function generateReport(
+  results: ScanResult[],
+  outputPath?: string,
+  aiSummary?: string | null
+): ReportTotals;

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "@rolandjlevy/css-ghost",
-  "version": "1.1.3",
+  "version": "1.3.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",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "main": "./src/index.js",
+  "types": "./index.d.ts",
   "bin": {
     "css-ghost": "bin/css-ghost.js"
   },
@@ -12,18 +17,22 @@
     "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"
+    "setup": "node bin/css-ghost.js --setup",
+    "test": "node test/run.js"
   },
   "files": [
     "bin",
     "src",
+    "index.d.ts",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "keywords": [
     "css",
     "unused",
     "orphan",
+    "orphaned-selectors",
     "selectors",
     "dead-code",
     "cleanup",
@@ -32,20 +41,29 @@
     "audit",
     "tree-shaking",
     "custom-properties",
+    "css-variables",
     "react",
     "vue",
     "svelte",
     "scss",
     "css-modules",
-    "purgecss"
+    "purgecss",
+    "vite",
+    "webpack",
+    "postcss",
+    "vanilla-extract",
+    "style-audit"
   ],
   "author": "Roland Levy",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/rolandjlevy/css-ghost.git"
+    "url": "git+https://github.com/rolandjlevy/css-ghost.git"
   },
   "homepage": "https://github.com/rolandjlevy/css-ghost#readme",
+  "bugs": {
+    "url": "https://github.com/rolandjlevy/css-ghost/issues"
+  },
   "engines": {
     "node": ">=18"
   },

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/index.js

@@ -0,0 +1,16 @@
+/**
+ * @rolandjlevy/css-ghost — Programmatic API
+ *
+ * Use this when integrating css-ghost into build tools, scripts, or plugins
+ * rather than running it as a CLI.
+ *
+ * @example
+ * import { scan, generateReport } from '@rolandjlevy/css-ghost';
+ *
+ * const results = scan(['/absolute/path/to/src']);
+ * const { totalAllOrphans } = generateReport(results, 'orphan-report.md');
+ * if (totalAllOrphans > 0) process.exit(1);
+ */
+
+export { scan } from './scanner.js';
+export { generateReport } from './reporter.js';

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) {