scss-variable-extractor 1.0.0 → 1.4.0

package/README.md

@@ -9,7 +9,11 @@ A standalone, reusable CLI tool that analyzes Angular project SCSS files, identi
 🔍 **Smart Pattern Recognition** - Detects colors, spacing, fonts, shadows, and more  
 📊 **Multiple Report Formats** - Table, JSON, or Markdown output  
 🛡️ **Safe Refactoring** - Preserves existing variables and avoids unsafe replacements  
-⚙️ **Highly Configurable** - Customize via `.scssextractrc.json`
+⚙️ **Highly Configurable** - Customize via `.scssextractrc.json`  
+🔧 **Modernization Tools** - Removes `::ng-deep` and `!important` anti-patterns  
+🚀 **Global Scope Scanning** - Analyze any folder in your project  
+📐 **Angular.json Integration** - Automatically detects project structure and settings  
+🔄 **Bootstrap to Material Migration** - Converts Bootstrap classes to Angular Material MDC components and utilities
 
 ## Installation
 
@@ -37,12 +41,18 @@ npm install
 
 ## Quick Start
 
+> **💡 Tip:** If you have an `angular.json` file, you can omit the source path - the tool will auto-detect your project structure!
+
 ### 1. Analyze (Dry Run)
 
 See what values would be extracted without modifying any files:
 
 ```bash
-npx scss-extract analyze --src ./apps/subapp/src --threshold 2
+# With angular.json (auto-detects project)
+npx scss-extract analyze
+
+# Or specify path manually
+npx scss-extract analyze ./apps/subapp/src --threshold 2
 ```
 
 ### 2. Generate Variables File
@@ -50,7 +60,11 @@ npx scss-extract analyze --src ./apps/subapp/src --threshold 2
 Create a `_variables.scss` file with extracted variables:
 
 ```bash
-npx scss-extract generate --src ./apps/subapp/src --output ./libs/styles/_variables.scss
+# With angular.json
+npx scss-extract generate
+
+# Or specify paths manually
+npx scss-extract generate ./apps/subapp/src --output ./libs/styles/_variables.scss
 ```
 
 ### 3. Full Refactoring
@@ -58,7 +72,19 @@ npx scss-extract generate --src ./apps/subapp/src --output ./libs/styles/_variab
 Generate variables file AND replace hardcoded values in all SCSS files:
 
 ```bash
-npx scss-extract refactor --src ./apps/subapp/src --output ./libs/styles/_variables.scss
+npx scss-extract refactor ./apps/subapp/src --output ./libs/styles/_variables.scss
+```
+
+### 4. Modernize Code (Remove Anti-Patterns)
+
+Remove `::ng-deep` and `!important` following Angular Material v15+ best practices:
+
+```bash
+# Preview changes first
+npx scss-extract modernize ./src --dry-run
+
+# Apply modernization
+npx scss-extract modernize ./src
 ```
 
 ## CLI Commands
@@ -68,18 +94,20 @@ npx scss-extract refactor --src ./apps/subapp/src --output ./libs/styles/_variab
 Scans SCSS files and reports repeated values without modifying anything.
 
 ```bash
-npx scss-extract analyze [options]
+npx scss-extract analyze <src> [options]
 ```
 
+**Arguments:**
+- `<src>` - Source directory to scan (required)
+
 **Options:**
-- `--src <path>` - Source directory to scan (default: `./apps/subapp/src`)
 - `--threshold <number>` - Minimum repeat count (default: `2`)
 - `--format <format>` - Report format: `table`, `json`, `markdown` (default: `table`)
 - `--config <path>` - Path to custom config file
 
 **Example:**
 ```bash
-npx scss-extract analyze --src ./src --threshold 3 --format markdown
+npx scss-extract analyze ./src --threshold 3 --format markdown
 ```
 
 ### `generate` - Generate Variables File
@@ -87,18 +115,20 @@ npx scss-extract analyze --src ./src --threshold 3 --format markdown
 Creates a `_variables.scss` file with extracted variables.
 
 ```bash
-npx scss-extract generate [options]
+npx scss-extract generate <src> [options]
 ```
 
+**Arguments:**
+- `<src>` - Source directory to scan (required)
+
 **Options:**
-- `--src <path>` - Source directory to scan
 - `--output <path>` - Output path for variables file (default: `./libs/styles/_variables.scss`)
 - `--threshold <number>` - Minimum repeat count
 - `--config <path>` - Path to custom config file
 
 **Example:**
 ```bash
-npx scss-extract generate --src ./apps/myapp/src --output ./styles/_variables.scss
+npx scss-extract generate ./apps/myapp/src --output ./styles/_variables.scss
 ```
 
 ### `refactor` - Full Extraction + Replacement
