@rolandjlevy/css-ghost 0.0.0-stage → 1.0.0

package/.devcontainer/devcontainer.json

@@ -0,0 +1,35 @@
+{
+  "name": "css-ghost",
+  "image": "mcr.microsoft.com/devcontainers/javascript-node:20",
+
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "dbaeumer.vscode-eslint",
+        "esbenp.prettier-vscode",
+        "GitHub.github-vscode-theme",
+        "christian-kohler.path-intellisense",
+        "streetsidesoftware.code-spell-checker"
+      ],
+      "settings": {
+        "workbench.colorTheme": "GitHub Dark Dimmed",
+        "workbench.iconTheme": "vs-seti",
+        "editor.fontSize": 14,
+        "editor.tabSize": 2,
+        "editor.formatOnSave": true,
+        "editor.defaultFormatter": "esbenp.prettier-vscode",
+        "editor.minimap.enabled": false,
+        "editor.wordWrap": "on",
+        "terminal.integrated.defaultProfile.linux": "bash",
+        "files.exclude": {
+          "node_modules": true,
+          "orphan-report.md": true
+        }
+      }
+    }
+  },
+
+  "postCreateCommand": "echo '👻 css-ghost dev container ready. Run: node bin/css-ghost.js --help'",
+
+  "remoteUser": "node"
+}

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,22 @@
 {
   "name": "@rolandjlevy/css-ghost",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "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"
+  },
+  "keywords": [
+    "css",
+    "orphan",
+    "unused",
+    "selectors",
+    "cli",
+    "linter"
+  ],
+  "author": "Roland Levy",
+  "license": "MIT"
+}

package/src/parser.js

@@ -0,0 +1,119 @@
+import { readFileSync } from 'fs';
+import { extname } from 'path';
+
+// ─── CSS / SCSS selector extraction ────────────────────────────────────────
+
+function extractCssSelectors(content) {
+  const selectors = new Set();
+
+  // Strip comments
+  const stripped = content
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/\/\/.*$/gm, '');
+
+  const regex = /\.([a-zA-Z_-][a-zA-Z0-9_-]*)/g;
+  let match;
+  while ((match = regex.exec(stripped)) !== null) {
+    selectors.add(match[1]);
+  }
+
+  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 Set();
+
+  // StyleSheet.create({ key: ... })
+  const ssMatch = content.match(/StyleSheet\.create\s*\(\s*\{([\s\S]*?)\}\s*\)/);
+  // Plain object: const styles = { key: ... }
+  const plainMatch = content.match(/(?:const|let|var)\s+styles?\s*=\s*\{([\s\S]*)\}/);
+
+  const objectContent = ssMatch?.[1] ?? plainMatch?.[1];
+  if (objectContent) {
+    const keyRegex = /^\s*([a-zA-Z_$][a-zA-Z0-9_$]*)\s*:/gm;
+    let m;
+    while ((m = keyRegex.exec(objectContent)) !== null) {
+      keys.add(m[1]);
+    }
+  }
+
+  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,86 @@
+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:**');
+      lines.push('');
+      orphaned.forEach(s => lines.push(`- \`.${s}\``));
+      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.log(`✅ Report written to ${outputPath}`);
+  console.log(`📊 ${totalOrphaned} orphaned selector${totalOrphaned !== 1 ? 's' : ''} across ${filesWithOrphans} file${filesWithOrphans !== 1 ? 's' : ''}`);
+  console.log(`📁 ${results.length} style file${results.length !== 1 ? 's' : ''} scanned\n`);
+}

package/src/scanner.js

@@ -0,0 +1,73 @@
+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);
+      const orphaned = [...selectors].filter(s => !globalUsed.has(s));
+
+      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 };
+}