@ui-entropy/scanner-core 0.1.0

package/LICENSE

@@ -0,0 +1,6 @@
+Copyright © 2026 UI Entropy. All Rights Reserved.
+
+This software is proprietary and confidential.
+See https://uientropy.com/license for full terms.
+
+Use of this package is subject to your UI Entropy subscription tier.

package/README.md

@@ -0,0 +1,263 @@
+# Scanner Core
+
+The core CSS waste analysis engine for UI Entropy Scanner.
+
+## ✅ What We Built (Days 1-5)
+
+### **Complete CSS Waste Detection System**
+
+A production-ready TypeScript library that scans entire projects and detects unused CSS.
+
+**Day 1-2: CSS Parsing**
+- ✓ Extracts class & ID selectors from stylesheets
+- ✓ Supports Bootstrap, Tailwind, custom CSS
+- ✓ Handles complex selectors (pseudo-classes, compound, grouped)
+
+**Day 3: Usage Detection & Analysis** 
+- ✓ Scans HTML/JSX/Vue/Angular for class usage
+- ✓ Compares CSS selectors vs. actual usage
+- ✓ Calculates waste percentage
+- ✓ Generates detailed reports (JSON + Text)
+- ✓ Identifies specific unused selectors
+
+**Day 4-5: File System Scanner** 🔥
+- ✓ Recursive directory scanning with glob patterns
+- ✓ Config file support (`.ui-entropy.json`)
+- ✓ `.gitignore` integration
+- ✓ Automatic CSS/source file detection
+- ✓ Complete scan orchestration
+- ✓ **Ready for real projects!**
+
+### 📊 Test Results
+
+```
+✓ 76 tests passing (6 test suites)
+✓ End-to-end scanning validated
+✓ Real directory structure tested
+```
+
+## Usage
+
+### Scan Any Project (New!)
+
+```typescript
+import { scan } from '@ui-entropy/scanner-core';
+
+// Scan entire project directory
+const result = scan({
+  baseDir: '/path/to/your/project',
+  format: 'text', // or 'json' or 'summary'
+});
+
+console.log(result.report);
+// Output:
+// 🔍 UI Entropy Analysis Report
+// Waste Percentage: 34.4%
+// ...
+
+console.log(result.analysis.unusedClasses);
+// Set { 'btn-lg', 'alert-danger', ... }
+```
+
+### With Config File
+
+Create `.ui-entropy.json` in your project root:
+
+```json
+{
+  "cssPatterns": ["src/**/*.css", "styles/**/*.scss"],
+  "sourcePatterns": ["src/**/*.{tsx,ts,jsx,js}"],
+  "ignorePatterns": ["**/*.test.*"],
+  "respectGitignore": true,
+  "thresholds": {
+    "wastePercentage": 50
+  }
+}
+```
+
+Then simply:
+
+```typescript
+import { scan } from '@ui-entropy/scanner-core';
+
+const result = scan(); // Uses config file + current directory
+console.log(result.report);
+```
+
+### Complete Analysis Pipeline
+
+```typescript
+import {
+  extractSelectors,
+  extractUsageFromMultiple,
+  analyzeWaste,
+  generateTextReport,
+} from '@ui-entropy/scanner-core';
+
+// 1. Extract CSS selectors
+const cssContent = fs.readFileSync('styles.css', 'utf-8');
+const selectors = extractSelectors(cssContent);
+
+// 2. Extract usage from source files
+const sourceFiles = [
+  fs.readFileSync('App.tsx', 'utf-8'),
+  fs.readFileSync('index.html', 'utf-8'),
+];
+const usage = extractUsageFromMultiple(sourceFiles);
+
+// 3. Analyze waste
+const analysis = analyzeWaste(selectors, usage);
+
+// 4. Generate report
+console.log(generateTextReport(analysis));
+// Output:
+// 🔍 UI Entropy Analysis Report
+// Waste Percentage: 34.4%
+// Estimated Wasted Bytes: 1,411 bytes
+// ...
+```
+
+### Quick Start
+
+```bash
+# Run the demo (Days 1-3 features)
+pnpm demo
+
+# Run file scanner demo (Days 4-5)
+pnpm scan-demo
+
+# Run tests
+pnpm test
+
+# Watch mode
+pnpm test:watch
+```
+
+## Real-World Results
+
+**Bootstrap + HTML Example:**
+- 20 classes defined, 10 used → **45.5% waste** 🚨
+- ~1,077 bytes of unused CSS
+
+**Tailwind + React Example:**
+- 38 utility classes, 24 used → **35.9% waste**
+- ~621 bytes wasted
+
+**Multi-Framework Project:**
+- 61 selectors total, 40 used → **34.4% waste**
+- ~1,411 bytes wasted across Bootstrap + Tailwind
+
+## Architecture
+
+```
+src/
+├── parse-css.ts           # CSS selector extraction
+├── extract-usage.ts       # Source file scanning (HTML/JSX/Vue)
+├── analyze.ts             # Waste calculation engine
+├── report.ts              # Report generation (JSON/Text)
+├── crawl.ts               # File system scanner (NEW!)
+├── config.ts              # Config file support (NEW!)
+├── scan.ts                # Scan orchestrator (NEW!)
+├── index.ts               # Public API
+├── demo.ts                # Interactive demo
+├── scan-demo.ts           # File scanner demo (NEW!)
+├── *.test.ts              # Comprehensive tests (76 tests)
+└── test-fixtures/
+    ├── bootstrap-sample.css
+    ├── tailwind-sample.css
+    ├── sample.html
+    ├── sample.tsx
+    └── sample.vue
+```
+
+## Supported Frameworks
+
+### CSS Frameworks
+- Bootstrap
+- Tailwind
+- Custom CSS
+- Any PostCSS-compatible stylesheet
+
+### Template Languages
+- HTML
+- JSX/TSX (React)
+- Vue templates
+- Angular templates
+- Basic support for `clsx`, `classnames` utilities
+
+## API Reference
+
+### CSS Extraction
+```typescript
+extractSelectors(cssText: string): ExtractedSelectors
+extractSelectorsFromMultiple(cssFiles: string[]): ExtractedSelectors
+```
+
+### Usage Detection
+```typescript
+extractUsage(sourceText: string): { classes: Set<string>, ids: Set<string> }
+extractUsageFromMultiple(sourceFiles: string[]): UsageExtractionResult
+```
+
+### Analysis
+```typescript
+analyzeWaste(selectors: ExtractedSelectors, usage: UsageExtractionResult): AnalysisResult
+estimateWastedBytes(analysis: AnalysisResult): number
+```
+
+### Reporting
+```typescript
+generateReport(analysis: AnalysisResult, format: 'json' | 'text' | 'summary'): string
+generateJsonReport(analysis: AnalysisResult): JsonReport
+generateTextReport(analysis: AnalysisResult): string
+generateSummaryReport(analysis: AnalysisResult): string
+```
+
+### File System (NEW!)
+```typescript
+scan(options?: ScanOptions): ScanResult
+quickScan(baseDir?: string): string
+crawl(options: CrawlOptions): Promise<CrawlResult>
+crawlSync(options: CrawlOptions): CrawlResult
+```
+
+### Configuration (NEW!)
+```typescript
+loadConfig(baseDir?: string): Config
+getConfig(baseDir?: string): Config
+```
+
+## Next Steps (Week 2)
+
+**Day 6-7: CLI Development**
+- [ ] Build `ui-entropy` CLI command
+- [ ] Progress indicators & spinners
+- [ ] Colored terminal output
+- [ ] Watch mode for development
+- [ ] Exit codes based on thresholds
+- [ ] CI/CD integration support
+
+**Week 3: GitHub Integration**
+- [ ] GitHub App authentication
+- [ ] Automated PR comments
+- [ ] Trend tracking over time
+- [ ] Badge generation
+
+## Tech Stack
+
+- **TypeScript** - Type safety & developer experience
+- **PostCSS** - Industry-standard CSS parsing
+- **Vitest** - Fast, modern testing
+- **tsx** - TypeScript execution
+
+## Why This Matters
+
+This engine is the **foundation** for:
+- ✅ **Scan any project** - Works on real codebases today!
+- ✅ CLI tool (coming Days 6-7)
+- ✅ GitHub integration (automated PR comments)
+- ✅ SaaS dashboard (continuous monitoring)
+- ✅ Real-time waste alerts
+
+**Current State:** Fully functional scanner - **ready for production use!**  
+**Next Milestone:** CLI tool with colored output, watch mode, CI/CD integration