@@ -106,11 +136,13 @@ npx scss-extract generate --src ./apps/myapp/src --output ./styles/_variables.sc
 Generates variables file AND refactors SCSS files to use variables.
 
 ```bash
-npx scss-extract refactor [options]
+npx scss-extract refactor <src> [options]
 ```
 
+**Arguments:**
+- `<src>` - Source directory to scan (required)
+
 **Options:**
-- `--src <path>` - Source directory to scan
 - `--output <path>` - Output path for variables file
 - `--threshold <number>` - Minimum repeat count
 - `--config <path>` - Path to custom config file
@@ -120,6 +152,266 @@ npx scss-extract refactor [options]
 npx scss-extract refactor --src ./apps/subapp/src --output ./libs/styles/_variables.scss
 ```
 
+### `analyze-patterns` - Analyze Angular Anti-Patterns
+
+Scans SCSS files for Angular Material v15+ anti-patterns like `::ng-deep` and `!important` usage.
+
+```bash
+npx scss-extract analyze-patterns <src> [options]
+```
+
+**Arguments:**
+- `<src>` - Source directory to scan (required)
+
+**Options:**
+- `--format <format>` - Report format: `table`, `json`, `markdown` (default: `table`)
+- `--config <path>` - Path to custom config file
+
+**Example:**
+```bash
+npx scss-extract analyze-patterns ./src --format table
+```
+
+### `modernize` - Refactor to Angular Material v15+ Best Practices
+
+Automatically refactors SCSS files by removing `::ng-deep`, `/deep/`, `>>>`, and `!important` declarations, following Angular Material v15+ best practices.
+
+```bash
+npx scss-extract modernize <src> [options]
+```
+
+**Arguments:**
+- `<src>` - Source directory to scan (required)
+
+**Options:**
+- `--global-styles <path>` - Path to global styles file (default: `./src/styles.scss`)
+- `--no-ng-deep` - Skip ::ng-deep refactoring
+- `--no-important` - Skip !important refactoring
+- `--dry-run` - Preview changes without modifying files
+- `--config <path>` - Path to custom config file
+
+**Example:**
+```bash
+# Preview changes
+npx scss-extract modernize ./src --dry-run
+
+# Apply changes
+npx scss-extract modernize ./src --global-styles ./src/styles.scss
+```
+
+**What it does:**
+- ✅ Removes `::ng-deep`, `/deep/`, and `>>>` (deprecated shadow-piercing selectors)
+- ✅ Removes `!important` declarations (suggests increasing specificity instead)
+- ✅ Extracts styles that were using `::ng-deep` to global styles file
+- ✅ Provides warnings and suggestions for manual review
+
+**Angular Material v15+ Best Practices:**
+- Use CSS custom properties for theming
+- Use Angular Material theme mixins for component customization
+- Place global styles in `styles.scss` instead of using `::ng-deep`
+- Increase selector specificity instead of using `!important`
+- Consider `ViewEncapsulation.None` for components that need global styles
+
+## Angular.json Integration
+
+The tool can automatically read your `angular.json` file to detect project structure and apply the correct schematics for style refactoring.
+
+### Auto-detection
+
+By default, all commands will look for `angular.json` in the current directory and use it to configure:
+- Source directory (`sourceRoot`)
+- Output path for variables (based on global styles)
+- Style preprocessor (scss, sass, less, css)
+- Component prefix
+- Ignore patterns (`.angular`, `dist`, etc.)
+
+### Usage
+
+**Without angular.json (manual configuration):**
+```bash
+scss-extract analyze ./apps/myapp/src
+```
+
+**With angular.json (auto-configured):**
+```bash
+# Uses default project from angular.json
+scss-extract analyze
+
+# Use specific project
+scss-extract analyze --project myapp
+
+# Specify angular.json location
+scss-extract analyze --angular-json ./path/to/angular.json
+```
+
+**Disable angular.json integration:**
+```bash
+scss-extract analyze ./src --no-angular
+```
+
+### All Commands Support Angular.json
+
+Every command supports these options:
+- `--angular-json <path>` - Path to angular.json file
+- `--project <name>` - Specify which project to use
+- `--no-angular` - Disable angular.json integration
+
+**Examples:**
+```bash
+# Analyze with angular.json
+scss-extract analyze --project frontend
+
+# Generate with specific project
+scss-extract generate --project admin-app
+
+# Modernize with angular.json auto-detection
+scss-extract modernize --dry-run
+
+# Refactor specific project
+scss-extract refactor --project mylib --output ./libs/mylib/styles/_variables.scss
+```
+
+### What Gets Auto-Configured
+
+When angular.json is detected, the tool automatically sets:
+
+| Config | Source |
+|--------|--------|
+| **src** | `project.sourceRoot` (e.g., `apps/myapp/src`) |
+| **output** | Derived from global styles location |
+| **styleExt** | From project schematics (scss, sass, etc.) |
+| **prefix** | Component prefix (e.g., `app`, `lib`) |
+| **ignore** | Adds `.angular/`, `dist/`, `out-tsc/` |
+
+The tool will display the detected Angular project info:
+```
+Angular Project: myapp
+Prefix: app
+Style: scss
+```
+
+## Bootstrap to Angular Material Migration
+
+Automatically detect and migrate Bootstrap classes to Angular Material MDC-based components and utilities. For flex/grid/spacing classes, the tool generates custom utilities.
+
+### Detect Bootstrap Usage
+
+Analyze your codebase for Bootstrap classes and get a comprehensive report:
+
+```bash
+npx scss-extract detect-bootstrap [src]
+
+# With output format
+npx scss-extract detect-bootstrap ./src --format table
+npx scss-extract detect-bootstrap ./src --format json
+npx scss-extract detect-bootstrap ./src --format markdown
+```
+
+**Arguments:**
+- `[src]` - Source directory to scan (optional, auto-detected from angular.json)
+
+**Options:**
+- `--format <type>` - Output format: table, json, markdown (default: table)
+- `--angular-json <path>` - Path to angular.json file
+- `--project <name>` - Specify which project to use
+- `--no-angular` - Disable angular.json integration
+
+**Example Output:**
+```
+Bootstrap Usage Report
+┌────────────┬───────┬─────────────────────────────────────────┐
+│ Category   │ Count │ Classes                                 │
+├────────────┼───────┼─────────────────────────────────────────┤
+│ Components │ 5     │ btn, card, form-control, navbar, modal  │
+│ Utilities  │ 12    │ d-flex, m-3, p-2, text-center, etc.     │
+└────────────┴───────┴─────────────────────────────────────────┘
+```
+
+### Migrate Bootstrap to Material
+
+Convert Bootstrap classes to Angular Material equivalents:
+
+```bash
+npx scss-extract migrate-bootstrap [src]
+
+# With options
+npx scss-extract migrate-bootstrap ./src --custom-utilities ./src/utilities.scss --dry-run
+```
+
+**Arguments:**
+- `[src]` - Source directory to scan (optional, auto-detected from angular.json)
+
+**Options:**
+- `--custom-utilities <path>` - Path for custom utilities file (default: `./src/utilities.scss`)
+- `--dry-run` - Preview changes without modifying files
+- `--angular-json <path>` - Path to angular.json file
+- `--project <name>` - Specify which project to use
+- `--no-angular` - Disable angular.json integration
+
+**What it does:**
+
+✅ **Component Migrations:**
+- `btn` → `mat-button` / `mat-raised-button` / `mat-stroked-button`
+- `card` → `mat-card` with `mat-card-header`, `mat-card-content`, `mat-card-actions`
+- `form-control` → `mat-form-field` with `matInput`
+- `navbar` → `mat-toolbar`
+- `modal` → `mat-dialog`
+- And 50+ more component mappings
+
+✅ **Utility Migrations:**
+- `d-flex` → Custom flex utilities
+- `justify-content-*` → Custom flexbox utilities
+- `align-items-*` → Custom flexbox utilities
+- `m-*`, `p-*` → Custom spacing utilities (0-5 scale)
+- `text-*` → Custom text utilities
+- `w-*`, `h-*` → Custom sizing utilities
+
+✅ **Generated Custom Utilities:**
+Creates a `utilities.scss` file with Material Design-aligned spacing:
+```scss
+// Spacing utilities (0, 4px, 8px, 16px, 24px, 48px)
+.m-0 { margin: 0; }
+.m-1 { margin: 4px; }
+.m-2 { margin: 8px; }
+.m-3 { margin: 16px; }
+.p-t-2 { padding-top: 8px; }
+
+// Flexbox utilities
+.d-flex { display: flex; }
+.justify-content-center { justify-content: center; }
+
+// Display utilities
+.d-block { display: block; }
+.d-none { display: none; }
+
+// Text utilities
+.text-center { text-align: center; }
+.fw-bold { font-weight: 700; }
+```
+
+**Migration Warnings:**
+
+The tool provides warnings for manual review items:
+- ⚠️ Bootstrap grid system → Material Layout or CSS Grid
+- ⚠️ Bootstrap forms → Material form fields (requires template changes)
+- ⚠️ Bootstrap modals → Material dialogs (requires component refactoring)
+- ⚠️ Complex component compositions → Manual Material implementation
+
+**Example Workflow:**
+```bash
+# 1. Detect Bootstrap usage
+npx scss-extract detect-bootstrap --format table
+
+# 2. Preview migration
+npx scss-extract migrate-bootstrap --dry-run
+
+# 3. Apply migration
+npx scss-extract migrate-bootstrap
+
+# 4. Review changes and test components
+# Manual review of generated utilities.scss and component templates
+```
+
 ## Configuration
 
 Create a `.scssextractrc.json` file in your project root: