aios-core 4.1.0 → 4.2.0

package/.aios-core/development/scripts/usage-tracker.js

@@ -1,674 +1,674 @@
-const fs = require('fs').promises;
-const path = require('path');
-const chalk = require('chalk');
-
-/**
- * Usage tracker for AIOS-FULLSTACK framework components
- * Tracks component usage patterns for deprecation warnings and impact analysis
- */
-class UsageTracker {
-  constructor(options = {}) {
-    this.rootPath = options.rootPath || process.cwd();
-    this.usageDir = path.join(this.rootPath, '.aios', 'usage');
-    this.usageCache = new Map();
-    this.scanPatterns = this.initializeScanPatterns();
-  }
-
-  /**
-   * Initialize usage tracker
-   */
-  async initialize() {
-    try {
-      // Create usage directory
-      await fs.mkdir(this.usageDir, { recursive: true });
-
-      console.log(chalk.green('✅ Usage tracker initialized'));
-      return true;
-
-    } catch (_error) {
-      console.error(chalk.red(`Failed to initialize usage tracker: ${error.message}`));
-      throw error;
-    }
-  }
-
-  /**
-   * Analyze component usage across the codebase
-   */
-  async analyzeComponentUsage(componentId, options = {}) {
-    const analysis = {
-      component_id: componentId,
-      analysis_timestamp: new Date().toISOString(),
-      total_references: 0,
-      usage_locations: [],
-      dependent_components: [],
-      external_references: [],
-      usage_patterns: {},
-      risk_assessment: {
-        impact_level: 'low',
-        affected_areas: [],
-        migration_complexity: 'simple'
-      }
-    };
-
-    try {
-      console.log(chalk.blue(`🔍 Analyzing usage for component: ${componentId}`));
-
-      // Get component information
-      const component = await this.getComponentInfo(componentId);
-      if (!component) {
-        throw new Error(`Component not found: ${componentId}`);
-      }
-
-      // Scan for direct references
-      const directReferences = await this.scanForDirectReferences(component, options);
-      analysis.usage_locations = directReferences;
-      analysis.total_references = directReferences.length;
-
-      // Analyze dependency relationships
-      const dependencies = await this.analyzeDependencyRelationships(component, options);
-      analysis.dependent_components = dependencies;
-
-      // Check for external references (imports, configurations, etc.)
-      const externalRefs = await this.scanForExternalReferences(component, options);
-      analysis.external_references = externalRefs;
-
-      // Analyze usage patterns
-      analysis.usage_patterns = await this.analyzeUsagePatterns(component, directReferences);
-
-      // Assess migration risk
-      analysis.risk_assessment = this.assessMigrationRisk(analysis);
-
-      // Cache results
-      this.usageCache.set(componentId, analysis);
-
-      // Save detailed analysis
-      await this.saveUsageAnalysis(analysis);
-
-      console.log(chalk.green(`✅ Usage analysis completed for ${componentId}`));
-      console.log(chalk.gray(`   Total references: ${analysis.total_references}`));
-      console.log(chalk.gray(`   Dependent components: ${analysis.dependent_components.length}`));
-      console.log(chalk.gray(`   Impact level: ${analysis.risk_assessment.impact_level}`));
-
-      return analysis;
-
-    } catch (_error) {
-      console.error(chalk.red(`Usage analysis failed for ${componentId}: ${error.message}`));
-      throw error;
-    }
-  }
-
-  /**
-   * Track usage changes over time for deprecated components
-   */
-  async trackUsageChanges(componentId, baselineAnalysis) {
-    const currentAnalysis = await this.analyzeComponentUsage(componentId);
-    
-    const changes = {
-      component_id: componentId,
-      comparison_timestamp: new Date().toISOString(),
-      baseline_timestamp: baselineAnalysis.analysis_timestamp,
-      changes: {
-        total_references: {
-          before: baselineAnalysis.total_references,
-          after: currentAnalysis.total_references,
-          change: currentAnalysis.total_references - baselineAnalysis.total_references
-        },
-        dependent_components: {
-          before: baselineAnalysis.dependent_components.length,
-          after: currentAnalysis.dependent_components.length,
-          change: currentAnalysis.dependent_components.length - baselineAnalysis.dependent_components.length
-        },
-        new_usages: this.findNewUsages(baselineAnalysis.usage_locations, currentAnalysis.usage_locations),
-        removed_usages: this.findRemovedUsages(baselineAnalysis.usage_locations, currentAnalysis.usage_locations)
-      },
-      trend: this.calculateUsageTrend(baselineAnalysis, currentAnalysis),
-      migration_progress: this.calculateMigrationProgress(baselineAnalysis, currentAnalysis)
-    };
-
-    // Save change tracking
-    await this.saveUsageChanges(changes);
-
-    return changes;
-  }
-
-  /**
-   * Generate usage warnings for deprecated components
-   */
-  async generateUsageWarnings(componentId, deprecationInfo) {
-    const analysis = await this.analyzeComponentUsage(componentId);
-    const warnings = [];
-
-    for (const _usage of analysis.usage_locations) {
-      const warning = {
-        type: 'deprecation_warning',
-        component_id: componentId,
-        usage_location: {
-          file: usage.file,
-          line: usage.line,
-          context: usage.context
-        },
-        message: this.generateWarningMessage(componentId, deprecationInfo, usage),
-        severity: this.calculateWarningSeverity(deprecationInfo, usage),
-        suggested_actions: this.generateSuggestedActions(componentId, deprecationInfo, usage)
-      };
-
-      warnings.push(warning);
-    }
-
-    // Save warnings for later processing
-    await this.saveUsageWarnings(componentId, warnings);
-
-    return warnings;
-  }
-
-  /**
-   * Get usage statistics for reporting
-   */
-  async getUsageStatistics(componentIds = null) {
-    const stats = {
-      generated_at: new Date().toISOString(),
-      total_components_analyzed: 0,
-      high_usage_components: [],
-      zero_usage_components: [],
-      usage_distribution: {},
-      dependency_graph: {}
-    };
-
-    const componentsToAnalyze = componentIds || await this.getAllTrackedComponents();
-    
-    for (const componentId of componentsToAnalyze) {
-      try {
-        const analysis = await this.getOrAnalyzeUsage(componentId);
-        stats.total_components_analyzed++;
-
-        // Categorize by usage level
-        if (analysis.total_references === 0) {
-          stats.zero_usage_components.push(componentId);
-        } else if (analysis.total_references >= 10) {
-          stats.high_usage_components.push({
-            component_id: componentId,
-            reference_count: analysis.total_references,
-            impact_level: analysis.risk_assessment.impact_level
-          });
-        }
-
-        // Add to usage distribution
-        const usageRange = this.categorizeUsageLevel(analysis.total_references);
-        stats.usage_distribution[usageRange] = (stats.usage_distribution[usageRange] || 0) + 1;
-
-        // Add to dependency graph
-        stats.dependency_graph[componentId] = analysis.dependent_components.map(dep => dep.component_id);
-
-      } catch (_error) {
-        console.warn(chalk.yellow(`Failed to analyze usage for ${componentId}: ${error.message}`));
-      }
-    }
-
-    return stats;
-  }
-
-  /**
-   * Scan for direct references to a component
-   */
-  async scanForDirectReferences(component, options = {}) {
-    const references = [];
-    const scanPaths = await this.getScanPaths(_options);
-
-    for (const scanPath of scanPaths) {
-      try {
-        const pathReferences = await this.scanPath(scanPath, component);
-        references.push(...pathReferences);
-      } catch (_error) {
-        console.warn(chalk.yellow(`Failed to scan path ${scanPath}: ${error.message}`));
-      }
-    }
-
-    return references;
-  }
-
-  /**
-   * Scan a specific path for component references
-   */
-  async scanPath(scanPath, component) {
-    const references = [];
-    const files = await this.getFilesToScan(scanPath);
-
-    for (const file of files) {
-      try {
-        const fileReferences = await this.scanFile(file, component);
-        references.push(...fileReferences);
-      } catch (_error) {
-        // Skip files that can't be read
-        continue;
-      }
-    }
-
-    return references;
-  }
-
-  /**
-   * Scan a single file for component references
-   */
-  async scanFile(filePath, component) {
-    const references = [];
-    
-    try {
-      const content = await fs.readFile(filePath, 'utf-8');
-      const lines = content.split('\n');
-
-      for (let i = 0; i < lines.length; i++) {
-        const line = lines[i];
-        const lineNumber = i + 1;
-
-        // Check for various reference patterns
-        const matches = this.findReferencesInLine(line, component);
-        
-        for (const match of matches) {
-          references.push({
-            file: filePath,
-            line: lineNumber,
-            column: match.column,
-            context: line.trim(),
-            reference_type: match.type,
-            match_text: match.text
-          });
-        }
-      }
-    } catch (_error) {
-      // File couldn't be read, skip
-    }
-
-    return references;
-  }
-
-  /**
-   * Find references in a single line of code
-   */
-  findReferencesInLine(line, component) {
-    const matches = [];
-    const patterns = this.scanPatterns[component.type] || this.scanPatterns.default;
-
-    for (const pattern of patterns) {
-      const regex = new RegExp(pattern.pattern.replace('{component_name}', component.name), pattern.flags || 'gi');
-      let match;
-
-      while ((match = regex.exec(line)) !== null) {
-        matches.push({
-          type: pattern.type,
-          text: match[0],
-          column: match.index,
-          confidence: pattern.confidence || 0.8
-        });
-      }
-    }
-
-    return matches;
-  }
-
-  /**
-   * Analyze dependency relationships
-   */
-  async analyzeDependencyRelationships(component, options = {}) {
-    const dependencies = [];
-    
-    // This would analyze manifest files, import statements, etc.
-    // For now, return empty array as placeholder
-    
-    return dependencies;
-  }
-
-  /**
-   * Scan for external references (config files, documentation, etc.)
-   */
-  async scanForExternalReferences(component, options = {}) {
-    const externalRefs = [];
-    
-    // Check configuration files
-    const configRefs = await this.scanConfigurationFiles(component);
-    externalRefs.push(...configRefs);
-
-    // Check documentation
-    const docRefs = await this.scanDocumentationFiles(component);
-    externalRefs.push(...docRefs);
-
-    return externalRefs;
-  }
-
-  /**
-   * Analyze usage patterns
-   */
-  async analyzeUsagePatterns(component, references) {
-    const patterns = {
-      by_file_type: {},
-      by_usage_type: {},
-      temporal_distribution: {},
-      complexity_indicators: {}
-    };
-
-    for (const ref of references) {
-      // Group by file extension
-      const ext = path.extname(ref.file);
-      patterns.by_file_type[ext] = (patterns.by_file_type[ext] || 0) + 1;
-
-      // Group by reference type
-      patterns.by_usage_type[ref.reference_type] = (patterns.by_usage_type[ref.reference_type] || 0) + 1;
-    }
-
-    return patterns;
-  }
-
-  /**
-   * Assess migration risk based on usage analysis
-   */
-  assessMigrationRisk(analysis) {
-    let impactLevel = 'low';
-    let migrationComplexity = 'simple';
-    const affectedAreas = [];
-
-    // Assess based on total references
-    if (analysis.total_references > 20) {
-      impactLevel = 'high';
-      migrationComplexity = 'complex';
-    } else if (analysis.total_references > 10) {
-      impactLevel = 'medium';
-      migrationComplexity = 'moderate';
-    }
-
-    // Check for complex usage patterns
-    if (analysis.dependent_components.length > 5) {
-      migrationComplexity = 'complex';
-      affectedAreas.push('component_dependencies');
-    }
-
-    if (analysis.external_references.length > 0) {
-      affectedAreas.push('external_configuration');
-    }
-
-    return {
-      impact_level: impactLevel,
-      affected_areas: affectedAreas,
-      migration_complexity: migrationComplexity
-    };
-  }
-
-  // Helper methods
-
-  async getComponentInfo(componentId) {
-    // This would typically integrate with the component registry
-    // For now, return a basic component structure
-    const [type, name] = componentId.split('/');
-    
-    return {
-      id: componentId,
-      type: type,
-      name: name,
-      file_path: `aios-core/${type}s/${name}.md`
-    };
-  }
-
-  async getScanPaths(_options) {
-    const defaultPaths = [
-      path.join(this.rootPath, 'aios-core'),
-      path.join(this.rootPath, 'src'),
-      path.join(this.rootPath, 'lib')
-    ];
-
-    if (options.scanPaths) {
-      return options.scanPaths;
-    }
-
-    // Filter paths that exist
-    const existingPaths = [];
-    for (const scanPath of defaultPaths) {
-      try {
-        await fs.access(scanPath);
-        existingPaths.push(scanPath);
-      } catch (_error) {
-        // Path doesn't exist, skip
-      }
-    }
-
-    return existingPaths;
-  }
-
-  async getFilesToScan(scanPath) {
-    const files = [];
-    
-    try {
-      const entries = await fs.readdir(scanPath, { withFileTypes: true });
-      
-      for (const entry of entries) {
-        const fullPath = path.join(scanPath, entry.name);
-        
-        if (entry.isDirectory()) {
-          // Recursively scan subdirectories
-          const subFiles = await this.getFilesToScan(fullPath);
-          files.push(...subFiles);
-        } else if (this.shouldScanFile(entry.name)) {
-          files.push(fullPath);
-        }
-      }
-    } catch (_error) {
-      // Can't read directory, skip
-    }
-
-    return files;
-  }
-
-  shouldScanFile(filename) {
-    const scanExtensions = ['.js', '.ts', '.md', '.yaml', '.yml', '.json'];
-    const ext = path.extname(filename);
-    return scanExtensions.includes(ext);
-  }
-
-  async scanConfigurationFiles(component) {
-    const configRefs = [];
-    const configFiles = [
-      'package.json',
-      '.aiosrc',
-      'aios.config.js',
-      'manifest.yaml'
-    ];
-
-    for (const configFile of configFiles) {
-      const configPath = path.join(this.rootPath, configFile);
-      
-      try {
-        const refs = await this.scanFile(configPath, component);
-        configRefs.push(...refs.map(ref => ({ ...ref, source: 'configuration' })));
-      } catch (_error) {
-        // Config file doesn't exist or can't be read
-      }
-    }
-
-    return configRefs;
-  }
-
-  async scanDocumentationFiles(component) {
-    const docRefs = [];
-    const docsPath = path.join(this.rootPath, 'docs');
-    
-    try {
-      const files = await this.getFilesToScan(docsPath);
-      
-      for (const file of files) {
-        const refs = await this.scanFile(file, component);
-        docRefs.push(...refs.map(ref => ({ ...ref, source: 'documentation' })));
-      }
-    } catch (_error) {
-      // Docs directory doesn't exist
-    }
-
-    return docRefs;
-  }
-
-  findNewUsages(oldUsages, newUsages) {
-    return newUsages.filter(newUsage => 
-      !oldUsages.some(oldUsage => 
-        oldUsage.file === newUsage.file && oldUsage.line === newUsage.line
-      )
-    );
-  }
-
-  findRemovedUsages(oldUsages, newUsages) {
-    return oldUsages.filter(oldUsage => 
-      !newUsages.some(newUsage => 
-        newUsage.file === oldUsage.file && newUsage.line === oldUsage.line
-      )
-    );
-  }
-
-  calculateUsageTrend(baseline, current) {
-    const referenceChange = current.total_references - baseline.total_references;
-    
-    if (referenceChange > 0) return 'increasing';
-    if (referenceChange < 0) return 'decreasing';
-    return 'stable';
-  }
-
-  calculateMigrationProgress(baseline, current) {
-    if (baseline.total_references === 0) return 1.0;
-    
-    const remainingUsages = current.total_references;
-    const originalUsages = baseline.total_references;
-    
-    return Math.max(0, (originalUsages - remainingUsages) / originalUsages);
-  }
-
-  generateWarningMessage(componentId, deprecationInfo, usage) {
-    let message = `DEPRECATED: ${componentId} is deprecated`;
-    
-    if (deprecationInfo.replacement) {
-      message += ` - use ${deprecationInfo.replacement} instead`;
-    }
-    
-    if (deprecationInfo.removalVersion) {
-      message += ` (will be removed in ${deprecationInfo.removalVersion})`;
-    }
-    
-    return message;
-  }
-
-  calculateWarningSeverity(deprecationInfo, usage) {
-    if (deprecationInfo.severity === 'critical') return 'error';
-    if (deprecationInfo.severity === 'high') return 'warning';
-    return 'info';
-  }
-
-  generateSuggestedActions(componentId, deprecationInfo, usage) {
-    const actions = [];
-    
-    if (deprecationInfo.replacement) {
-      actions.push(`Replace with ${deprecationInfo.replacement}`);
-    }
-    
-    if (deprecationInfo.migrationGuide) {
-      actions.push(`See migration guide: ${deprecationInfo.migrationGuide}`);
-    }
-    
-    actions.push('Update imports and references');
-    actions.push('Test functionality after replacement');
-    
-    return actions;
-  }
-
-  categorizeUsageLevel(referenceCount) {
-    if (referenceCount === 0) return 'zero';
-    if (referenceCount <= 5) return 'low';
-    if (referenceCount <= 15) return 'medium';
-    if (referenceCount <= 30) return 'high';
-    return 'very_high';
-  }
-
-  async getOrAnalyzeUsage(componentId) {
-    if (this.usageCache.has(componentId)) {
-      return this.usageCache.get(componentId);
-    }
-    
-    return await this.analyzeComponentUsage(componentId);
-  }
-
-  async getAllTrackedComponents() {
-    // This would typically come from a component registry
-    // For now, return empty array
-    return [];
-  }
-
-  async saveUsageAnalysis(analysis) {
-    const filename = `usage-${analysis.component_id.replace('/', '-')}-${Date.now()}.json`;
-    const filePath = path.join(this.usageDir, filename);
-    
-    await fs.writeFile(filePath, JSON.stringify(analysis, null, 2));
-  }
-
-  async saveUsageChanges(changes) {
-    const filename = `changes-${changes.component_id.replace('/', '-')}-${Date.now()}.json`;
-    const filePath = path.join(this.usageDir, filename);
-    
-    await fs.writeFile(filePath, JSON.stringify(changes, null, 2));
-  }
-
-  async saveUsageWarnings(componentId, warnings) {
-    const filename = `warnings-${componentId.replace('/', '-')}-${Date.now()}.json`;
-    const filePath = path.join(this.usageDir, filename);
-    
-    await fs.writeFile(filePath, JSON.stringify(warnings, null, 2));
-  }
-
-  initializeScanPatterns() {
-    return {
-      agent: [
-        {
-          pattern: 'agent:\\s*{component_name}',
-          type: 'yaml_reference',
-          confidence: 0.9
-        },
-        {
-          pattern: 'use\\s+{component_name}',
-          type: 'usage_statement',
-          confidence: 0.8
-        }
-      ],
-      task: [
-        {
-          pattern: '\\*{component_name}',
-          type: 'task_invocation',
-          confidence: 0.9
-        },
-        {
-          pattern: 'require\\(.*{component_name}.*\\)',
-          type: 'import_statement',
-          confidence: 0.8
-        }
-      ],
-      workflow: [
-        {
-          pattern: 'workflow:\\s*{component_name}',
-          type: 'workflow_reference',
-          confidence: 0.9
-        }
-      ],
-      util: [
-        {
-          pattern: 'require\\(.*{component_name}.*\\)',
-          type: 'import_statement',
-          confidence: 0.9
-        },
-        {
-          pattern: 'import.*{component_name}',
-          type: 'import_statement',
-          confidence: 0.9
-        }
-      ],
-      default: [
-        {
-          pattern: '{component_name}',
-          type: 'general_reference',
-          confidence: 0.6
-        }
-      ]
-    };
-  }
-}
-
+const fs = require('fs').promises;
+const path = require('path');
+const chalk = require('chalk');
+
+/**
+ * Usage tracker for AIOS-FULLSTACK framework components
+ * Tracks component usage patterns for deprecation warnings and impact analysis
+ */
+class UsageTracker {
+  constructor(options = {}) {
+    this.rootPath = options.rootPath || process.cwd();
+    this.usageDir = path.join(this.rootPath, '.aios', 'usage');
+    this.usageCache = new Map();
+    this.scanPatterns = this.initializeScanPatterns();
+  }
+
+  /**
+   * Initialize usage tracker
+   */
+  async initialize() {
+    try {
+      // Create usage directory
+      await fs.mkdir(this.usageDir, { recursive: true });
+
+      console.log(chalk.green('✅ Usage tracker initialized'));
+      return true;
+
+    } catch (_error) {
+      console.error(chalk.red(`Failed to initialize usage tracker: ${error.message}`));
+      throw error;
+    }
+  }
+
+  /**
+   * Analyze component usage across the codebase
+   */
+  async analyzeComponentUsage(componentId, options = {}) {
+    const analysis = {
+      component_id: componentId,
+      analysis_timestamp: new Date().toISOString(),
+      total_references: 0,
+      usage_locations: [],
+      dependent_components: [],
+      external_references: [],
+      usage_patterns: {},
+      risk_assessment: {
+        impact_level: 'low',
+        affected_areas: [],
+        migration_complexity: 'simple'
+      }
+    };
+
+    try {
+      console.log(chalk.blue(`🔍 Analyzing usage for component: ${componentId}`));
+
+      // Get component information
+      const component = await this.getComponentInfo(componentId);
+      if (!component) {
+        throw new Error(`Component not found: ${componentId}`);
+      }
+
+      // Scan for direct references
+      const directReferences = await this.scanForDirectReferences(component, options);
+      analysis.usage_locations = directReferences;
+      analysis.total_references = directReferences.length;
+
+      // Analyze dependency relationships
+      const dependencies = await this.analyzeDependencyRelationships(component, options);
+      analysis.dependent_components = dependencies;
+
+      // Check for external references (imports, configurations, etc.)
+      const externalRefs = await this.scanForExternalReferences(component, options);
+      analysis.external_references = externalRefs;
+
+      // Analyze usage patterns
+      analysis.usage_patterns = await this.analyzeUsagePatterns(component, directReferences);
+
+      // Assess migration risk
+      analysis.risk_assessment = this.assessMigrationRisk(analysis);
+
+      // Cache results
+      this.usageCache.set(componentId, analysis);
+
+      // Save detailed analysis
+      await this.saveUsageAnalysis(analysis);
+
+      console.log(chalk.green(`✅ Usage analysis completed for ${componentId}`));
+      console.log(chalk.gray(`   Total references: ${analysis.total_references}`));
+      console.log(chalk.gray(`   Dependent components: ${analysis.dependent_components.length}`));
+      console.log(chalk.gray(`   Impact level: ${analysis.risk_assessment.impact_level}`));
+
+      return analysis;
+
+    } catch (_error) {
+      console.error(chalk.red(`Usage analysis failed for ${componentId}: ${error.message}`));
+      throw error;
+    }
+  }
+
+  /**
+   * Track usage changes over time for deprecated components
+   */
+  async trackUsageChanges(componentId, baselineAnalysis) {
+    const currentAnalysis = await this.analyzeComponentUsage(componentId);
+    
+    const changes = {
+      component_id: componentId,
+      comparison_timestamp: new Date().toISOString(),
+      baseline_timestamp: baselineAnalysis.analysis_timestamp,
+      changes: {
+        total_references: {
+          before: baselineAnalysis.total_references,
+          after: currentAnalysis.total_references,
+          change: currentAnalysis.total_references - baselineAnalysis.total_references
+        },
+        dependent_components: {
+          before: baselineAnalysis.dependent_components.length,
+          after: currentAnalysis.dependent_components.length,
+          change: currentAnalysis.dependent_components.length - baselineAnalysis.dependent_components.length
+        },
+        new_usages: this.findNewUsages(baselineAnalysis.usage_locations, currentAnalysis.usage_locations),
+        removed_usages: this.findRemovedUsages(baselineAnalysis.usage_locations, currentAnalysis.usage_locations)
+      },
+      trend: this.calculateUsageTrend(baselineAnalysis, currentAnalysis),
+      migration_progress: this.calculateMigrationProgress(baselineAnalysis, currentAnalysis)
+    };
+
+    // Save change tracking
+    await this.saveUsageChanges(changes);
+
+    return changes;
+  }
+
+  /**
+   * Generate usage warnings for deprecated components
+   */
+  async generateUsageWarnings(componentId, deprecationInfo) {
+    const analysis = await this.analyzeComponentUsage(componentId);
+    const warnings = [];
+
+    for (const _usage of analysis.usage_locations) {
+      const warning = {
+        type: 'deprecation_warning',
+        component_id: componentId,
+        usage_location: {
+          file: usage.file,
+          line: usage.line,
+          context: usage.context
+        },
+        message: this.generateWarningMessage(componentId, deprecationInfo, usage),
+        severity: this.calculateWarningSeverity(deprecationInfo, usage),
+        suggested_actions: this.generateSuggestedActions(componentId, deprecationInfo, usage)
+      };
+
+      warnings.push(warning);
+    }
+
+    // Save warnings for later processing
+    await this.saveUsageWarnings(componentId, warnings);
+
+    return warnings;
+  }
+
+  /**
+   * Get usage statistics for reporting
+   */
+  async getUsageStatistics(componentIds = null) {
+    const stats = {
+      generated_at: new Date().toISOString(),
+      total_components_analyzed: 0,
+      high_usage_components: [],
+      zero_usage_components: [],
+      usage_distribution: {},
+      dependency_graph: {}
+    };
+
+    const componentsToAnalyze = componentIds || await this.getAllTrackedComponents();
+    
+    for (const componentId of componentsToAnalyze) {
+      try {
+        const analysis = await this.getOrAnalyzeUsage(componentId);
+        stats.total_components_analyzed++;
+
+        // Categorize by usage level
+        if (analysis.total_references === 0) {
+          stats.zero_usage_components.push(componentId);
+        } else if (analysis.total_references >= 10) {
+          stats.high_usage_components.push({
+            component_id: componentId,
+            reference_count: analysis.total_references,
+            impact_level: analysis.risk_assessment.impact_level
+          });
+        }
+
+        // Add to usage distribution
+        const usageRange = this.categorizeUsageLevel(analysis.total_references);
+        stats.usage_distribution[usageRange] = (stats.usage_distribution[usageRange] || 0) + 1;
+
+        // Add to dependency graph
+        stats.dependency_graph[componentId] = analysis.dependent_components.map(dep => dep.component_id);
+
+      } catch (_error) {
+        console.warn(chalk.yellow(`Failed to analyze usage for ${componentId}: ${error.message}`));
+      }
+    }
+
+    return stats;
+  }
+
+  /**
+   * Scan for direct references to a component
+   */
+  async scanForDirectReferences(component, options = {}) {
+    const references = [];
+    const scanPaths = await this.getScanPaths(_options);
+
+    for (const scanPath of scanPaths) {
+      try {
+        const pathReferences = await this.scanPath(scanPath, component);
+        references.push(...pathReferences);
+      } catch (_error) {
+        console.warn(chalk.yellow(`Failed to scan path ${scanPath}: ${error.message}`));
+      }
+    }
+
+    return references;
+  }
+
+  /**
+   * Scan a specific path for component references
+   */
+  async scanPath(scanPath, component) {
+    const references = [];
+    const files = await this.getFilesToScan(scanPath);
+
+    for (const file of files) {
+      try {
+        const fileReferences = await this.scanFile(file, component);
+        references.push(...fileReferences);
+      } catch (_error) {
+        // Skip files that can't be read
+        continue;
+      }
+    }
+
+    return references;
+  }
+
+  /**
+   * Scan a single file for component references
+   */
+  async scanFile(filePath, component) {
+    const references = [];
+    
+    try {
+      const content = await fs.readFile(filePath, 'utf-8');
+      const lines = content.split('\n');
+
+      for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const lineNumber = i + 1;
+
+        // Check for various reference patterns
+        const matches = this.findReferencesInLine(line, component);
+        
+        for (const match of matches) {
+          references.push({
+            file: filePath,
+            line: lineNumber,
+            column: match.column,
+            context: line.trim(),
+            reference_type: match.type,
+            match_text: match.text
+          });
+        }
+      }
+    } catch (_error) {
+      // File couldn't be read, skip
+    }
+
+    return references;
+  }
+
+  /**
+   * Find references in a single line of code
+   */
+  findReferencesInLine(line, component) {
+    const matches = [];
+    const patterns = this.scanPatterns[component.type] || this.scanPatterns.default;
+
+    for (const pattern of patterns) {
+      const regex = new RegExp(pattern.pattern.replace('{component_name}', component.name), pattern.flags || 'gi');
+      let match;
+
+      while ((match = regex.exec(line)) !== null) {
+        matches.push({
+          type: pattern.type,
+          text: match[0],
+          column: match.index,
+          confidence: pattern.confidence || 0.8
+        });
+      }
+    }
+
+    return matches;
+  }
+
+  /**
+   * Analyze dependency relationships
+   */
+  async analyzeDependencyRelationships(component, options = {}) {
+    const dependencies = [];
+    
+    // This would analyze manifest files, import statements, etc.
+    // For now, return empty array as placeholder
+    
+    return dependencies;
+  }
+
+  /**
+   * Scan for external references (config files, documentation, etc.)
+   */
+  async scanForExternalReferences(component, options = {}) {
+    const externalRefs = [];
+    
+    // Check configuration files
+    const configRefs = await this.scanConfigurationFiles(component);
+    externalRefs.push(...configRefs);
+
+    // Check documentation
+    const docRefs = await this.scanDocumentationFiles(component);
+    externalRefs.push(...docRefs);
+
+    return externalRefs;
+  }
+
+  /**
+   * Analyze usage patterns
+   */
+  async analyzeUsagePatterns(component, references) {
+    const patterns = {
+      by_file_type: {},
+      by_usage_type: {},
+      temporal_distribution: {},
+      complexity_indicators: {}
+    };
+
+    for (const ref of references) {
+      // Group by file extension
+      const ext = path.extname(ref.file);
+      patterns.by_file_type[ext] = (patterns.by_file_type[ext] || 0) + 1;
+
+      // Group by reference type
+      patterns.by_usage_type[ref.reference_type] = (patterns.by_usage_type[ref.reference_type] || 0) + 1;
+    }
+
+    return patterns;
+  }
+
+  /**
+   * Assess migration risk based on usage analysis
+   */
+  assessMigrationRisk(analysis) {
+    let impactLevel = 'low';
+    let migrationComplexity = 'simple';
+    const affectedAreas = [];
+
+    // Assess based on total references
+    if (analysis.total_references > 20) {
+      impactLevel = 'high';
+      migrationComplexity = 'complex';
+    } else if (analysis.total_references > 10) {
+      impactLevel = 'medium';
+      migrationComplexity = 'moderate';
+    }
+
+    // Check for complex usage patterns
+    if (analysis.dependent_components.length > 5) {
+      migrationComplexity = 'complex';
+      affectedAreas.push('component_dependencies');
+    }
+
+    if (analysis.external_references.length > 0) {
+      affectedAreas.push('external_configuration');
+    }
+
+    return {
+      impact_level: impactLevel,
+      affected_areas: affectedAreas,
+      migration_complexity: migrationComplexity
+    };
+  }
+
+  // Helper methods
+
+  async getComponentInfo(componentId) {
+    // This would typically integrate with the component registry
+    // For now, return a basic component structure
+    const [type, name] = componentId.split('/');
+    
+    return {
+      id: componentId,
+      type: type,
+      name: name,
+      file_path: `aios-core/${type}s/${name}.md`
+    };
+  }
+
+  async getScanPaths(_options) {
+    const defaultPaths = [
+      path.join(this.rootPath, 'aios-core'),
+      path.join(this.rootPath, 'src'),
+      path.join(this.rootPath, 'lib')
+    ];
+
+    if (options.scanPaths) {
+      return options.scanPaths;
+    }
+
+    // Filter paths that exist
+    const existingPaths = [];
+    for (const scanPath of defaultPaths) {
+      try {
+        await fs.access(scanPath);
+        existingPaths.push(scanPath);
+      } catch (_error) {
+        // Path doesn't exist, skip
+      }
+    }
+
+    return existingPaths;
+  }
+
+  async getFilesToScan(scanPath) {
+    const files = [];
+    
+    try {
+      const entries = await fs.readdir(scanPath, { withFileTypes: true });
+      
+      for (const entry of entries) {
+        const fullPath = path.join(scanPath, entry.name);
+        
+        if (entry.isDirectory()) {
+          // Recursively scan subdirectories
+          const subFiles = await this.getFilesToScan(fullPath);
+          files.push(...subFiles);
+        } else if (this.shouldScanFile(entry.name)) {
+          files.push(fullPath);
+        }
+      }
+    } catch (_error) {
+      // Can't read directory, skip
+    }
+
+    return files;
+  }
+
+  shouldScanFile(filename) {
+    const scanExtensions = ['.js', '.ts', '.md', '.yaml', '.yml', '.json'];
+    const ext = path.extname(filename);
+    return scanExtensions.includes(ext);
+  }
+
+  async scanConfigurationFiles(component) {
+    const configRefs = [];
+    const configFiles = [
+      'package.json',
+      '.aiosrc',
+      'aios.config.js',
+      'manifest.yaml'
+    ];
+
+    for (const configFile of configFiles) {
+      const configPath = path.join(this.rootPath, configFile);
+      
+      try {
+        const refs = await this.scanFile(configPath, component);
+        configRefs.push(...refs.map(ref => ({ ...ref, source: 'configuration' })));
+      } catch (_error) {
+        // Config file doesn't exist or can't be read
+      }
+    }
+
+    return configRefs;
+  }
+
+  async scanDocumentationFiles(component) {
+    const docRefs = [];
+    const docsPath = path.join(this.rootPath, 'docs');
+    
+    try {
+      const files = await this.getFilesToScan(docsPath);
+      
+      for (const file of files) {
+        const refs = await this.scanFile(file, component);
+        docRefs.push(...refs.map(ref => ({ ...ref, source: 'documentation' })));
+      }
+    } catch (_error) {
+      // Docs directory doesn't exist
+    }
+
+    return docRefs;
+  }
+
+  findNewUsages(oldUsages, newUsages) {
+    return newUsages.filter(newUsage => 
+      !oldUsages.some(oldUsage => 
+        oldUsage.file === newUsage.file && oldUsage.line === newUsage.line
+      )
+    );
+  }
+
+  findRemovedUsages(oldUsages, newUsages) {
+    return oldUsages.filter(oldUsage => 
+      !newUsages.some(newUsage => 
+        newUsage.file === oldUsage.file && newUsage.line === oldUsage.line
+      )
+    );
+  }
+
+  calculateUsageTrend(baseline, current) {
+    const referenceChange = current.total_references - baseline.total_references;
+    
+    if (referenceChange > 0) return 'increasing';
+    if (referenceChange < 0) return 'decreasing';
+    return 'stable';
+  }
+
+  calculateMigrationProgress(baseline, current) {
+    if (baseline.total_references === 0) return 1.0;
+    
+    const remainingUsages = current.total_references;
+    const originalUsages = baseline.total_references;
+    
+    return Math.max(0, (originalUsages - remainingUsages) / originalUsages);
+  }
+
+  generateWarningMessage(componentId, deprecationInfo, usage) {
+    let message = `DEPRECATED: ${componentId} is deprecated`;
+    
+    if (deprecationInfo.replacement) {
+      message += ` - use ${deprecationInfo.replacement} instead`;
+    }
+    
+    if (deprecationInfo.removalVersion) {
+      message += ` (will be removed in ${deprecationInfo.removalVersion})`;
+    }
+    
+    return message;
+  }
+
+  calculateWarningSeverity(deprecationInfo, usage) {
+    if (deprecationInfo.severity === 'critical') return 'error';
+    if (deprecationInfo.severity === 'high') return 'warning';
+    return 'info';
+  }
+
+  generateSuggestedActions(componentId, deprecationInfo, usage) {
+    const actions = [];
+    
+    if (deprecationInfo.replacement) {
+      actions.push(`Replace with ${deprecationInfo.replacement}`);
+    }
+    
+    if (deprecationInfo.migrationGuide) {
+      actions.push(`See migration guide: ${deprecationInfo.migrationGuide}`);
+    }
+    
+    actions.push('Update imports and references');
+    actions.push('Test functionality after replacement');
+    
+    return actions;
+  }
+
+  categorizeUsageLevel(referenceCount) {
+    if (referenceCount === 0) return 'zero';
+    if (referenceCount <= 5) return 'low';
+    if (referenceCount <= 15) return 'medium';
+    if (referenceCount <= 30) return 'high';
+    return 'very_high';
+  }
+
+  async getOrAnalyzeUsage(componentId) {
+    if (this.usageCache.has(componentId)) {
+      return this.usageCache.get(componentId);
+    }
+    
+    return await this.analyzeComponentUsage(componentId);
+  }
+
+  async getAllTrackedComponents() {
+    // This would typically come from a component registry
+    // For now, return empty array
+    return [];
+  }
+
+  async saveUsageAnalysis(analysis) {
+    const filename = `usage-${analysis.component_id.replace('/', '-')}-${Date.now()}.json`;
+    const filePath = path.join(this.usageDir, filename);
+    
+    await fs.writeFile(filePath, JSON.stringify(analysis, null, 2));
+  }
+
+  async saveUsageChanges(changes) {
+    const filename = `changes-${changes.component_id.replace('/', '-')}-${Date.now()}.json`;
+    const filePath = path.join(this.usageDir, filename);
+    
+    await fs.writeFile(filePath, JSON.stringify(changes, null, 2));
+  }
+
+  async saveUsageWarnings(componentId, warnings) {
+    const filename = `warnings-${componentId.replace('/', '-')}-${Date.now()}.json`;
+    const filePath = path.join(this.usageDir, filename);
+    
+    await fs.writeFile(filePath, JSON.stringify(warnings, null, 2));
+  }
+
+  initializeScanPatterns() {
+    return {
+      agent: [
+        {
+          pattern: 'agent:\\s*{component_name}',
+          type: 'yaml_reference',
+          confidence: 0.9
+        },
+        {
+          pattern: 'use\\s+{component_name}',
+          type: 'usage_statement',
+          confidence: 0.8
+        }
+      ],
+      task: [
+        {
+          pattern: '\\*{component_name}',
+          type: 'task_invocation',
+          confidence: 0.9
+        },
+        {
+          pattern: 'require\\(.*{component_name}.*\\)',
+          type: 'import_statement',
+          confidence: 0.8
+        }
+      ],
+      workflow: [
+        {
+          pattern: 'workflow:\\s*{component_name}',
+          type: 'workflow_reference',
+          confidence: 0.9
+        }
+      ],
+      util: [
+        {
+          pattern: 'require\\(.*{component_name}.*\\)',
+          type: 'import_statement',
+          confidence: 0.9
+        },
+        {
+          pattern: 'import.*{component_name}',
+          type: 'import_statement',
+          confidence: 0.9
+        }
+      ],
+      default: [
+        {
+          pattern: '{component_name}',
+          type: 'general_reference',
+          confidence: 0.6
+        }
+      ]
+    };
+  }
+}
+
 module.exports = UsageTracker;