@ui-entropy/scanner-core 0.1.0

package/dist/report.js

@@ -0,0 +1,137 @@
+import { estimateWastedBytes } from './analyze.js';
+/**
+ * Generate JSON report from analysis
+ */
+export function generateJsonReport(analysis, warnings = []) {
+    const totalSelectors = analysis.totalClasses + analysis.totalIds;
+    const usedSelectors = analysis.usedClasses + analysis.usedIds;
+    const unusedSelectors = analysis.unusedClasses.size + analysis.unusedIds.size;
+    return {
+        version: '1.0.0',
+        timestamp: new Date().toISOString(),
+        summary: {
+            totalCssBytes: analysis.totalCssBytes,
+            totalRules: analysis.totalRules,
+            totalSelectors,
+            usedSelectors,
+            unusedSelectors,
+            wastePercentage: analysis.wastePercentage,
+            estimatedWastedBytes: estimateWastedBytes(analysis),
+            filesScanned: analysis.filesScanned,
+        },
+        details: {
+            classes: {
+                total: analysis.totalClasses,
+                used: analysis.usedClasses,
+                unused: analysis.unusedClasses.size,
+                unusedList: Array.from(analysis.unusedClasses).sort(),
+            },
+            ids: {
+                total: analysis.totalIds,
+                used: analysis.usedIds,
+                unused: analysis.unusedIds.size,
+                unusedList: Array.from(analysis.unusedIds).sort(),
+            },
+        },
+        warnings,
+    };
+}
+/**
+ * Generate human-readable text report
+ */
+export function generateTextReport(analysis) {
+    const wastedBytes = estimateWastedBytes(analysis);
+    const totalSelectors = analysis.totalClasses + analysis.totalIds;
+    const usedSelectors = analysis.usedClasses + analysis.usedIds;
+    let report = '';
+    report += '🔍 UI Entropy Analysis Report\n';
+    report += '═══════════════════════════════════════════════════════\n\n';
+    // Summary
+    report += '📊 Summary\n';
+    report += '─────────────────────────────────────────────────────\n';
+    report += `Total CSS Size:           ${analysis.totalCssBytes.toLocaleString()} bytes\n`;
+    report += `Total Rules:              ${analysis.totalRules.toLocaleString()}\n`;
+    report += `Files Scanned:            ${analysis.filesScanned}\n\n`;
+    // Selectors
+    report += '🎯 Selectors\n';
+    report += '─────────────────────────────────────────────────────\n';
+    report += `Total Selectors:          ${totalSelectors}\n`;
+    report += `Used Selectors:           ${usedSelectors} (${Math.round((usedSelectors / totalSelectors) * 100)}%)\n`;
+    report += `Unused Selectors:         ${totalSelectors - usedSelectors}\n\n`;
+    // Classes breakdown
+    report += `Classes:                  ${analysis.totalClasses} total\n`;
+    report += `  ├─ Used:                ${analysis.usedClasses}\n`;
+    report += `  └─ Unused:              ${analysis.unusedClasses.size}\n\n`;
+    // IDs breakdown
+    report += `IDs:                      ${analysis.totalIds} total\n`;
+    report += `  ├─ Used:                ${analysis.usedIds}\n`;
+    report += `  └─ Unused:              ${analysis.unusedIds.size}\n\n`;
+    // Waste calculation
+    report += '💰 CSS Waste Analysis\n';
+    report += '─────────────────────────────────────────────────────\n';
+    report += `Waste Percentage:         ${analysis.wastePercentage}%\n`;
+    report += `Estimated Wasted Bytes:   ${wastedBytes.toLocaleString()} bytes\n\n`;
+    // Top unused classes
+    if (analysis.unusedClasses.size > 0) {
+        report += '🚨 Top Unused Classes\n';
+        report += '─────────────────────────────────────────────────────\n';
+        const topUnused = Array.from(analysis.unusedClasses).slice(0, 20);
+        topUnused.forEach((cls, i) => {
+            report += `  ${i + 1}. .${cls}\n`;
+        });
+        if (analysis.unusedClasses.size > 20) {
+            report += `  ... and ${analysis.unusedClasses.size - 20} more\n`;
+        }
+        report += '\n';
+    }
+    // Unused IDs
+    if (analysis.unusedIds.size > 0) {
+        report += '🚨 Unused IDs\n';
+        report += '─────────────────────────────────────────────────────\n';
+        Array.from(analysis.unusedIds).forEach((id, i) => {
+            report += `  ${i + 1}. #${id}\n`;
+        });
+        report += '\n';
+    }
+    // Recommendations
+    report += '💡 Recommendations\n';
+    report += '─────────────────────────────────────────────────────\n';
+    if (analysis.wastePercentage > 50) {
+        report += '  ⚠️  HIGH WASTE: Consider using PurgeCSS or removing\n';
+        report += '     unused framework imports.\n\n';
+    }
+    else if (analysis.wastePercentage > 25) {
+        report += '  ⚡ MODERATE WASTE: Review and remove unused selectors.\n\n';
+    }
+    else {
+        report += '  ✅ GOOD: CSS waste is within acceptable range.\n\n';
+    }
+    return report;
+}
+/**
+ * Generate a brief summary report (for CLI output)
+ */
+export function generateSummaryReport(analysis) {
+    const wastedBytes = estimateWastedBytes(analysis);
+    const totalSelectors = analysis.totalClasses + analysis.totalIds;
+    return `
+CSS Waste: ${analysis.wastePercentage}% | ${wastedBytes.toLocaleString()} bytes wasted
+Total: ${totalSelectors} selectors | Used: ${analysis.usedClasses + analysis.usedIds} | Unused: ${analysis.unusedClasses.size + analysis.unusedIds.size}
+Scanned ${analysis.filesScanned} files | ${analysis.totalCssBytes.toLocaleString()} bytes CSS
+`.trim();
+}
+/**
+ * Generate report in specified format
+ */
+export function generateReport(analysis, format = 'text', warnings = []) {
+    switch (format) {
+        case 'json':
+            return JSON.stringify(generateJsonReport(analysis, warnings), null, 2);
+        case 'summary':
+            return generateSummaryReport(analysis);
+        case 'text':
+        default:
+            return generateTextReport(analysis);
+    }
+}
+//# sourceMappingURL=report.js.map