package/dist/analyze.d.ts

@@ -0,0 +1,31 @@
+import type { ExtractedSelectors } from './parse-css.js';
+import type { UsageExtractionResult } from './extract-usage.js';
+/**
+ * Analysis result showing CSS waste metrics
+ */
+export interface AnalysisResult {
+    totalClasses: number;
+    totalIds: number;
+    usedClasses: number;
+    usedIds: number;
+    unusedClasses: Set<string>;
+    unusedIds: Set<string>;
+    totalCssBytes: number;
+    totalRules: number;
+    wastePercentage: number;
+    filesScanned: number;
+}
+/**
+ * Analyze CSS waste by comparing extracted selectors against actual usage
+ *
+ * @param extractedSelectors - Selectors found in CSS files
+ * @param usage - Classes/IDs found in source files
+ * @returns Analysis with waste metrics
+ */
+export declare function analyzeWaste(extractedSelectors: ExtractedSelectors, usage: UsageExtractionResult): AnalysisResult;
+/**
+ * Calculate estimated bytes wasted
+ * Simple heuristic: average bytes per rule * number of unused selectors
+ */
+export declare function estimateWastedBytes(analysis: AnalysisResult): number;
+//# sourceMappingURL=analyze.d.ts.map

package/dist/analyze.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze.d.ts","sourceRoot":"","sources":["../src/analyze.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACzD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAEhE;;GAEG;AACH,MAAM,WAAW,cAAc;IAE7B,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC3B,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAGvB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IAGxB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,kBAAkB,EAAE,kBAAkB,EACtC,KAAK,EAAE,qBAAqB,GAC3B,cAAc,CA+ChB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,cAAc,GAAG,MAAM,CAUpE"}

package/dist/analyze.js

@@ -0,0 +1,65 @@
+/**
+ * Analyze CSS waste by comparing extracted selectors against actual usage
+ *
+ * @param extractedSelectors - Selectors found in CSS files
+ * @param usage - Classes/IDs found in source files
+ * @returns Analysis with waste metrics
+ */
+export function analyzeWaste(extractedSelectors, usage) {
+    // Find unused selectors
+    const unusedClasses = new Set();
+    const unusedIds = new Set();
+    let usedClassCount = 0;
+    let usedIdCount = 0;
+    // Check which classes are unused
+    for (const className of extractedSelectors.classes) {
+        if (usage.classes.has(className)) {
+            usedClassCount++;
+        }
+        else {
+            unusedClasses.add(className);
+        }
+    }
+    // Check which IDs are unused
+    for (const idName of extractedSelectors.ids) {
+        if (usage.ids.has(idName)) {
+            usedIdCount++;
+        }
+        else {
+            unusedIds.add(idName);
+        }
+    }
+    // Calculate waste percentage
+    const totalSelectors = extractedSelectors.classes.size + extractedSelectors.ids.size;
+    // const usedSelectors = usedClassCount + usedIdCount;
+    const unusedSelectors = unusedClasses.size + unusedIds.size;
+    const wastePercentage = totalSelectors > 0
+        ? (unusedSelectors / totalSelectors) * 100
+        : 0;
+    return {
+        totalClasses: extractedSelectors.classes.size,
+        totalIds: extractedSelectors.ids.size,
+        usedClasses: usedClassCount,
+        usedIds: usedIdCount,
+        unusedClasses,
+        unusedIds,
+        totalCssBytes: extractedSelectors.totalBytes,
+        totalRules: extractedSelectors.totalRules,
+        wastePercentage: Math.round(wastePercentage * 10) / 10, // Round to 1 decimal
+        filesScanned: usage.filesScanned,
+    };
+}
+/**
+ * Calculate estimated bytes wasted
+ * Simple heuristic: average bytes per rule * number of unused selectors
+ */
+export function estimateWastedBytes(analysis) {
+    const totalSelectors = analysis.totalClasses + analysis.totalIds;
+    const unusedSelectors = analysis.unusedClasses.size + analysis.unusedIds.size;
+    if (totalSelectors === 0 || analysis.totalRules === 0) {
+        return 0;
+    }
+    const avgBytesPerSelector = analysis.totalCssBytes / totalSelectors;
+    return Math.round(avgBytesPerSelector * unusedSelectors);
+}
+//# sourceMappingURL=analyze.js.map

