scss-variable-extractor 1.9.1 → 2.0.1

package/README.md

@@ -43,54 +43,154 @@ cd scss-variable-extractor
 npm install
 ```
 
+## ⚡ Minimal Example
+
+**Got an Angular project? Generate a theme in one command:**
+
+```bash
+cd my-angular-app
+npx scss-extract generate-themes --analyze
+```
+
+That's it! The tool:
+
+- ✅ Finds your Angular project from `angular.json`
+- ✅ Scans your SCSS files
+- ✅ Extracts your app's actual colors
+- ✅ Generates complete dark/light theme structure
+- ✅ Places files in the right location
+
+No configuration needed! 🎉
+
 ## Quick Start
 
-> **💡 Tip:** If you have an `angular.json` file, you can omit the source path - the tool will auto-detect your project structure!
+> **� Zero Config:** If you have an `angular.json` file, just run the commands without any arguments - the tool automatically detects your project structure, source directories, and output paths!
 
 ### 1. Analyze (Dry Run)
 
 See what values would be extracted without modifying any files:
 
 ```bash
-# With angular.json (auto-detects project)
+# Auto-detects everything from angular.json ✨
 npx scss-extract analyze
 
 # Or specify path manually
 npx scss-extract analyze ./apps/subapp/src --threshold 2
 ```
 
-### 2. Generate Variables File
+### 2. Generate Theme Structure (Most Used!)
+
+Generate a complete dark/light theme with colors extracted from your app:
+
+```bash
+# Auto-detects project and extracts YOUR colors! ✨
+npx scss-extract generate-themes --analyze
+
+# Without color extraction (uses Material defaults)
+npx scss-extract generate-themes
+```
+
+### 3. Generate Variables File
 
 Create a `_variables.scss` file with extracted variables:
 
 ```bash
-# With angular.json
+# Auto-detects project ✨
 npx scss-extract generate
 
 # Or specify paths manually
 npx scss-extract generate ./apps/subapp/src --output ./libs/styles/_variables.scss
 ```
 
-### 3. Full Refactoring
+### 4. Full Refactoring
 
 Generate variables file AND replace hardcoded values in all SCSS files:
 
 ```bash
+# Auto-detects project ✨
+npx scss-extract refactor
+
+# Or specify paths manually
 npx scss-extract refactor ./apps/subapp/src --output ./libs/styles/_variables.scss
 ```
 
-### 4. Modernize Code (Remove Anti-Patterns)
+### 5. 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
+# Preview changes first (auto-detects project) ✨
+npx scss-extract modernize --dry-run
 
 # Apply modernization
-npx scss-extract modernize ./src
+npx scss-extract modernize
+```
+
+## 🔧 Angular.json Integration
+
+The tool **automatically detects and uses your Angular project structure** from `angular.json`. This means you can run commands **without specifying any paths**!
+
+### How It Works
+
+When you run a command (like `generate-themes --analyze`), the tool:
+
+1. **Finds angular.json** in your current directory
+2. **Detects your project** (uses default project or specify with `--project`)
+3. **Auto-discovers:**
+   - ✅ Source directory (`src/app`, etc.)
+   - ✅ Global styles location (`src/styles.scss`)
+   - ✅ Output path for generated files
+   - ✅ Style preprocessor (scss, sass, css)
+   - ✅ Project prefix and configuration
+
+### Example
+
+Instead of:
+
+```bash
+# ❌ Manual paths - tedious!
+npx scss-extract generate-themes ./apps/my-app/src --output ./apps/my-app/src/styles
+```
+
+Just run:
+
+```bash
+# ✅ Auto-detects everything!
+npx scss-extract generate-themes --analyze
+```
+
+### Multi-Project Workspaces
+
+If you have multiple projects in your Angular workspace:
+
+```bash
+# Use specific project
+npx scss-extract generate-themes --analyze --project my-app
+
+# Use default project (auto-detected)
+npx scss-extract generate-themes --analyze
+```
+
+### Disable Auto-Detection
+
+If you want to use manual paths instead:
+
+```bash
+npx scss-extract generate-themes ./src --output ./src/styles --no-angular
 ```
 