package/dist/scan.d.ts

@@ -0,0 +1,48 @@
+import { type ParseWarning } from './parse-css.js';
+import { type AnalysisResult } from './analyze.js';
+import { type ReportFormat } from './report.js';
+export interface ScanOptions {
+    /**
+     * Directory to scan
+     * @default process.cwd()
+     */
+    baseDir?: string;
+    /**
+     * Report format
+     * @default 'text'
+     */
+    format?: ReportFormat;
+    /**
+     * Override config file settings
+     */
+    cssPatterns?: string[];
+    sourcePatterns?: string[];
+    ignorePatterns?: string[];
+}
+export interface ScanResult {
+    analysis: AnalysisResult;
+    report: string;
+    files: {
+        cssFiles: number;
+        sourceFiles: number;
+        totalBytes: number;
+    };
+    warnings: ParseWarning[];
+}
+/**
+ * Scan a project directory for CSS waste
+ *
+ * This is the main entry point that orchestrates:
+ * 1. Load config
+ * 2. Crawl files
+ * 3. Extract CSS selectors
+ * 4. Extract usage from source files
+ * 5. Analyze waste
+ * 6. Generate report
+ */
+export declare function scan(options?: ScanOptions): ScanResult;
+/**
+ * Quick scan that just returns the report as a string
+ */
+export declare function quickScan(baseDir?: string): string;
+//# sourceMappingURL=scan.d.ts.map

package/dist/scan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan.d.ts","sourceRoot":"","sources":["../src/scan.ts"],"names":[],"mappings":"AAEA,OAAO,EAAgC,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEjF,OAAO,EAAgB,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AACjE,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhE,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;IAEtB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,cAAc,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE;QACL,QAAQ,EAAE,MAAM,CAAC;QACjB,WAAW,EAAE,MAAM,CAAC;QACpB,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;IACF,QAAQ,EAAE,YAAY,EAAE,CAAC;CAC1B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,IAAI,CAAC,OAAO,GAAE,WAAgB,GAAG,UAAU,CA+D1D;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,OAAO,GAAE,MAAsB,GAAG,MAAM,CAGjE"}

package/dist/scan.js

