@rolandjlevy/css-ghost 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -4,6 +4,20 @@ 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

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
@@ -158,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.2.0",
+  "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,11 +17,13 @@
     "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"
@@ -25,6 +32,7 @@
     "css",
     "unused",
     "orphan",
+    "orphaned-selectors",
     "selectors",
     "dead-code",
     "cleanup",
@@ -33,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/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';