+### All Commands Support angular.json
+
+Every command works with angular.json integration:
+
+- `analyze`
+- `generate`
+- `refactor`
+- `modernize`
+- `generate-themes` ⭐
+- `detect-bootstrap`
+- `migrate-bootstrap`
+
 ## CLI Commands
 
 ### `analyze` - Dry-run Analysis
@@ -573,13 +673,66 @@ npx scss-extract generate-themes ./src --output ./src/styles --analyze
 **Example Usage:**
 
 ```bash
-# Generate theme structure with default Material colors
-npx scss-extract generate-themes --output ./src/styles
+# 🚀 SIMPLEST: Auto-detects everything from angular.json and extracts YOUR colors!
+npx scss-extract generate-themes --analyze
+
+# Without color extraction (uses Material Design defaults)
+npx scss-extract generate-themes
 
-# 🎨 Analyze existing styles and use YOUR app's colors
+# Manual paths (if no angular.json)
 npx scss-extract generate-themes ./src --analyze --output ./src/styles
 ```
 
+**Output Example:**
+
+When you run with `--analyze`, you'll see:
+
+```
+🎨 Theme Structure Generator
+
+📦 Angular Project: my-app
+   Prefix: app
+   Style: scss
+   Source: src/app
+
+🔍 Analyzing styles in: src/app
+
+   Found 47 SCSS files
+
+📊 Theme Readiness Analysis:
+
+   Total hardcoded colors: 156
+   Unique colors: 12
+   Components needing theme mixins: 8
+
+🎨 Extracted Color Palettes:
+
+Primary Color:
+  Light theme: #007bff
+  Dark theme:  #66b0ff
+
+Accent Color:
+  Light theme: #28a745
+  Dark theme:  #74d77c
+
+Warn Color:
+  Light theme: #dc3545
+  Dark theme:  #dc3545
+
+📁 Output directory: src/styles
+
+✓ Using extracted colors from your app
+
+✓ Created _theme-base.scss
+✓ Created _theme-light.scss
+✓ Created _theme-dark.scss
+✓ Created themes.scss
+✓ Created _css-variables.scss
+✓ Created _component-theme-mixin.scss
+
+✓ Theme structure generated!
+```
+
 **How Color Extraction Works:**
 
 When you use `--analyze`, the tool:
@@ -1202,6 +1355,38 @@ MIT License - see [LICENSE](./LICENSE) file for details
 
 ## Changelog
 
+### 2.0.0 (2026-02-12) - Zero Config Release 🚀
+
+**BREAKING CHANGES:**
+
+- `generate-themes --output` default removed (now auto-detected from angular.json)
+
+**Major Improvements:**
+
+- **🎉 Zero Configuration:** All commands now fully leverage angular.json integration
+- **✨ Auto-Detection:** `generate-themes` automatically finds source directory and output path
+- **📦 Smart Project Detection:** Shows Angular project info (name, prefix, style preprocessor)
+- **🔧 Simplified Usage:** Just run `npx scss-extract generate-themes --analyze` - no arguments needed!
+- **📚 Comprehensive Documentation:** New angular.json integration guide
+- **⚡ Minimal Example:** Added quick-start section showing one-command theme generation
+- **🎯 Better UX:** Clearer console output with project context and file counts
+- **💡 Helpful Tips:** Shows suggestions when auto-detection features aren't used
+
+**Enhanced Commands:**
+
+- `generate-themes` now accepts `--angular-json`, `--project`, `--no-angular` options
+- Auto-detects output directory from global styles configuration
+- Shows Angular project metadata in output
+- Provides context-aware help messages
+
+**Documentation:**
+
+- Added "Minimal Example" section showing simplest usage
+- Added "Angular.json Integration" section explaining auto-detection
+- Updated all examples to show angular.json usage first
+- Improved THEME-GUIDE.md with zero-config examples
+- Added output examples showing what users will see
+
 ### 1.9.0 (2026-02-12)
 
 - **Added:** 🎨 Automatic color extraction from existing app styles

package/THEME-GUIDE.md

@@ -101,8 +101,25 @@ This ensures only your **brand colors** are selected for theme palettes.
 
 Generate a complete theme structure for your Angular Material app:
 
