@ui-entropy/scanner-core 0.1.0 → 0.1.1

package/README.md

@@ -1,263 +1,132 @@
-# Scanner Core
+# @ui-entropy/scanner-core
 
-The core CSS waste analysis engine for UI Entropy Scanner.
+> Professional CSS waste detection engine. Find unused classes, reduce bundle sizes, and maintain clean stylesheets.
 
-## ✅ What We Built (Days 1-5)
+[![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)
 
-### **Complete CSS Waste Detection System**
+## 🎯 What is UI Entropy?
 
-A production-ready TypeScript library that scans entire projects and detects unused CSS.
+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.
 
-**Day 1-2: CSS Parsing**
-- ✓ Extracts class & ID selectors from stylesheets
-- ✓ Supports Bootstrap, Tailwind, custom CSS
-- ✓ Handles complex selectors (pseudo-classes, compound, grouped)
+This is the **core scanning engine** used by the UI Entropy CLI and dashboard products.
 
-**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
+## 🚀 Features
 
-**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!**
+- **Smart CSS Parsing** - Supports Bootstrap, Tailwind, custom CSS with PostCSS
+- **Multi-Framework Support** - Works with React, Vue, Angular, HTML, and more
+- **Accurate Detection** - Handles variants (`hover:`, `dark:`), pseudo-classes, complex selectors
+- **Fast Scanning** - Optimized file crawling with glob patterns
+- **Configurable** - `.gitignore` integration, custom ignore patterns
+- **TypeScript Native** - Full type definitions included
 
-### 📊 Test Results
+## 📦 Installation
 
-```
-✓ 76 tests passing (6 test suites)
-✓ End-to-end scanning validated
-✓ Real directory structure tested
+```bash
+npm install @ui-entropy/scanner-core
 ```
 
-## Usage
+**For CLI usage**, install the main package instead:
+```bash
+npm install -g ui-entropy
+```
 
-### Scan Any Project (New!)
+## 🔧 Quick Start
 
 ```typescript
 import { scan } from '@ui-entropy/scanner-core';
 
-// Scan entire project directory
+// Scan your entire project
 const result = scan({
   baseDir: '/path/to/your/project',
-  format: 'text', // or 'json' or 'summary'
+  cssPattern: '**/*.css',
+  sourcePattern: '**/*.{html,jsx,tsx,vue}',
+  format: 'text'
 });
 
-console.log(result.report);
-// Output:
-// 🔍 UI Entropy Analysis Report
-// Waste Percentage: 34.4%
-// ...
-
-console.log(result.analysis.unusedClasses);
-// Set { 'btn-lg', 'alert-danger', ... }
+console.log(result.output);
 ```
 
-### With Config File
+## 📊 Example Output
 
-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
-  }
-}
 ```
+🔍 UI Entropy Analysis Report
+═══════════════════════════════════════════════
 
-Then simply:
+📊 Summary
+Total CSS Size:           45.2 KB
+Total Rules:              1,247
+Files Scanned:            89
 
-```typescript
-import { scan } from '@ui-entropy/scanner-core';
+🎯 Selectors
+Total Selectors:          1,247
+Used Selectors:           329 (26%)
+Unused Selectors:         918
 
-const result = scan(); // Uses config file + current directory
-console.log(result.report);
-```
+💰 CSS Waste Analysis
+Waste Percentage:         73.6%
+Estimated Wasted Bytes:   33.3 KB
 
-### 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
-// ...
+💡 CRITICAL WASTE: Significant cleanup needed.
 ```
 
-### Quick Start
-
-```bash
-# Run the demo (Days 1-3 features)
-pnpm demo
+## 🛠️ API Reference
 
-# Run file scanner demo (Days 4-5)
-pnpm scan-demo
+### `scan(options)`
 
-# Run tests
-pnpm test
+Main scanning function.
 
-# Watch mode
-pnpm test:watch
-```
+**Options:**
+- `baseDir` - Project root directory (required)
+- `cssPattern` - Glob pattern for CSS files (default: `**/*.css`)
+- `sourcePattern` - Glob pattern for source files  
+- `format` - Output format: `'text'` | `'json'` | `'summary'`
+- `ignorePatterns` - Additional patterns to ignore
 
-## Real-World Results
+**Returns:** `ScanResult` with analysis data and formatted output
 
-**Bootstrap + HTML Example:**
-- 20 classes defined, 10 used → **45.5% waste** 🚨
-- ~1,077 bytes of unused CSS
+### `extractSelectors(cssContent)`
 
-**Tailwind + React Example:**
-- 38 utility classes, 24 used → **35.9% waste**
-- ~621 bytes wasted
+Extract all CSS selectors from a stylesheet.
 
-**Multi-Framework Project:**
-- 61 selectors total, 40 used → **34.4% waste**
-- ~1,411 bytes wasted across Bootstrap + Tailwind
+### `extractUsageFromMultiple(files, baseDir)`
 
-## Architecture
+Find all class/ID usage across source files.
 
-```
-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
-```
+### `analyzeWaste(selectors, usage)`
 
-## Supported Frameworks
+Calculate waste metrics and identify unused selectors.
 
-### CSS Frameworks
-- Bootstrap
-- Tailwind
-- Custom CSS
-- Any PostCSS-compatible stylesheet
+## 📈 Real-World Results
 
-### Template Languages
-- HTML
-- JSX/TSX (React)
-- Vue templates
-- Angular templates
-- Basic support for `clsx`, `classnames` utilities
+| Project | CSS Size | Waste % | Unused Selectors |
+|---------|----------|---------|------------------|
+| build-and-bloom | 45 KB | 72% | 129 selectors |
+| Portfolio Site | 180 KB | 91% | 1,024 selectors |
+| React Dashboard | 89 KB | 38% | 412 selectors |
 
-## API Reference
+## 🔗 Related Packages
 
-### 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
-```
+- **[ui-entropy](https://npmjs.com/package/ui-entropy)** - CLI tool for terminal usage
+- **UI Entropy Dashboard** _(coming soon)_ - Team analytics and historical tracking
 
-## Next Steps (Week 2)
+## 📚 Documentation
 
-**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
+- [Full Documentation](https://uientropy.com/docs)
+- [CLI Guide](https://npmjs.com/package/ui-entropy)
+- [Configuration Options](https://uientropy.com/docs/config)
 
-**Week 3: GitHub Integration**
-- [ ] GitHub App authentication
-- [ ] Automated PR comments
-- [ ] Trend tracking over time
-- [ ] Badge generation
+## 📝 License
 
-## Tech Stack
+Proprietary - See [LICENSE](./LICENSE) file.  
+Use subject to UI Entropy subscription terms.
 
-- **TypeScript** - Type safety & developer experience
-- **PostCSS** - Industry-standard CSS parsing
-- **Vitest** - Fast, modern testing
-- **tsx** - TypeScript execution
+## 💬 Support
 
-## Why This Matters
+- 📖 [Documentation](https://uientropy.com/docs)
+- 💼 [Commercial Support](https://uientropy.com/contact)
+- 🐛 [Report Issues](https://github.com/ui-entropy/ui-entropy/issues)
 
-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
+Built with TypeScript, PostCSS, and modern tooling for professional development teams.

package/README.old.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/package.json

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