@rolandjlevy/css-ghost 1.0.0 → 1.0.2

package/README.md

@@ -4,7 +4,7 @@ Find orphaned CSS class selectors in your codebase — defined in style files bu
 
 ## 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.
+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`
@@ -22,13 +22,13 @@ Files containing `styles[variable]` or template literal class names are flagged
 ## Install
 
 ```bash
-npm install -g css-ghost
+npm install -g @rolandjlevy/css-ghost
 ```
 
-Or run directly without installing:
+Or run without installing:
 
 ```bash
-npx css-ghost ./src
+npx @rolandjlevy/css-ghost ./src
 ```
 
 ## Usage
@@ -47,44 +47,95 @@ css-ghost <directory> [directory2] ... [options]
 ## Examples
 
 ```bash
-# Scan a single directory
+# Scan your src folder
 css-ghost ./src
 
 # Scan multiple directories
 css-ghost ./src ./components ./pages
 
-# Custom output path
+# Write report to a custom path
 css-ghost ./src --output ./reports/css-audit.md
 ```
 
-## Output
+## CLI output
 
-Generates a markdown report (`orphan-report.md` by default):
+Running `css-ghost ./src` prints a live summary to your terminal:
+
+```
+✅ Report written to orphan-report.md
+📊 3 orphaned selectors across 1 file
+
+📄 src/components/Button/Button.module.css
+   👻 .iconLeft (line 4)
+      .iconLeft {
+        margin-right: 6px;
+        flex-shrink: 0;
+      }
+
+   👻 .loadingSpinner (line 12)
+      .loadingSpinner {
+        animation: spin 0.8s linear infinite;
+      }
+
+   👻 .disabled (line 18)
+      .disabled {
+        opacity: 0.4;
+        pointer-events: none;
+      }
+
+📁 1 style file scanned
+```
+
+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
+
+## Markdown report
+
+A full report is also written to `orphan-report.md` (or your `--output` path):
 
 ---
 
-# 👻 css-ghost — Orphaned Selector Report
+### 👻 Orphaned selectors
 
-## Summary
-| Metric | Value |
-| --- | --- |
-| Style files scanned | 12 |
-| Total selectors defined | 84 |
-| Total orphaned selectors | 7 |
-| Files with orphans | 3 |
-| Overall unused rate | 8% |
+#### `.iconLeft` — line 4
 
-## `src/components/Button/Button.module.css`
-| Defined | Orphaned | Unused % |
-| --- | --- | --- |
-| 6 | 2 | 33% |
+```css
+.iconLeft {
+  margin-right: 6px;
+  flex-shrink: 0;
+}
+```
 
-**Orphaned selectors:**
-- `.iconLeft`
-- `.loadingSpinner`
+#### `.loadingSpinner` — line 12
+
+```css
+.loadingSpinner {
+  animation: spin 0.8s linear infinite;
+}
+```
 
 ---
 
+## Using with npm scripts
+
+If you're working inside the project itself, add a `scan` script to `package.json`:
+
+```json
+"scripts": {
+  "scan": "css-ghost ./src"
+}
+```
+
+Then run:
+
+```bash
+npm run scan
+
+# Pass extra args with --
+npm run scan -- --output ./reports/audit.md
+```
+
 ## No dependencies
 
 Built with Node.js built-ins only (`fs`, `path`). No npm packages required.

package/package.json

@@ -1,22 +1,40 @@
 {
   "name": "@rolandjlevy/css-ghost",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "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"
+    "start": "node bin/css-ghost.js",
+    "scan": "node bin/css-ghost.js ./test"
   },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
   "keywords": [
     "css",
     "orphan",
     "unused",
     "selectors",
     "cli",
-    "linter"
+    "linter",
+    "react",
+    "scss",
+    "stylesheet",
+    "audit"
   ],
   "author": "Roland Levy",
-  "license": "MIT"
+  "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

@@ -4,17 +4,68 @@ import { extname } from 'path';
 // ─── CSS / SCSS selector extraction ────────────────────────────────────────
 
 function extractCssSelectors(content) {
-  const selectors = new Set();
+  const selectors = new Map(); // name → { line, rule }
+  const lines = content.split('\n');
 
-  // Strip comments
-  const stripped = content
-    .replace(/\/\*[\s\S]*?\*\//g, '')
-    .replace(/\/\/.*$/gm, '');
+  // Strip block comments but preserve line numbers by replacing with spaces
+  const stripped = content.replace(/\/\*[\s\S]*?\*\//g, m =>
+    m.replace(/[^\n]/g, ' ')
+  );
 
-  const regex = /\.([a-zA-Z_-][a-zA-Z0-9_-]*)/g;
-  let match;
-  while ((match = regex.exec(stripped)) !== null) {
-    selectors.add(match[1]);
+  // 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;
@@ -30,19 +81,29 @@ export function isJsStyleFile(content, filePath) {
 }
 
 function extractJsStyleKeys(content) {
-  const keys = new Set();
+  const keys = new Map(); // name → { line, rule }
+  const lines = content.split('\n');
 
-  // 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) {
+    // 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) {
-      keys.add(m[1]);
+      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 });
+      }
     }
   }
 

package/src/reporter.js

@@ -43,10 +43,18 @@ export function generateReport(results, outputPath = 'orphan-report.md') {
     }
 
     if (hasOrphans) {
-      lines.push('**Orphaned selectors:**');
-      lines.push('');
-      orphaned.forEach(s => lines.push(`- \`.${s}\``));
-      lines.push('');
+      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('---');
@@ -80,7 +88,20 @@ export function generateReport(results, outputPath = 'orphan-report.md') {
   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`);
+  // Console output — also print orphans inline
+  console.log(`📊 ${totalOrphaned} orphaned selector${totalOrphaned !== 1 ? 's' : ''} in ${filesWithOrphans} file${filesWithOrphans !== 1 ? 's' : ''}. See: ${outputPath}\n`);
+
+  for (const result of results) {
+    if (result.orphaned.length === 0) continue;
+    const relPath = relative(process.cwd(), result.filePath);
+    console.log(`✅ ${relPath}\n`);
+    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('');
+    });
+  }
 }

package/src/scanner.js

@@ -55,7 +55,10 @@ export function scan(dirs) {
   for (const styleFile of styleFiles) {
     try {
       const { selectors, hasDynamic } = parseStyleFile(styleFile);
-      const orphaned = [...selectors].filter(s => !globalUsed.has(s));
+      // 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,

package/.devcontainer/devcontainer.json

@@ -1,35 +0,0 @@
-{
-  "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"
-}