+### With angular.json (Recommended - Zero Config!)
+
+```bash
+# 🚀 Auto-detects everything and extracts YOUR app's colors!
+npx scss-extract generate-themes --analyze
+```
+
+That's it! The tool automatically:
+
+- ✅ Finds your Angular project from angular.json
+- ✅ Detects source directory
+- ✅ Places theme files in your styles folder
+- ✅ Extracts actual colors from your app
+- ✅ Generates dark/light theme variants
+
+### Without angular.json (Manual Paths)
+
 ```bash
-# Analyze existing styles and generate themes
+# Specify paths manually
 npx scss-extract generate-themes ./src --analyze --output ./src/styles
 ```
 

package/bin/cli.js

@@ -694,58 +694,102 @@ program
 program
   .command('generate-themes')
   .description('Generate theme structure for dark/light mode support with Angular Material')
-  .argument('[src]', 'Source directory to scan for analysis (optional)')
-  .option('--output <dir>', 'Output directory for theme files', './src/styles')
-  .option('--analyze', 'Analyze existing styles for theme readiness')
+  .argument('[src]', 'Source directory to scan for analysis (optional if using angular.json)')
+  .option('--output <dir>', 'Output directory for theme files (auto-detected from angular.json)')
+  .option('--analyze', 'Analyze existing styles and extract colors from your app')
   .option('--format <format>', 'Report format (table, json, markdown)', 'table')
