scss-variable-extractor 1.6.3 → 1.6.5

package/README.md

@@ -1,778 +1,1015 @@
-# SCSS Variable Extractor
-
-A standalone, reusable CLI tool that analyzes Angular project SCSS files, identifies repeated hardcoded values, extracts them into SCSS variables, and refactors the codebase to use those variables.
-
-## Features
-
-✨ **Automated Variable Extraction** - Identifies and extracts repeated hardcoded values  
-🎯 **Angular 15 & Material 15 Ready** - Follows best practices with `@use` imports  
-🔍 **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`  
-🔧 **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
-
-### From Git Repository
-
-```bash
-npm install git+https://github.com/lpaszkiewicz/scss-variable-extractor.git
-```
-
-### As a Git Submodule
-
-```bash
-git submodule add https://github.com/lpaszkiewicz/scss-variable-extractor.git tools/scss-extract
-cd tools/scss-extract
-npm install
-```
-
-### Local Development
-
-```bash
-git clone https://github.com/lpaszkiewicz/scss-variable-extractor.git
-cd scss-variable-extractor
-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
-# 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
-
-Create a `_variables.scss` file with extracted variables:
-
-```bash
-# 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
-
-Generate variables file AND replace hardcoded values in all SCSS files:
-
-```bash
-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
-
-### `analyze` - Dry-run Analysis
-
-Scans SCSS files and reports repeated values without modifying anything.
-
-```bash
-npx scss-extract analyze <src> [options]
-```
-
-**Arguments:**
-- `<src>` - Source directory to scan (required)
-
-**Options:**
-- `--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 --threshold 3 --format markdown
-```
-
-### `generate` - Generate Variables File
-
-Creates a `_variables.scss` file with extracted variables.
-
-```bash
-npx scss-extract generate <src> [options]
-```
-
-**Arguments:**
-- `<src>` - Source directory to scan (required)
-
-**Options:**
-- `--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 ./apps/myapp/src --output ./styles/_variables.scss
-```
-
-### `refactor` - Full Extraction + Replacement
-
-Generates variables file AND refactors SCSS files to use variables.
-
-```bash
-npx scss-extract refactor <src> [options]
-```
-
-**Arguments:**
-- `<src>` - Source directory to scan (required)
-
-**Options:**
-- `--output <path>` - Output path for variables file
-- `--threshold <number>` - Minimum repeat count
-- `--config <path>` - Path to custom config file
-
-**Example:**
-```bash
-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/styles/utilities.scss`)
-- `--no-custom-utilities` - Skip creating custom utility classes
-- `--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. Apply migration with custom utilities path
-npx scss-extract migrate-bootstrap --custom-utilities ./custom/utilities.scss
-
-# 5. Skip utilities generation
-npx scss-extract migrate-bootstrap --no-custom-utilities
-
-# 6. Review changes and test components
-# Manual review of generated utilities.scss and component templates
-```
-
-## Configuration
-
-Create a `.scssextractrc.json` file in your project root:
-
-```json
-{
-  "src": "./apps/subapp/src",
-  "output": "./libs/styles/_variables.scss",
-  "threshold": 2,
-  "categories": {
-    "colors": true,
-    "spacing": true,
-    "fontSizes": true,
-    "fontWeights": true,
-    "fontFamilies": true,
-    "borderRadius": true,
-    "shadows": true,
-    "zIndex": true,
-    "sizing": true,
-    "lineHeight": true,
-    "opacity": true,
-    "transitions": true
-  },
-  "spacingScale": {
-    "xxs": "2px",
-    "xs": "4px",
-    "sm": "8px",
-    "md": "16px",
-    "lg": "24px",
-    "xl": "32px",
-    "xxl": "48px"
-  },
-  "ignore": [
-    "**/node_modules/**",
-    "**/dist/**",
-    "**/_variables.scss"
-  ],
-  "importStyle": "use",
-  "reportFormat": "table"
-}
-```
-
-See [`.scssextractrc.example.json`](./.scssextractrc.example.json) for a complete example.
-
-## Value Detection Categories
-
-The tool detects and categorizes these types of repeated values:
-
-| Category | Prefix | Examples |
-|----------|--------|----------|
-| **Colors** | `$color-` | `#1976d2`, `rgb(25, 118, 210)`, `rgba(0,0,0,0.87)`, `white` |
-| **Spacing** | `$spacing-` | `4px`, `8px`, `16px`, `24px` (mapped to t-shirt sizes) |
-| **Font Sizes** | `$font-size-` | `12px`, `14px`, `16px`, `20px` |
-| **Font Weights** | `$font-weight-` | `400`, `500`, `700`, `bold` |
-| **Font Families** | `$font-family-` | `'Roboto', sans-serif` |
-| **Border Radius** | `$border-radius-` | `4px`, `8px`, `50%` |
-| **Box Shadows** | `$shadow-` | `0 2px 4px rgba(0,0,0,0.1)` |
-| **Z-Index** | `$z-index-` | `100`, `1000`, `9999` |
-| **Sizing** | `$size-` | Width/height pixel values |
-| **Line Height** | `$line-height-` | `1.5`, `1.25`, `24px` |
-| **Opacity** | `$opacity-` | `0.5`, `0.87` |
-| **Transitions** | `$transition-` | `all 0.3s ease` |
-
-## How It Works
-
-1. **Scanning** - Recursively finds all `.scss` files in the specified directory
-2. **Parsing** - Extracts hardcoded values using regex patterns
-3. **Analyzing** - Counts occurrences and groups by category
-4. **Generating** - Creates `_variables.scss` with smart variable names
-5. **Refactoring** - Replaces hardcoded values with `$variable` references
-
-## Variable Naming Convention
-
-The tool uses intelligent naming based on value patterns and context:
-
-- **Kebab-case** for all variable names
-- **Category prefixes** (e.g., `$color-`, `$spacing-`)
-- **Semantic names** when possible:
-  - `#1976d2` → `$color-brand-primary`
-  - `rgba(0,0,0,0.87)` → `$color-text-primary`
-  - `16px` (padding) → `$spacing-md`
-  - `14px` (font-size) → `$font-size-sm`
-  - `500` (font-weight) → `$font-weight-medium`
-
-### Spacing Scale (T-shirt Sizing)
-
-| Variable | Value |
-|----------|-------|
-| `$spacing-xxs` | `2px` |
-| `$spacing-xs` | `4px` |
-| `$spacing-sm` | `8px` |
-| `$spacing-md` | `16px` |
-| `$spacing-lg` | `24px` |
-| `$spacing-xl` | `32px` |
-| `$spacing-xxl` | `48px` |
-
-## Safe Refactoring Rules
-
-The tool **WILL NOT** replace values in these contexts:
-
-✅ Already-defined `$variable` declarations  
-✅ Values inside `url()` functions  
-✅ Values inside `content:` property  
-✅ Values inside string interpolation `#{}`  
-✅ Values inside `@use` or `@forward` statements  
-✅ Values inside comments  
-✅ Values in Angular Material mixin calls (e.g., `mat.define-palette()`)  
-✅ Single-use values (below the threshold)
-
-## Angular 15 + Material 15 Integration
-
-The tool is designed for Angular 15 and Angular Material 15 projects:
-
-- ✨ Uses `@use` syntax (not deprecated `@import`)
-- 🎨 Recognizes Material theming patterns
-- 🛡️ Preserves Material palette functions:
-  - `mat.define-palette()`
-  - `mat.get-color-from-palette()`
-  - `mat.define-light-theme()` / `mat.define-dark-theme()`
-  - `mat.all-component-themes()`
-
-### Generated Variables File
-
-```scss
-//
-// Auto-generated SCSS Variables
-// Generated by scss-variable-extractor v1.0.0
-// Generated at: 2026-02-12T13:00:00.000Z
-//
-// DO NOT EDIT THIS FILE MANUALLY
-// This file is auto-generated. Your changes will be overwritten.
-//
-
-// Colors
-// ────────────────────────────────────────
-$color-brand-primary: #1976d2;
-$color-text-primary: rgba(0, 0, 0, 0.87);
-$color-white: white;
-
-// Spacing
-// ────────────────────────────────────────
-$spacing-sm: 8px;
-$spacing-md: 16px;
-$spacing-lg: 24px;
-
-// Font Sizes
-// ────────────────────────────────────────
-$font-size-xs: 12px;
-$font-size-sm: 14px;
-$font-size-xl: 20px;
-```
-
-### Refactored Component Example
-
-**Before:**
-```scss
-.component-a {
-  background-color: #1976d2;
-  color: rgba(0, 0, 0, 0.87);
-  padding: 16px;
-  font-size: 14px;
-  border-radius: 4px;
-}
-```
-
-**After:**
-```scss
-@use '../../../libs/styles/variables' as *;
-
-.component-a {
-  background-color: $color-brand-primary;
-  color: $color-text-primary;
-  padding: $spacing-md;
-  font-size: $font-size-sm;
-  border-radius: $border-radius-sm;
-}
-```
-
-## Output Reports
-
-### Console Table (default)
-
-```
-Category     | Value              | Count | Files | Suggested Variable
-─────────────|────────────────────|───────|───────|─────────────────────
-color        | #1976d2            | 5     | 3     | $color-brand-primary
-color        | rgba(0,0,0,0.87)  | 8     | 6     | $color-text-primary
-spacing      | 16px              | 12    | 8     | $spacing-md
-font-size    | 14px              | 7     | 5     | $font-size-sm
-```
-
-### JSON (`--format json`)
-
-```json
-{
-  "colors": [
-    {
-      "value": "#1976d2",
-      "count": 5,
-      "fileCount": 3,
-      "suggestedName": "$color-brand-primary"
-    }
-  ]
-}
-```
-
-### Markdown (`--format markdown`)
-
-```markdown
-## Colors
-
-| Value | Count | Files | Suggested Variable |
-|-------|-------|-------|-------------------|
-| #1976d2 | 5 | 3 | `$color-brand-primary` |
-```
-
-## Testing
-
-Run the test suite:
-
-```bash
-npm test
-```
-
-Run tests with coverage:
-
-```bash
-npm test -- --coverage
-```
-
-## Project Structure
-
-```
-scss-variable-extractor/
-├── bin/
-│   └── cli.js                    # CLI entry point
-├── src/
-│   ├── scanner.js                # Finds .scss files
-│   ├── parser.js                 # Extracts hardcoded values
-│   ├── analyzer.js               # Identifies repeated values
-│   ├── generator.js              # Generates _variables.scss
-│   ├── refactorer.js             # Replaces values with variables
-│   ├── config.js                 # Configuration management
-│   └── index.js                  # Main exports
-├── templates/
-│   └── _variables.scss.template  # Variables file template
-├── test/
-│   ├── fixtures/                 # Sample SCSS files
-│   ├── scanner.test.js
-│   ├── parser.test.js
-│   ├── analyzer.test.js
-│   ├── generator.test.js
-│   └── refactorer.test.js
-├── .scssextractrc.example.json   # Example config
-├── package.json
-├── README.md
-└── LICENSE
-```
-
-## Requirements
-
-- **Node.js** >= 14.0.0
-- **npm** >= 6.0.0
-
-## Contributing
-
-Contributions are welcome! Please follow these guidelines:
-
-1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/amazing-feature`)
-3. Make your changes
-4. Add tests for new functionality
-5. Ensure all tests pass (`npm test`)
-6. Commit your changes (`git commit -m 'Add amazing feature'`)
-7. Push to the branch (`git push origin feature/amazing-feature`)
-8. Open a Pull Request
-
-## License
-
-MIT License - see [LICENSE](./LICENSE) file for details
-
-## Support
-
-- 🐛 [Report a bug](https://github.com/lpaszkiewicz/scss-variable-extractor/issues)
-- 💡 [Request a feature](https://github.com/lpaszkiewicz/scss-variable-extractor/issues)
-- 📖 [Documentation](https://github.com/lpaszkiewicz/scss-variable-extractor)
-
-## Changelog
-
-### 1.5.3 (2026-02-12)
-
-- **Fixed:** `migrate-bootstrap` now actually detects Bootstrap classes and generates utilities
-- **Fixed:** Invalid CSS ("Manual migration required") no longer added to utilities.scss
-- **Enhanced:** Utility classes are now properly added to customUtilitiesSet during migration
-- **Improved:** Component migrations are tracked and reported
-
-### 1.5.2 (2026-02-12)
-
-- **Fixed:** `migrate-bootstrap` command option renamed from `--utilities` to `--custom-utilities` to work with `--no-custom-utilities`
-- **Fixed:** Default utilities path corrected to `./src/styles/utilities.scss`
-
-### 1.5.1 (2026-02-12)
-
-- **Enhanced:** HTML class detection now handles spaces around `=` (e.g., `class = "py-3"`)
-- **Added:** Support for backtick quotes in class attributes (e.g., `class=\`py-3\``)
-- **Added:** Support for Angular property binding (e.g., `[class]="py-3"`)
-- **Improved:** More robust Bootstrap class detection across different HTML/template formats
-
-### 1.5.0 (2026-02-12)
-
-- **Fixed:** Bootstrap detection now scans SCSS class selectors (`.py-3`, `.mt-4`, etc.)
-- **Enhanced:** Bootstrap commands now scan SCSS, HTML, and TypeScript files
-- **Added:** New `scanTemplateFiles` function for comprehensive file scanning
-- **Improved:** Bootstrap class detection with deduplication
-
-### 1.4.0 (2026-02-12)
-
-- **Added:** Bootstrap to Angular Material migration capability
-- **Added:** `detect-bootstrap` command for analyzing Bootstrap usage
-- **Added:** `migrate-bootstrap` command for converting Bootstrap classes
-- **Added:** Custom utilities generation for flex/grid/spacing classes
-- **Added:** Material Design spacing scale (0, 4px, 8px, 16px, 24px, 48px)
-- 100+ Bootstrap class mappings
-
-### 1.3.0 (2026-02-12)
-
-- **Added:** Angular.json integration for automatic project configuration
-- **Added:** Auto-detection of source directory and style preprocessor
-- **Added:** Support for multi-project Angular workspaces
-- All commands support `--angular-json`, `--project`, `--no-angular` options
-
-### 1.2.0 (2026-02-12)
-
-- **Added:** Angular Material v15+ pattern refactoring
-- **Added:** `analyze-patterns` command to detect anti-patterns
-- **Added:** `modernize` command to remove `::ng-deep` and `!important`
-- Best practice enforcement with migration suggestions
-
-### 1.1.0 (2026-02-12)
-
-- **Added:** Global installation support via npm link/publish
-- **Added:** Positional `[src]` argument for all commands
-- **Enhanced:** Scan any folder in your project
-- **Improved:** CLI help and documentation
-
-### 1.0.0 (2026-02-12)
-
-- Initial release
-- Support for 12 value categories
-- Angular 15 & Material 15 compatibility
-- Three CLI commands: analyze, generate, refactor
-- Multiple report formats
-- Comprehensive test coverage
-
----
-
-Made with ❤️ for the Angular community
+# SCSS Variable Extractor
+
+A standalone, reusable CLI tool that analyzes Angular project SCSS files, identifies repeated hardcoded values, extracts them into SCSS variables, and refactors the codebase to use those variables.
+
+## Features
+
+✨ **Automated Variable Extraction** - Identifies and extracts repeated hardcoded values  
+🎯 **Angular 15 & Material 15 Ready** - Follows best practices with `@use` imports  
+🔍 **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`  
+🔧 **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  
+🎨 **Theme Generation** - Creates dark/light theme structure with Material Design support  
+✨ **Auto Formatting** - Prettier integration for consistent code style  
+🌍 **Global Styles Preservation** - Moves ::ng-deep and !important styles to global files
+
+## Installation
+
+### From Git Repository
+
+```bash
+npm install git+https://github.com/lpaszkiewicz/scss-variable-extractor.git
+```
+
+### As a Git Submodule
+
+```bash
+git submodule add https://github.com/lpaszkiewicz/scss-variable-extractor.git tools/scss-extract
+cd tools/scss-extract
+npm install
+```
+
+### Local Development
+
+```bash
+git clone https://github.com/lpaszkiewicz/scss-variable-extractor.git
+cd scss-variable-extractor
+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
+# 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
+
+Create a `_variables.scss` file with extracted variables:
+
+```bash
+# 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
+
+Generate variables file AND replace hardcoded values in all SCSS files:
+
+```bash
+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
+
+### `analyze` - Dry-run Analysis
+
+Scans SCSS files and reports repeated values without modifying anything.
+
+```bash
+npx scss-extract analyze <src> [options]
+```
+
+**Arguments:**
+
+- `<src>` - Source directory to scan (required)
+
+**Options:**
+
+- `--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 --threshold 3 --format markdown
+```
+
+### `generate` - Generate Variables File
+
+Creates a `_variables.scss` file with extracted variables.
+
+```bash
+npx scss-extract generate <src> [options]
+```
+
+**Arguments:**
+
+- `<src>` - Source directory to scan (required)
+
+**Options:**
+
+- `--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 ./apps/myapp/src --output ./styles/_variables.scss
+```
+
+### `refactor` - Full Extraction + Replacement
+
+Generates variables file AND refactors SCSS files to use variables.
+
+```bash
+npx scss-extract refactor <src> [options]
+```
+
+**Arguments:**
+
+- `<src>` - Source directory to scan (required)
+
+**Options:**
+
+- `--output <path>` - Output path for variables file
+- `--threshold <number>` - Minimum repeat count
+- `--config <path>` - Path to custom config file
+
+**Example:**
+
+```bash
+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
+- ✅ **Preserves styles in global file** - Extracts ng-deep and !important rules to global styles
+- ✅ **Prevents parent overrides** - Global styles maintain proper specificity
+- ✅ Provides warnings and suggestions for manual review
+- ✅ Maintains code functionality while improving maintainability
+
+**How Global Preservation Works:**
+
+When `--global-styles` is enabled (default), the tool:
+
+1. **Identifies** rules using `::ng-deep` or `!important`
+2. **Extracts** complete CSS rules with their selectors
+3. **Moves** them to the global styles file with source comments
+4. **Preserves** `!important` where necessary for specificity
+5. **Removes** them from component files
+
+This ensures styles aren't lost when parent components would otherwise override them.
+
+**Example:**
+
+Component file (before):
+
+```scss
+.my-component {
+  ::ng-deep .nested {
+    color: red !important; // Needed to override parent
+  }
+}
+```
+
+After refactoring:
+
+Component file:
+
+```scss
+.my-component {
+  // ng-deep and !important removed - see global styles
+}
+```
+
+Global styles file:
+
+```scss
+/* Moved from my-component.component.scss - requires !important for specificity */
+.my-component .nested {
+  color: red !important;
+}
+```
+
+**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/styles/utilities.scss`)
+- `--no-custom-utilities` - Skip creating custom utility classes
+- `--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. Apply migration with custom utilities path
+npx scss-extract migrate-bootstrap --custom-utilities ./custom/utilities.scss
+
+# 5. Skip utilities generation
+npx scss-extract migrate-bootstrap --no-custom-utilities
+
+# 6. Review changes and test components
+# Manual review of generated utilities.scss and component templates
+```
+
+---
+
+### `generate-themes` - Theme Structure Generator
+
+Generate a complete dark/light theme structure for Angular Material applications.
+
+```bash
+npx scss-extract generate-themes [src]
+
+# With options
+npx scss-extract generate-themes ./src --output ./src/styles --analyze
+```
+
+**Arguments:**
+
+- `[src]` - Source directory to analyze for colors (optional)
+
+**Options:**
+
+- `--output <dir>` - Output directory for theme files (default: `./src/styles`)
+- `--analyze` - Analyze existing styles for theme readiness
+- `--format <format>` - Report format for analysis (table, json, markdown)
+
+**What it generates:**
+
+✅ **Theme Files Created:**
+
+- `_theme-base.scss` - Shared variables (spacing, typography, shadows, z-index)
+- `_theme-light.scss` - Light theme color variables
+- `_theme-dark.scss` - Dark theme color variables
+- `themes.scss` - Angular Material theme configuration and loader
+- `_css-variables.scss` - CSS custom properties for runtime switching
+- `_component-theme-mixin.scss` - Template for component theme mixins
+
+✅ **Features:**
+
+- Material Design color palettes
+- Automatic dark/light mode switching
+- CSS custom properties support
+- Component theme mixin patterns
+- Proper encapsulation (no ::ng-deep needed!)
+
+**Example Usage:**
+
+```bash
+# Generate theme structure
+npx scss-extract generate-themes --output ./src/styles
+
+# Analyze existing styles first
+npx scss-extract generate-themes ./src --analyze --output ./src/styles
+```
+
+**Using Generated Themes:**
+
+1. Import in your `styles.scss`:
+
+```scss
+@use './styles/themes';
+```
+
+2. Add theme toggle to your app component:
+
+```typescript
+export class AppComponent {
+  isDarkMode = false;
+
+  toggleTheme() {
+    this.isDarkMode = !this.isDarkMode;
+  }
+}
+```
+
+```html
+<div [class.dark-theme]="isDarkMode">
+  <router-outlet></router-outlet>
+</div>
+```
+
+3. Use theme variables in components:
+
+```scss
+@use '../../styles/theme-base' as base;
+
+.my-component {
+  padding: base.$spacing-md;
+  border-radius: base.$border-radius-md;
+
+  &__header {
+    background-color: var(--color-primary);
+    color: var(--text-primary);
+  }
+}
+```
+
+**Theme Best Practices:**
+
+- ✅ Use SCSS variables for build-time constants (spacing, shadows)
+- ✅ Use CSS custom properties for runtime theme switching (colors)
+- ✅ Create component theme mixins instead of using ::ng-deep
+- ✅ Keep global styles in dedicated theme files
+- ❌ Avoid ViewEncapsulation.None unless absolutely necessary
+- ❌ Don't use ::ng-deep for theming - use theme mixins instead
+
+---
+
+## Auto Formatting
+
+The tool now includes Prettier for consistent code formatting:
+
+```bash
+# Format all files
+npm run format
+
+# Check formatting without changes
+npm run format:check
+```
+
+The formatting runs automatically before releases to ensure code quality.
+
+---
+
+## Configuration
+
+Create a `.scssextractrc.json` file in your project root:
+
+```json
+{
+  "src": "./apps/subapp/src",
+  "output": "./libs/styles/_variables.scss",
+  "threshold": 2,
+  "categories": {
+    "colors": true,
+    "spacing": true,
+    "fontSizes": true,
+    "fontWeights": true,
+    "fontFamilies": true,
+    "borderRadius": true,
+    "shadows": true,
+    "zIndex": true,
+    "sizing": true,
+    "lineHeight": true,
+    "opacity": true,
+    "transitions": true
+  },
+  "spacingScale": {
+    "xxs": "2px",
+    "xs": "4px",
+    "sm": "8px",
+    "md": "16px",
+    "lg": "24px",
+    "xl": "32px",
+    "xxl": "48px"
+  },
+  "ignore": ["**/node_modules/**", "**/dist/**", "**/_variables.scss"],
+  "importStyle": "use",
+  "reportFormat": "table"
+}
+```
+
+See [`.scssextractrc.example.json`](./.scssextractrc.example.json) for a complete example.
+
+## Value Detection Categories
+
+The tool detects and categorizes these types of repeated values:
+
+| Category          | Prefix            | Examples                                                    |
+| ----------------- | ----------------- | ----------------------------------------------------------- |
+| **Colors**        | `$color-`         | `#1976d2`, `rgb(25, 118, 210)`, `rgba(0,0,0,0.87)`, `white` |
+| **Spacing**       | `$spacing-`       | `4px`, `8px`, `16px`, `24px` (mapped to t-shirt sizes)      |
+| **Font Sizes**    | `$font-size-`     | `12px`, `14px`, `16px`, `20px`                              |
+| **Font Weights**  | `$font-weight-`   | `400`, `500`, `700`, `bold`                                 |
+| **Font Families** | `$font-family-`   | `'Roboto', sans-serif`                                      |
+| **Border Radius** | `$border-radius-` | `4px`, `8px`, `50%`                                         |
+| **Box Shadows**   | `$shadow-`        | `0 2px 4px rgba(0,0,0,0.1)`                                 |
+| **Z-Index**       | `$z-index-`       | `100`, `1000`, `9999`                                       |
+| **Sizing**        | `$size-`          | Width/height pixel values                                   |
+| **Line Height**   | `$line-height-`   | `1.5`, `1.25`, `24px`                                       |
+| **Opacity**       | `$opacity-`       | `0.5`, `0.87`                                               |
+| **Transitions**   | `$transition-`    | `all 0.3s ease`                                             |
+
+## How It Works
+
+1. **Scanning** - Recursively finds all `.scss` files in the specified directory
+2. **Parsing** - Extracts hardcoded values using regex patterns
+3. **Analyzing** - Counts occurrences and groups by category
+4. **Generating** - Creates `_variables.scss` with smart variable names
+5. **Refactoring** - Replaces hardcoded values with `$variable` references
+
+## Variable Naming Convention
+
+The tool uses intelligent naming based on value patterns and context:
+
+- **Kebab-case** for all variable names
+- **Category prefixes** (e.g., `$color-`, `$spacing-`)
+- **Semantic names** when possible:
+  - `#1976d2` → `$color-brand-primary`
+  - `rgba(0,0,0,0.87)` → `$color-text-primary`
+  - `16px` (padding) → `$spacing-md`
+  - `14px` (font-size) → `$font-size-sm`
+  - `500` (font-weight) → `$font-weight-medium`
+
+### Spacing Scale (T-shirt Sizing)
+
+| Variable       | Value  |
+| -------------- | ------ |
+| `$spacing-xxs` | `2px`  |
+| `$spacing-xs`  | `4px`  |
+| `$spacing-sm`  | `8px`  |
+| `$spacing-md`  | `16px` |
+| `$spacing-lg`  | `24px` |
+| `$spacing-xl`  | `32px` |
+| `$spacing-xxl` | `48px` |
+
+## Safe Refactoring Rules
+
+The tool **WILL NOT** replace values in these contexts:
+
+✅ Already-defined `$variable` declarations  
+✅ Values inside `url()` functions  
+✅ Values inside `content:` property  
+✅ Values inside string interpolation `#{}`  
+✅ Values inside `@use` or `@forward` statements  
+✅ Values inside comments  
+✅ Values in Angular Material mixin calls (e.g., `mat.define-palette()`)  
+✅ Single-use values (below the threshold)
+
+## Angular 15 + Material 15 Integration
+
+The tool is designed for Angular 15 and Angular Material 15 projects:
+
+- ✨ Uses `@use` syntax (not deprecated `@import`)
+- 🎨 Recognizes Material theming patterns
+- 🛡️ Preserves Material palette functions:
+  - `mat.define-palette()`
+  - `mat.get-color-from-palette()`
+  - `mat.define-light-theme()` / `mat.define-dark-theme()`
+  - `mat.all-component-themes()`
+
+### Generated Variables File
+
+```scss
+//
+// Auto-generated SCSS Variables
+// Generated by scss-variable-extractor v1.0.0
+// Generated at: 2026-02-12T13:00:00.000Z
+//
+// DO NOT EDIT THIS FILE MANUALLY
+// This file is auto-generated. Your changes will be overwritten.
+//
+
+// Colors
+// ────────────────────────────────────────
+$color-brand-primary: #1976d2;
+$color-text-primary: rgba(0, 0, 0, 0.87);
+$color-white: white;
+
+// Spacing
+// ────────────────────────────────────────
+$spacing-sm: 8px;
+$spacing-md: 16px;
+$spacing-lg: 24px;
+
+// Font Sizes
+// ────────────────────────────────────────
+$font-size-xs: 12px;
+$font-size-sm: 14px;
+$font-size-xl: 20px;
+```
+
+### Refactored Component Example
+
+**Before:**
+
+```scss
+.component-a {
+  background-color: #1976d2;
+  color: rgba(0, 0, 0, 0.87);
+  padding: 16px;
+  font-size: 14px;
+  border-radius: 4px;
+}
+```
+
+**After:**
+
+```scss
+@use '../../../libs/styles/variables' as *;
+
+.component-a {
+  background-color: $color-brand-primary;
+  color: $color-text-primary;
+  padding: $spacing-md;
+  font-size: $font-size-sm;
+  border-radius: $border-radius-sm;
+}
+```
+
+## Output Reports
+
+### Console Table (default)
+
+```
+Category     | Value              | Count | Files | Suggested Variable
+─────────────|────────────────────|───────|───────|─────────────────────
+color        | #1976d2            | 5     | 3     | $color-brand-primary
+color        | rgba(0,0,0,0.87)  | 8     | 6     | $color-text-primary
+spacing      | 16px              | 12    | 8     | $spacing-md
+font-size    | 14px              | 7     | 5     | $font-size-sm
+```
+
+### JSON (`--format json`)
+
+```json
+{
+  "colors": [
+    {
+      "value": "#1976d2",
+      "count": 5,
+      "fileCount": 3,
+      "suggestedName": "$color-brand-primary"
+    }
+  ]
+}
+```
+
+### Markdown (`--format markdown`)
+
+```markdown
+## Colors
+
+| Value   | Count | Files | Suggested Variable     |
+| ------- | ----- | ----- | ---------------------- |
+| #1976d2 | 5     | 3     | `$color-brand-primary` |
+```
+
+## Testing
+
+Run the test suite:
+
+```bash
+npm test
+```
+
+Run tests with coverage:
+
+```bash
+npm test -- --coverage
+```
+
+## Project Structure
+
+```
+scss-variable-extractor/
+├── bin/
+│   └── cli.js                    # CLI entry point
+├── src/
+│   ├── scanner.js                # Finds .scss files
+│   ├── parser.js                 # Extracts hardcoded values
+│   ├── analyzer.js               # Identifies repeated values
+│   ├── generator.js              # Generates _variables.scss
+│   ├── refactorer.js             # Replaces values with variables
+│   ├── config.js                 # Configuration management
+│   └── index.js                  # Main exports
+├── templates/
+│   └── _variables.scss.template  # Variables file template
+├── test/
+│   ├── fixtures/                 # Sample SCSS files
+│   ├── scanner.test.js
+│   ├── parser.test.js
+│   ├── analyzer.test.js
+│   ├── generator.test.js
+│   └── refactorer.test.js
+├── .scssextractrc.example.json   # Example config
+├── package.json
+├── README.md
+└── LICENSE
+```
+
+## Requirements
+
+- **Node.js** >= 14.0.0
+- **npm** >= 6.0.0
+
+## Contributing
+
+Contributions are welcome! Please follow these guidelines:
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes
+4. Add tests for new functionality
+5. Ensure all tests pass (`npm test`)
+6. Commit your changes (`git commit -m 'Add amazing feature'`)
+7. Push to the branch (`git push origin feature/amazing-feature`)
+8. Open a Pull Request
+
+## License
+
+MIT License - see [LICENSE](./LICENSE) file for details
+
+## Support
+
+- 🐛 [Report a bug](https://github.com/lpaszkiewicz/scss-variable-extractor/issues)
+- 💡 [Request a feature](https://github.com/lpaszkiewicz/scss-variable-extractor/issues)
+- 📖 [Documentation](https://github.com/lpaszkiewicz/scss-variable-extractor)
+
+## Changelog
+
+### 1.7.0 (2026-02-12)
+
+- **Added:** `generate-themes` command for automatic dark/light theme structure generation
+- **Added:** Prettier integration for automatic code formatting
+- **Added:** Theme utilities module with Material Design color palettes
+- **Enhanced:** `modernize` command now preserves ::ng-deep and !important styles in global files
+- **Enhanced:** !important rules are extracted to global styles instead of being removed
+- **Fixed:** Global styles preserve proper specificity to prevent parent component overrides
+- **Added:** Theme readiness analysis to identify hardcoded colors
+- **Added:** Component theme mixin template for proper encapsulation
+- **Added:** CSS custom properties support for runtime theme switching
+- **Added:** `format` and `format:check` npm scripts
+- **Improved:** Release process now includes automatic formatting
+
+### 1.5.3 (2026-02-12)
+
+- **Fixed:** `migrate-bootstrap` now actually detects Bootstrap classes and generates utilities
+- **Fixed:** Invalid CSS ("Manual migration required") no longer added to utilities.scss
+- **Enhanced:** Utility classes are now properly added to customUtilitiesSet during migration
+- **Improved:** Component migrations are tracked and reported
+
+### 1.5.2 (2026-02-12)
+
+- **Fixed:** `migrate-bootstrap` command option renamed from `--utilities` to `--custom-utilities` to work with `--no-custom-utilities`
+- **Fixed:** Default utilities path corrected to `./src/styles/utilities.scss`
+
+### 1.5.1 (2026-02-12)
+
+- **Enhanced:** HTML class detection now handles spaces around `=` (e.g., `class = "py-3"`)
+- **Added:** Support for backtick quotes in class attributes (e.g., `class=\`py-3\``)
+- **Added:** Support for Angular property binding (e.g., `[class]="py-3"`)
+- **Improved:** More robust Bootstrap class detection across different HTML/template formats
+
+### 1.5.0 (2026-02-12)
+
+- **Fixed:** Bootstrap detection now scans SCSS class selectors (`.py-3`, `.mt-4`, etc.)
+- **Enhanced:** Bootstrap commands now scan SCSS, HTML, and TypeScript files
+- **Added:** New `scanTemplateFiles` function for comprehensive file scanning
+- **Improved:** Bootstrap class detection with deduplication
+
+### 1.4.0 (2026-02-12)
+
+- **Added:** Bootstrap to Angular Material migration capability
+- **Added:** `detect-bootstrap` command for analyzing Bootstrap usage
+- **Added:** `migrate-bootstrap` command for converting Bootstrap classes
+- **Added:** Custom utilities generation for flex/grid/spacing classes
+- **Added:** Material Design spacing scale (0, 4px, 8px, 16px, 24px, 48px)
+- 100+ Bootstrap class mappings
+
+### 1.3.0 (2026-02-12)
+
+- **Added:** Angular.json integration for automatic project configuration
+- **Added:** Auto-detection of source directory and style preprocessor
+- **Added:** Support for multi-project Angular workspaces
+- All commands support `--angular-json`, `--project`, `--no-angular` options
+
+### 1.2.0 (2026-02-12)
+
+- **Added:** Angular Material v15+ pattern refactoring
+- **Added:** `analyze-patterns` command to detect anti-patterns
+- **Added:** `modernize` command to remove `::ng-deep` and `!important`
+- Best practice enforcement with migration suggestions
+
+### 1.1.0 (2026-02-12)
+
+- **Added:** Global installation support via npm link/publish
+- **Added:** Positional `[src]` argument for all commands
+- **Enhanced:** Scan any folder in your project
+- **Improved:** CLI help and documentation
+
+### 1.0.0 (2026-02-12)
+
+- Initial release
+- Support for 12 value categories
+- Angular 15 & Material 15 compatibility
+- Three CLI commands: analyze, generate, refactor
+- Multiple report formats
+- Comprehensive test coverage
+
+---
+
+Made with ❤️ for the Angular community