@ui-entropy/scanner-core 0.2.1 → 0.3.0

package/README.md

@@ -1,15 +1,14 @@
 # @ui-entropy/scanner-core
 
-> Professional CSS waste detection engine. Find unused classes, reduce bundle sizes, and maintain clean stylesheets.
+> Core CSS waste detection engine for programmatic use. Powers the UI Entropy CLI and dashboard.
 
 [![npm version](https://img.shields.io/npm/v/@ui-entropy/scanner-core.svg)](https://www.npmjs.com/package/@ui-entropy/scanner-core)
-[![License](https://img.shields.io/badge/license-Proprietary-blue.svg)](https://uientropy.com/license)
+[![Tests](https://img.shields.io/badge/tests-79%20passing-brightgreen)]()
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue)]()
 
-## 🎯 What is UI Entropy?
+This package provides the **core analysis engine** for UI Entropy Scanner. It's designed for programmatic use in Node.js applications, build tools, and custom integrations.
 
-UI Entropy is a **professional developer tool** that scans your codebase to identify unused CSS. Think of it as **SonarQube for your UI** - helping teams maintain code quality, reduce technical debt, and optimize bundle sizes.
-
-This is the **core scanning engine** used by the UI Entropy CLI and dashboard products.
+**For command-line usage**, see [@ui-entropy/cli](../cli) which includes smart initialization and colored output.
 
 ## 🚀 Features
 

package/dist/analyzers/duplication.d.ts

@@ -1,26 +1,44 @@
 /**
- * Duplication Analyzer (Placeholder for v0.3+)
+ * Duplication Analyzer
  *
  * Analyzes CSS selector duplication and similar styles.
- * Currently returns score of 0 (no duplication detected).
+ * Detects rules with identical properties that could be consolidated.
  */
 import type { Analyzer, AnalyzerContext, AnalyzerResult } from './types.js';
 export interface DuplicationMetrics {
-    duplicateSelectors: number;
-    similarRules: number;
+    duplicateRuleGroups: number;
+    totalDuplicatedRules: number;
     duplicationPercentage: number;
-    potentialSavings: number;
+    potentialSavingsBytes: number;
+    examples: Array<{
+        properties: string;
+        selectors: string[];
+        count: number;
+    }>;
 }
 /**
- * Duplication Analyzer (v0.3+ feature)
+ * Duplication Analyzer
  *
- * Detects duplicate selectors and similar CSS rules.
- * Currently a placeholder that returns 0.
+ * Detects CSS rules with identical properties.
+ * Score = percentage of rules that are duplicates (0-100)
  */
 export declare class DuplicationAnalyzer implements Analyzer {
     name: string;
     weight: number;
-    analyze(_context: AnalyzerContext): AnalyzerResult;
+    analyze(context: AnalyzerContext): AnalyzerResult;
+    /**
+     * Extract and normalize CSS properties from a rule
+     * Returns sorted array of "property: value" strings
+     */
+    private normalizeProperties;
+    /**
+     * Format properties for display (limit length)
+     */
+    private formatProperties;
+    /**
+     * Generate actionable recommendations based on duplication score
+     */
+    private generateRecommendations;
 }
 /**
  * Factory function for creating Duplication analyzer

package/dist/analyzers/duplication.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"duplication.d.ts","sourceRoot":"","sources":["../../src/analyzers/duplication.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5E,MAAM,WAAW,kBAAkB;IACjC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;GAKG;AACH,qBAAa,mBAAoB,YAAW,QAAQ;IAClD,IAAI,SAAiB;IACrB,MAAM,SAAO;IAEb,OAAO,CAAC,QAAQ,EAAE,eAAe,GAAG,cAAc;CAuBnD;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,mBAAmB,CAEzD"}
+{"version":3,"file":"duplication.d.ts","sourceRoot":"","sources":["../../src/analyzers/duplication.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5E,MAAM,WAAW,kBAAkB;IACjC,mBAAmB,EAAE,MAAM,CAAC;IAC5B,oBAAoB,EAAE,MAAM,CAAC;IAC7B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,QAAQ,EAAE,KAAK,CAAC;QACd,UAAU,EAAE,MAAM,CAAC;QACnB,SAAS,EAAE,MAAM,EAAE,CAAC;QACpB,KAAK,EAAE,MAAM,CAAC;KACf,CAAC,CAAC;CACJ;AAQD;;;;;GAKG;AACH,qBAAa,mBAAoB,YAAW,QAAQ;IAClD,IAAI,SAAiB;IACrB,MAAM,SAAO;IAEb,OAAO,CAAC,OAAO,EAAE,eAAe,GAAG,cAAc;IAyFjD;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAc3B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAQxB;;OAEG;IACH,OAAO,CAAC,uBAAuB;CAsChC;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,mBAAmB,CAEzD"}

package/dist/analyzers/duplication.js

@@ -1,39 +1,166 @@
 /**
- * Duplication Analyzer (Placeholder for v0.3+)
+ * Duplication Analyzer
  *
  * Analyzes CSS selector duplication and similar styles.
- * Currently returns score of 0 (no duplication detected).
+ * Detects rules with identical properties that could be consolidated.
  */
+import postcss from 'postcss';
 /**
- * Duplication Analyzer (v0.3+ feature)
+ * Duplication Analyzer
  *
- * Detects duplicate selectors and similar CSS rules.
- * Currently a placeholder that returns 0.
+ * Detects CSS rules with identical properties.
+ * Score = percentage of rules that are duplicates (0-100)
  */
 export class DuplicationAnalyzer {
     name = 'Duplication';
     weight = 0.4; // 40% of overall entropy score
-    analyze(_context) {
-        // TODO: Implement duplication detection in v0.3+
-        // - Find duplicate selectors
-        // - Detect similar CSS rules (same properties, different selectors)
-        // - Calculate consolidation opportunities
+    analyze(context) {
+        const { crawl } = context;
+        // Parse CSS files and group by property signature
+        const signatureMap = new Map();
+        let totalRules = 0;
+        for (const cssFile of crawl.cssFiles) {
+            try {
+                const root = postcss.parse(cssFile.content);
+                root.walkRules((rule) => {
+                    totalRules++;
+                    // Extract and normalize properties
+                    const properties = this.normalizeProperties(rule);
+                    if (!properties || properties.length === 0) {
+                        return; // Skip rules with no properties
+                    }
+                    // Create a signature from sorted properties
+                    const signature = properties.join(';');
+                    // Group rules by signature
+                    if (signatureMap.has(signature)) {
+                        const existing = signatureMap.get(signature);
+                        existing.selectors.push(rule.selector);
+                        existing.bytes += Buffer.byteLength(rule.toString(), 'utf8');
+                    }
+                    else {
+                        signatureMap.set(signature, {
+                            properties: signature,
+                            selectors: [rule.selector],
+                            bytes: Buffer.byteLength(rule.toString(), 'utf8'),
+                        });
+                    }
+                });
+            }
+            catch (error) {
+                // Skip files that can't be parsed
+                continue;
+            }
+        }
+        // Find duplicates (groups with 2+ selectors)
+        const duplicates = [];
+        let totalDuplicatedRules = 0;
+        let potentialSavingsBytes = 0;
+        for (const sig of signatureMap.values()) {
+            if (sig.selectors.length > 1) {
+                duplicates.push(sig);
+                totalDuplicatedRules += sig.selectors.length;
+                // Savings = (n-1) * bytes per rule (keep one, remove n-1)
+                potentialSavingsBytes += ((sig.selectors.length - 1) * sig.bytes) / sig.selectors.length;
+            }
+        }
+        // Calculate duplication percentage
+        const duplicationPercentage = totalRules > 0
+            ? Math.round((totalDuplicatedRules / totalRules) * 100)
+            : 0;
+        // Sort duplicates by impact (most duplicated first)
+        duplicates.sort((a, b) => b.selectors.length - a.selectors.length);
+        // Build metrics
         const metrics = {
-            duplicateSelectors: 0,
-            similarRules: 0,
-            duplicationPercentage: 0,
-            potentialSavings: 0,
+            duplicateRuleGroups: duplicates.length,
+            totalDuplicatedRules,
+            duplicationPercentage,
+            potentialSavingsBytes: Math.round(potentialSavingsBytes),
+            examples: duplicates.slice(0, 5).map(dup => ({
+                properties: this.formatProperties(dup.properties),
+                selectors: dup.selectors,
+                count: dup.selectors.length,
+            })),
         };
+        // Generate recommendations
+        const recommendations = this.generateRecommendations(duplicationPercentage, duplicates.length);
         return {
             name: this.name,
-            score: 0, // Placeholder: no duplication detected
+            score: duplicationPercentage,
             weight: this.weight,
             metrics,
-            recommendations: [
-                'Duplication analysis coming in v0.3',
-            ],
+            recommendations,
         };
     }
+    /**
+     * Extract and normalize CSS properties from a rule
+     * Returns sorted array of "property: value" strings
+     */
+    normalizeProperties(rule) {
+        const properties = [];
+        rule.walkDecls((decl) => {
+            // Normalize whitespace and create canonical form
+            const prop = decl.prop.trim().toLowerCase();
+            const value = decl.value.trim().replace(/\s+/g, ' ');
+            properties.push(`${prop}:${value}`);
+        });
+        // Sort for consistent comparison
+        return properties.sort();
+    }
+    /**
+     * Format properties for display (limit length)
+     */
+    formatProperties(properties) {
+        const parts = properties.split(';').filter(Boolean);
+        if (parts.length <= 3) {
+            return parts.join('; ');
+        }
+        return `${parts.slice(0, 3).join('; ')}... (+${parts.length - 3} more)`;
+    }
+    /**
+     * Generate actionable recommendations based on duplication score
+     */
+    generateRecommendations(percentage, groupCount) {
+        if (percentage === 0) {
+            return [
+                'Excellent! No duplicate CSS rules detected.',
+                'Your styles are well-organized.',
+            ];
+        }
+        else if (percentage < 10) {
+            return [
+                'Minimal duplication detected.',
+                `Consider consolidating ${groupCount} rule groups with identical properties.`,
+                'Use CSS variables or utility classes for repeated styles.',
+            ];
+        }
+        else if (percentage < 25) {
+            return [
+                'Moderate duplication detected.',
+                `${groupCount} groups of rules share identical properties.`,
+                'Consolidate duplicate rules into shared classes.',
+                'Consider using a utility-first CSS framework (Tailwind, UnoCSS).',
+            ];
+        }
+        else if (percentage < 50) {
+            return [
+                'High duplication: Significant consolidation opportunities.',
+                `${groupCount} rule groups could be merged.`,
+                'Extract common patterns into reusable utility classes.',
+                'Consider using CSS-in-JS with style composition.',
+                'Review component styles for shared patterns.',
+            ];
+        }
+        else {
+            return [
+                'Critical duplication: Major refactoring recommended.',
+                `${groupCount} duplicate rule groups detected.`,
+                'Switch to utility-first CSS (Tailwind, UnoCSS).',
+                'Extract all common styles into utility classes.',
+                'Consider atomic CSS architecture.',
+                'Use design tokens and CSS variables for consistency.',
+            ];
+        }
+    }
 }
 /**
  * Factory function for creating Duplication analyzer

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ui-entropy/scanner-core",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "type": "module",
   "description": "CSS waste detection engine - finds unused classes and IDs in your codebase",
   "main": "./dist/index.js",

package/README.old.md

@@ -1,263 +0,0 @@
-# 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