@rolandjlevy/css-ghost 0.0.0-stage → 1.0.1

package/README.md

@@ -1,3 +1,123 @@
-# Temporary Holding Version
+# 👻 css-ghost
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Find orphaned CSS class selectors in your codebase — defined in style files but never referenced in your components.
+
+## 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.
+
+**Supported style files:**
+- `.css`, `.module.css`, `.scss`, `.sass`, `.less`
+- `.js` / `.ts` files using `StyleSheet.create({})` or named style objects
+
+**Detected usage patterns:**
+- `className="foo"`
+- `className={styles.foo}`
+- `styles['foo']`
+- `cx('foo')`, `clsx('foo')`, `classnames('foo')`
+
+**Dynamic class detection:**
+Files containing `styles[variable]` or template literal class names are flagged with a ⚠️ warning — results for those files may be incomplete.
+
+## Install
+
+```bash
+npm install -g css-ghost
+```
+
+Or run directly without installing:
+
+```bash
+npx css-ghost ./src
+```
+
+## Usage
+
+```bash
+css-ghost <directory> [directory2] ... [options]
+```
+
+**Options:**
+
+| Flag | Description | Default |
+| --- | --- | --- |
+| `--output <file>` | Output report file path | `orphan-report.md` |
+| `-h, --help` | Show help | — |
+
+## Examples
+
+```bash
+# Scan a single directory
+css-ghost ./src
+
+# Scan multiple directories
+css-ghost ./src ./components ./pages
+
+# Custom output path
+css-ghost ./src --output ./reports/css-audit.md
+```
+
+## Output
+
+Generates a markdown report (`orphan-report.md` by default):
+
+---
+
+# 👻 css-ghost — Orphaned Selector Report
+
+## Summary
+| Metric | Value |
+| --- | --- |
+| Style files scanned | 12 |
+| Total selectors defined | 84 |
+| Total orphaned selectors | 7 |
+| Files with orphans | 3 |
+| Overall unused rate | 8% |
+
+## `src/components/Button/Button.module.css`
+| Defined | Orphaned | Unused % |
+| --- | --- | --- |
+| 6 | 2 | 33% |
+
+**Orphaned selectors:**
+- `.iconLeft`
+- `.loadingSpinner`
+
+---
+
+## No dependencies
+
+Built with Node.js built-ins only (`fs`, `path`). No npm packages required.
+
+## 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
+
+Get a free API key at [openrouter.ai/keys](https://openrouter.ai/keys), then add these aliases to your `~/.zshrc`:
+
+```bash
+# Store your key once
+export OPENROUTER_API_KEY="sk-or-v1-YOUR_KEY"
+
+# Llama 3.3 70B — fast, capable, free
+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"'
+
+# 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"'
+```
+
+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.
+
+## License
+
+MIT

package/bin/css-ghost.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+
+import { resolve } from 'path';
+import { existsSync as fsExists } from 'fs';
+import { scan } from '../src/scanner.js';
+import { generateReport } from '../src/reporter.js';
+
+const args = process.argv.slice(2);
+
+if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
+  console.log(`
+👻 css-ghost — Find orphaned CSS class selectors
+
+Usage:
+  css-ghost <directory> [directory2] ... [options]
+
+Options:
+  --output <file>   Output report file path (default: orphan-report.md)
+  -h, --help        Show this help message
+
+Examples:
+  css-ghost ./src
+  css-ghost ./src ./components
+  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';
+
+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));
+
+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);
+  }
+  dirs.push(resolved);
+}
+
+console.log(`\n👻 css-ghost scanning ${dirs.length} director${dirs.length === 1 ? 'y' : 'ies'}...`);
+dirs.forEach(d => console.log(`   📁 ${d}`));
+console.log('');
+
+const results = scan(dirs);
+
+if (results.length === 0) {
+  console.log('🔍 No style files found in the specified directories.\n');
+  process.exit(0);
+}
+
+generateReport(results, outputPath);

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@rolandjlevy/css-ghost",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "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"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "keywords": [
+    "css",
+    "orphan",
+    "unused",
+    "selectors",
+    "cli",
+    "linter",
+    "react",
+    "scss",
+    "stylesheet",
+    "audit"
+  ],
+  "author": "Roland Levy",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rolandjlevy/css-ghost.git"
+  },
+  "homepage": "https://github.com/rolandjlevy/css-ghost#readme",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/parser.js

@@ -0,0 +1,180 @@
+import { readFileSync } from 'fs';
+import { extname } from 'path';
+
+// ─── CSS / SCSS selector extraction ────────────────────────────────────────
+
+function extractCssSelectors(content) {
+  const selectors = new Map(); // name → { line, rule }
+  const lines = content.split('\n');
+
+  // Strip block comments but preserve line numbers by replacing with spaces
+  const stripped = content.replace(/\/\*[\s\S]*?\*\//g, m =>
+    m.replace(/[^\n]/g, ' ')
+  );
+
+  // Walk line by line to track line numbers
+  const strippedLines = stripped.split('\n');
+  let insideRule = false;
+  let currentRule = [];
+  let currentSelectors = [];
+  let ruleStartLine = 0;
+
+  for (let i = 0; i < strippedLines.length; i++) {
+    const line = strippedLines[i];
+    const lineNum = i + 1;
+
+    if (!insideRule) {
+      // Look for .className optionally followed by { on same or next line
+      const selectorRegex = /\.([a-zA-Z_-][a-zA-Z0-9_-]*)/g;
+      let m;
+      while ((m = selectorRegex.exec(line)) !== null) {
+        currentSelectors.push({ name: m[1], line: lineNum });
+      }
+
+      if (line.includes('{')) {
+        insideRule = true;
+        ruleStartLine = lineNum;
+        currentRule = [lines[i]];
+
+        if (line.includes('}')) {
+          // Single-line rule
+          const ruleText = currentRule.join('\n').trim();
+          currentSelectors.forEach(({ name, line: l }) => {
+            if (!selectors.has(name)) {
+              selectors.set(name, { line: l, rule: ruleText });
+            }
+          });
+          currentSelectors = [];
+          currentRule = [];
+          insideRule = false;
+        }
+      } else if (currentSelectors.length > 0 && line.trim() === '') {
+        // Empty line with no { means these weren't selectors for a rule
+        currentSelectors = [];
+      }
+    } else {
+      currentRule.push(lines[i]);
+      if (line.includes('}')) {
+        const ruleText = currentRule.join('\n').trim();
+        currentSelectors.forEach(({ name, line: l }) => {
+          if (!selectors.has(name)) {
+            selectors.set(name, { line: l, rule: ruleText });
+          }
+        });
+        currentSelectors = [];
+        currentRule = [];
+        insideRule = false;
+      }
+    }
+  }
+
+  return selectors;
+}
+
+// ─── JS style file detection & key extraction ───────────────────────────────
+
+export function isJsStyleFile(content, filePath) {
+  return (
+    /StyleSheet\.create\s*\(\s*\{/.test(content) ||
+    (/styles?\.(js|ts)$/.test(filePath) && /(const|let|var)\s+styles?\s*=\s*\{/.test(content))
+  );
+}
+
+function extractJsStyleKeys(content) {
+  const keys = new Map(); // name → { line, rule }
+  const lines = content.split('\n');
+
+  const ssMatch = content.match(/StyleSheet\.create\s*\(\s*\{([\s\S]*?)\}\s*\)/);
+  const plainMatch = content.match(/(?:const|let|var)\s+styles?\s*=\s*\{([\s\S]*)\}/);
+  const objectContent = ssMatch?.[1] ?? plainMatch?.[1];
+
+  if (objectContent) {
+    // Find start offset in original content
+    const startOffset = content.indexOf(objectContent);
+    const preContent = content.slice(0, startOffset);
+    const startLine = preContent.split('\n').length;
+
+    const keyRegex = /^\s*([a-zA-Z_$][a-zA-Z0-9_$]*)\s*:/gm;
+    let m;
+    while ((m = keyRegex.exec(objectContent)) !== null) {
+      const keyLine = startLine + objectContent.slice(0, m.index).split('\n').length - 1;
+      const name = m[1];
+      if (!keys.has(name)) {
+        // Grab the value snippet for context
+        const lineText = lines[keyLine - 1]?.trim() ?? '';
+        keys.set(name, { line: keyLine, rule: lineText });
+      }
+    }
+  }
+
+  return keys;
+}
+
+// ─── Component file usage extraction ────────────────────────────────────────
+
+export function extractUsages(content) {
+  const used = new Set();
+  let hasDynamic = false;
+
+  // className="foo bar" or className='foo'
+  const directRegex = /className\s*=\s*["']([^"']+)["']/g;
+  let m;
+  while ((m = directRegex.exec(content)) !== null) {
+    m[1].trim().split(/\s+/).forEach(c => c && used.add(c));
+  }
+
+  // styles.foo
+  const dotRegex = /styles?\.([a-zA-Z_$][a-zA-Z0-9_$]*)/g;
+  while ((m = dotRegex.exec(content)) !== null) {
+    used.add(m[1]);
+  }
+
+  // styles['foo'] or styles["foo"]
+  const bracketStringRegex = /styles?\[['"]([a-zA-Z_$][a-zA-Z0-9_$]*)['"]]/g;
+  while ((m = bracketStringRegex.exec(content)) !== null) {
+    used.add(m[1]);
+  }
+
+  // styles[variable] — dynamic, flag it
+  if (/styles?\[(?!['"])/.test(content)) {
+    hasDynamic = true;
+  }
+
+  // cx('foo', 'bar') / clsx('foo') / classnames('foo')
+  const cxRegex = /(?:cx|clsx|classnames)\s*\(([^)]+)\)/g;
+  while ((m = cxRegex.exec(content)) !== null) {
+    const inner = m[1];
+    const strRegex = /['"]([a-zA-Z_-][a-zA-Z0-9_-]*)["']/g;
+    let sm;
+    while ((sm = strRegex.exec(inner)) !== null) {
+      used.add(sm[1]);
+    }
+  }
+
+  // Template literal dynamic class names
+  if (/`[^`]*\$\{[^}]+\}[^`]*`/.test(content)) {
+    hasDynamic = true;
+  }
+
+  return { used, hasDynamic };
+}
+
+// ─── Public API ─────────────────────────────────────────────────────────────
+
+export function parseStyleFile(filePath) {
+  const content = readFileSync(filePath, 'utf-8');
+  const ext = extname(filePath);
+
+  if (['.css', '.scss', '.sass', '.less'].includes(ext)) {
+    return { selectors: extractCssSelectors(content), hasDynamic: false };
+  }
+
+  // JS/TS style file
+  const selectors = extractJsStyleKeys(content);
+  return { selectors, hasDynamic: false };
+}
+
+export function parseComponentFile(filePath) {
+  const content = readFileSync(filePath, 'utf-8');
+  return extractUsages(content);
+}

package/src/reporter.js

@@ -0,0 +1,110 @@
+import { writeFileSync } from 'fs';
+import { relative } from 'path';
+
+export function generateReport(results, outputPath = 'orphan-report.md') {
+  let totalDefined = 0;
+  let totalOrphaned = 0;
+  let filesWithOrphans = 0;
+
+  const sections = [];
+
+  for (const result of results) {
+    const { filePath, orphaned, total, hasDynamic, dynamicFiles } = result;
+    totalDefined += total;
+    totalOrphaned += orphaned.length;
+
+    const hasOrphans = orphaned.length > 0;
+    if (hasOrphans) filesWithOrphans++;
+
+    // Skip files with nothing to report
+    if (!hasOrphans && !hasDynamic) continue;
+
+    const relPath = relative(process.cwd(), filePath);
+    const pct = total > 0 ? Math.round((orphaned.length / total) * 100) : 0;
+
+    const lines = [
+      `## \`${relPath}\``,
+      '',
+      `| Defined | Orphaned | Unused % |`,
+      `| --- | --- | --- |`,
+      `| ${total} | ${orphaned.length} | ${pct}% |`,
+      '',
+    ];
+
+    if (hasDynamic) {
+      lines.push(`> ⚠️ **Dynamic class references detected** — results may be incomplete.`);
+      if (dynamicFiles?.length > 0) {
+        const relDynamic = dynamicFiles
+          .map(f => `\`${relative(process.cwd(), f)}\``)
+          .join(', ');
+        lines.push(`> Dynamic references found in: ${relDynamic}`);
+      }
+      lines.push('');
+    }
+
+    if (hasOrphans) {
+      lines.push('### 👻 Orphaned selectors\n');
+
+      orphaned.forEach(({ name, line, rule }) => {
+        lines.push(`#### \`.${name}\` — line ${line}`);
+        lines.push('');
+        if (rule) {
+          lines.push('```css');
+          lines.push(rule);
+          lines.push('```');
+        }
+        lines.push('');
+      });
+    }
+
+    lines.push('---');
+    lines.push('');
+    sections.push(lines.join('\n'));
+  }
+
+  const unusedPct = totalDefined > 0
+    ? Math.round((totalOrphaned / totalDefined) * 100)
+    : 0;
+
+  const summary = [
+    '# 👻 css-ghost — Orphaned Selector Report',
+    '',
+    `_Generated: ${new Date().toUTCString()}_`,
+    '',
+    '## Summary',
+    '',
+    `| Metric | Value |`,
+    `| --- | --- |`,
+    `| Style files scanned | ${results.length} |`,
+    `| Total selectors defined | ${totalDefined} |`,
+    `| Total orphaned selectors | ${totalOrphaned} |`,
+    `| Files with orphans | ${filesWithOrphans} |`,
+    `| Overall unused rate | ${unusedPct}% |`,
+    '',
+    '---',
+    '',
+  ].join('\n');
+
+  const content = summary + 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`);
+
+  for (const result of results) {
+    if (result.orphaned.length === 0) continue;
+    const relPath = relative(process.cwd(), result.filePath);
+    console.log(`📄 ${relPath}`);
+    result.orphaned.forEach(({ name, line, rule }) => {
+      console.log(`   👻 .${name} (line ${line})`);
+      if (rule) {
+        const preview = rule.split('\n').slice(0, 4).join('\n');
+        console.log(preview.split('\n').map(l => `      ${l}`).join('\n'));
+      }
+      console.log('');
+    });
+  }
+
+  console.log(`📁 ${results.length} style file${results.length !== 1 ? 's' : ''} scanned\n`);
+}

package/src/scanner.js

@@ -0,0 +1,76 @@
+import { readFileSync } from 'fs';
+import { extname } from 'path';
+import { walkDir } from './walker.js';
+import { parseStyleFile, parseComponentFile, isJsStyleFile } from './parser.js';
+
+export function scan(dirs) {
+  const allStyleFiles = [];
+  const allJsCandidates = [];
+
+  for (const dir of dirs) {
+    const { styleFiles, componentFiles } = walkDir(dir);
+    allStyleFiles.push(...styleFiles);
+    allJsCandidates.push(...componentFiles);
+  }
+
+  // Split JS/TS files into style files vs component files
+  const jsStyleFiles = [];
+  const componentFiles = [];
+
+  for (const file of allJsCandidates) {
+    const ext = extname(file);
+    if (['.js', '.ts'].includes(ext)) {
+      try {
+        const content = readFileSync(file, 'utf-8');
+        if (isJsStyleFile(content, file)) {
+          jsStyleFiles.push(file);
+          continue;
+        }
+      } catch {
+        // unreadable — treat as component
+      }
+    }
+    componentFiles.push(file);
+  }
+
+  const styleFiles = [...allStyleFiles, ...jsStyleFiles];
+
+  // Build global usage map from all component files
+  const globalUsed = new Set();
+  const dynamicComponentFiles = [];
+
+  for (const file of componentFiles) {
+    try {
+      const { used, hasDynamic } = parseComponentFile(file);
+      for (const cls of used) globalUsed.add(cls);
+      if (hasDynamic) dynamicComponentFiles.push(file);
+    } catch {
+      // skip unreadable files
+    }
+  }
+
+  // Analyse each style file
+  const results = [];
+
+  for (const styleFile of styleFiles) {
+    try {
+      const { selectors, hasDynamic } = parseStyleFile(styleFile);
+      // selectors is now a Map: name → { line, rule }
+      const orphaned = [...selectors.entries()]
+        .filter(([name]) => !globalUsed.has(name))
+        .map(([name, meta]) => ({ name, ...meta }));
+
+      results.push({
+        filePath: styleFile,
+        total: selectors.size,
+        orphaned,
+        hasDynamic: hasDynamic || dynamicComponentFiles.length > 0,
+        dynamicFiles: dynamicComponentFiles,
+      });
+    } catch (e) {
+      console.warn(`⚠️  Could not parse ${styleFile}: ${e.message}`);
+    }
+  }
+
+  return results;
+}

package/src/walker.js

@@ -0,0 +1,42 @@
+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 IGNORE_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.next', 'out', 'coverage', '.cache']);
+
+export function walkDir(dir) {
+  const styleFiles = [];
+  const componentFiles = [];
+
+  function walk(currentDir) {
+    let entries;
+    try {
+      entries = readdirSync(currentDir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      if (entry.name.startsWith('.') || IGNORE_DIRS.has(entry.name)) continue;
+
+      const fullPath = join(currentDir, entry.name);
+
+      if (entry.isDirectory()) {
+        walk(fullPath);
+      } else {
+        const name = basename(entry.name);
+        const ext = extname(entry.name);
+
+        if (STYLE_EXTENSIONS.some(se => name.endsWith(se))) {
+          styleFiles.push(fullPath);
+        } else if (COMPONENT_EXTENSIONS.has(ext)) {
+          componentFiles.push(fullPath);
+        }
+      }
+    }
+  }
+
+  walk(dir);
+  return { styleFiles, componentFiles };
+}