scss-variable-extractor 1.0.0

package/.scssextractrc.example.json

@@ -0,0 +1,35 @@
+{
+  "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"
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SCSS Variable Extractor Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,423 @@
+# 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`
+
+## 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
+
+### 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
+```
+
+### 2. Generate Variables File
+
+Create a `_variables.scss` file with extracted variables:
+
+```bash
+npx scss-extract generate --src ./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 --src ./apps/subapp/src --output ./libs/styles/_variables.scss
+```
+
+## CLI Commands
+
+### `analyze` - Dry-run Analysis
+
+Scans SCSS files and reports repeated values without modifying anything.
+
+```bash
+npx scss-extract analyze [options]
+```
+
+**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
+```
+
+### `generate` - Generate Variables File
+
+Creates a `_variables.scss` file with extracted variables.
+
+```bash
+npx scss-extract generate [options]
+```
+
+**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
+```
+
+### `refactor` - Full Extraction + Replacement
+
+Generates variables file AND refactors SCSS files to use variables.
+
+```bash
+npx scss-extract refactor [options]
+```
+
+**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
+
+**Example:**
+```bash
+npx scss-extract refactor --src ./apps/subapp/src --output ./libs/styles/_variables.scss
+```
+
+## 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.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

package/bin/cli.js

@@ -0,0 +1,226 @@
+#!/usr/bin/env node
+
+const { Command } = require('commander');
+const chalk = require('chalk');
+const path = require('path');
+const { loadConfig } = require('../src/config');
+const { scanScssFiles } = require('../src/scanner');
+const { parseScss } = require('../src/parser');
+const { analyzeValues } = require('../src/analyzer');
+const { generateVariablesFile, generateReport } = require('../src/generator');
+const { refactorScssFiles } = require('../src/refactorer');
+
+const program = new Command();
+
+program
+  .name('scss-extract')
+  .description('Analyzes Angular SCSS files and extracts repeated hardcoded values into reusable variables')
+  .version('1.0.0');
+
+// Analyze command
+program
+  .command('analyze')
+  .description('Dry-run analysis - identifies repeated values without modifying files')
+  .option('--src <path>', 'Source directory to scan')
+  .option('--threshold <number>', 'Minimum repeat count threshold', parseInt)
+  .option('--format <format>', 'Report format (table, json, markdown)', 'table')
+  .option('--config <path>', 'Path to config file')
+  .action(async (options) => {
+    try {
+      console.log(chalk.cyan.bold('\n🔍 SCSS Variable Extraction Analysis\n'));
+      
+      const config = loadConfig(options.config);
+      
+      // Override config with command-line options
+      if (options.src) config.src = options.src;
+      if (options.threshold) config.threshold = options.threshold;
+      if (options.format) config.reportFormat = options.format;
+      
+      console.log(chalk.gray(`Scanning: ${config.src}`));
+      console.log(chalk.gray(`Threshold: ${config.threshold} occurrences\n`));
+      
+      // Scan files
+      const files = await scanScssFiles(config.src, config.ignore);
+      console.log(chalk.green(`✓ Found ${files.length} SCSS files\n`));
+      
+      // Parse all files
+      const allExtracted = {
+        colors: [],
+        spacing: [],
+        fontSizes: [],
+        fontWeights: [],
+        fontFamilies: [],
+        borderRadius: [],
+        shadows: [],
+        zIndex: [],
+        sizing: [],
+        lineHeight: [],
+        opacity: [],
+        transitions: []
+      };
+      
+      files.forEach(file => {
+        const content = require('fs').readFileSync(file, 'utf8');
+        const extracted = parseScss(content, file);
+        
+        Object.keys(extracted).forEach(category => {
+          allExtracted[category].push(...extracted[category]);
+        });
+      });
+      
+      // Analyze
+      const analysis = analyzeValues(allExtracted, config);
+      
+      // Generate report
+      const report = generateReport(analysis, config.reportFormat, config);
+      console.log(report);
+      
+    } catch (error) {
+      console.error(chalk.red('✗ Error:'), error.message);
+      process.exit(1);
+    }
+  });
+
+// Generate command
+program
+  .command('generate')
+  .description('Generate variables file only (does not modify existing SCSS files)')
+  .option('--src <path>', 'Source directory to scan')
+  .option('--output <path>', 'Output path for variables file')
+  .option('--threshold <number>', 'Minimum repeat count threshold', parseInt)
+  .option('--config <path>', 'Path to config file')
+  .action(async (options) => {
+    try {
+      console.log(chalk.cyan.bold('\n📝 Generating SCSS Variables File\n'));
+      
+      const config = loadConfig(options.config);
+      
+      // Override config with command-line options
+      if (options.src) config.src = options.src;
+      if (options.output) config.output = options.output;
+      if (options.threshold) config.threshold = options.threshold;
+      
+      console.log(chalk.gray(`Scanning: ${config.src}`));
+      console.log(chalk.gray(`Output: ${config.output}\n`));
+      
+      // Scan files
+      const files = await scanScssFiles(config.src, config.ignore);
+      console.log(chalk.green(`✓ Found ${files.length} SCSS files`));
+      
+      // Parse all files
+      const allExtracted = {
+        colors: [],
+        spacing: [],
+        fontSizes: [],
+        fontWeights: [],
+        fontFamilies: [],
+        borderRadius: [],
+        shadows: [],
+        zIndex: [],
+        sizing: [],
+        lineHeight: [],
+        opacity: [],
+        transitions: []
+      };
+      
+      files.forEach(file => {
+        const content = require('fs').readFileSync(file, 'utf8');
+        const extracted = parseScss(content, file);
+        
+        Object.keys(extracted).forEach(category => {
+          allExtracted[category].push(...extracted[category]);
+        });
+      });
+      
+      // Analyze
+      const analysis = analyzeValues(allExtracted, config);
+      
+      // Generate variables file
+      generateVariablesFile(analysis, config.output, config);
+      
+      console.log(chalk.green(`\n✓ Generated variables file: ${config.output}`));
+      
+      // Show summary
+      const totalVars = Object.values(analysis).reduce((sum, arr) => sum + arr.length, 0);
+      console.log(chalk.bold(`\nTotal variables extracted: ${totalVars}\n`));
+      
+    } catch (error) {
+      console.error(chalk.red('✗ Error:'), error.message);
+      process.exit(1);
+    }
+  });
+
+// Refactor command
+program
+  .command('refactor')
+  .description('Full extraction + replacement (generates variables file and refactors SCSS files)')
+  .option('--src <path>', 'Source directory to scan')
+  .option('--output <path>', 'Output path for variables file')
+  .option('--threshold <number>', 'Minimum repeat count threshold', parseInt)
+  .option('--config <path>', 'Path to config file')
+  .action(async (options) => {
+    try {
+      console.log(chalk.cyan.bold('\n🔧 SCSS Refactoring - Full Extraction\n'));
+      
+      const config = loadConfig(options.config);
+      
+      // Override config with command-line options
+      if (options.src) config.src = options.src;
+      if (options.output) config.output = options.output;
+      if (options.threshold) config.threshold = options.threshold;
+      
+      console.log(chalk.gray(`Scanning: ${config.src}`));
+      console.log(chalk.gray(`Output: ${config.output}\n`));
+      
+      // Scan files
+      const files = await scanScssFiles(config.src, config.ignore);
+      console.log(chalk.green(`✓ Found ${files.length} SCSS files`));
+      
+      // Parse all files
+      const allExtracted = {
+        colors: [],
+        spacing: [],
+        fontSizes: [],
+        fontWeights: [],
+        fontFamilies: [],
+        borderRadius: [],
+        shadows: [],
+        zIndex: [],
+        sizing: [],
+        lineHeight: [],
+        opacity: [],
+        transitions: []
+      };
+      
+      files.forEach(file => {
+        const content = require('fs').readFileSync(file, 'utf8');
+        const extracted = parseScss(content, file);
+        
+        Object.keys(extracted).forEach(category => {
+          allExtracted[category].push(...extracted[category]);
+        });
+      });
+      
+      // Analyze
+      const analysis = analyzeValues(allExtracted, config);
+      
+      // Generate variables file
+      generateVariablesFile(analysis, config.output, config);
+      console.log(chalk.green(`✓ Generated variables file: ${config.output}`));
+      
+      // Refactor files
+      const refactoredFiles = refactorScssFiles(files, analysis, config.output, config);
+      console.log(chalk.green(`✓ Refactored ${refactoredFiles.length} SCSS files`));
+      
+      // Show summary
+      const totalVars = Object.values(analysis).reduce((sum, arr) => sum + arr.length, 0);
+      console.log(chalk.bold(`\nTotal variables extracted: ${totalVars}`));
+      console.log(chalk.bold(`Files modified: ${refactoredFiles.length}\n`));
+      
+    } catch (error) {
+      console.error(chalk.red('✗ Error:'), error.message);
+      process.exit(1);
+    }
+  });
+
+program.parse();