+  .option('--angular-json <path>', 'Path to angular.json file')
+  .option('--project <name>', 'Angular project name (uses default if not specified)')
+  .option('--no-angular', 'Disable angular.json integration')
   .action(async (src, options) => {
     try {
       console.log(chalk.cyan.bold('\n🎨 Theme Structure Generator\n'));
 
       const fs = require('fs');
-      const outputDir = path.resolve(options.output);
+
+      // Load config with angular.json integration
+      const config = loadConfig(null, {
+        useAngularJson: options.angular !== false,
+        angularJsonPath: options.angularJson,
+        projectName: options.project,
+      });
+
+      // Override with command-line options
+      if (src) {
+        config.src = src;
+      }
+
+      // Determine output directory
+      let outputDir;
+      if (options.output) {
+        outputDir = path.resolve(options.output);
+      } else if (config.angular && config.output) {
+        // Use the styles directory from angular.json
+        outputDir = path.resolve(path.dirname(config.output));
+      } else {
+        outputDir = path.resolve('./src/styles');
+      }
+
+      // Show Angular project info if available
+      if (config.angular) {
+        console.log(chalk.cyan(`📦 Angular Project: ${config.angular.project}`));
+        console.log(chalk.gray(`   Prefix: ${config.angular.prefix}`));
+        console.log(chalk.gray(`   Style: ${config.angular.stylePreprocessor}`));
+        console.log(chalk.gray(`   Source: ${config.src}\n`));
+      }
+
       let extractedPalettes = null;
 
       // Analyze existing styles if requested
-      if (options.analyze && src) {
-        console.log(chalk.gray(`Analyzing: ${src}\n`));
-        const config = loadConfig();
-        const files = await scanScssFiles(src, config.ignore);
-        const analysis = analyzeThemeReadiness(files);
-
-        console.log(chalk.blue.bold('Theme Readiness Analysis:\n'));
-        console.log(chalk.gray(`Total hardcoded colors: ${analysis.hardcodedColors.length}`));
-        console.log(chalk.gray(`Unique colors: ${analysis.colorUsage.size}`));
-        console.log(
-          chalk.gray(`Components needing theme mixins: ${analysis.themeableComponents.length}\n`)
-        );
+      if (options.analyze) {
+        const scanDir = config.src || './src';
+        console.log(chalk.gray(`🔍 Analyzing styles in: ${scanDir}\n`));
 
-        // Extract color palettes from usage
-        extractedPalettes = extractColorPalettes(analysis.colorUsage);
-
-        console.log(chalk.green.bold('🎨 Extracted Color Palettes:\n'));
-        console.log(chalk.cyan('Primary Color:'));
-        console.log(chalk.gray(`  Light theme: ${extractedPalettes.primary.light}`));
-        console.log(chalk.gray(`  Dark theme:  ${extractedPalettes.primary.dark}`));
-        console.log(chalk.cyan('Accent Color:'));
-        console.log(chalk.gray(`  Light theme: ${extractedPalettes.accent.light}`));
-        console.log(chalk.gray(`  Dark theme:  ${extractedPalettes.accent.dark}`));
-        console.log(chalk.cyan('Warn Color:'));
-        console.log(chalk.gray(`  Light theme: ${extractedPalettes.warn.light}`));
-        console.log(chalk.gray(`  Dark theme:  ${extractedPalettes.warn.dark}\n`));
-
-        if (analysis.recommendations.length > 0) {
-          console.log(chalk.yellow.bold('📋 Recommendations:\n'));
-          analysis.recommendations.forEach(rec => {
-            const icon = rec.priority === 'high' ? '🔴' : '🟡';
-            console.log(chalk.gray(`${icon} ${rec.message}`));
-          });
-          console.log();
+        const files = await scanScssFiles(scanDir, config.ignore);
+
+        if (files.length === 0) {
+          console.log(chalk.yellow('⚠  No SCSS files found. Using default Material colors.\n'));
+        } else {
+          console.log(chalk.gray(`   Found ${files.length} SCSS files\n`));
+
+          const analysis = analyzeThemeReadiness(files);
+
+          console.log(chalk.blue.bold('📊 Theme Readiness Analysis:\n'));
+          console.log(chalk.gray(`   Total hardcoded colors: ${analysis.hardcodedColors.length}`));
+          console.log(chalk.gray(`   Unique colors: ${analysis.colorUsage.size}`));
+          console.log(
+            chalk.gray(
+              `   Components needing theme mixins: ${analysis.themeableComponents.length}\n`
+            )
+          );
+
+          // Extract color palettes from usage
+          extractedPalettes = extractColorPalettes(analysis.colorUsage);
+
+          console.log(chalk.green.bold('🎨 Extracted Color Palettes:\n'));
+          console.log(chalk.cyan('Primary Color:'));
+          console.log(chalk.gray(`  Light theme: ${extractedPalettes.primary.light}`));
+          console.log(chalk.gray(`  Dark theme:  ${extractedPalettes.primary.dark}`));
+          console.log(chalk.cyan('Accent Color:'));
+          console.log(chalk.gray(`  Light theme: ${extractedPalettes.accent.light}`));
+          console.log(chalk.gray(`  Dark theme:  ${extractedPalettes.accent.dark}`));
+          console.log(chalk.cyan('Warn Color:'));
+          console.log(chalk.gray(`  Light theme: ${extractedPalettes.warn.light}`));
+          console.log(chalk.gray(`  Dark theme:  ${extractedPalettes.warn.dark}\n`));
+
+          if (analysis.recommendations.length > 0) {
+            console.log(chalk.yellow.bold('📋 Recommendations:\n'));
+            analysis.recommendations.forEach(rec => {
+              const icon = rec.priority === 'high' ? '🔴' : '🟡';
+              console.log(chalk.gray(`   ${icon} ${rec.message}`));
+            });
+            console.log();
+          }
         }
       }
 
       // Generate theme files
-      console.log(chalk.gray(`Generating theme files in: ${outputDir}\n`));
+      console.log(chalk.gray(`📁 Output directory: ${outputDir}\n`));
 
       const themeOptions = {
         outputDir,
@@ -757,11 +801,8 @@ program
         themeOptions.themePalettes = extractedPalettes;
         console.log(chalk.green('✓ Using extracted colors from your app\n'));
       } else {
-        console.log(
-          chalk.yellow(
-            'ℹ Using default Material Design colors (use --analyze to extract from your app)\n'
-          )
-        );
+        console.log(chalk.yellow('ℹ  Using default Material Design colors\n'));
+        console.log(chalk.gray('   💡 Tip: Use --analyze to extract colors from your app\n'));
       }
 
       const themeStructure = generateThemeStructure(themeOptions);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scss-variable-extractor",
-  "version": "1.9.1",
+  "version": "2.0.1",
   "description": "Analyzes Angular SCSS files and extracts repeated hardcoded values into reusable variables",
   "bin": {
     "scss-extract": "./bin/cli.js"