gbu-accessibility-package 3.4.0 → 3.8.0

package/lib/fixer.js

@@ -1236,6 +1236,9 @@ class AccessibilityFixer {
       altCreativity: config.altCreativity || 'balanced', // conservative, balanced, creative
       includeEmotions: config.includeEmotions || false,
       strictAltChecking: config.strictAltChecking || false,
+      // New options for advanced features
+      autoFixHeadings: config.autoFixHeadings || false, // Enable automatic heading fixes
+      fixDescriptionLists: config.fixDescriptionLists || true, // Enable DL structure fixes
       ...config
     };
     
@@ -2271,10 +2274,13 @@ class AccessibilityFixer {
       console.log(chalk.yellow('\n📑 Step 8: Heading analysis...'));
       results.headings = await this.analyzeHeadings(directory);
       
-      // Step 9: Check broken links (no auto-fix)
-      console.log(chalk.yellow('\n🔗 Step 9: Broken links check...'));
+      // Step 9: Check broken links and missing resources (no auto-fix)
+      console.log(chalk.yellow('\n🔗 Step 9: External links check...'));
       results.brokenLinks = await this.checkBrokenLinks(directory);
       
+      console.log(chalk.yellow('\n📁 Step 9b: Missing resources check...'));
+      results.missingResources = await this.check404Resources(directory);
+      
       // Step 10: Cleanup duplicate roles
       console.log(chalk.yellow('\n🧹 Step 10: Cleanup duplicate roles...'));
       results.cleanup = await this.cleanupDuplicateRoles(directory);
@@ -2863,9 +2869,9 @@ class AccessibilityFixer {
     return fixed;
   }
 
-  // Check for broken links and 404 resources
+  // Check for broken external links only
   async checkBrokenLinks(directory = '.') {
-    console.log(chalk.blue('🔗 Checking for broken links and 404 resources...'));
+    console.log(chalk.blue('🔗 Checking for broken external links...'));
     
     const htmlFiles = await this.findHtmlFiles(directory);
     const results = [];
@@ -2873,7 +2879,7 @@ class AccessibilityFixer {
     for (const file of htmlFiles) {
       try {
         const content = await fs.readFile(file, 'utf8');
-        const issues = await this.analyzeBrokenLinks(content, file);
+        const issues = await this.analyzeBrokenLinks(content, file, 'external-only');
         
         if (issues.length > 0) {
           console.log(chalk.cyan(`\n📁 ${file}:`));
@@ -2892,12 +2898,46 @@ class AccessibilityFixer {
       }
     }
     
-    console.log(chalk.blue(`\n📊 Summary: Analyzed links in ${results.length} files`));
+    console.log(chalk.blue(`\n📊 Summary: Analyzed external links in ${results.length} files`));
     console.log(chalk.gray('💡 Broken link issues require manual review and cannot be auto-fixed'));
     return results;
   }
 
-  async analyzeBrokenLinks(content, filePath) {
+  // Check for 404 resources (local files) only
+  async check404Resources(directory = '.') {
+    console.log(chalk.blue('📁 Checking for 404 resources (missing local files)...'));
+    
+    const htmlFiles = await this.findHtmlFiles(directory);
+    const results = [];
+    
+    for (const file of htmlFiles) {
+      try {
+        const content = await fs.readFile(file, 'utf8');
+        const issues = await this.analyzeBrokenLinks(content, file, 'local-only');
+        
+        if (issues.length > 0) {
+          console.log(chalk.cyan(`\n📁 ${file}:`));
+          issues.forEach(issue => {
+            console.log(chalk.yellow(`  ${issue.type}: ${issue.description}`));
+            if (issue.suggestion) {
+              console.log(chalk.gray(`    💡 ${issue.suggestion}`));
+            }
+          });
+        }
+        
+        results.push({ file, status: 'analyzed', issues: issues.length, missingResources: issues });
+      } catch (error) {
+        console.error(chalk.red(`❌ Error processing ${file}: ${error.message}`));
+        results.push({ file, status: 'error', error: error.message });
+      }
+    }
+    
+    console.log(chalk.blue(`\n📊 Summary: Analyzed local resources in ${results.length} files`));
+    console.log(chalk.gray('💡 Missing resource issues require manual review and cannot be auto-fixed'));
+    return results;
+  }
+
+  async analyzeBrokenLinks(content, filePath, mode = 'all') {
     const issues = [];
     const path = require('path');
     const http = require('http');
@@ -2905,20 +2945,33 @@ class AccessibilityFixer {
     const { URL } = require('url');
     
     // Extract all links and resources
-    const linkPatterns = [
-      // Anchor links
-      { pattern: /<a[^>]*href\s*=\s*["']([^"']+)["'][^>]*>/gi, type: 'Link', element: 'a' },
-      // Images
-      { pattern: /<img[^>]*src\s*=\s*["']([^"']+)["'][^>]*>/gi, type: 'Image', element: 'img' },
-      // CSS links
-      { pattern: /<link[^>]*href\s*=\s*["']([^"']+)["'][^>]*>/gi, type: 'CSS', element: 'link' },
-      // Script sources
-      { pattern: /<script[^>]*src\s*=\s*["']([^"']+)["'][^>]*>/gi, type: 'Script', element: 'script' },
-      // Video sources
-      { pattern: /<video[^>]*src\s*=\s*["']([^"']+)["'][^>]*>/gi, type: 'Video', element: 'video' },
-      // Audio sources
-      { pattern: /<audio[^>]*src\s*=\s*["']([^"']+)["'][^>]*>/gi, type: 'Audio', element: 'audio' }
-    ];
+    let linkPatterns = [];
+    
+    if (mode === 'external-only') {
+      // Only anchor links for external link checking
+      linkPatterns = [
+        { pattern: /<a[^>]*href\s*=\s*["']([^"']+)["'][^>]*>/gi, type: 'Link', element: 'a' }
+      ];
+    } else if (mode === 'local-only') {
+      // Only resources (not anchor links) for 404 resource checking
+      linkPatterns = [
+        { pattern: /<img[^>]*src\s*=\s*["']([^"']+)["'][^>]*>/gi, type: 'Image', element: 'img' },
+        { pattern: /<link[^>]*href\s*=\s*["']([^"']+)["'][^>]*>/gi, type: 'CSS', element: 'link' },
+        { pattern: /<script[^>]*src\s*=\s*["']([^"']+)["'][^>]*>/gi, type: 'Script', element: 'script' },
+        { pattern: /<video[^>]*src\s*=\s*["']([^"']+)["'][^>]*>/gi, type: 'Video', element: 'video' },
+        { pattern: /<audio[^>]*src\s*=\s*["']([^"']+)["'][^>]*>/gi, type: 'Audio', element: 'audio' }
+      ];
+    } else {
+      // All patterns for comprehensive checking
+      linkPatterns = [
+        { pattern: /<a[^>]*href\s*=\s*["']([^"']+)["'][^>]*>/gi, type: 'Link', element: 'a' },
+        { pattern: /<img[^>]*src\s*=\s*["']([^"']+)["'][^>]*>/gi, type: 'Image', element: 'img' },
+        { pattern: /<link[^>]*href\s*=\s*["']([^"']+)["'][^>]*>/gi, type: 'CSS', element: 'link' },
+        { pattern: /<script[^>]*src\s*=\s*["']([^"']+)["'][^>]*>/gi, type: 'Script', element: 'script' },
+        { pattern: /<video[^>]*src\s*=\s*["']([^"']+)["'][^>]*>/gi, type: 'Video', element: 'video' },
+        { pattern: /<audio[^>]*src\s*=\s*["']([^"']+)["'][^>]*>/gi, type: 'Audio', element: 'audio' }
+      ];
+    }
     
     const baseDir = path.dirname(filePath);
     
@@ -2926,7 +2979,7 @@ class AccessibilityFixer {
       let match;
       while ((match = linkPattern.pattern.exec(content)) !== null) {
         const url = match[1];
-        const issue = await this.checkSingleLink(url, baseDir, linkPattern.type, linkPattern.element);
+        const issue = await this.checkSingleLink(url, baseDir, linkPattern.type, linkPattern.element, mode);
         if (issue) {
           issues.push(issue);
         }
@@ -2936,7 +2989,7 @@ class AccessibilityFixer {
     return issues;
   }
 
-  async checkSingleLink(url, baseDir, resourceType, elementType) {
+  async checkSingleLink(url, baseDir, resourceType, elementType, mode = 'all') {
     // Skip certain URLs
     if (this.shouldSkipUrl(url)) {
       return null;
@@ -2944,10 +2997,16 @@ class AccessibilityFixer {
     
     try {
       if (this.isExternalUrl(url)) {
-        // Check external URLs
+        // Check external URLs only if mode allows
+        if (mode === 'local-only') {
+          return null; // Skip external URLs in local-only mode
+        }
         return await this.checkExternalUrl(url, resourceType, elementType);
       } else {
-        // Check local files
+        // Check local files only if mode allows
+        if (mode === 'external-only') {
+          return null; // Skip local files in external-only mode
+        }
         return await this.checkLocalFile(url, baseDir, resourceType, elementType);
       }
     } catch (error) {
@@ -3609,12 +3668,18 @@ class AccessibilityFixer {
       results.steps.push({ step: 8, name: 'Heading analysis', suggestions: totalHeadingSuggestions });
       console.log(chalk.gray('💡 Heading issues require manual review and cannot be auto-fixed'));
       
-      // Step 9: Broken links check
-      console.log(chalk.blue('🔗 Step 9: Broken links check...'));
+      // Step 9: Broken links and missing resources check
+      console.log(chalk.blue('🔗 Step 9a: External links check...'));
       const brokenLinksResults = await this.checkBrokenLinks(directory);
       const totalBrokenLinks = brokenLinksResults.reduce((sum, r) => sum + (r.issues || 0), 0);
-      results.steps.push({ step: 9, name: 'Broken links check', issues: totalBrokenLinks });
-      console.log(chalk.gray('💡 Broken link issues require manual review and cannot be auto-fixed'));
+      results.steps.push({ step: '9a', name: 'External links check', issues: totalBrokenLinks });
+      
+      console.log(chalk.blue('📁 Step 9b: Missing resources check...'));
+      const missingResourcesResults = await this.check404Resources(directory);
+      const totalMissingResources = missingResourcesResults.reduce((sum, r) => sum + (r.issues || 0), 0);
+      results.steps.push({ step: '9b', name: 'Missing resources check', issues: totalMissingResources });
+      
+      console.log(chalk.gray('💡 Link and resource issues require manual review and cannot be auto-fixed'));
       
       // Step 10: Cleanup duplicate roles
       console.log(chalk.blue('🧹 Step 10: Cleanup duplicate roles...'));
@@ -3981,71 +4046,7 @@ class AccessibilityFixer {
     return results;
   }
 
-  async checkBrokenLinks(directory = '.') {
-    console.log(chalk.blue('🔗 Checking for broken links and 404 resources...'));
-    
-    const htmlFiles = await this.findHtmlFiles(directory);
-    const results = [];
-    let totalIssuesFound = 0;
-    
-    for (const file of htmlFiles) {
-      try {
-        const content = await fs.readFile(file, 'utf8');
-        const issues = this.analyzeBrokenLinks(content, file);
-        
-        if (issues.length > 0) {
-          console.log(chalk.cyan(`\n📁 ${file}:`));
-          issues.forEach(issue => {
-            console.log(chalk.yellow(`  ${issue.type}: ${issue.description}`));
-            if (issue.suggestion) {
-              console.log(chalk.gray(`    💡 ${issue.suggestion}`));
-            }
-            totalIssuesFound++;
-          });
-        }
-        
-        results.push({ file, status: 'analyzed', issues: issues.length });
-      } catch (error) {
-        console.error(chalk.red(`❌ Error processing ${file}: ${error.message}`));
-        results.push({ file, status: 'error', error: error.message });
-      }
-    }
-    
-    console.log(chalk.blue(`\n📊 Summary: Analyzed links in ${results.length} files`));
-    console.log(chalk.gray('💡 Broken link issues require manual review and cannot be auto-fixed'));
-    return results;
-  }
 
-  analyzeBrokenLinks(content, filePath) {
-    const issues = [];
-    
-    // Check for local image files
-    const imgPattern = /<img[^>]*src\s*=\s*["']([^"']+)["'][^>]*>/gi;
-    let match;
-    
-    while ((match = imgPattern.exec(content)) !== null) {
-      const src = match[1];
-      
-      // Skip external URLs and data URLs
-      if (src.startsWith('http') || src.startsWith('data:') || src.startsWith('//')) {
-        continue;
-      }
-      
-      // Check if local file exists
-      const fullPath = path.resolve(path.dirname(filePath), src);
-      try {
-        require('fs').statSync(fullPath);
-      } catch (error) {
-        issues.push({
-          type: '📁 Image not found',
-          description: `img file does not exist: ${src}`,
-          suggestion: 'Create the missing file or update the image path'
-        });
-      }
-    }
-    
-    return issues;
-  }
 
   async cleanupDuplicateRoles(directory = '.') {
     console.log(chalk.blue('🧹 Cleaning up duplicate role attributes...'));
@@ -4400,12 +4401,18 @@ class AccessibilityFixer {
       results.steps.push({ step: 9, name: 'Heading analysis', suggestions: totalHeadingSuggestions });
       console.log(chalk.gray('💡 Heading issues require manual review and cannot be auto-fixed'));
       
-      // Step 10: Broken links check
-      console.log(chalk.blue('🔗 Step 10: Broken links check...'));
+      // Step 10: Broken links and missing resources check
+      console.log(chalk.blue('🔗 Step 10a: External links check...'));
       const brokenLinksResults = await this.checkBrokenLinks(directory);
       const totalBrokenLinks = brokenLinksResults.reduce((sum, r) => sum + (r.issues || 0), 0);
-      results.steps.push({ step: 10, name: 'Broken links check', issues: totalBrokenLinks });
-      console.log(chalk.gray('💡 Broken link issues require manual review and cannot be auto-fixed'));
+      results.steps.push({ step: '10a', name: 'External links check', issues: totalBrokenLinks });
+      
+      console.log(chalk.blue('📁 Step 10b: Missing resources check...'));
+      const missingResourcesResults = await this.check404Resources(directory);
+      const totalMissingResources = missingResourcesResults.reduce((sum, r) => sum + (r.issues || 0), 0);
+      results.steps.push({ step: '10b', name: 'Missing resources check', issues: totalMissingResources });
+      
+      console.log(chalk.gray('💡 Link and resource issues require manual review and cannot be auto-fixed'));
       
       // Step 11: Cleanup duplicate roles
       console.log(chalk.blue('🧹 Step 11: Cleanup duplicate roles...'));
@@ -4454,37 +4461,2005 @@ class AccessibilityFixer {
     }
   }
 
-  async findHtmlFiles(directory) {
-    const files = [];
+  async fixHeadingStructure(directory = '.') {
+    console.log(chalk.blue('📑 Fixing heading structure...'));
     
-    // Check if the path is a file or directory
-    const stat = await fs.stat(directory);
+    const htmlFiles = await this.findHtmlFiles(directory);
+    const results = [];
+    let totalIssuesFound = 0;
+    let totalIssuesFixed = 0;
     
-    if (stat.isFile()) {
-      // If it's a file, check if it's HTML
-      if (directory.endsWith('.html')) {
-        files.push(directory);
+    for (const file of htmlFiles) {
+      try {
+        const content = await fs.readFile(file, 'utf8');
+        const analysis = this.analyzeHeadingStructure(content);
+        
+        if (analysis.issues.length > 0) {
+          console.log(chalk.cyan(`\n📁 ${file}:`));
+          analysis.issues.forEach(issue => {
+            console.log(chalk.yellow(`  ${issue.type}: ${issue.description}`));
+            if (issue.suggestion) {
+              console.log(chalk.gray(`    💡 ${issue.suggestion}`));
+            }
+            totalIssuesFound++;
+          });
+        }
+        
+        let fixed = content;
+        let changesMade = false;
+        
+        if (this.config.autoFixHeadings) {
+          fixed = this.fixHeadingStructureInContent(content, analysis);
+          changesMade = fixed !== content;
+          
+          if (changesMade) {
+            const fixedCount = this.countHeadingFixes(content, fixed);
+            totalIssuesFixed += fixedCount;
+            
+            if (this.config.backupFiles) {
+              await fs.writeFile(`${file}.backup`, content);
+            }
+            
+            if (!this.config.dryRun) {
+              await fs.writeFile(file, fixed);
+            }
+            
+            console.log(chalk.green(`✅ Fixed heading structure in: ${file} (${fixedCount} fixes)`));
+            results.push({ file, status: 'fixed', issues: analysis.issues.length, fixes: fixedCount });
+          } else {
+            results.push({ file, status: 'no-change', issues: analysis.issues.length });
+          }
+        } else {
+          results.push({ file, status: 'analyzed', issues: analysis.issues.length });
+        }
+      } catch (error) {
+        console.error(chalk.red(`❌ Error processing ${file}: ${error.message}`));
+        results.push({ file, status: 'error', error: error.message });
       }
-      return files;
     }
     
-    // If it's a directory, scan recursively
-    async function scan(dir) {
-      const entries = await fs.readdir(dir, { withFileTypes: true });
+    console.log(chalk.blue(`\n📊 Summary: Found ${totalIssuesFound} heading issues across ${results.length} files`));
+    if (this.config.autoFixHeadings) {
+      console.log(chalk.green(`   Fixed ${totalIssuesFixed} heading issues automatically`));
+    } else {
+      console.log(chalk.gray('💡 Use --auto-fix-headings option to enable automatic fixes'));
+    }
+    
+    return results;
+  }
+
+  analyzeHeadingStructure(content) {
+    const issues = [];
+    const suggestions = [];
+    
+    // Extract all headings with their levels, text, and positions
+    const headingPattern = /<h([1-6])[^>]*>([\s\S]*?)<\/h[1-6]>/gi;
+    const headings = [];
+    let match;
+    
+    while ((match = headingPattern.exec(content)) !== null) {
+      const level = parseInt(match[1]);
+      const rawText = match[2];
+      const text = rawText.replace(/<[^>]*>/g, '').trim();
+      const fullTag = match[0];
       
-      for (const entry of entries) {
-        const fullPath = path.join(dir, entry.name);
-        
-        if (entry.isDirectory() && !entry.name.startsWith('.')) {
-          await scan(fullPath);
-        } else if (entry.isFile() && entry.name.endsWith('.html')) {
-          files.push(fullPath);
-        }
+      headings.push({ 
+        level, 
+        text, 
+        rawText,
+        fullTag,
+        position: match.index,
+        originalMatch: match[0]
+      });
+    }
+    
+    if (headings.length === 0) {
+      issues.push({
+        type: '📑 No headings found',
+        description: 'Page has no heading elements',
+        suggestion: 'Add heading elements (h1-h6) to structure content',
+        severity: 'error',
+        fixable: false
+      });
+      return { issues, suggestions, headings };
+    }
+    
+    // Check for h1
+    const h1Count = headings.filter(h => h.level === 1).length;
+    if (h1Count === 0) {
+      issues.push({
+        type: '📑 Missing h1',
+        description: 'Page should have exactly one h1 element',
+        suggestion: 'Add an h1 element as the main page heading',
+        severity: 'error',
+        fixable: true,
+        fix: 'add-h1'
+      });
+    } else if (h1Count > 1) {
+      issues.push({
+        type: '📑 Multiple h1 elements',
+        description: `Found ${h1Count} h1 elements, should have only one`,
+        suggestion: 'Convert extra h1 elements to h2-h6 as appropriate',
+        severity: 'error',
+        fixable: true,
+        fix: 'fix-multiple-h1'
+      });
+    }
+    
+    // Check heading order and hierarchy
+    for (let i = 1; i < headings.length; i++) {
+      const current = headings[i];
+      const previous = headings[i - 1];
+      
+      // Check for level skipping
+      if (current.level > previous.level + 1) {
+        issues.push({
+          type: '📑 Heading level skip',
+          description: `Heading level jumps from h${previous.level} to h${current.level}`,
+          suggestion: `Use h${previous.level + 1} instead of h${current.level}`,
+          severity: 'warning',
+          fixable: true,
+          fix: 'fix-level-skip',
+          targetIndex: i,
+          correctLevel: previous.level + 1
+        });
       }
     }
     
-    await scan(directory);
-    return files;
+    // Check for empty headings
+    headings.forEach((heading, index) => {
+      if (!heading.text) {
+        issues.push({
+          type: '📑 Empty heading',
+          description: `Heading ${index + 1} (h${heading.level}) is empty`,
+          suggestion: 'Add descriptive text to the heading or remove it',
+          severity: 'error',
+          fixable: true,
+          fix: 'fix-empty-heading',
+          targetIndex: index
+        });
+      }
+    });
+    
+    // Check for consecutive headings with same level and similar content
+    for (let i = 1; i < headings.length; i++) {
+      const current = headings[i];
+      const previous = headings[i - 1];
+      
+      if (current.level === previous.level && 
+          current.text.toLowerCase() === previous.text.toLowerCase() &&
+          current.text.length > 0) {
+        issues.push({
+          type: '📑 Duplicate heading',
+          description: `Duplicate h${current.level} heading: "${current.text}"`,
+          suggestion: 'Make heading text unique or merge content',
+          severity: 'warning',
+          fixable: false
+        });
+      }
+    }
+    
+    return { issues, suggestions, headings };
+  }
+
+  fixHeadingStructureInContent(content, analysis) {
+    let fixed = content;
+    const { issues, headings } = analysis;
+    
+    // Sort issues by position (descending) to avoid position shifts
+    const fixableIssues = issues
+      .filter(issue => issue.fixable)
+      .sort((a, b) => (b.targetIndex || 0) - (a.targetIndex || 0));
+    
+    fixableIssues.forEach(issue => {
+      switch (issue.fix) {
+        case 'add-h1':
+          fixed = this.addMissingH1(fixed);
+          break;
+          
+        case 'fix-multiple-h1':
+          fixed = this.fixMultipleH1(fixed, headings);
+          break;
+          
+        case 'fix-level-skip':
+          if (issue.targetIndex !== undefined && issue.correctLevel) {
+            fixed = this.fixHeadingLevelSkip(fixed, headings[issue.targetIndex], issue.correctLevel);
+          }
+          break;
+          
+        case 'fix-empty-heading':
+          if (issue.targetIndex !== undefined) {
+            fixed = this.fixEmptyHeading(fixed, headings[issue.targetIndex]);
+          }
+          break;
+      }
+    });
+    
+    return fixed;
+  }
+
+  addMissingH1(content) {
+    // Try to find the first heading and convert it to h1
+    const firstHeadingMatch = content.match(/<h([2-6])[^>]*>([\s\S]*?)<\/h[2-6]>/i);
+    
+    if (firstHeadingMatch) {
+      const level = firstHeadingMatch[1];
+      const replacement = firstHeadingMatch[0].replace(
+        new RegExp(`<h${level}([^>]*)>`, 'i'),
+        '<h1$1>'
+      ).replace(
+        new RegExp(`</h${level}>`, 'i'),
+        '</h1>'
+      );
+      
+      const result = content.replace(firstHeadingMatch[0], replacement);
+      console.log(chalk.yellow(`  📑 Converted first h${level} to h1`));
+      return result;
+    }
+    
+    // If no headings found, try to add h1 based on title or first significant text
+    const titleMatch = content.match(/<title[^>]*>([^<]+)<\/title>/i);
+    if (titleMatch) {
+      const title = titleMatch[1].trim();
+      // Insert h1 after opening body tag
+      const bodyMatch = content.match(/(<body[^>]*>)/i);
+      if (bodyMatch) {
+        const h1Element = `\n  <h1>${title}</h1>\n`;
+        const result = content.replace(bodyMatch[1], bodyMatch[1] + h1Element);
+        console.log(chalk.yellow(`  📑 Added h1 element with title: "${title}"`));
+        return result;
+      }
+    }
+    
+    return content;
+  }
+
+  fixMultipleH1(content, headings) {
+    const h1Elements = headings.filter(h => h.level === 1);
+    
+    // Keep the first h1, convert others to h2
+    for (let i = 1; i < h1Elements.length; i++) {
+      const h1 = h1Elements[i];
+      const replacement = h1.fullTag.replace(/<h1([^>]*)>/i, '<h2$1>').replace(/<\/h1>/i, '</h2>');
+      content = content.replace(h1.fullTag, replacement);
+      console.log(chalk.yellow(`  📑 Converted extra h1 to h2: "${h1.text}"`));
+    }
+    
+    return content;
+  }
+
+  fixHeadingLevelSkip(content, heading, correctLevel) {
+    const replacement = heading.fullTag
+      .replace(new RegExp(`<h${heading.level}([^>]*)>`, 'i'), `<h${correctLevel}$1>`)
+      .replace(new RegExp(`</h${heading.level}>`, 'i'), `</h${correctLevel}>`);
+    
+    const result = content.replace(heading.fullTag, replacement);
+    console.log(chalk.yellow(`  📑 Fixed level skip: h${heading.level} → h${correctLevel} for "${heading.text}"`));
+    return result;
+  }
+
+  fixEmptyHeading(content, heading) {
+    // Generate meaningful text based on context
+    const contextText = this.generateHeadingText(content, heading);
+    
+    if (contextText) {
+      const replacement = heading.fullTag.replace(
+        /<h([1-6])([^>]*)>[\s\S]*?<\/h[1-6]>/i,
+        `<h$1$2>${contextText}</h$1>`
+      );
+      
+      const result = content.replace(heading.fullTag, replacement);
+      console.log(chalk.yellow(`  📑 Added text to empty heading: "${contextText}"`));
+      return result;
+    }
+    
+    // If can't generate text, remove the empty heading
+    const result = content.replace(heading.fullTag, '');
+    console.log(chalk.yellow(`  📑 Removed empty h${heading.level} heading`));
+    return result;
+  }
+
+  generateHeadingText(content, heading) {
+    const lang = this.config.language;
+    
+    // Try to find nearby text content
+    const position = heading.position;
+    const contextRange = 500;
+    const beforeContext = content.substring(Math.max(0, position - contextRange), position);
+    const afterContext = content.substring(position + heading.fullTag.length, position + heading.fullTag.length + contextRange);
+    
+    // Look for meaningful text in nearby paragraphs
+    const nearbyText = (beforeContext + afterContext).replace(/<[^>]*>/g, ' ').trim();
+    const words = nearbyText.split(/\s+/).filter(word => word.length > 2);
+    
+    if (words.length > 0) {
+      const meaningfulWords = words.slice(0, 3);
+      return meaningfulWords.join(' ');
+    }
+    
+    // Fallback to generic text based on language
+    const genericTexts = {
+      ja: ['見出し', 'セクション', 'コンテンツ'],
+      en: ['Heading', 'Section', 'Content'],
+      vi: ['Tiêu đề', 'Phần', 'Nội dung']
+    };
+    
+    const texts = genericTexts[lang] || genericTexts.en;
+    return texts[0];
+  }
+
+  countHeadingFixes(originalContent, fixedContent) {
+    // Count the number of heading-related changes
+    const originalHeadings = (originalContent.match(/<h[1-6][^>]*>[\s\S]*?<\/h[1-6]>/gi) || []).length;
+    const fixedHeadings = (fixedContent.match(/<h[1-6][^>]*>[\s\S]*?<\/h[1-6]>/gi) || []).length;
+    
+    // Simple heuristic: count tag changes
+    let changes = 0;
+    
+    // Count h1 additions
+    const originalH1 = (originalContent.match(/<h1[^>]*>/gi) || []).length;
+    const fixedH1 = (fixedContent.match(/<h1[^>]*>/gi) || []).length;
+    changes += Math.abs(fixedH1 - originalH1);
+    
+    // Count level changes (rough estimate)
+    for (let level = 1; level <= 6; level++) {
+      const originalCount = (originalContent.match(new RegExp(`<h${level}[^>]*>`, 'gi')) || []).length;
+      const fixedCount = (fixedContent.match(new RegExp(`<h${level}[^>]*>`, 'gi')) || []).length;
+      changes += Math.abs(fixedCount - originalCount);
+    }
+    
+    return Math.max(1, Math.floor(changes / 2)); // Rough estimate
+  }
+
+  async fixDescriptionLists(directory = '.') {
+    console.log(chalk.blue('📋 Fixing description list structure...'));
+    
+    const htmlFiles = await this.findHtmlFiles(directory);
+    const results = [];
+    let totalIssuesFound = 0;
+    
+    for (const file of htmlFiles) {
+      try {
+        const content = await fs.readFile(file, 'utf8');
+        const issues = this.analyzeDescriptionListStructure(content);
+        
+        if (issues.length > 0) {
+          console.log(chalk.cyan(`\n📁 ${file}:`));
+          issues.forEach(issue => {
+            console.log(chalk.yellow(`  ${issue.type}: ${issue.description}`));
+            if (issue.suggestion) {
+              console.log(chalk.gray(`    💡 ${issue.suggestion}`));
+            }
+            totalIssuesFound++;
+          });
+        }
+        
+        const fixed = this.fixDescriptionListStructureInContent(content);
+        
+        if (fixed !== content) {
+          if (this.config.backupFiles) {
+            await fs.writeFile(`${file}.backup`, content);
+          }
+          
+          if (!this.config.dryRun) {
+            await fs.writeFile(file, fixed);
+          }
+          
+          console.log(chalk.green(`✅ Fixed description list structure in: ${file}`));
+          results.push({ file, status: 'fixed', issues: issues.length });
+        } else {
+          results.push({ file, status: 'no-change', issues: issues.length });
+        }
+      } catch (error) {
+        console.error(chalk.red(`❌ Error processing ${file}: ${error.message}`));
+        results.push({ file, status: 'error', error: error.message });
+      }
+    }
+    
+    console.log(chalk.blue(`\n📊 Summary: Found ${totalIssuesFound} description list issues across ${results.length} files`));
+    return results;
+  }
+
+  analyzeDescriptionListStructure(content) {
+    const issues = [];
+    
+    // Find all dl elements
+    const dlPattern = /<dl[^>]*>([\s\S]*?)<\/dl>/gi;
+    let dlMatch;
+    let dlIndex = 0;
+    
+    while ((dlMatch = dlPattern.exec(content)) !== null) {
+      dlIndex++;
+      const dlContent = dlMatch[1];
+      const dlElement = dlMatch[0];
+      
+      // Analyze the content inside dl
+      const dtElements = (dlContent.match(/<dt[^>]*>[\s\S]*?<\/dt>/gi) || []);
+      const ddElements = (dlContent.match(/<dd[^>]*>[\s\S]*?<\/dd>/gi) || []);
+      
+      // Check for empty dl
+      if (dtElements.length === 0 && ddElements.length === 0) {
+        issues.push({
+          type: '📋 Empty description list',
+          description: `Description list ${dlIndex} is empty`,
+          suggestion: 'Add dt/dd pairs or remove the empty dl element',
+          severity: 'error',
+          dlIndex,
+          fix: 'remove-empty-dl'
+        });
+        continue;
+      }
+      
+      // Check for missing dt elements
+      if (dtElements.length === 0 && ddElements.length > 0) {
+        issues.push({
+          type: '📋 Missing dt elements',
+          description: `Description list ${dlIndex} has dd elements but no dt elements`,
+          suggestion: 'Add dt elements to describe the dd content',
+          severity: 'error',
+          dlIndex,
+          fix: 'add-missing-dt'
+        });
+      }
+      
+      // Check for missing dd elements
+      if (dtElements.length > 0 && ddElements.length === 0) {
+        issues.push({
+          type: '📋 Missing dd elements',
+          description: `Description list ${dlIndex} has dt elements but no dd elements`,
+          suggestion: 'Add dd elements to provide descriptions',
+          severity: 'error',
+          dlIndex,
+          fix: 'add-missing-dd'
+        });
+      }
+      
+      // Check for improper nesting (non-dt/dd elements directly in dl)
+      const invalidChildren = dlContent.match(/<(?!dt|dd|\/dt|\/dd)[a-zA-Z][^>]*>/g);
+      if (invalidChildren) {
+        const invalidTags = [...new Set(invalidChildren.map(tag => tag.match(/<([a-zA-Z]+)/)[1]))];
+        issues.push({
+          type: '📋 Invalid dl children',
+          description: `Description list ${dlIndex} contains invalid child elements: ${invalidTags.join(', ')}`,
+          suggestion: 'Only dt and dd elements should be direct children of dl',
+          severity: 'warning',
+          dlIndex,
+          fix: 'wrap-invalid-children'
+        });
+      }
+      
+      // Check for empty dt/dd elements
+      dtElements.forEach((dt, index) => {
+        const dtText = dt.replace(/<[^>]*>/g, '').trim();
+        if (!dtText) {
+          issues.push({
+            type: '📋 Empty dt element',
+            description: `Empty dt element in description list ${dlIndex}`,
+            suggestion: 'Add descriptive text to the dt element',
+            severity: 'warning',
+            dlIndex,
+            dtIndex: index,
+            fix: 'fix-empty-dt'
+          });
+        }
+      });
+      
+      ddElements.forEach((dd, index) => {
+        const ddText = dd.replace(/<[^>]*>/g, '').trim();
+        if (!ddText) {
+          issues.push({
+            type: '📋 Empty dd element',
+            description: `Empty dd element in description list ${dlIndex}`,
+            suggestion: 'Add descriptive content to the dd element',
+            severity: 'warning',
+            dlIndex,
+            ddIndex: index,
+            fix: 'fix-empty-dd'
+          });
+        }
+      });
+      
+      // Check for proper dt/dd pairing
+      if (dtElements.length > 0 && ddElements.length > 0) {
+        // Basic check: should have at least one dd for each dt
+        if (ddElements.length < dtElements.length) {
+          issues.push({
+            type: '📋 Insufficient dd elements',
+            description: `Description list ${dlIndex} has ${dtElements.length} dt elements but only ${ddElements.length} dd elements`,
+            suggestion: 'Each dt should have at least one corresponding dd element',
+            severity: 'warning',
+            dlIndex
+          });
+        }
+      }
+    }
+    
+    return issues;
+  }
+
+  fixDescriptionListStructureInContent(content) {
+    let fixed = content;
+    
+    // Fix empty dl elements
+    fixed = fixed.replace(/<dl[^>]*>\s*<\/dl>/gi, (match) => {
+      console.log(chalk.yellow(`  📋 Removed empty description list`));
+      return '';
+    });
+    
+    // Fix dl elements with only whitespace
+    fixed = fixed.replace(/<dl[^>]*>[\s\n\r]*<\/dl>/gi, (match) => {
+      console.log(chalk.yellow(`  📋 Removed empty description list`));
+      return '';
+    });
+    
+    // Fix dl elements with invalid direct children
+    fixed = fixed.replace(/<dl([^>]*)>([\s\S]*?)<\/dl>/gi, (match, attributes, content) => {
+      // Extract dt and dd elements
+      const dtElements = content.match(/<dt[^>]*>[\s\S]*?<\/dt>/gi) || [];
+      const ddElements = content.match(/<dd[^>]*>[\s\S]*?<\/dd>/gi) || [];
+      
+      // Find invalid children (not dt or dd)
+      let cleanContent = content;
+      
+      // Remove invalid direct children by wrapping them in dd
+      cleanContent = cleanContent.replace(/<(?!dt|dd|\/dt|\/dd)([a-zA-Z][^>]*)>([\s\S]*?)<\/[a-zA-Z]+>/gi, (invalidMatch, tag, innerContent) => {
+        console.log(chalk.yellow(`  📋 Wrapped invalid child element in dd`));
+        return `<dd>${invalidMatch}</dd>`;
+      });
+      
+      // Handle text nodes that are not in dt/dd
+      cleanContent = cleanContent.replace(/^([^<]+)(?=<(?:dt|dd))/gm, (textMatch) => {
+        const trimmed = textMatch.trim();
+        if (trimmed) {
+          console.log(chalk.yellow(`  📋 Wrapped loose text in dd`));
+          return `<dd>${trimmed}</dd>`;
+        }
+        return '';
+      });
+      
+      return `<dl${attributes}>${cleanContent}</dl>`;
+    });
+    
+    // Add missing dd elements for dt elements without corresponding dd
+    fixed = fixed.replace(/<dl([^>]*)>([\s\S]*?)<\/dl>/gi, (match, attributes, content) => {
+      const dtPattern = /<dt[^>]*>([\s\S]*?)<\/dt>/gi;
+      const ddPattern = /<dd[^>]*>[\s\S]*?<\/dd>/gi;
+      
+      const dtMatches = [...content.matchAll(dtPattern)];
+      const ddMatches = [...content.matchAll(ddPattern)];
+      
+      if (dtMatches.length > 0 && ddMatches.length === 0) {
+        // Add dd elements after each dt
+        let fixedContent = content;
+        
+        // Process from end to beginning to maintain positions
+        for (let i = dtMatches.length - 1; i >= 0; i--) {
+          const dtMatch = dtMatches[i];
+          const dtText = dtMatch[1].replace(/<[^>]*>/g, '').trim();
+          const ddText = this.generateDescriptionForTerm(dtText);
+          
+          const insertPosition = dtMatch.index + dtMatch[0].length;
+          fixedContent = fixedContent.slice(0, insertPosition) + 
+                        `\n    <dd>${ddText}</dd>` + 
+                        fixedContent.slice(insertPosition);
+        }
+        
+        console.log(chalk.yellow(`  📋 Added missing dd elements for ${dtMatches.length} dt elements`));
+        return `<dl${attributes}>${fixedContent}</dl>`;
+      }
+      
+      return match;
+    });
+    
+    // Fix empty dt/dd elements
+    fixed = fixed.replace(/<dt[^>]*>\s*<\/dt>/gi, (match) => {
+      const lang = this.config.language;
+      const defaultText = lang === 'ja' ? '項目' : lang === 'vi' ? 'Mục' : 'Term';
+      console.log(chalk.yellow(`  📋 Added text to empty dt element`));
+      return match.replace(/>\s*</, `>${defaultText}<`);
+    });
+    
+    fixed = fixed.replace(/<dd[^>]*>\s*<\/dd>/gi, (match) => {
+      const lang = this.config.language;
+      const defaultText = lang === 'ja' ? '説明' : lang === 'vi' ? 'Mô tả' : 'Description';
+      console.log(chalk.yellow(`  📋 Added text to empty dd element`));
+      return match.replace(/>\s*</, `>${defaultText}<`);
+    });
+    
+    return fixed;
+  }
+
+  generateDescriptionForTerm(termText) {
+    const lang = this.config.language;
+    
+    // Try to generate meaningful description based on term
+    if (termText) {
+      const descriptions = {
+        ja: `${termText}の説明`,
+        en: `Description of ${termText}`,
+        vi: `Mô tả về ${termText}`
+      };
+      return descriptions[lang] || descriptions.en;
+    }
+    
+    // Fallback to generic description
+    const fallbacks = {
+      ja: '説明',
+      en: 'Description',
+      vi: 'Mô tả'
+    };
+    
+    return fallbacks[lang] || fallbacks.en;
+  }
+
+  /**
+   * Fix heading structure issues
+   * Ensures proper heading hierarchy: only one h1, proper nesting, no duplicates in same section
+   */
+  async fixHeadingStructure(directory = '.') {
+    console.log(chalk.blue('📑 Fixing heading structure...'));
+    
+    const htmlFiles = await this.findHtmlFiles(directory);
+    const results = [];
+    let totalIssuesFound = 0;
+    let totalFixesApplied = 0;
+    
+    for (const file of htmlFiles) {
+      try {
+        const content = await fs.readFile(file, 'utf8');
+        const analysis = this.analyzeHeadingStructure(content);
+        
+        if (analysis.issues.length > 0) {
+          console.log(chalk.cyan(`\n📁 ${file}:`));
+          analysis.issues.forEach(issue => {
+            console.log(chalk.yellow(`  📑 ${issue.type}: ${issue.description}`));
+            console.log(chalk.gray(`    💡 ${issue.suggestion}`));
+            totalIssuesFound++;
+          });
+        }
+        
+        let fixed = content;
+        let fixesApplied = 0;
+        
+        if (this.config.autoFixHeadings) {
+          const fixResult = this.fixHeadingStructureInContent(content, analysis);
+          fixed = fixResult.content;
+          fixesApplied = fixResult.fixes;
+          totalFixesApplied += fixesApplied;
+          
+          if (fixesApplied > 0) {
+            console.log(chalk.green(`✅ Fixed heading structure in: ${file} (${fixesApplied} fixes)`));
+          }
+        }
+        
+        if (fixed !== content) {
+          if (this.config.backupFiles) {
+            await fs.writeFile(`${file}.backup`, content);
+          }
+          
+          if (!this.config.dryRun) {
+            await fs.writeFile(file, fixed);
+          }
+          
+          results.push({ 
+            file, 
+            status: 'fixed', 
+            issues: analysis.issues.length,
+            fixes: fixesApplied
+          });
+        } else {
+          results.push({ 
+            file, 
+            status: 'no-change', 
+            issues: analysis.issues.length,
+            fixes: 0
+          });
+        }
+      } catch (error) {
+        console.error(chalk.red(`❌ Error processing ${file}: ${error.message}`));
+        results.push({ file, status: 'error', error: error.message });
+      }
+    }
+    
+    console.log(chalk.blue(`\n📊 Summary: Found ${totalIssuesFound} heading issues across ${results.length} files`));
+    if (this.config.autoFixHeadings) {
+      console.log(chalk.blue(`   Fixed ${totalFixesApplied} heading issues automatically`));
+    } else {
+      console.log(chalk.gray('💡 Use --auto-fix-headings option to enable automatic fixes'));
+    }
+    
+    return results;
+  }
+
+  /**
+   * Analyze heading structure for issues
+   */
+  analyzeHeadingStructure(content) {
+    const issues = [];
+    const headings = [];
+    
+    // Extract all headings with their positions and context
+    const headingRegex = /<h([1-6])([^>]*)>(.*?)<\/h[1-6]>/gi;
+    let match;
+    let headingIndex = 0;
+    
+    while ((match = headingRegex.exec(content)) !== null) {
+      headingIndex++;
+      const level = parseInt(match[1]);
+      const attributes = match[2];
+      const text = match[3].replace(/<[^>]*>/g, '').trim();
+      const fullMatch = match[0];
+      const position = match.index;
+      
+      // Find the section context (look for parent elements)
+      const beforeContent = content.substring(0, position);
+      const sectionContext = this.findSectionContext(beforeContent);
+      
+      headings.push({
+        level,
+        text,
+        attributes,
+        fullMatch,
+        position,
+        index: headingIndex,
+        sectionContext
+      });
+    }
+    
+    if (headings.length === 0) {
+      return { issues, headings };
+    }
+    
+    // Check for multiple h1 elements
+    const h1Elements = headings.filter(h => h.level === 1);
+    if (h1Elements.length > 1) {
+      issues.push({
+        type: 'Multiple h1 elements',
+        description: `Found ${h1Elements.length} h1 elements, should have only one`,
+        suggestion: 'Convert extra h1 elements to h2-h6 as appropriate',
+        severity: 'error',
+        headings: h1Elements,
+        fix: 'convert-extra-h1'
+      });
+    } else if (h1Elements.length === 0) {
+      issues.push({
+        type: 'Missing h1 element',
+        description: 'Page should have exactly one h1 element',
+        suggestion: 'Convert the first heading to h1 or add an h1 element',
+        severity: 'error',
+        fix: 'add-missing-h1'
+      });
+    }
+    
+    // Check for heading level skipping
+    for (let i = 1; i < headings.length; i++) {
+      const current = headings[i];
+      const previous = headings[i - 1];
+      
+      if (current.level > previous.level + 1) {
+        issues.push({
+          type: 'Heading level skip',
+          description: `Heading level jumps from h${previous.level} to h${current.level}`,
+          suggestion: `Use h${previous.level + 1} instead of h${current.level}`,
+          severity: 'warning',
+          heading: current,
+          previousHeading: previous,
+          fix: 'fix-level-skip'
+        });
+      }
+    }
+    
+    // Check for empty headings
+    headings.forEach(heading => {
+      if (!heading.text || heading.text.length === 0) {
+        issues.push({
+          type: 'Empty heading',
+          description: `Heading ${heading.index} (h${heading.level}) is empty`,
+          suggestion: 'Add descriptive text to the heading or remove it',
+          severity: 'warning',
+          heading,
+          fix: 'fix-empty-heading'
+        });
+      }
+    });
+    
+    // Check for duplicate headings in the same section
+    const sectionGroups = {};
+    headings.forEach(heading => {
+      const sectionKey = heading.sectionContext || 'root';
+      if (!sectionGroups[sectionKey]) {
+        sectionGroups[sectionKey] = [];
+      }
+      sectionGroups[sectionKey].push(heading);
+    });
+    
+    Object.entries(sectionGroups).forEach(([section, sectionHeadings]) => {
+      const textGroups = {};
+      sectionHeadings.forEach(heading => {
+        if (heading.text) {
+          const normalizedText = heading.text.toLowerCase().trim();
+          if (!textGroups[normalizedText]) {
+            textGroups[normalizedText] = [];
+          }
+          textGroups[normalizedText].push(heading);
+        }
+      });
+      
+      Object.entries(textGroups).forEach(([text, duplicates]) => {
+        if (duplicates.length > 1 && duplicates[0].level === duplicates[1].level) {
+          issues.push({
+            type: 'Duplicate heading',
+            description: `Duplicate h${duplicates[0].level} heading: "${text}"`,
+            suggestion: 'Make heading text unique or merge content',
+            severity: 'warning',
+            headings: duplicates,
+            section,
+            fix: 'fix-duplicate-heading'
+          });
+        }
+      });
+    });
+    
+    return { issues, headings };
+  }
+
+  /**
+   * Find section context for a heading
+   */
+  findSectionContext(beforeContent) {
+    // Look for common section elements
+    const sectionPatterns = [
+      /<section[^>]*>/gi,
+      /<article[^>]*>/gi,
+      /<main[^>]*>/gi,
+      /<div[^>]*class[^>]*section[^>]*>/gi,
+      /<div[^>]*id[^>]*section[^>]*>/gi
+    ];
+    
+    let lastSectionMatch = null;
+    let lastSectionPosition = -1;
+    
+    sectionPatterns.forEach(pattern => {
+      let match;
+      pattern.lastIndex = 0; // Reset regex
+      while ((match = pattern.exec(beforeContent)) !== null) {
+        if (match.index > lastSectionPosition) {
+          lastSectionPosition = match.index;
+          lastSectionMatch = match[0];
+        }
+      }
+    });
+    
+    return lastSectionMatch ? `section_${lastSectionPosition}` : 'root';
+  }
+
+  /**
+   * Fix heading structure issues in content
+   */
+  fixHeadingStructureInContent(content, analysis) {
+    let fixed = content;
+    let fixesApplied = 0;
+    
+    if (!analysis || !analysis.issues) {
+      return { content: fixed, fixes: fixesApplied };
+    }
+    
+    // Sort issues by position (from end to start to avoid position shifts)
+    const sortedIssues = analysis.issues
+      .filter(issue => issue.fix)
+      .sort((a, b) => {
+        const posA = a.heading?.position || a.headings?.[0]?.position || 0;
+        const posB = b.heading?.position || b.headings?.[0]?.position || 0;
+        return posB - posA;
+      });
+    
+    sortedIssues.forEach(issue => {
+      switch (issue.fix) {
+        case 'convert-extra-h1':
+          // Convert extra h1 elements to h2
+          if (issue.headings && issue.headings.length > 1) {
+            // Keep the first h1, convert others to h2
+            for (let i = 1; i < issue.headings.length; i++) {
+              const heading = issue.headings[i];
+              const newHeading = heading.fullMatch.replace(/h1/gi, 'h2');
+              fixed = fixed.replace(heading.fullMatch, newHeading);
+              console.log(chalk.yellow(`  📑 Converted extra h1 to h2: "${heading.text}"`));
+              fixesApplied++;
+            }
+          }
+          break;
+          
+        case 'add-missing-h1':
+          // Convert the first heading to h1
+          if (analysis.headings && analysis.headings.length > 0) {
+            const firstHeading = analysis.headings[0];
+            const newHeading = firstHeading.fullMatch.replace(
+              new RegExp(`h${firstHeading.level}`, 'gi'), 
+              'h1'
+            );
+            fixed = fixed.replace(firstHeading.fullMatch, newHeading);
+            console.log(chalk.yellow(`  📑 Converted first heading to h1: "${firstHeading.text}"`));
+            fixesApplied++;
+          }
+          break;
+          
+        case 'fix-level-skip':
+          // Fix heading level skipping
+          if (issue.heading && issue.previousHeading) {
+            const correctLevel = issue.previousHeading.level + 1;
+            const newHeading = issue.heading.fullMatch.replace(
+              new RegExp(`h${issue.heading.level}`, 'gi'),
+              `h${correctLevel}`
+            );
+            fixed = fixed.replace(issue.heading.fullMatch, newHeading);
+            console.log(chalk.yellow(`  📑 Fixed level skip: h${issue.heading.level} → h${correctLevel} for "${issue.heading.text}"`));
+            fixesApplied++;
+          }
+          break;
+          
+        case 'fix-empty-heading':
+          // Add text to empty headings based on context
+          if (issue.heading) {
+            const contextText = this.generateHeadingText(issue.heading, content);
+            const newHeading = issue.heading.fullMatch.replace(
+              /(<h[1-6][^>]*>)(\s*)(.*?)(\s*)(<\/h[1-6]>)/i,
+              `$1${contextText}$5`
+            );
+            fixed = fixed.replace(issue.heading.fullMatch, newHeading);
+            console.log(chalk.yellow(`  📑 Added text to empty heading: "${contextText}"`));
+            fixesApplied++;
+          }
+          break;
+          
+        case 'fix-duplicate-heading':
+          // Make duplicate headings unique by adding numbers
+          if (issue.headings && issue.headings.length > 1) {
+            for (let i = 1; i < issue.headings.length; i++) {
+              const heading = issue.headings[i];
+              const newText = `${heading.text} (${i + 1})`;
+              const newHeading = heading.fullMatch.replace(
+                heading.text,
+                newText
+              );
+              fixed = fixed.replace(heading.fullMatch, newHeading);
+              console.log(chalk.yellow(`  📑 Made duplicate heading unique: "${newText}"`));
+              fixesApplied++;
+            }
+          }
+          break;
+      }
+    });
+    
+    return { content: fixed, fixes: fixesApplied };
+  }
+
+  /**
+   * Generate appropriate text for empty headings based on context
+   */
+  generateHeadingText(heading, content) {
+    // Look for context around the heading
+    const position = heading.position;
+    const beforeText = content.substring(Math.max(0, position - 200), position);
+    const afterText = content.substring(position + heading.fullMatch.length, position + heading.fullMatch.length + 200);
+    
+    // Extract meaningful words from surrounding content
+    const contextWords = (beforeText + ' ' + afterText)
+      .replace(/<[^>]*>/g, ' ')
+      .replace(/[^\w\s]/g, ' ')
+      .split(/\s+/)
+      .filter(word => word.length > 3 && !/^\d+$/.test(word))
+      .slice(0, 3);
+    
+    if (contextWords.length > 0) {
+      return contextWords.join(' ');
+    }
+    
+    // Fallback based on heading level
+    const levelNames = {
+      1: 'Main Content',
+      2: 'Section',
+      3: 'Subsection', 
+      4: 'Details',
+      5: 'Information',
+      6: 'Notes'
+    };
+    
+    return levelNames[heading.level] || 'Content';
+  }
+
+  async findHtmlFiles(directory) {
+    const files = [];
+    
+    // Check if the path is a file or directory
+    const stat = await fs.stat(directory);
+    
+    if (stat.isFile()) {
+      // If it's a file, check if it's HTML
+      if (directory.endsWith('.html')) {
+        files.push(directory);
+      }
+      return files;
+    }
+    
+    // If it's a directory, scan recursively
+    async function scan(dir) {
+      const entries = await fs.readdir(dir, { withFileTypes: true });
+      
+      for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        
+        if (entry.isDirectory() && !entry.name.startsWith('.')) {
+          await scan(fullPath);
+        } else if (entry.isFile() && entry.name.endsWith('.html')) {
+          files.push(fullPath);
+        }
+      }
+    }
+    
+    await scan(directory);
+    return files;
+  }
+
+  // Check for unused files in the project
+  async checkUnusedFiles(directory = '.') {
+    console.log(chalk.blue('🗂️ Checking for unused files...'));
+    
+    const results = [];
+    const allFiles = await this.findAllProjectFiles(directory);
+    const referencedFiles = await this.findReferencedFiles(directory);
+    
+    // Normalize paths for comparison
+    const normalizedReferenced = new Set();
+    referencedFiles.forEach(file => {
+      normalizedReferenced.add(path.resolve(file));
+    });
+    
+    for (const file of allFiles) {
+      const absolutePath = path.resolve(file);
+      
+      // Skip certain files that are typically not referenced directly
+      if (this.shouldSkipUnusedCheck(file)) {
+        continue;
+      }
+      
+      if (!normalizedReferenced.has(absolutePath)) {
+        const relativePath = path.relative(directory, file);
+        const fileType = this.getFileType(file);
+        
+        console.log(chalk.yellow(`  🗑️ Unused ${fileType}: ${relativePath}`));
+        
+        results.push({
+          type: `🗑️ Unused ${fileType}`,
+          description: `File not referenced anywhere: ${relativePath}`,
+          suggestion: `Consider removing if truly unused: ${relativePath}`,
+          filePath: file,
+          fileType: fileType,
+          relativePath: relativePath
+        });
+      }
+    }
+    
+    console.log(chalk.blue(`\n📊 Summary: Found ${results.length} potentially unused files`));
+    console.log(chalk.gray('💡 Review carefully before removing - some files may be referenced dynamically'));
+    
+    return results;
+  }
+
+  async findAllProjectFiles(directory) {
+    const files = [];
+    const extensions = ['.html', '.css', '.js', '.jpg', '.jpeg', '.png', '.gif', '.svg', '.webp', '.ico', '.pdf', '.mp4', '.webm', '.mp3', '.wav'];
+    
+    async function scan(dir) {
+      try {
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        
+        for (const entry of entries) {
+          const fullPath = path.join(dir, entry.name);
+          
+          if (entry.isDirectory()) {
+            // Skip common directories that shouldn't be analyzed
+            if (!this.shouldSkipDirectory(entry.name)) {
+              await scan(fullPath);
+            }
+          } else if (entry.isFile()) {
+            const ext = path.extname(entry.name).toLowerCase();
+            if (extensions.includes(ext)) {
+              files.push(fullPath);
+            }
+          }
+        }
+      } catch (error) {
+        // Skip directories we can't read
+      }
+    }
+    
+    await scan.call(this, directory);
+    return files;
+  }
+
+  async findReferencedFiles(directory) {
+    const referenced = new Set();
+    const htmlFiles = await this.findHtmlFiles(directory);
+    const cssFiles = await this.findCssFiles(directory);
+    const jsFiles = await this.findJsFiles(directory);
+    
+    // Find references in HTML files
+    for (const htmlFile of htmlFiles) {
+      try {
+        const content = await fs.readFile(htmlFile, 'utf8');
+        const refs = this.extractFileReferences(content, path.dirname(htmlFile));
+        refs.forEach(ref => referenced.add(ref));
+      } catch (error) {
+        // Skip files we can't read
+      }
+    }
+    
+    // Find references in CSS files
+    for (const cssFile of cssFiles) {
+      try {
+        const content = await fs.readFile(cssFile, 'utf8');
+        const refs = this.extractCssReferences(content, path.dirname(cssFile));
+        refs.forEach(ref => referenced.add(ref));
+      } catch (error) {
+        // Skip files we can't read
+      }
+    }
+    
+    // Find references in JS files
+    for (const jsFile of jsFiles) {
+      try {
+        const content = await fs.readFile(jsFile, 'utf8');
+        const refs = this.extractJsReferences(content, path.dirname(jsFile));
+        refs.forEach(ref => referenced.add(ref));
+      } catch (error) {
+        // Skip files we can't read
+      }
+    }
+    
+    return Array.from(referenced);
+  }
+
+  extractFileReferences(content, baseDir) {
+    const references = [];
+    
+    // HTML patterns for file references
+    const patterns = [
+      // Images
+      /<img[^>]*src\s*=\s*["']([^"']+)["']/gi,
+      // Links (CSS, other files)
+      /<link[^>]*href\s*=\s*["']([^"']+)["']/gi,
+      // Scripts
+      /<script[^>]*src\s*=\s*["']([^"']+)["']/gi,
+      // Anchors
+      /<a[^>]*href\s*=\s*["']([^"']+)["']/gi,
+      // Video/Audio
+      /<(?:video|audio)[^>]*src\s*=\s*["']([^"']+)["']/gi,
+      // Object/Embed
+      /<(?:object|embed)[^>]*src\s*=\s*["']([^"']+)["']/gi,
+      // Iframe
+      /<iframe[^>]*src\s*=\s*["']([^"']+)["']/gi,
+      // Meta (for icons)
+      /<meta[^>]*content\s*=\s*["']([^"']+\.(ico|png|jpg|jpeg|svg))["']/gi
+    ];
+    
+    for (const pattern of patterns) {
+      let match;
+      while ((match = pattern.exec(content)) !== null) {
+        const url = match[1];
+        if (this.isLocalFile(url)) {
+          const resolvedPath = this.resolveFilePath(url, baseDir);
+          if (resolvedPath) {
+            references.push(resolvedPath);
+          }
+        }
+      }
+    }
+    
+    return references;
+  }
+
+  extractCssReferences(content, baseDir) {
+    const references = [];
+    
+    // CSS patterns for file references
+    const patterns = [
+      // url() function
+      /url\s*\(\s*["']?([^"')]+)["']?\s*\)/gi,
+      // @import
+      /@import\s+["']([^"']+)["']/gi
+    ];
+    
+    for (const pattern of patterns) {
+      let match;
+      while ((match = pattern.exec(content)) !== null) {
+        const url = match[1];
+        if (this.isLocalFile(url)) {
+          const resolvedPath = this.resolveFilePath(url, baseDir);
+          if (resolvedPath) {
+            references.push(resolvedPath);
+          }
+        }
+      }
+    }
+    
+    return references;
+  }
+
+  extractJsReferences(content, baseDir) {
+    const references = [];
+    
+    // JavaScript patterns for file references
+    const patterns = [
+      // require() calls
+      /require\s*\(\s*["']([^"']+)["']\s*\)/gi,
+      // import statements
+      /import\s+.*?from\s+["']([^"']+)["']/gi,
+      // fetch() calls with local files
+      /fetch\s*\(\s*["']([^"']*\.(html|css|js|json|xml))["']\s*\)/gi,
+      // XMLHttpRequest
+      /\.open\s*\(\s*["'][^"']*["']\s*,\s*["']([^"']*\.(html|css|js|json|xml))["']/gi
+    ];
+    
+    for (const pattern of patterns) {
+      let match;
+      while ((match = pattern.exec(content)) !== null) {
+        const url = match[1];
+        if (this.isLocalFile(url)) {
+          const resolvedPath = this.resolveFilePath(url, baseDir);
+          if (resolvedPath) {
+            references.push(resolvedPath);
+          }
+        }
+      }
+    }
+    
+    return references;
+  }
+
+  async findCssFiles(directory) {
+    const files = [];
+    
+    async function scan(dir) {
+      try {
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        
+        for (const entry of entries) {
+          const fullPath = path.join(dir, entry.name);
+          
+          if (entry.isDirectory() && !entry.name.startsWith('.')) {
+            await scan(fullPath);
+          } else if (entry.isFile() && entry.name.endsWith('.css')) {
+            files.push(fullPath);
+          }
+        }
+      } catch (error) {
+        // Skip directories we can't read
+      }
+    }
+    
+    await scan(directory);
+    return files;
+  }
+
+  async findJsFiles(directory) {
+    const files = [];
+    
+    async function scan(dir) {
+      try {
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        
+        for (const entry of entries) {
+          const fullPath = path.join(dir, entry.name);
+          
+          if (entry.isDirectory() && !entry.name.startsWith('.')) {
+            await scan(fullPath);
+          } else if (entry.isFile() && (entry.name.endsWith('.js') || entry.name.endsWith('.mjs'))) {
+            files.push(fullPath);
+          }
+        }
+      } catch (error) {
+        // Skip directories we can't read
+      }
+    }
+    
+    await scan(directory);
+    return files;
+  }
+
+  shouldSkipDirectory(dirName) {
+    const skipDirs = [
+      'node_modules', '.git', '.svn', '.hg', 'bower_components',
+      'vendor', 'tmp', 'temp', '.cache', 'dist', 'build', 'coverage',
+      '.nyc_output', '.vscode', '.idea', '__pycache__', '.DS_Store'
+    ];
+    return skipDirs.includes(dirName) || dirName.startsWith('.');
+  }
+
+  shouldSkipUnusedCheck(filePath) {
+    const fileName = path.basename(filePath);
+    const dirName = path.basename(path.dirname(filePath));
+    
+    // Skip certain file types and patterns
+    const skipPatterns = [
+      // Common files that might not be directly referenced
+      /^(index|main|app)\.(html|js|css)$/i,
+      /^(readme|license|changelog)/i,
+      /^package\.json$/i,
+      /^\.gitignore$/i,
+      /^favicon\.(ico|png)$/i,
+      /^robots\.txt$/i,
+      /^sitemap\.xml$/i,
+      // Backup files
+      /\.backup$/i,
+      // Test directories
+      /test|spec|__tests__/i
+    ];
+    
+    return skipPatterns.some(pattern => 
+      pattern.test(fileName) || pattern.test(dirName)
+    );
+  }
+
+  getFileType(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    const typeMap = {
+      '.html': 'HTML',
+      '.css': 'CSS',
+      '.js': 'JavaScript',
+      '.mjs': 'JavaScript Module',
+      '.jpg': 'Image',
+      '.jpeg': 'Image',
+      '.png': 'Image',
+      '.gif': 'Image',
+      '.svg': 'SVG',
+      '.webp': 'Image',
+      '.ico': 'Icon',
+      '.pdf': 'PDF',
+      '.mp4': 'Video',
+      '.webm': 'Video',
+      '.mp3': 'Audio',
+      '.wav': 'Audio'
+    };
+    
+    return typeMap[ext] || 'File';
+  }
+
+  isLocalFile(url) {
+    return !url.startsWith('http://') && 
+           !url.startsWith('https://') && 
+           !url.startsWith('//') &&
+           !url.startsWith('data:') &&
+           !url.startsWith('mailto:') &&
+           !url.startsWith('tel:') &&
+           !url.startsWith('#');
+  }
+
+  resolveFilePath(url, baseDir) {
+    try {
+      let filePath;
+      
+      if (url.startsWith('/')) {
+        // Absolute path from web root
+        filePath = path.join(baseDir, url.substring(1));
+      } else {
+        // Relative path
+        filePath = path.resolve(baseDir, url);
+      }
+      
+      return filePath;
+    } catch (error) {
+      return null;
+    }
+  }
+
+  // Check for dead code in CSS and JavaScript files
+  async checkDeadCode(directory = '.') {
+    console.log(chalk.blue('☠️ Checking for dead code...'));
+    
+    const results = [];
+    
+    // Check CSS dead code
+    const cssDeadCode = await this.checkDeadCss(directory);
+    results.push(...cssDeadCode);
+    
+    // Check JavaScript dead code
+    const jsDeadCode = await this.checkDeadJs(directory);
+    results.push(...jsDeadCode);
+    
+    console.log(chalk.blue(`\n📊 Summary: Found ${results.length} potential dead code issues`));
+    console.log(chalk.gray('💡 Dead code analysis is heuristic - manual review recommended'));
+    
+    return results;
+  }
+
+  async checkDeadCss(directory) {
+    console.log(chalk.cyan('🎨 Analyzing CSS dead code...'));
+    
+    const results = [];
+    const cssFiles = await this.findCssFiles(directory);
+    const htmlFiles = await this.findHtmlFiles(directory);
+    
+    // Get all HTML content to check against
+    let allHtmlContent = '';
+    for (const htmlFile of htmlFiles) {
+      try {
+        const content = await fs.readFile(htmlFile, 'utf8');
+        allHtmlContent += content + '\n';
+      } catch (error) {
+        // Skip files we can't read
+      }
+    }
+    
+    for (const cssFile of cssFiles) {
+      try {
+        const content = await fs.readFile(cssFile, 'utf8');
+        const deadRules = this.findDeadCssRules(content, allHtmlContent);
+        
+        if (deadRules.length > 0) {
+          const relativePath = path.relative(directory, cssFile);
+          console.log(chalk.cyan(`\n📁 ${relativePath}:`));
+          
+          deadRules.forEach(rule => {
+            console.log(chalk.yellow(`  ☠️ Potentially dead CSS: ${rule.selector}`));
+            results.push({
+              type: '☠️ Dead CSS rule',
+              description: `CSS selector not found in HTML: ${rule.selector}`,
+              suggestion: `Consider removing unused CSS rule: ${rule.selector}`,
+              filePath: cssFile,
+              relativePath: relativePath,
+              selector: rule.selector,
+              lineNumber: rule.lineNumber
+            });
+          });
+        }
+        
+      } catch (error) {
+        console.error(chalk.red(`❌ Error analyzing CSS ${cssFile}: ${error.message}`));
+      }
+    }
+    
+    return results;
+  }
+
+  findDeadCssRules(cssContent, htmlContent) {
+    const deadRules = [];
+    
+    // Simple CSS parser to extract selectors
+    const cssRules = this.parseCssSelectors(cssContent);
+    
+    for (const rule of cssRules) {
+      if (this.isCssSelectorUsed(rule.selector, htmlContent)) {
+        continue; // Selector is used
+      }
+      
+      // Skip certain selectors that are commonly dynamic
+      if (this.shouldSkipCssSelector(rule.selector)) {
+        continue;
+      }
+      
+      deadRules.push(rule);
+    }
+    
+    return deadRules;
+  }
+
+  parseCssSelectors(cssContent) {
+    const rules = [];
+    const lines = cssContent.split('\n');
+    let inRule = false;
+    
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i].trim();
+      
+      // Skip comments and empty lines
+      if (line.startsWith('/*') || line.includes('*/') || !line) {
+        continue;
+      }
+      
+      // Skip @rules like @media, @keyframes
+      if (line.startsWith('@')) {
+        continue;
+      }
+      
+      // Check if we're entering a rule block
+      if (line.includes('{')) {
+        inRule = true;
+        // Extract selector part before the {
+        const selectorPart = line.split('{')[0].trim();
+        if (selectorPart && !selectorPart.includes(':') && !selectorPart.includes(';')) {
+          rules.push({
+            selector: selectorPart,
+            lineNumber: i + 1
+          });
+        }
+        continue;
+      }
+      
+      // Check if we're exiting a rule block
+      if (line.includes('}')) {
+        inRule = false;
+        continue;
+      }
+      
+      // If we're not in a rule and line doesn't contain CSS properties, it might be a selector
+      if (!inRule && !line.includes(':') && !line.includes(';') && line.length > 0) {
+        rules.push({
+          selector: line,
+          lineNumber: i + 1
+        });
+      }
+    }
+    
+    return rules;
+  }
+
+  isCssSelectorUsed(selector, htmlContent) {
+    // Simple heuristic checks
+    
+    // Check for class selectors
+    if (selector.startsWith('.')) {
+      const className = selector.substring(1).split(/[:\s>+~]/)[0];
+      return htmlContent.includes(`class="${className}"`) || 
+             htmlContent.includes(`class='${className}'`) ||
+             htmlContent.includes(`class=".*${className}.*"`) ||
+             htmlContent.includes(`class='.*${className}.*'`);
+    }
+    
+    // Check for ID selectors
+    if (selector.startsWith('#')) {
+      const idName = selector.substring(1).split(/[:\s>+~]/)[0];
+      return htmlContent.includes(`id="${idName}"`) || 
+             htmlContent.includes(`id='${idName}'`);
+    }
+    
+    // Check for tag selectors
+    const tagMatch = selector.match(/^([a-zA-Z]+)/);
+    if (tagMatch) {
+      const tagName = tagMatch[1].toLowerCase();
+      return htmlContent.toLowerCase().includes(`<${tagName}`);
+    }
+    
+    return true; // Conservative approach - assume complex selectors are used
+  }
+
+  shouldSkipCssSelector(selector) {
+    const skipPatterns = [
+      // Pseudo-classes and pseudo-elements
+      /:hover|:focus|:active|:visited|:before|:after/,
+      // Media queries and complex selectors
+      /@media|@keyframes|@font-face/,
+      // Dynamic classes that might be added by JavaScript
+      /\.active|\.selected|\.hidden|\.show|\.hide/,
+      // Common framework classes
+      /\.btn|\.form|\.nav|\.modal|\.tooltip/
+    ];
+    
+    return skipPatterns.some(pattern => pattern.test(selector));
+  }
+
+  async checkDeadJs(directory) {
+    console.log(chalk.cyan('📜 Analyzing JavaScript dead code...'));
+    
+    const results = [];
+    const jsFiles = await this.findJsFiles(directory);
+    const htmlFiles = await this.findHtmlFiles(directory);
+    
+    // Get all HTML content to check against
+    let allHtmlContent = '';
+    for (const htmlFile of htmlFiles) {
+      try {
+        const content = await fs.readFile(htmlFile, 'utf8');
+        allHtmlContent += content + '\n';
+      } catch (error) {
+        // Skip files we can't read
+      }
+    }
+    
+    for (const jsFile of jsFiles) {
+      try {
+        const content = await fs.readFile(jsFile, 'utf8');
+        const deadCode = this.findDeadJsCode(content, allHtmlContent, jsFile);
+        
+        if (deadCode.length > 0) {
+          const relativePath = path.relative(directory, jsFile);
+          console.log(chalk.cyan(`\n📁 ${relativePath}:`));
+          
+          deadCode.forEach(code => {
+            console.log(chalk.yellow(`  ☠️ Potentially dead JS: ${code.name}`));
+            results.push({
+              type: '☠️ Dead JavaScript',
+              description: `${code.type} not referenced: ${code.name}`,
+              suggestion: `Consider removing unused ${code.type.toLowerCase()}: ${code.name}`,
+              filePath: jsFile,
+              relativePath: relativePath,
+              name: code.name,
+              codeType: code.type,
+              lineNumber: code.lineNumber
+            });
+          });
+        }
+        
+      } catch (error) {
+        console.error(chalk.red(`❌ Error analyzing JS ${jsFile}: ${error.message}`));
+      }
+    }
+    
+    return results;
+  }
+
+  findDeadJsCode(jsContent, htmlContent, jsFilePath) {
+    const deadCode = [];
+    
+    // Find function declarations
+    const functions = this.parseJsFunctions(jsContent);
+    const variables = this.parseJsVariables(jsContent);
+    
+    // Check if functions are used
+    for (const func of functions) {
+      if (!this.isJsFunctionUsed(func.name, jsContent, htmlContent)) {
+        deadCode.push({
+          type: 'Function',
+          name: func.name,
+          lineNumber: func.lineNumber
+        });
+      }
+    }
+    
+    // Check if variables are used
+    for (const variable of variables) {
+      if (!this.isJsVariableUsed(variable.name, jsContent, htmlContent)) {
+        deadCode.push({
+          type: 'Variable',
+          name: variable.name,
+          lineNumber: variable.lineNumber
+        });
+      }
+    }
+    
+    return deadCode;
+  }
+
+  parseJsFunctions(jsContent) {
+    const functions = [];
+    const lines = jsContent.split('\n');
+    
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      
+      // Function declarations
+      const funcMatch = line.match(/function\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s*\(/);
+      if (funcMatch) {
+        functions.push({
+          name: funcMatch[1],
+          lineNumber: i + 1
+        });
+      }
+      
+      // Arrow functions assigned to variables
+      const arrowMatch = line.match(/(?:const|let|var)\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s*=\s*\([^)]*\)\s*=>/);
+      if (arrowMatch) {
+        functions.push({
+          name: arrowMatch[1],
+          lineNumber: i + 1
+        });
+      }
+    }
+    
+    return functions;
+  }
+
+  parseJsVariables(jsContent) {
+    const variables = [];
+    const lines = jsContent.split('\n');
+    
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      
+      // Variable declarations
+      const varMatch = line.match(/(?:const|let|var)\s+([a-zA-Z_$][a-zA-Z0-9_$]*)/);
+      if (varMatch && !line.includes('=') && !line.includes('function')) {
+        variables.push({
+          name: varMatch[1],
+          lineNumber: i + 1
+        });
+      }
+    }
+    
+    return variables;
+  }
+
+  isJsFunctionUsed(functionName, jsContent, htmlContent) {
+    // Check if function is called in JS
+    const jsCallPattern = new RegExp(`${functionName}\\s*\\(`, 'g');
+    if (jsCallPattern.test(jsContent)) {
+      return true;
+    }
+    
+    // Check if function is referenced in HTML (onclick, etc.)
+    const htmlCallPattern = new RegExp(`${functionName}\\s*\\(`, 'g');
+    if (htmlCallPattern.test(htmlContent)) {
+      return true;
+    }
+    
+    // Check for event handlers in HTML
+    const eventPattern = new RegExp(`on\\w+\\s*=\\s*["'][^"']*${functionName}`, 'g');
+    if (eventPattern.test(htmlContent)) {
+      return true;
+    }
+    
+    return false;
+  }
+
+  isJsVariableUsed(variableName, jsContent, htmlContent) {
+    // Create pattern that excludes the declaration line
+    const lines = jsContent.split('\n');
+    let usageFound = false;
+    
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      
+      // Skip the declaration line
+      if (line.includes(`${variableName}`) && 
+          (line.includes('const ') || line.includes('let ') || line.includes('var '))) {
+        continue;
+      }
+      
+      // Check for usage
+      const usagePattern = new RegExp(`\\b${variableName}\\b`);
+      if (usagePattern.test(line)) {
+        usageFound = true;
+        break;
+      }
+    }
+    
+    return usageFound;
+  }
+
+  // Check file sizes and suggest optimizations
+  async checkFileSizes(directory = '.') {
+    console.log(chalk.blue('📏 Analyzing file sizes and suggesting optimizations...'));
+    
+    const results = [];
+    const allFiles = await this.findAllProjectFiles(directory);
+    const sizeThresholds = {
+      image: 500 * 1024,      // 500KB for images
+      // css: 100 * 1024,        // 100KB for CSS
+      js: 200 * 1024,         // 200KB for JavaScript
+      // html: 50 * 1024,        // 50KB for HTML
+      video: 10 * 1024 * 1024, // 10MB for videos
+      audio: 5 * 1024 * 1024,  // 5MB for audio
+      other: 1 * 1024 * 1024   // 1MB for other files
+    };
+    
+    let totalSize = 0;
+    const fileSizes = [];
+    
+    for (const file of allFiles) {
+      try {
+        const stats = await require('fs').promises.stat(file);
+        const fileSize = stats.size;
+        const fileType = this.getFileCategory(file);
+        const relativePath = path.relative(directory, file);
+        
+        totalSize += fileSize;
+        fileSizes.push({
+          path: file,
+          relativePath: relativePath,
+          size: fileSize,
+          type: fileType,
+          sizeFormatted: this.formatFileSize(fileSize)
+        });
+        
+        // Check if file exceeds threshold
+        const threshold = sizeThresholds[fileType] || sizeThresholds.other;
+        if (fileSize > threshold) {
+          const suggestions = this.getSizeOptimizationSuggestions(file, fileSize, fileType);
+          
+          console.log(chalk.yellow(`  📏 Large ${fileType}: ${relativePath} (${this.formatFileSize(fileSize)})`));
+          suggestions.forEach(suggestion => {
+            console.log(chalk.gray(`    💡 ${suggestion}`));
+          });
+          
+          results.push({
+            type: `📏 Large ${fileType}`,
+            description: `File size ${this.formatFileSize(fileSize)} exceeds recommended ${this.formatFileSize(threshold)}`,
+            filePath: file,
+            relativePath: relativePath,
+            size: fileSize,
+            sizeFormatted: this.formatFileSize(fileSize),
+            threshold: threshold,
+            thresholdFormatted: this.formatFileSize(threshold),
+            suggestions: suggestions,
+            fileType: fileType
+          });
+        }
+      } catch (error) {
+        // Skip files we can't read
+      }
+    }
+    
+    // Sort files by size (largest first)
+    fileSizes.sort((a, b) => b.size - a.size);
+    
+    // Get type breakdown for return data only
+    const typeBreakdown = this.getFileSizeBreakdown(fileSizes);
+    
+    console.log(chalk.blue(`\n📊 Summary: Found ${results.length} files that could be optimized`));
+    console.log(chalk.gray('💡 File size analysis is based on common best practices'));
+    
+    return {
+      largeFiles: results,
+      allFiles: fileSizes,
+      totalSize: totalSize,
+      totalFiles: fileSizes.length,
+      typeBreakdown: typeBreakdown
+    };
+  }
+
+  getFileCategory(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    
+    if (['.jpg', '.jpeg', '.png', '.gif', '.svg', '.webp', '.ico', '.bmp'].includes(ext)) {
+      return 'image';
+    } else if (['.css', '.scss', '.sass', '.less'].includes(ext)) {
+      return 'css';
+    } else if (['.js', '.mjs', '.ts', '.jsx', '.tsx'].includes(ext)) {
+      return 'js';
+    } else if (['.html', '.htm', '.xhtml'].includes(ext)) {
+      return 'html';
+    } else if (['.mp4', '.avi', '.mov', '.wmv', '.flv', '.webm', '.mkv'].includes(ext)) {
+      return 'video';
+    } else if (['.mp3', '.wav', '.ogg', '.aac', '.flac'].includes(ext)) {
+      return 'audio';
+    } else if (['.pdf', '.doc', '.docx', '.txt'].includes(ext)) {
+      return 'document';
+    } else if (['.zip', '.rar', '.tar', '.gz', '.7z'].includes(ext)) {
+      return 'archive';
+    } else if (['.ttf', '.woff', '.woff2', '.otf', '.eot'].includes(ext)) {
+      return 'font';
+    } else {
+      return 'other';
+    }
+  }
+
+  getFileIcon(fileType) {
+    const icons = {
+      image: '🖼️',
+      css: '🎨',
+      js: '📜',
+      html: '📄',
+      video: '🎥',
+      audio: '🎵',
+      document: '📃',
+      archive: '📦',
+      font: '🔤',
+      other: '📄'
+    };
+    return icons[fileType] || '📄';
+  }
+
+  formatFileSize(bytes) {
+    if (bytes === 0) return '0 B';
+    
+    const k = 1024;
+    const sizes = ['B', 'KB', 'MB', 'GB'];
+    const i = Math.floor(Math.log(bytes) / Math.log(k));
+    
+    return parseFloat((bytes / Math.pow(k, i)).toFixed(1)) + ' ' + sizes[i];
+  }
+
+  getSizeOptimizationSuggestions(filePath, fileSize, fileType) {
+    const suggestions = [];
+    const fileName = path.basename(filePath);
+    const ext = path.extname(filePath).toLowerCase();
+    
+    switch (fileType) {
+      case 'image':
+        if (['.jpg', '.jpeg'].includes(ext)) {
+          suggestions.push('Compress JPEG with tools like ImageOptim, TinyPNG, or jpegoptim');
+          suggestions.push('Consider converting to WebP format for better compression');
+          if (fileSize > 1024 * 1024) {
+            suggestions.push('Resize image dimensions if currently larger than needed');
+          }
+        } else if (ext === '.png') {
+          suggestions.push('Compress PNG with tools like OptiPNG, PNGCrush, or TinyPNG');
+          suggestions.push('Consider converting to WebP for smaller size');
+          suggestions.push('Use JPEG for photos if transparency not needed');
+        } else if (ext === '.svg') {
+          suggestions.push('Minify SVG code with SVGO or similar tools');
+          suggestions.push('Remove unnecessary metadata and comments');
+        } else if (ext === '.gif') {
+          suggestions.push('Consider converting to WebP or MP4 for animations');
+          suggestions.push('Reduce color palette if possible');
+        }
+        break;
+        
+      case 'js':
+        suggestions.push('Minify JavaScript code with tools like UglifyJS or Terser');
+        suggestions.push('Enable gzip/brotli compression on your web server');
+        suggestions.push('Consider code splitting for large bundles');
+        suggestions.push('Remove unused code and dead code elimination');
+        if (fileSize > 500 * 1024) {
+          suggestions.push('Consider breaking into smaller modules');
+        }
+        break;
+        
+      case 'css':
+        suggestions.push('Minify CSS with tools like CleanCSS or cssnano');
+        suggestions.push('Remove unused CSS rules (run --dead-code analysis)');
+        suggestions.push('Enable gzip/brotli compression on your web server');
+        suggestions.push('Consider using CSS-in-JS or CSS modules for better tree-shaking');
+        break;
+        
+      case 'html':
+        suggestions.push('Minify HTML by removing whitespace and comments');
+        suggestions.push('Enable gzip/brotli compression on your web server');
+        suggestions.push('Inline critical CSS for above-the-fold content');
+        break;
+        
+      case 'video':
+        suggestions.push('Compress video with H.264 or H.265 codecs');
+        suggestions.push('Consider multiple quality versions (720p, 1080p)');
+        suggestions.push('Use streaming formats like HLS or DASH for large videos');
+        suggestions.push('Consider hosting on CDN or video platforms');
+        break;
+        
+      case 'audio':
+        suggestions.push('Use compressed formats like MP3 or AAC instead of WAV');
+        suggestions.push('Reduce bitrate if quality allows (128-192 kbps often sufficient)');
+        suggestions.push('Consider streaming for long audio files');
+        break;
+        
+      case 'font':
+        suggestions.push('Use WOFF2 format for better compression');
+        suggestions.push('Subset fonts to include only needed characters');
+        suggestions.push('Consider using system fonts or web font alternatives');
+        break;
+        
+      case 'document':
+        if (ext === '.pdf') {
+          suggestions.push('Compress PDF with tools like Ghostscript or online compressors');
+          suggestions.push('Reduce image quality in PDF if acceptable');
+        }
+        break;
+        
+      default:
+        suggestions.push('Enable compression on your web server');
+        suggestions.push('Consider if this file is necessary in production');
+    }
+    
+    // General suggestions for all large files
+    if (fileSize > 1024 * 1024) {
+      suggestions.push('Consider lazy loading if not needed immediately');
+      suggestions.push('Use CDN for better delivery performance');
+    }
+    
+    return suggestions;
+  }
+
+  getFileSizeBreakdown(fileSizes) {
+    const breakdown = {};
+    
+    fileSizes.forEach(file => {
+      if (!breakdown[file.type]) {
+        breakdown[file.type] = {
+          count: 0,
+          totalSize: 0
+        };
+      }
+      breakdown[file.type].count++;
+      breakdown[file.type].totalSize += file.size;
+    });
+    
+    // Sort by total size
+    const sortedBreakdown = {};
+    Object.entries(breakdown)
+      .sort(([,a], [,b]) => b.totalSize - a.totalSize)
+      .forEach(([key, value]) => {
+        sortedBreakdown[key] = value;
+      });
+    
+    return sortedBreakdown;
   }
 }