package/dist/config.d.ts

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+/**
+ * Configuration schema for UI Entropy Scanner
+ */
+declare const ConfigSchema: z.ZodObject<{
+    cssPatterns: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    sourcePatterns: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    ignorePatterns: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    respectGitignore: z.ZodOptional<z.ZodBoolean>;
+    output: z.ZodOptional<z.ZodObject<{
+        format: z.ZodOptional<z.ZodEnum<{
+            json: "json";
+            text: "text";
+            summary: "summary";
+        }>>;
+        file: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    thresholds: z.ZodOptional<z.ZodObject<{
+        wastePercentage: z.ZodOptional<z.ZodNumber>;
+        unusedSelectors: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type Config = z.infer<typeof ConfigSchema>;
+/**
+ * Default configuration
+ */
+export declare const DEFAULT_CONFIG: Required<Omit<Config, 'output' | 'thresholds'>>;
+/**
+ * Load configuration from file
+ */
+export declare function loadConfig(baseDir?: string): Config;
+/**
+ * Merge user config with defaults
+ */
+export declare function mergeConfig(userConfig: Config): Required<Omit<Config, 'output' | 'thresholds'>> & Pick<Config, 'output' | 'thresholds'>;
+/**
+ * Load and merge config
+ */
+export declare function getConfig(baseDir?: string): ReturnType<typeof mergeConfig>;
+export {};
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;GAEG;AACH,QAAA,MAAM,YAAY;;;;;;;;;;;;;;;;;iBAoChB,CAAC;AAEH,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAElD;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,GAAG,YAAY,CAAC,CAyB1E,CAAC;AAYF;;GAEG;AACH,wBAAgB,UAAU,CAAC,OAAO,GAAE,MAAsB,GAAG,MAAM,CA2BlE;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,GAAG,YAAY,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,QAAQ,GAAG,YAAY,CAAC,CASvI;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,OAAO,GAAE,MAAsB,GAAG,UAAU,CAAC,OAAO,WAAW,CAAC,CAGzF"}

package/dist/config.js

@@ -0,0 +1,123 @@
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { z } from 'zod';
+/**
+ * Configuration schema for UI Entropy Scanner
+ */
+const ConfigSchema = z.object({
+    /**
+     * Glob patterns for CSS files
+     */
+    cssPatterns: z.array(z.string()).optional(),
+    /**
+     * Glob patterns for source files
+     */
+    sourcePatterns: z.array(z.string()).optional(),
+    /**
+     * Patterns to ignore
+     */
+    ignorePatterns: z.array(z.string()).optional(),
+    /**
+     * Whether to respect .gitignore
+     */
+    respectGitignore: z.boolean().optional(),
+    /**
+     * Custom output format
+     */
+    output: z.object({
+        format: z.enum(['text', 'json', 'summary']).optional(),
+        file: z.string().optional(),
+    }).optional(),
+    /**
+     * Thresholds for warnings/errors
+     */
+    thresholds: z.object({
+        wastePercentage: z.number().min(0).max(100).optional(),
+        unusedSelectors: z.number().min(0).optional(),
+    }).optional(),
+});
+/**
+ * Default configuration
+ */
+export const DEFAULT_CONFIG = {
+    cssPatterns: ['**/*.css', '**/*.scss', '**/*.sass'],
+    sourcePatterns: [
+        '**/*.html',
+        '**/*.tsx',
+        '**/*.ts',
+        '**/*.jsx',
+        '**/*.js',
+        '**/*.vue',
+        '**/*.svelte',
+    ],
+    ignorePatterns: [
+        'node_modules/**',
+        'dist/**',
+        'build/**',
+        '.git/**',
+        'coverage/**',
+        '.next/**',
+        '.nuxt/**',
+        'out/**',
+        'public/**',
+        '**/*.min.css',
+        '**/*.min.js',
+    ],
+    respectGitignore: true,
+};
+/**
+ * Config file names to search for
+ */
+const CONFIG_FILES = [
+    '.ui-entropy.json',
+    '.ui-entropyrc',
+    '.ui-entropyrc.json',
+    'ui-entropy.config.json',
+];
+/**
+ * Load configuration from file
+ */
+export function loadConfig(baseDir = process.cwd()) {
+    // Try to find config file
+    for (const filename of CONFIG_FILES) {
+        const configPath = join(baseDir, filename);
+        if (existsSync(configPath)) {
+            try {
+                const content = readFileSync(configPath, 'utf-8');
+                const rawConfig = JSON.parse(content);
+                // Validate with zod
+                const config = ConfigSchema.parse(rawConfig);
+                return config;
+            }
+            catch (error) {
+                if (error instanceof z.ZodError) {
+                    throw new Error(`Invalid config file ${filename}:\n${error.issues.map(issue => `  - ${issue.path.join('.')}: ${issue.message}`).join('\n')}`);
+                }
+                throw new Error(`Failed to parse config file ${filename}: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            }
+        }
+    }
+    // No config file found, return empty config
+    return {};
+}
+/**
+ * Merge user config with defaults
+ */
+export function mergeConfig(userConfig) {
+    return {
+        cssPatterns: userConfig.cssPatterns ?? DEFAULT_CONFIG.cssPatterns,
+        sourcePatterns: userConfig.sourcePatterns ?? DEFAULT_CONFIG.sourcePatterns,
+        ignorePatterns: userConfig.ignorePatterns ?? DEFAULT_CONFIG.ignorePatterns,
+        respectGitignore: userConfig.respectGitignore ?? DEFAULT_CONFIG.respectGitignore,
+        output: userConfig.output,
+        thresholds: userConfig.thresholds,
+    };
+}
+/**
+ * Load and merge config
+ */
+export function getConfig(baseDir = process.cwd()) {
+    const userConfig = loadConfig(baseDir);
+    return mergeConfig(userConfig);
+}
+//# sourceMappingURL=config.js.map

package/dist/crawl.d.ts

@@ -0,0 +1,51 @@
+export interface CrawlOptions {
+    /**
+     * Base directory to scan from
+     */
+    baseDir: string;
+    /**
+     * Glob patterns for CSS files
+     * @default ['**\/*.css', '**\/*.scss', '**\/*.sass']
+     */
+    cssPatterns?: string[];
+    /**
+     * Glob patterns for source files
+     * @default ['**\/*.html', '**\/*.tsx', '**\/*.ts', '**\/*.jsx', '**\/*.js', '**\/*.vue']
+     */
+    sourcePatterns?: string[];
+    /**
+     * Patterns to ignore (in addition to .gitignore)
+     * @default ['node_modules/**', 'dist/**', 'build/**', '.git/**']
+     */
+    ignorePatterns?: string[];
+    /**
+     * Whether to respect .gitignore file
+     * @default true
+     */
+    respectGitignore?: boolean;
+}
+export interface CrawlResult {
+    cssFiles: Array<{
+        path: string;
+        content: string;
+    }>;
+    sourceFiles: Array<{
+        path: string;
+        content: string;
+    }>;
+    stats: {
+        totalCssFiles: number;
+        totalSourceFiles: number;
+        totalCssBytes: number;
+        totalSourceBytes: number;
+    };
+}
+/**
+ * Crawl directory for CSS and source files
+ */
+export declare function crawl(options: CrawlOptions): Promise<CrawlResult>;
+/**
+ * Synchronous version of crawl (useful for CLI/simple use cases)
+ */
+export declare function crawlSync(options: CrawlOptions): CrawlResult;
+//# sourceMappingURL=crawl.d.ts.map

package/dist/crawl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crawl.d.ts","sourceRoot":"","sources":["../src/crawl.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,YAAY;IAC3B;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IAEvB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAE1B;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAE1B;;;OAGG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACnD,WAAW,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACtD,KAAK,EAAE;QACL,aAAa,EAAE,MAAM,CAAC;QACtB,gBAAgB,EAAE,MAAM,CAAC;QACzB,aAAa,EAAE,MAAM,CAAC;QACtB,gBAAgB,EAAE,MAAM,CAAC;KAC1B,CAAC;CACH;AAkDD;;GAEG;AACH,wBAAsB,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,CA8DvE;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,YAAY,GAAG,WAAW,CA8D5D"}