scss-variable-extractor 1.6.5 → 1.9.1

package/MULTI-APP-GUIDE.md

@@ -0,0 +1,262 @@
+# Multi-App Dependency Analysis Guide
+
+## Your Scenario: Cafe Library Submodule + Unified App
+
+This guide shows how to use the new `analyze-dependencies` command for your specific setup with:
+
+- Multiple apps (unified, customer, admin, etc.)
+- Git submodule: fluffySubby library
+- Apps that reference each other's styles
+
+## Step 1: Create Configuration File
+
+Create `multi-app-config.json` in your workspace root:
+
+```json
+{
+  "workspaceRoot": ".",
+  "apps": [
+    {
+      "name": "unified-app",
+      "path": "./apps/unified/src",
+      "type": "app",
+      "description": "Unified app that references other apps"
+    },
+    {
+      "name": "customer-app",
+      "path": "./apps/customer/src",
+      "type": "app",
+      "description": "Customer-facing app"
+    },
+    {
+      "name": "admin-app",
+      "path": "./apps/admin/src",
+      "type": "app",
+      "description": "Admin dashboard"
+    }
+  ],
+  "sharedLibraries": [
+    {
+      "name": "fluffySubby-lib",
+      "path": "./libs/fluffySubby",
+      "type": "library",
+      "isSubmodule": true,
+      "description": "Git submodule fluffySubby library - shared across apps"
+    }
+  ]
+}
+```
+
+## Step 2: Run Analysis
+
+```bash
+npx scss-extract analyze-dependencies --config multi-app-config.json
+```
+
+## What You'll See
+
+### App Overview
+
+```
+📱 unified-app: 45 files, 127 classes, 38 variables
+📱 customer-app: 32 files, 89 classes, 25 variables
+📱 admin-app: 28 files, 76 classes, 22 variables
+📚 fluffySubby-lib: 15 files, 54 classes, 31 variables (submodule)
+```
+
+### Dependencies Detected
+
+```
+Dependencies:
+  Strong (explicit imports):
+    unified-app → fluffySubby-lib (@use)       ← Unified uses fluffySubby library
+    customer-app → fluffySubby-lib (@use)      ← Customer uses fluffySubby library
+    unified-app → customer-app (@use)   ← ⚠️ Unified imports from customer!
+
+  Weak (shared classes):
+    unified-app ↔ customer-app (12 shared classes)
+    customer-app ↔ admin-app (8 shared classes)
+```
+
+### Recommendations
+
+```
+💡 Recommendations:
+
+🟡 fluffySubby-lib is a root dependency - already set up correctly as submodule ✓
+🟡 12 CSS classes shared between unified-app and customer-app - should be in fluffySubby-lib
+🟡 unified-app imports from customer-app - consider extracting shared styles to fluffySubby-lib
+🔴 Potential circular dependency if customer-app also imports from unified-app
+```
+
+## Step 3: Understanding the Results
+
+### What the Tool Tells You
+
+**1. Which App Relies on Which:**
+
+- ✅ fluffySubby-lib is used by unified-app and customer-app (good - it's a library)
+- ⚠️ unified-app imports from customer-app (might be problematic)
+- ℹ️ Shows you the dependency chain
+
+**2. What Should Be Shared:**
+
+- Classes used in 2+ apps → Move to fluffySubby-lib
+- Variables used in 2+ apps → Move to fluffySubby-lib
+- App-specific styles → Keep in app
+
+**3. Organization Strategy:**
+
+```
+Recommended Structure:
+
+libs/fluffySubby/ (git submodule)
+├── styles/
+│   ├── _variables.scss     ← Shared variables (tool identifies these)
+│   ├── _utilities.scss     ← Shared classes (tool identifies these)
+│   ├── _mixins.scss        ← Shared mixins
+│   └── index.scss          ← Main export
+
+apps/unified/
+└── src/styles/
+    └── unified-specific.scss   ← Only unified-specific styles
+
+apps/customer/
+└── src/styles/
+    └── customer-specific.scss  ← Only customer-specific styles
+```
+
+## Step 4: Act on Recommendations
+
+### If Tool Says: "Move these classes to fluffySubby-lib"
+
+**Classes detected in multiple apps:**
+
+- `.btn-primary` (in unified, customer, admin)
+- `.card-container` (in unified, customer)
+- `.header-nav` (in all apps)
+
+**Action:**
+
+```bash
+# The tool tells you exactly what to move
+# Create utilities file in fluffySubby-lib
+touch libs/fluffySubby/styles/_utilities.scss
+
+# Add the shared classes there
+# Tool can show you which classes from the analysis
+```
+
+### If Tool Says: "Circular dependency detected"
+
+**Example:** unified-app → customer-app → unified-app
+
+**Action:**
+
+1. Review what unified-app needs from customer-app
+2. Extract those shared styles to fluffySubby-lib
+3. Both apps import from fluffySubby-lib instead
+
+## Step 5: Export Detailed Analysis (Optional)
+
+```bash
+# Get JSON output for detailed review
+npx scss-extract analyze-dependencies --config multi-app-config.json --format json > dependency-analysis.json
+
+# Review:
+# - Exact list of shared classes
+# - Exact list of shared variables
+# - Complete import graph
+# - Step-by-step migration plan
+```
+
+## Common Patterns the Tool Detects
+
+### ✅ Good Pattern
+
+```
+unified-app → fluffySubby-lib (submodule)
+customer-app → fluffySubby-lib (submodule)
+admin-app → fluffySubby-lib (submodule)
+```
+
+**Tool says:** ✓ Good architecture, fluffySubby-lib is properly used as shared library
+
+### ⚠️ Warning Pattern
+
+```
+unified-app → customer-app → styles.scss
+```
+
+**Tool says:** ⚠️ unified-app depends on customer-app styles - extract to fluffySubby-lib
+
+### 🔴 Problem Pattern
+
+```
+unified-app → customer-app
+customer-app → unified-app
+```
+
+**Tool says:** 🔴 Circular dependency - extract shared styles to fluffySubby-lib immediately
+
+## Real Example: Your Cafe Library
+
+**Before Analysis:**
+
+```
+// unified-app/styles.scss
+@use '../../customer-app/src/styles/buttons';  ← Bad: app imports from app
+@use '../../../libs/fluffySubby/styles' as fluffySubby;      ← Good: app imports from lib
+```
+
+**After Analysis & Refactoring:**
+
+```
+// Move shared styles to fluffySubby-lib
+libs/fluffySubby/styles/_buttons.scss
+
+// unified-app/styles.scss
+@use '../../../libs/fluffySubby/styles' as fluffySubby;      ← Good: only lib imports
+
+// customer-app/styles.scss
+@use '../../../libs/fluffySubby/styles' as fluffySubby;      ← Good: only lib imports
+```
+
+## Questions the Tool Answers
+
+❓ **"Where should I put this style?"**
+→ Tool tells you if it's used in 1 app (keep local) or 2+ apps (move to fluffySubby-lib)
+
+❓ **"Is my unified app correctly using the fluffySubby library?"**
+→ Tool shows dependency graph and highlights if it's importing from apps instead
+
+❓ **"What styles should be in the fluffySubby submodule vs app-specific?"**
+→ Tool identifies exactly which classes/variables are shared
+
+❓ **"Are there any circular dependencies?"**
+→ Tool detects and highlights them with 🔴 critical priority
+
+## Next Steps After Analysis
+
+1. **Review the recommendations** - Prioritize critical (🔴) and high (🟡) items
+2. **Move shared styles to fluffySubby-lib** - Use the tool's list of shared classes/variables
+3. **Update imports** - Change app-to-app imports to app-to-lib imports
+4. **Test** - Ensure all apps still work correctly
+5. **Commit fluffySubby-lib changes** - Update the submodule
+6. **Update apps** - Pull latest fluffySubby-lib in each app
+
+## Automation Coming Soon
+
+Future versions will support:
+
+```bash
+# Auto-migrate shared styles to library
+npx scss-extract migrate-to-library --config multi-app-config.json
+
+# Auto-update imports
+npx scss-extract update-imports --config multi-app-config.json
+```
+
+---
+
+**Bottom Line:** The tool analyzes your multi-app setup and tells you exactly which app relies on which, what should be shared vs app-specific, and the best way to organize everything!

package/README.md

@@ -16,7 +16,8 @@ A standalone, reusable CLI tool that analyzes Angular project SCSS files, identi
 🔄 **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
+🌍 **Global Styles Preservation** - Moves ::ng-deep and !important styles to global files  
+🔗 **Multi-App Dependency Analysis** - Analyzes style dependencies across apps, submodules, and libraries
 
 ## Installation
 
@@ -527,7 +528,7 @@ npx scss-extract migrate-bootstrap --no-custom-utilities
 
 ### `generate-themes` - Theme Structure Generator
 
-Generate a complete dark/light theme structure for Angular Material applications.
+Generate a complete dark/light theme structure for Angular Material applications with **automatic color extraction** from your existing styles.
 
 ```bash
 npx scss-extract generate-themes [src]
@@ -543,7 +544,7 @@ npx scss-extract generate-themes ./src --output ./src/styles --analyze
 **Options:**
 
 - `--output <dir>` - Output directory for theme files (default: `./src/styles`)
-- `--analyze` - Analyze existing styles for theme readiness
+- `--analyze` - Analyze existing styles and extract actual colors from your app
 - `--format <format>` - Report format for analysis (table, json, markdown)
 
 **What it generates:**
@@ -559,6 +560,10 @@ npx scss-extract generate-themes ./src --output ./src/styles --analyze
 
 ✅ **Features:**
 
+- **🎨 Automatic Color Extraction** - Uses actual colors from your app (with `--analyze`)
+- **Intelligent Color Selection** - Automatically picks primary, accent, and warn colors based on usage
+- **Smart Red Detection** - Prefers red hues for warn colors
+- **Dark Theme Variants** - Auto-generates lightened colors for dark mode
 - Material Design color palettes
 - Automatic dark/light mode switching
 - CSS custom properties support
@@ -568,13 +573,27 @@ npx scss-extract generate-themes ./src --output ./src/styles --analyze
 **Example Usage:**
 
 ```bash
-# Generate theme structure
+# Generate theme structure with default Material colors
 npx scss-extract generate-themes --output ./src/styles
 
-# Analyze existing styles first
+# 🎨 Analyze existing styles and use YOUR app's colors
 npx scss-extract generate-themes ./src --analyze --output ./src/styles
 ```
 
+**How Color Extraction Works:**
+
+When you use `--analyze`, the tool:
+
+1. **Scans all SCSS files** in your source directory
+2. **Extracts all colors** (hex, rgba) and counts usage frequency
+3. **Filters out utility colors** (black, white, grays)
+4. **Intelligently categorizes**:
+   - Most used color → **Primary** palette
+   - Second most used → **Accent** palette
+   - Red hues (or third most used) → **Warn** palette
+5. **Generates dark variants** by lightening colors for dark theme
+6. **Creates theme files** with your actual brand colors
+
 **Using Generated Themes:**
 
 1. Import in your `styles.scss`:
@@ -644,6 +663,258 @@ The formatting runs automatically before releases to ensure code quality.
 
 ---
 
+## Multi-App Dependency Analysis
+
+Perfect for **monorepos**, **multi-repo setups**, and **projects with git submodules**. Analyzes style dependencies across multiple apps to recommend the best organization strategy.
+
+### Use Cases
+
+**Ideal for:**
+
+- ✅ Multiple apps sharing styles
+- ✅ Git submodules (like a fluffySubby library used by multiple apps)
+- ✅ Apps that reference other apps' styles
+- ✅ Determining where to put shared styles
+- ✅ Identifying circular dependencies
+- ✅ Planning style library extraction
+
+### Command
+
+```bash
+npx scss-extract analyze-dependencies --config multi-app.json
+```
+
+### Configuration File
+
+Create a `multi-app.json` file describing your workspace:
+
+```json
+{
+  "workspaceRoot": ".",
+  "apps": [
+    {
+      "name": "unified-app",
+      "path": "./apps/unified/src",
+      "type": "app",
+      "description": "Unified app that references other apps"
+    },
+    {
+      "name": "customer-app",
+      "path": "./apps/customer/src",
+      "type": "app"
+    },
+    {
+      "name": "admin-app",
+      "path": "./apps/admin/src",
+      "type": "app"
+    }
+  ],
+  "sharedLibraries": [
+    {
+      "name": "libs",
+      "path": "./libs/lib1",
+      "type": "library",
+      "isSubmodule": true,
+      "description": "Git submodule fluffySubby library"
+    }
+  ]
+}
+```
+
+### What It Analyzes
+
+**1. Cross-App Dependencies:**
+
+- Detects which apps import styles from other apps
+- Identifies apps using git submodule styles
+- Finds apps referencing each other
+
+**2. Shared Styles:**
+
+- CSS classes used in multiple apps
+- SCSS variables duplicated across apps
+- Mixins defined in multiple places
+
+**3. Dependency Graph:**
+
+- Builds a complete dependency map
+- Shows which apps depend on which
+- Detects circular dependencies (⚠️ critical issues)
+
+**4. Organization Recommendations:**
+
+- Suggests creating shared style libraries
+- Recommends where to put common styles
+- Identifies styles to consolidate
+
+### Example Output
+
+```
+🔗 Multi-App Dependency Analysis
+
+Apps & Libraries:
+  📱 unified-app: 45 files, 127 classes, 38 variables
+  📱 customer-app: 32 files, 89 classes, 25 variables
+  📱 admin-app: 28 files, 76 classes, 22 variables
+  📚 libs: 15 files, 54 classes, 31 variables
+
+Dependencies:
+  Strong (explicit imports):
+    unified-app → libs (@use)
+    customer-app → libs (@use)
+    unified-app → customer-app (@use)
+
+  Weak (shared classes):
+    customer-app ↔ admin-app (12 shared classes)
+    unified-app ↔ admin-app (8 shared classes)
+
+Shared Styles:
+  23 shared CSS classes
+    Examples: .btn-primary, .card-container, .header-nav, .footer-links
+  15 shared variables
+    Examples: $primary-color, $spacing-md, $border-radius
+
+💡 Recommendations:
+
+🟡 [Architecture] libs is a root dependency - consider making it a shared library
+🟡 [Shared Styles] 23 CSS classes are shared across multiple apps - move to shared library
+🟡 [Shared Styles] 15 SCSS variables are shared across multiple apps - consolidate in shared library
+🟢 [Best Practices] unified-app imports Material styles directly - consider creating shared theme library
+
+📋 Organization Plan:
+
+1. Create shared library structure
+   Set up shared styles library with proper organization
+   ✓ Automated: scss-extract migrate-to-library --type variables
+
+2. Extract shared variables
+   Move shared SCSS variables to library
+
+3. Extract shared classes
+   Move shared CSS classes to library
+
+4. Update imports in apps
+   Update @use/@import statements to reference shared library
+
+5. Test and validate
+   Build all apps and verify styles work correctly
+   ⚠ Manual step required
+```
+
+### Real-World Example: Cafe Library Submodule
+
+**Your Setup:**
+
+- Multiple apps (unified, customer, admin)
+- Git submodule: `fluffySubby` library
+- Apps reference each other's styles
+
+**Problem:** Not sure where to put shared styles
+
+**Solution:**
+
+```bash
+# 1. Analyze dependencies
+npx scss-extract analyze-dependencies --config multi-app.json --format json > analysis.json
+
+# 2. Review recommendations
+# Tool will tell you:
+# - Which apps depend on fluffySubby library
+# - Which styles should be in fluffySubby vs app-specific
+# - If unified-app should be a library or just uses others
+
+# 3. Create organization based on recommendations
+npx scss-extract generate-themes --output ./libs/lib1/styles
+
+# 4. Move shared styles
+# Tool identifies what's truly shared vs app-specific
+```
+
+**Recommended Structure (based on analysis):**
+
+```
+libs/
+  fluffySubby/                    # Git submodule
+    styles/
+      _variables.scss      # Shared variables (identified by tool)
+      _mixins.scss         # Shared mixins
+      _utilities.scss      # Shared utility classes
+      index.scss           # Main export
+apps/
+  unified/
+    src/
+      styles/
+        app-specific.scss  # Unified-specific styles
+  customer/
+    src/
+      styles/
+        app-specific.scss  # Customer-specific styles
+  admin/
+    src/
+      styles/
+        app-specific.scss  # Admin-specific styles
+```
+
+### Advanced: Detecting App Relationships
+
+The tool understands these patterns:
+
+**1. App A uses Library B (git submodule):**
+
+```scss
+// unified-app/styles.scss
+@use '../../../libs/lib1/styles' as fluffySubby;
+```
+
+✅ **Recommendation:** Keep styles in fluffySubby library, unified-app imports them
+
+**2. App A uses App B's styles:**
+
+```scss
+// unified-app/styles.scss
+@use '../../customer-app/styles' as customer;
+```
+
+⚠️ **Warning:** Circular dependency risk
+
+💡 **Recommendation:** Extract shared styles to library
+
+**3. Multiple apps share classes:**
+
+```scss
+// customer-app
+.btn-primary { ... }
+
+// admin-app
+.btn-primary { ... }  // Duplicate!
+```
+
+💡 **Recommendation:** Move to shared library
+
+### Quick Start
+
+```bash
+# 1. Create config
+cat > multi-app.json << EOF
+{
+  "apps": [
+    { "name": "app1", "path": "./apps/app1/src" },
+    { "name": "app2", "path": "./apps/app2/src" }
+  ],
+  "sharedLibraries": [
+    { "name": "fluffySubby", "path": "./libs/lib1", "isSubmodule": true }
+  ]
+}
+EOF
+
+# 2. Analyze
+npx scss-extract analyze-dependencies --config multi-app.json
+
+# 3. Follow recommendations
+```
+
+---
+
 ## Configuration
 
 Create a `.scssextractrc.json` file in your project root:
@@ -931,6 +1202,34 @@ MIT License - see [LICENSE](./LICENSE) file for details
 
 ## Changelog
 
+### 1.9.0 (2026-02-12)
+
+- **Added:** 🎨 Automatic color extraction from existing app styles
+- **Added:** `extractColorPalettes()` function to intelligently select primary, accent, and warn colors
+- **Added:** Smart red hue detection for warn color selection
+- **Enhanced:** `generate-themes --analyze` now uses actual app colors instead of Material defaults
+- **Enhanced:** Gray shade filtering to exclude utility colors
+- **Enhanced:** Automatic dark theme variant generation (lightens colors for dark mode)
+- **Added:** Color normalization (hex3 → hex6, rgba → hex)
+- **Added:** Usage-based color ranking (most-used = primary, etc.)
+- **Documented:** Comprehensive color extraction examples in THEME-GUIDE.md
+- **Tested:** 12 new tests for color extraction (144 total tests passing)
+
+### 1.8.0 (2026-02-12)
+
+- **Added:** `analyze-dependencies` command for multi-app dependency analysis
+- **Added:** Support for analyzing monorepos and multi-repo setups
+- **Added:** Git submodule detection and analysis
+- **Added:** Cross-app style dependency detection
+- **Added:** Dependency graph visualization
+- **Added:** Circular dependency detection
+- **Added:** Shared style identification across apps
+- **Added:** Organization recommendations based on app relationships
+- **Added:** Multi-app configuration file support
+- **Improved:** Better understanding of which app relies on which
+- **Improved:** Automatic detection of shared vs app-specific styles
+- **Documented:** Comprehensive guide for fluffySubby library and unified app scenarios
+
 ### 1.7.0 (2026-02-12)
 
 - **Added:** `generate-themes` command for automatic dark/light theme structure generation