@@ -0,0 +1,72 @@
+import { crawlSync } from './crawl.js';
+import { getConfig } from './config.js';
+import { extractSelectorsFromMultiple } from './parse-css.js';
+import { extractUsageFromMultiple } from './extract-usage.js';
+import { analyzeWaste } from './analyze.js';
+import { generateReport } from './report.js';
+/**
+ * Scan a project directory for CSS waste
+ *
+ * This is the main entry point that orchestrates:
+ * 1. Load config
+ * 2. Crawl files
+ * 3. Extract CSS selectors
+ * 4. Extract usage from source files
+ * 5. Analyze waste
+ * 6. Generate report
+ */
+export function scan(options = {}) {
+    const { baseDir = process.cwd(), format = 'text', cssPatterns, sourcePatterns, ignorePatterns, } = options;
+    // 1. Load configuration
+    const config = getConfig(baseDir);
+    // Override with CLI options if provided
+    const finalCssPatterns = cssPatterns ?? config.cssPatterns;
+    const finalSourcePatterns = sourcePatterns ?? config.sourcePatterns;
+    // Merge ignore patterns: CLI patterns are ADDED to config patterns, not replacing them
+    const finalIgnorePatterns = ignorePatterns
+        ? [...config.ignorePatterns, ...ignorePatterns]
+        : config.ignorePatterns;
+    // 2. Crawl filesystem
+    const crawlResult = crawlSync({
+        baseDir,
+        cssPatterns: finalCssPatterns,
+        sourcePatterns: finalSourcePatterns,
+        ignorePatterns: finalIgnorePatterns,
+        respectGitignore: config.respectGitignore,
+    });
+    // Early exit if no files found
+    if (crawlResult.cssFiles.length === 0) {
+        throw new Error('No CSS files found. Check your cssPatterns configuration.');
+    }
+    if (crawlResult.sourceFiles.length === 0) {
+        throw new Error('No source files found. Check your sourcePatterns configuration.');
+    }
+    // 3. Extract CSS selectors (pass file objects for better error reporting)
+    const selectors = extractSelectorsFromMultiple(crawlResult.cssFiles);
+    // 4. Extract usage from source files
+    const sourceContents = crawlResult.sourceFiles.map(f => f.content);
+    const usage = extractUsageFromMultiple(sourceContents);
+    // 5. Analyze waste
+    const analysis = analyzeWaste(selectors, usage);
+    // 6. Generate report
+    const reportFormat = config.output?.format ?? format;
+    const report = generateReport(analysis, reportFormat, selectors.warnings);
+    return {
+        analysis,
+        report,
+        files: {
+            cssFiles: crawlResult.stats.totalCssFiles,
+            sourceFiles: crawlResult.stats.totalSourceFiles,
+            totalBytes: crawlResult.stats.totalCssBytes + crawlResult.stats.totalSourceBytes,
+        },
+        warnings: selectors.warnings,
+    };
+}
+/**
+ * Quick scan that just returns the report as a string
+ */
+export function quickScan(baseDir = process.cwd()) {
+    const result = scan({ baseDir });
+    return result.report;
+}
+//# sourceMappingURL=scan.js.map

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@ui-entropy/scanner-core",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "CSS waste detection engine - finds unused classes and IDs in your codebase",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "type-check": "tsc --noEmit",
+    "demo": "tsx src/demo.ts",
+    "scan-demo": "tsx src/scan-demo.ts",
+    "test-real": "tsx src/test-real-repo.ts",
+    "test-tailwind": "tsx src/test-tailwind.ts"
+  },
+  "keywords": [
+    "css",
+    "unused",
+    "waste",
+    "optimization",
+    "bundle-size",
+    "tailwind",
+    "postcss"
+  ],
+  "author": "UI Entropy",
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://uientropy.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ui-entropy/ui-entropy.git",
+    "directory": "packages/scanner-core"
+  },
+  "bugs": {
+    "url": "https://github.com/ui-entropy/ui-entropy/issues"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "dist/**/*.d.ts.map",
+    "!dist/demo.*",
+    "!dist/scan-demo.*",
+    "!dist/test-*.* ",
+    "!dist/quick-test.*",
+    "README.md",
+    "LICENSE"
+  ],
+  "packageManager": "pnpm@10.30.0",
+  "devDependencies": {
+    "@types/node": "^25.2.3",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "dependencies": {
+    "fast-glob": "^3.3.3",
+    "ignore": "^7.0.5",
+    "postcss": "^8.5.6",
+    "postcss-selector-parser": "^7.1.1",
+    "zod": "^4.3.6"
+  }
+}