scss-variable-extractor 1.6.3 → 1.6.5

package/src/style-organizer.js

@@ -1,499 +1,500 @@
-const fs = require('fs');
-const path = require('path');
-
-/**
- * Analyzes style organization across the project
- * @param {Array<string>} scssFiles - Array of SCSS file paths
- * @param {Object} config - Configuration options
- * @returns {Object} - Organization analysis results
- */
-function analyzeStyleOrganization(scssFiles, config = {}) {
-  const analysis = {
-    summary: {
-      totalFiles: scssFiles.length,
-      componentStyles: 0,
-      globalStyles: 0,
-      utilityFiles: 0,
-      themeFiles: 0,
-      mixinFiles: 0
-    },
-    duplicates: {
-      selectors: [],
-      rules: [],
-      mixins: []
-    },
-    imports: {
-      global: [],
-      component: [],
-      unused: [],
-      circular: []
-    },
-    recommendations: [],
-    structure: {
-      current: {},
-      suggested: {}
-    }
-  };
-
-  const selectorMap = new Map(); // Track selector usage across files
-  const ruleMap = new Map(); // Track identical rule blocks
-  const mixinMap = new Map(); // Track mixin definitions
-  const importMap = new Map(); // Track import statements
-
-  scssFiles.forEach(filePath => {
-    const content = fs.readFileSync(filePath, 'utf8');
-    const fileName = path.basename(filePath);
-    const fileInfo = analyzeFile(content, filePath);
-
-    // Categorize file type
-    if (fileName.includes('theme') || fileName.includes('_variables')) {
-      analysis.summary.themeFiles++;
-    } else if (fileName.includes('mixin') || fileName.includes('_mixins')) {
-      analysis.summary.mixinFiles++;
-    } else if (fileName.includes('util') || fileName.includes('helper')) {
-      analysis.summary.utilityFiles++;
-    } else if (filePath.includes('styles.scss') || filePath.includes('global')) {
-      analysis.summary.globalStyles++;
-    } else if (fileName.includes('.component.scss')) {
-      analysis.summary.componentStyles++;
-    }
-
-    // Track selectors
-    fileInfo.selectors.forEach(selector => {
-      if (!selectorMap.has(selector)) {
-        selectorMap.set(selector, []);
-      }
-      selectorMap.get(selector).push({ file: filePath, content: fileInfo.selectorContent[selector] });
-    });
-
-    // Track rules
-    fileInfo.rules.forEach(rule => {
-      const ruleKey = rule.replace(/\s+/g, ' ').trim();
-      if (!ruleMap.has(ruleKey)) {
-        ruleMap.set(ruleKey, []);
-      }
-      ruleMap.get(ruleKey).push(filePath);
-    });
-
-    // Track mixins
-    fileInfo.mixins.forEach(mixin => {
-      if (!mixinMap.has(mixin)) {
-        mixinMap.set(mixin, []);
-      }
-      mixinMap.get(mixin).push(filePath);
-    });
-
-    // Track imports
-    fileInfo.imports.forEach(importPath => {
-      if (!importMap.has(importPath)) {
-        importMap.set(importPath, []);
-      }
-      importMap.get(importPath).push(filePath);
-    });
-  });
-
-  // Analyze duplicates
-  selectorMap.forEach((files, selector) => {
-    if (files.length > 1) {
-      analysis.duplicates.selectors.push({
-        selector,
-        count: files.length,
-        files: files.map(f => f.file)
-      });
-    }
-  });
-
-  ruleMap.forEach((files, rule) => {
-    if (files.length > 2 && rule.length > 50) { // Only report significant duplicates
-      analysis.duplicates.rules.push({
-        rule: rule.substring(0, 100) + '...',
-        count: files.length,
-        files
-      });
-    }
-  });
-
-  mixinMap.forEach((files, mixin) => {
-    if (files.length > 1) {
-      analysis.duplicates.mixins.push({
-        mixin,
-        count: files.length,
-        files
-      });
-    }
-  });
-
-  // Analyze imports
-  analyzeImportPatterns(importMap, analysis, scssFiles);
-
-  // Generate recommendations
-  generateRecommendations(analysis, config);
-
-  // Suggest structure
-  suggestStructure(analysis, config);
-
-  return analysis;
-}
-
-/**
- * Analyzes a single SCSS file
- * @param {string} content - File content
- * @param {string} filePath - File path
- * @returns {Object} - File analysis
- */
-function analyzeFile(content, filePath) {
-  const selectors = [];
-  const selectorContent = {};
-  const rules = [];
-  const mixins = [];
-  const imports = [];
-
-  // Extract selectors
-  const selectorRegex = /([.#]?[\w-]+(?:\s*[>+~]\s*[\w-]+)*)\s*\{([^}]*)\}/g;
-  let match;
-  while ((match = selectorRegex.exec(content)) !== null) {
-    const selector = match[1].trim();
-    const ruleContent = match[2].trim();
-    selectors.push(selector);
-    selectorContent[selector] = ruleContent;
-    if (ruleContent.length > 20) {
-      rules.push(match[0]);
-    }
-  }
-
-  // Extract mixins
-  const mixinRegex = /@mixin\s+([\w-]+)/g;
-  while ((match = mixinRegex.exec(content)) !== null) {
-    mixins.push(match[1]);
-  }
-
-  // Extract imports
-  const importRegex = /@(?:import|use|forward)\s+['"]([^'"]+)['"]/g;
-  while ((match = importRegex.exec(content)) !== null) {
-    imports.push(match[1]);
-  }
-
-  return {
-    selectors,
-    selectorContent,
-    rules,
-    mixins,
-    imports
-  };
-}
-
-/**
- * Analyzes import patterns
- * @param {Map} importMap - Map of imports
- * @param {Object} analysis - Analysis object
- * @param {Array} scssFiles - All SCSS files
- */
-function analyzeImportPatterns(importMap, analysis, scssFiles) {
-  const fileSet = new Set(scssFiles.map(f => path.basename(f, '.scss')));
-
-  importMap.forEach((importingFiles, importPath) => {
-    const isGlobal = importPath.includes('variables') || 
-                     importPath.includes('theme') || 
-                     importPath.includes('mixins');
-    
-    if (isGlobal && importingFiles.length > 5) {
-      analysis.imports.global.push({
-        path: importPath,
-        usedIn: importingFiles.length,
-        suggestion: 'Consider adding to global styles.scss'
-      });
-    } else if (importingFiles.length === 1) {
-      analysis.imports.unused.push({
-        path: importPath,
-        file: importingFiles[0],
-        suggestion: 'Potentially unused or should be in component file'
-      });
-    }
-
-    // Check for component-level imports
-    importingFiles.forEach(file => {
-      if (file.includes('.component.scss')) {
-        analysis.imports.component.push({
-          path: importPath,
-          component: path.basename(file)
-        });
-      }
-    });
-  });
-}
-
-/**
- * Generates organization recommendations
- * @param {Object} analysis - Analysis object
- * @param {Object} config - Configuration
- */
-function generateRecommendations(analysis, config) {
-  const recs = analysis.recommendations;
-
-  // Duplicate selectors
-  if (analysis.duplicates.selectors.length > 0) {
-    recs.push({
-      priority: 'high',
-      category: 'duplication',
-      title: 'Duplicate selectors detected',
-      description: `Found ${analysis.duplicates.selectors.length} selectors used in multiple files`,
-      action: 'Extract common selectors to shared utility files or use mixins',
-      files: analysis.duplicates.selectors.slice(0, 5)
-    });
-  }
-
-  // Duplicate rules
-  if (analysis.duplicates.rules.length > 0) {
-    recs.push({
-      priority: 'high',
-      category: 'duplication',
-      title: 'Duplicate CSS rules detected',
-      description: `Found ${analysis.duplicates.rules.length} identical rule blocks`,
-      action: 'Create reusable mixins or utility classes',
-      count: analysis.duplicates.rules.length
-    });
-  }
-
-  // Component vs global styles
-  if (analysis.summary.componentStyles > 10 && analysis.summary.globalStyles === 0) {
-    recs.push({
-      priority: 'medium',
-      category: 'organization',
-      title: 'No global styles file detected',
-      description: 'Consider creating a global styles.scss for shared utilities and resets',
-      action: 'Create src/styles.scss with @use imports'
-    });
-  }
-
-  // Import optimization
-  if (analysis.imports.global.length > 3) {
-    recs.push({
-      priority: 'medium',
-      category: 'imports',
-      title: 'Optimize global imports',
-      description: `${analysis.imports.global.length} files are imported globally across many components`,
-      action: 'Consolidate into a single theme file or add to styles.scss',
-      files: analysis.imports.global.map(i => i.path)
-    });
-  }
-
-  // Theme organization
-  if (analysis.summary.themeFiles === 0 && analysis.summary.componentStyles > 5) {
-    recs.push({
-      priority: 'medium',
-      category: 'theming',
-      title: 'No theme structure detected',
-      description: 'Consider organizing styles following Angular Material theming patterns',
-      action: 'Create theme files: _variables.scss, _typography.scss, _theme.scss'
-    });
-  }
-
-  // Mixin organization
-  if (analysis.duplicates.mixins.length > 0) {
-    recs.push({
-      priority: 'low',
-      category: 'mixins',
-      title: 'Duplicate mixin definitions',
-      description: `${analysis.duplicates.mixins.length} mixins defined in multiple files`,
-      action: 'Consolidate mixins into a shared _mixins.scss file'
-    });
-  }
-}
-
-/**
- * Suggests ideal folder structure
- * @param {Object} analysis - Analysis object
- * @param {Object} config - Configuration
- */
-function suggestStructure(analysis, config) {
-  const angularConfigured = config.angular !== undefined;
-  
-  analysis.structure.current = {
-    componentStyles: analysis.summary.componentStyles,
-    globalStyles: analysis.summary.globalStyles,
-    themeFiles: analysis.summary.themeFiles,
-    utilityFiles: analysis.summary.utilityFiles,
-    mixinFiles: analysis.summary.mixinFiles
-  };
-
-  analysis.structure.suggested = {
-    description: 'Recommended Angular Material theme structure',
-    folders: [
-      {
-        path: 'src/styles/',
-        files: [
-          '_variables.scss - Design tokens (colors, spacing, typography)',
-          '_mixins.scss - Reusable SCSS mixins',
-          '_utilities.scss - Utility classes (flex, spacing, etc.)',
-          '_theme.scss - Angular Material theme configuration',
-          '_typography.scss - Typography styles',
-          'styles.scss - Global entry point'
-        ]
-      },
-      {
-        path: 'src/app/components/',
-        files: [
-          '*.component.scss - Component-scoped styles only',
-          'Use @use for variables/mixins instead of @import'
-        ]
-      }
-    ],
-    imports: {
-      global: [
-        '@use "@angular/material" as mat;',
-        '@use "./styles/variables" as vars;',
-        '@use "./styles/mixins";',
-        '@use "./styles/utilities";'
-      ],
-      component: [
-        '@use "../../../styles/variables" as vars;',
-        '@use "../../../styles/mixins";'
-      ]
-    }
-  };
-}
-
-/**
- * Generates organization report
- * @param {Object} analysis - Analysis results
- * @param {string} format - Report format
- * @returns {string} - Formatted report
- */
-function generateOrganizationReport(analysis, format = 'table') {
-  if (format === 'json') {
-    return JSON.stringify(analysis, null, 2);
-  }
-
-  if (format === 'markdown') {
-    return generateMarkdownOrganizationReport(analysis);
-  }
-
-  // Table format
-  const chalk = require('chalk');
-  const Table = require('cli-table3');
-
-  let report = chalk.cyan.bold('\n📋 Style Organization Analysis\n\n');
-
-  // Summary
-  report += chalk.white.bold('Summary:\n');
-  const summaryTable = new Table({
-    head: ['Metric', 'Count'],
-    style: { head: ['cyan'] }
-  });
-  
-  summaryTable.push(
-    ['Total SCSS Files', analysis.summary.totalFiles],
-    ['Component Styles', analysis.summary.componentStyles],
-    ['Global Styles', analysis.summary.globalStyles],
-    ['Theme Files', analysis.summary.themeFiles],
-    ['Utility Files', analysis.summary.utilityFiles],
-    ['Mixin Files', analysis.summary.mixinFiles]
-  );
-  
-  report += summaryTable.toString() + '\n\n';
-
-  // Duplicates
-  if (analysis.duplicates.selectors.length > 0 || 
-      analysis.duplicates.rules.length > 0) {
-    report += chalk.yellow.bold('Duplication Issues:\n');
-    const dupTable = new Table({
-      head: ['Type', 'Count', 'Example'],
-      style: { head: ['yellow'] }
-    });
-
-    if (analysis.duplicates.selectors.length > 0) {
-      const example = analysis.duplicates.selectors[0];
-      dupTable.push([
-        'Duplicate Selectors',
-        analysis.duplicates.selectors.length,
-        `${example.selector} (${example.count} files)`
-      ]);
-    }
-
-    if (analysis.duplicates.rules.length > 0) {
-      dupTable.push([
-        'Duplicate Rules',
-        analysis.duplicates.rules.length,
-        'Identical CSS blocks'
-      ]);
-    }
-
-    if (analysis.duplicates.mixins.length > 0) {
-      dupTable.push([
-        'Duplicate Mixins',
-        analysis.duplicates.mixins.length,
-        analysis.duplicates.mixins[0].mixin
-      ]);
-    }
-
-    report += dupTable.toString() + '\n\n';
-  }
-
-  // Recommendations
-  if (analysis.recommendations.length > 0) {
-    report += chalk.green.bold('Recommendations:\n\n');
-    analysis.recommendations.forEach((rec, i) => {
-      const priorityColor = rec.priority === 'high' ? 'red' : 
-                           rec.priority === 'medium' ? 'yellow' : 'gray';
-      report += chalk[priorityColor](`${i + 1}. [${rec.priority.toUpperCase()}] ${rec.title}\n`);
-      report += chalk.gray(`   ${rec.description}\n`);
-      report += chalk.white(`   → ${rec.action}\n\n`);
-    });
-  }
-
-  // Suggested structure
-  report += chalk.blue.bold('Suggested Structure:\n\n');
-  analysis.structure.suggested.folders.forEach(folder => {
-    report += chalk.cyan(`${folder.path}\n`);
-    folder.files.forEach(file => {
-      report += chalk.gray(`  • ${file}\n`);
-    });
-    report += '\n';
-  });
-
-  return report;
-}
-
-/**
- * Generates markdown report
- * @param {Object} analysis - Analysis results
- * @returns {string} - Markdown formatted report
- */
-function generateMarkdownOrganizationReport(analysis) {
-  let md = '# Style Organization Analysis\n\n';
-
-  md += '## Summary\n\n';
-  md += '| Metric | Count |\n';
-  md += '|--------|-------|\n';
-  md += `| Total SCSS Files | ${analysis.summary.totalFiles} |\n`;
-  md += `| Component Styles | ${analysis.summary.componentStyles} |\n`;
-  md += `| Global Styles | ${analysis.summary.globalStyles} |\n`;
-  md += `| Theme Files | ${analysis.summary.themeFiles} |\n`;
-  md += `| Utility Files | ${analysis.summary.utilityFiles} |\n`;
-  md += `| Mixin Files | ${analysis.summary.mixinFiles} |\n\n`;
-
-  if (analysis.recommendations.length > 0) {
-    md += '## Recommendations\n\n';
-    analysis.recommendations.forEach((rec, i) => {
-      md += `### ${i + 1}. ${rec.title} (${rec.priority})\n\n`;
-      md += `**Description:** ${rec.description}\n\n`;
-      md += `**Action:** ${rec.action}\n\n`;
-    });
-  }
-
-  md += '## Suggested Structure\n\n';
-  analysis.structure.suggested.folders.forEach(folder => {
-    md += `### ${folder.path}\n\n`;
-    folder.files.forEach(file => {
-      md += `- ${file}\n`;
-    });
-    md += '\n';
-  });
-
-  return md;
-}
-
-module.exports = {
-  analyzeStyleOrganization,
-  generateOrganizationReport
-};
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Analyzes style organization across the project
+ * @param {Array<string>} scssFiles - Array of SCSS file paths
+ * @param {Object} config - Configuration options
+ * @returns {Object} - Organization analysis results
+ */
+function analyzeStyleOrganization(scssFiles, config = {}) {
+  const analysis = {
+    summary: {
+      totalFiles: scssFiles.length,
+      componentStyles: 0,
+      globalStyles: 0,
+      utilityFiles: 0,
+      themeFiles: 0,
+      mixinFiles: 0,
+    },
+    duplicates: {
+      selectors: [],
+      rules: [],
+      mixins: [],
+    },
+    imports: {
+      global: [],
+      component: [],
+      unused: [],
+      circular: [],
+    },
+    recommendations: [],
+    structure: {
+      current: {},
+      suggested: {},
+    },
+  };
+
+  const selectorMap = new Map(); // Track selector usage across files
+  const ruleMap = new Map(); // Track identical rule blocks
+  const mixinMap = new Map(); // Track mixin definitions
+  const importMap = new Map(); // Track import statements
+
+  scssFiles.forEach(filePath => {
+    // Skip if file doesn't exist (e.g., temp test files)
+    if (!fs.existsSync(filePath)) {
+      return;
+    }
+
+    const content = fs.readFileSync(filePath, 'utf8');
+    const fileName = path.basename(filePath);
+    const fileInfo = analyzeFile(content, filePath);
+
+    // Categorize file type
+    if (fileName.includes('theme') || fileName.includes('_variables')) {
+      analysis.summary.themeFiles++;
+    } else if (fileName.includes('mixin') || fileName.includes('_mixins')) {
+      analysis.summary.mixinFiles++;
+    } else if (fileName.includes('util') || fileName.includes('helper')) {
+      analysis.summary.utilityFiles++;
+    } else if (filePath.includes('styles.scss') || filePath.includes('global')) {
+      analysis.summary.globalStyles++;
+    } else if (fileName.includes('.component.scss')) {
+      analysis.summary.componentStyles++;
+    }
+
+    // Track selectors
+    fileInfo.selectors.forEach(selector => {
+      if (!selectorMap.has(selector)) {
+        selectorMap.set(selector, []);
+      }
+      selectorMap
+        .get(selector)
+        .push({ file: filePath, content: fileInfo.selectorContent[selector] });
+    });
+
+    // Track rules
+    fileInfo.rules.forEach(rule => {
+      const ruleKey = rule.replace(/\s+/g, ' ').trim();
+      if (!ruleMap.has(ruleKey)) {
+        ruleMap.set(ruleKey, []);
+      }
+      ruleMap.get(ruleKey).push(filePath);
+    });
+
+    // Track mixins
+    fileInfo.mixins.forEach(mixin => {
+      if (!mixinMap.has(mixin)) {
+        mixinMap.set(mixin, []);
+      }
+      mixinMap.get(mixin).push(filePath);
+    });
+
+    // Track imports
+    fileInfo.imports.forEach(importPath => {
+      if (!importMap.has(importPath)) {
+        importMap.set(importPath, []);
+      }
+      importMap.get(importPath).push(filePath);
+    });
+  });
+
+  // Analyze duplicates
+  selectorMap.forEach((files, selector) => {
+    if (files.length > 1) {
+      analysis.duplicates.selectors.push({
+        selector,
+        count: files.length,
+        files: files.map(f => f.file),
+      });
+    }
+  });
+
+  ruleMap.forEach((files, rule) => {
+    if (files.length > 2 && rule.length > 50) {
+      // Only report significant duplicates
+      analysis.duplicates.rules.push({
+        rule: rule.substring(0, 100) + '...',
+        count: files.length,
+        files,
+      });
+    }
+  });
+
+  mixinMap.forEach((files, mixin) => {
+    if (files.length > 1) {
+      analysis.duplicates.mixins.push({
+        mixin,
+        count: files.length,
+        files,
+      });
+    }
+  });
+
+  // Analyze imports
+  analyzeImportPatterns(importMap, analysis, scssFiles);
+
+  // Generate recommendations
+  generateRecommendations(analysis, config);
+
+  // Suggest structure
+  suggestStructure(analysis, config);
+
+  return analysis;
+}
+
+/**
+ * Analyzes a single SCSS file
+ * @param {string} content - File content
+ * @param {string} filePath - File path
+ * @returns {Object} - File analysis
+ */
+function analyzeFile(content, filePath) {
+  const selectors = [];
+  const selectorContent = {};
+  const rules = [];
+  const mixins = [];
+  const imports = [];
+
+  // Extract selectors
+  const selectorRegex = /([.#]?[\w-]+(?:\s*[>+~]\s*[\w-]+)*)\s*\{([^}]*)\}/g;
+  let match;
+  while ((match = selectorRegex.exec(content)) !== null) {
+    const selector = match[1].trim();
+    const ruleContent = match[2].trim();
+    selectors.push(selector);
+    selectorContent[selector] = ruleContent;
+    if (ruleContent.length > 20) {
+      rules.push(match[0]);
+    }
+  }
+
+  // Extract mixins
+  const mixinRegex = /@mixin\s+([\w-]+)/g;
+  while ((match = mixinRegex.exec(content)) !== null) {
+    mixins.push(match[1]);
+  }
+
+  // Extract imports
+  const importRegex = /@(?:import|use|forward)\s+['"]([^'"]+)['"]/g;
+  while ((match = importRegex.exec(content)) !== null) {
+    imports.push(match[1]);
+  }
+
+  return {
+    selectors,
+    selectorContent,
+    rules,
+    mixins,
+    imports,
+  };
+}
+
+/**
+ * Analyzes import patterns
+ * @param {Map} importMap - Map of imports
+ * @param {Object} analysis - Analysis object
+ * @param {Array} scssFiles - All SCSS files
+ */
+function analyzeImportPatterns(importMap, analysis, scssFiles) {
+  const fileSet = new Set(scssFiles.map(f => path.basename(f, '.scss')));
+
+  importMap.forEach((importingFiles, importPath) => {
+    const isGlobal =
+      importPath.includes('variables') ||
+      importPath.includes('theme') ||
+      importPath.includes('mixins');
+
+    if (isGlobal && importingFiles.length > 5) {
+      analysis.imports.global.push({
+        path: importPath,
+        usedIn: importingFiles.length,
+        suggestion: 'Consider adding to global styles.scss',
+      });
+    } else if (importingFiles.length === 1) {
+      analysis.imports.unused.push({
+        path: importPath,
+        file: importingFiles[0],
+        suggestion: 'Potentially unused or should be in component file',
+      });
+    }
+
+    // Check for component-level imports
+    importingFiles.forEach(file => {
+      if (file.includes('.component.scss')) {
+        analysis.imports.component.push({
+          path: importPath,
+          component: path.basename(file),
+        });
+      }
+    });
+  });
+}
+
+/**
+ * Generates organization recommendations
+ * @param {Object} analysis - Analysis object
+ * @param {Object} config - Configuration
+ */
+function generateRecommendations(analysis, config) {
+  const recs = analysis.recommendations;
+
+  // Duplicate selectors
+  if (analysis.duplicates.selectors.length > 0) {
+    recs.push({
+      priority: 'high',
+      category: 'duplication',
+      title: 'Duplicate selectors detected',
+      description: `Found ${analysis.duplicates.selectors.length} selectors used in multiple files`,
+      action: 'Extract common selectors to shared utility files or use mixins',
+      files: analysis.duplicates.selectors.slice(0, 5),
+    });
+  }
+
+  // Duplicate rules
+  if (analysis.duplicates.rules.length > 0) {
+    recs.push({
+      priority: 'high',
+      category: 'duplication',
+      title: 'Duplicate CSS rules detected',
+      description: `Found ${analysis.duplicates.rules.length} identical rule blocks`,
+      action: 'Create reusable mixins or utility classes',
+      count: analysis.duplicates.rules.length,
+    });
+  }
+
+  // Component vs global styles
+  if (analysis.summary.componentStyles > 10 && analysis.summary.globalStyles === 0) {
+    recs.push({
+      priority: 'medium',
+      category: 'organization',
+      title: 'No global styles file detected',
+      description: 'Consider creating a global styles.scss for shared utilities and resets',
+      action: 'Create src/styles.scss with @use imports',
+    });
+  }
+
+  // Import optimization
+  if (analysis.imports.global.length > 3) {
+    recs.push({
+      priority: 'medium',
+      category: 'imports',
+      title: 'Optimize global imports',
+      description: `${analysis.imports.global.length} files are imported globally across many components`,
+      action: 'Consolidate into a single theme file or add to styles.scss',
+      files: analysis.imports.global.map(i => i.path),
+    });
+  }
+
+  // Theme organization
+  if (analysis.summary.themeFiles === 0 && analysis.summary.componentStyles > 5) {
+    recs.push({
+      priority: 'medium',
+      category: 'theming',
+      title: 'No theme structure detected',
+      description: 'Consider organizing styles following Angular Material theming patterns',
+      action: 'Create theme files: _variables.scss, _typography.scss, _theme.scss',
+    });
+  }
+
+  // Mixin organization
+  if (analysis.duplicates.mixins.length > 0) {
+    recs.push({
+      priority: 'low',
+      category: 'mixins',
+      title: 'Duplicate mixin definitions',
+      description: `${analysis.duplicates.mixins.length} mixins defined in multiple files`,
+      action: 'Consolidate mixins into a shared _mixins.scss file',
+    });
+  }
+}
+
+/**
+ * Suggests ideal folder structure
+ * @param {Object} analysis - Analysis object
+ * @param {Object} config - Configuration
+ */
+function suggestStructure(analysis, config) {
+  const angularConfigured = config.angular !== undefined;
+
+  analysis.structure.current = {
+    componentStyles: analysis.summary.componentStyles,
+    globalStyles: analysis.summary.globalStyles,
+    themeFiles: analysis.summary.themeFiles,
+    utilityFiles: analysis.summary.utilityFiles,
+    mixinFiles: analysis.summary.mixinFiles,
+  };
+
+  analysis.structure.suggested = {
+    description: 'Recommended Angular Material theme structure',
+    folders: [
+      {
+        path: 'src/styles/',
+        files: [
+          '_variables.scss - Design tokens (colors, spacing, typography)',
+          '_mixins.scss - Reusable SCSS mixins',
+          '_utilities.scss - Utility classes (flex, spacing, etc.)',
+          '_theme.scss - Angular Material theme configuration',
+          '_typography.scss - Typography styles',
+          'styles.scss - Global entry point',
+        ],
+      },
+      {
+        path: 'src/app/components/',
+        files: [
+          '*.component.scss - Component-scoped styles only',
+          'Use @use for variables/mixins instead of @import',
+        ],
+      },
+    ],
+    imports: {
+      global: [
+        '@use "@angular/material" as mat;',
+        '@use "./styles/variables" as vars;',
+        '@use "./styles/mixins";',
+        '@use "./styles/utilities";',
+      ],
+      component: ['@use "../../../styles/variables" as vars;', '@use "../../../styles/mixins";'],
+    },
+  };
+}
+
+/**
+ * Generates organization report
+ * @param {Object} analysis - Analysis results
+ * @param {string} format - Report format
+ * @returns {string} - Formatted report
+ */
+function generateOrganizationReport(analysis, format = 'table') {
+  if (format === 'json') {
+    return JSON.stringify(analysis, null, 2);
+  }
+
+  if (format === 'markdown') {
+    return generateMarkdownOrganizationReport(analysis);
+  }
+
+  // Table format
+  const chalk = require('chalk');
+  const Table = require('cli-table3');
+
+  let report = chalk.cyan.bold('\n📋 Style Organization Analysis\n\n');
+
+  // Summary
+  report += chalk.white.bold('Summary:\n');
+  const summaryTable = new Table({
+    head: ['Metric', 'Count'],
+    style: { head: ['cyan'] },
+  });
+
+  summaryTable.push(
+    ['Total SCSS Files', analysis.summary.totalFiles],
+    ['Component Styles', analysis.summary.componentStyles],
+    ['Global Styles', analysis.summary.globalStyles],
+    ['Theme Files', analysis.summary.themeFiles],
+    ['Utility Files', analysis.summary.utilityFiles],
+    ['Mixin Files', analysis.summary.mixinFiles]
+  );
+
+  report += summaryTable.toString() + '\n\n';
+
+  // Duplicates
+  if (analysis.duplicates.selectors.length > 0 || analysis.duplicates.rules.length > 0) {
+    report += chalk.yellow.bold('Duplication Issues:\n');
+    const dupTable = new Table({
+      head: ['Type', 'Count', 'Example'],
+      style: { head: ['yellow'] },
+    });
+
+    if (analysis.duplicates.selectors.length > 0) {
+      const example = analysis.duplicates.selectors[0];
+      dupTable.push([
+        'Duplicate Selectors',
+        analysis.duplicates.selectors.length,
+        `${example.selector} (${example.count} files)`,
+      ]);
+    }
+
+    if (analysis.duplicates.rules.length > 0) {
+      dupTable.push(['Duplicate Rules', analysis.duplicates.rules.length, 'Identical CSS blocks']);
+    }
+
+    if (analysis.duplicates.mixins.length > 0) {
+      dupTable.push([
+        'Duplicate Mixins',
+        analysis.duplicates.mixins.length,
+        analysis.duplicates.mixins[0].mixin,
+      ]);
+    }
+
+    report += dupTable.toString() + '\n\n';
+  }
+
+  // Recommendations
+  if (analysis.recommendations.length > 0) {
+    report += chalk.green.bold('Recommendations:\n\n');
+    analysis.recommendations.forEach((rec, i) => {
+      const priorityColor =
+        rec.priority === 'high' ? 'red' : rec.priority === 'medium' ? 'yellow' : 'gray';
+      report += chalk[priorityColor](`${i + 1}. [${rec.priority.toUpperCase()}] ${rec.title}\n`);
+      report += chalk.gray(`   ${rec.description}\n`);
+      report += chalk.white(`   → ${rec.action}\n\n`);
+    });
+  }
+
+  // Suggested structure
+  report += chalk.blue.bold('Suggested Structure:\n\n');
+  analysis.structure.suggested.folders.forEach(folder => {
+    report += chalk.cyan(`${folder.path}\n`);
+    folder.files.forEach(file => {
+      report += chalk.gray(`  • ${file}\n`);
+    });
+    report += '\n';
+  });
+
+  return report;
+}
+
+/**
+ * Generates markdown report
+ * @param {Object} analysis - Analysis results
+ * @returns {string} - Markdown formatted report
+ */
+function generateMarkdownOrganizationReport(analysis) {
+  let md = '# Style Organization Analysis\n\n';
+
+  md += '## Summary\n\n';
+  md += '| Metric | Count |\n';
+  md += '|--------|-------|\n';
+  md += `| Total SCSS Files | ${analysis.summary.totalFiles} |\n`;
+  md += `| Component Styles | ${analysis.summary.componentStyles} |\n`;
+  md += `| Global Styles | ${analysis.summary.globalStyles} |\n`;
+  md += `| Theme Files | ${analysis.summary.themeFiles} |\n`;
+  md += `| Utility Files | ${analysis.summary.utilityFiles} |\n`;
+  md += `| Mixin Files | ${analysis.summary.mixinFiles} |\n\n`;
+
+  if (analysis.recommendations.length > 0) {
+    md += '## Recommendations\n\n';
+    analysis.recommendations.forEach((rec, i) => {
+      md += `### ${i + 1}. ${rec.title} (${rec.priority})\n\n`;
+      md += `**Description:** ${rec.description}\n\n`;
+      md += `**Action:** ${rec.action}\n\n`;
+    });
+  }
+
+  md += '## Suggested Structure\n\n';
+  analysis.structure.suggested.folders.forEach(folder => {
+    md += `### ${folder.path}\n\n`;
+    folder.files.forEach(file => {
+      md += `- ${file}\n`;
+    });
+    md += '\n';
+  });
+
+  return md;
+}
+
+module.exports = {
+  analyzeStyleOrganization,
+  generateOrganizationReport,
+};