thuban 0.3.2 → 0.3.3

package/packages/scanner/widget-generator.js

@@ -1,415 +1,415 @@
-/**
- * Sentinel Widget Generator
- *
- * Automatically generates widget contracts for files that don't have them.
- * Uses dependency graph, code analysis, and file path heuristics to
- * create meaningful @purpose, @module, @layer, etc. annotations.
- *
- * @purpose Generate widget contracts for undocumented files
- * @module sentinel
- * @layer infrastructure
- * @imports-from dependency-graph, fs, path
- * @exports-to sentinel-core, CLI tools
- * @side-effects File system reads; optionally writes widgets to files
- */
-
-const fs = require('fs');
-const path = require('path');
-const DependencyGraph = require('./dependency-graph');
-
-class WidgetGenerator {
-  constructor(config = {}) {
-    this.config = {
-      rootPath: config.rootPath || process.cwd(),
-      dryRun: config.dryRun !== false, // Default to dry run (don't write)
-      ...config
-    };
-
-    this.dependencyGraph = config.dependencyGraph || null;
-
-    // Module detection patterns
-    this.modulePatterns = {
-      'sentinel': /^sentinel[\\\/]/,
-      'citadel': /^citadel[\\\/]/,
-      'forge': /^forge[\\\/]/,
-      'server': /^server[\\\/]/,
-      'build-engine': /^build-engine[\\\/]/,
-      'autopilot': /^autopilot[\\\/]/,
-      'silverwings': /^silverwings[\\\/]/,
-      'output': /^output[\\\/]/
-    };
-
-    // Layer detection patterns
-    this.layerPatterns = {
-      'presentation': /routes|api|handlers|controllers|views/i,
-      'application': /service|manager|orchestrat|core|engine/i,
-      'domain': /model|entity|domain|types/i,
-      'infrastructure': /utils|helpers|lib|data|store|memory/i
-    };
-
-    // Side effect patterns
-    this.sideEffectPatterns = [
-      { pattern: /fs\.(write|append|unlink|mkdir|rmdir|rename)/i, effect: 'File system writes' },
-      { pattern: /fs\.read/i, effect: 'File system reads' },
-      { pattern: /fetch\(|axios\.|http\.|https\./i, effect: 'HTTP requests' },
-      { pattern: /process\.exit/i, effect: 'Process termination' },
-      { pattern: /child_process|spawn|exec\(/i, effect: 'Spawns child processes' },
-      { pattern: /console\.(log|error|warn)/i, effect: 'Console output' },
-      { pattern: /\.emit\(|EventEmitter/i, effect: 'Event emission' },
-      { pattern: /supabase|createClient/i, effect: 'Database operations' },
-      { pattern: /twilio|sendgrid|resend/i, effect: 'External API calls' }
-    ];
-
-    // Purpose detection from common patterns
-    this.purposePatterns = [
-      { pattern: /class\s+(\w+).*extends.*Router/i, purpose: (m) => `Express router for ${m[1]}` },
-      { pattern: /class\s+(\w+).*extends.*EventEmitter/i, purpose: (m) => `Event-driven ${m[1]} component` },
-      { pattern: /class\s+(\w+)/i, purpose: (m) => `${m[1]} class implementation` },
-      { pattern: /module\.exports\s*=\s*\{([^}]+)\}/i, purpose: (m) => `Exports: ${m[1].match(/\w+/g)?.slice(0, 5).join(', ')}` },
-      { pattern: /router\.(get|post|put|delete)/i, purpose: () => 'API route handlers' },
-      { pattern: /async function\s+(\w+)/i, purpose: (m) => `Provides ${m[1]} functionality` },
-      { pattern: /function\s+(\w+)/i, purpose: (m) => `Provides ${m[1]} functionality` }
-    ];
-  }
-
-  /**
-   * Generate widgets for all files missing them
-   */
-  async generateAll() {
-    console.log('[WIDGET-GENERATOR] Starting widget generation...');
-
-    // Build dependency graph if not provided
-    if (!this.dependencyGraph) {
-      this.dependencyGraph = new DependencyGraph({ rootPath: this.config.rootPath });
-      await this.dependencyGraph.build();
-    }
-
-    // Find files without widgets
-    const files = await this._discoverFiles(this.config.rootPath);
-    const results = {
-      total: files.length,
-      generated: 0,
-      skipped: 0,
-      alreadyHasWidget: 0,
-      widgets: []
-    };
-
-    for (const file of files) {
-      const content = fs.readFileSync(file, 'utf8');
-
-      // Skip if already has widget
-      if (this._hasWidget(content)) {
-        results.alreadyHasWidget++;
-        continue;
-      }
-
-      const widget = await this.generateWidget(file, content);
-      results.generated++;
-      results.widgets.push({
-        file,
-        relativePath: path.relative(this.config.rootPath, file),
-        widget
-      });
-
-      // Apply widget if not dry run
-      if (!this.config.dryRun) {
-        await this._applyWidget(file, content, widget);
-      }
-    }
-
-    console.log(`[WIDGET-GENERATOR] Generated ${results.generated} widgets (${results.alreadyHasWidget} already had widgets)`);
-    return results;
-  }
-
-  /**
-   * Generate widget for a single file
-   */
-  async generateWidget(filePath, content = null) {
-    if (!content) {
-      content = fs.readFileSync(filePath, 'utf8');
-    }
-
-    const relativePath = path.relative(this.config.rootPath, filePath);
-    const fileName = path.basename(filePath, path.extname(filePath));
-
-    // Analyze file
-    const analysis = {
-      purpose: this._detectPurpose(content, fileName, relativePath),
-      module: this._detectModule(relativePath),
-      layer: this._detectLayer(relativePath, content),
-      importsFrom: this._getImportsFrom(filePath),
-      exportsTo: this._getExportsTo(filePath),
-      sideEffects: this._detectSideEffects(content),
-      criticalFor: this._detectCriticalFor(filePath)
-    };
-
-    // Build widget string
-    const widget = this._buildWidgetString(analysis, fileName);
-
-    return {
-      analysis,
-      widgetString: widget,
-      fileName,
-      relativePath
-    };
-  }
-
-  /**
-   * Preview widgets for all files (dry run report)
-   */
-  async preview(limit = 20) {
-    const results = await this.generateAll();
-
-    console.log('\n' + '='.repeat(70));
-    console.log('WIDGET GENERATION PREVIEW');
-    console.log('='.repeat(70));
-    console.log(`Total files: ${results.total}`);
-    console.log(`Already have widgets: ${results.alreadyHasWidget}`);
-    console.log(`Will generate: ${results.generated}`);
-    console.log('');
-
-    for (const item of results.widgets.slice(0, limit)) {
-      console.log('-'.repeat(70));
-      console.log(`FILE: ${item.relativePath}`);
-      console.log('-'.repeat(70));
-      console.log(item.widget.widgetString);
-      console.log('');
-    }
-
-    if (results.widgets.length > limit) {
-      console.log(`... and ${results.widgets.length - limit} more files`);
-    }
-
-    return results;
-  }
-
-  /**
-   * Apply widgets to files (actually writes them)
-   */
-  async apply() {
-    this.config.dryRun = false;
-    const results = await this.generateAll();
-    console.log(`[WIDGET-GENERATOR] Applied ${results.generated} widgets to files`);
-    return results;
-  }
-
-  // Private methods
-
-  _hasWidget(content) {
-    // Check for existing widget with @purpose, @module, or @layer
-    const widgetPattern = /\/\*\*[\s\S]*?@(purpose|module|layer)[\s\S]*?\*\//;
-    return widgetPattern.test(content);
-  }
-
-  _detectPurpose(content, fileName, relativePath) {
-    // Try pattern matching first
-    for (const { pattern, purpose } of this.purposePatterns) {
-      const match = content.match(pattern);
-      if (match) {
-        return typeof purpose === 'function' ? purpose(match) : purpose;
-      }
-    }
-
-    // Fall back to file name analysis
-    const nameWords = fileName.replace(/[-_]/g, ' ').replace(/([A-Z])/g, ' $1').trim();
-
-    // Common suffixes
-    if (fileName.includes('route')) return `Route handlers for ${nameWords}`;
-    if (fileName.includes('api')) return `API endpoints for ${nameWords}`;
-    if (fileName.includes('service')) return `Service layer for ${nameWords}`;
-    if (fileName.includes('manager')) return `Manager for ${nameWords}`;
-    if (fileName.includes('store')) return `State store for ${nameWords}`;
-    if (fileName.includes('util')) return `Utility functions for ${nameWords}`;
-    if (fileName.includes('helper')) return `Helper functions for ${nameWords}`;
-    if (fileName.includes('test')) return `Tests for ${nameWords}`;
-    if (fileName.includes('config')) return `Configuration for ${nameWords}`;
-    if (fileName.includes('index')) return `Entry point for ${path.dirname(relativePath).split(path.sep).pop()}`;
-
-    return `Provides ${nameWords} functionality`;
-  }
-
-  _detectModule(relativePath) {
-    const normalized = relativePath.replace(/\\/g, '/');
-
-    for (const [module, pattern] of Object.entries(this.modulePatterns)) {
-      if (pattern.test(normalized)) {
-        return module;
-      }
-    }
-
-    // Use first directory as module
-    const parts = normalized.split('/');
-    return parts[0] || 'root';
-  }
-
-  _detectLayer(relativePath, content) {
-    // Check path patterns
-    for (const [layer, pattern] of Object.entries(this.layerPatterns)) {
-      if (pattern.test(relativePath)) {
-        return layer;
-      }
-    }
-
-    // Check content patterns
-    if (/router\.(get|post|put|delete)|app\.(get|post)/i.test(content)) {
-      return 'presentation';
-    }
-    if (/class.*Service|class.*Manager/i.test(content)) {
-      return 'application';
-    }
-    if (/class.*Model|schema|entity/i.test(content)) {
-      return 'domain';
-    }
-
-    return 'application'; // Default
-  }
-
-  _getImportsFrom(filePath) {
-    if (!this.dependencyGraph) return [];
-
-    const deps = this.dependencyGraph.getDependencies(filePath);
-    const imports = [];
-
-    for (const dep of deps.slice(0, 10)) { // Limit to 10
-      if (dep.resolved) {
-        const relPath = path.relative(this.config.rootPath, dep.resolved);
-        const moduleParts = relPath.split(path.sep);
-        const module = moduleParts[0];
-        const file = moduleParts[moduleParts.length - 1];
-        imports.push(`${module}/${file}`);
-      } else if (!dep.module.startsWith('.')) {
-        // External module
-        imports.push(dep.module);
-      }
-    }
-
-    return imports;
-  }
-
-  _getExportsTo(filePath) {
-    if (!this.dependencyGraph) return [];
-
-    const dependents = this.dependencyGraph.getDependents(filePath);
-    const exports = [];
-
-    for (const dep of dependents.slice(0, 10)) { // Limit to 10
-      const relPath = path.relative(this.config.rootPath, dep);
-      const moduleParts = relPath.split(path.sep);
-      const module = moduleParts[0];
-      exports.push(module);
-    }
-
-    // Deduplicate
-    return [...new Set(exports)];
-  }
-
-  _detectSideEffects(content) {
-    const effects = [];
-
-    for (const { pattern, effect } of this.sideEffectPatterns) {
-      if (pattern.test(content)) {
-        effects.push(effect);
-      }
-    }
-
-    return effects.length > 0 ? effects : ['None detected'];
-  }
-
-  _detectCriticalFor(filePath) {
-    if (!this.dependencyGraph) return [];
-
-    const impact = this.dependencyGraph.getImpactAnalysis(filePath);
-
-    if (impact.riskLevel === 'critical') {
-      return [`CRITICAL: ${impact.totalImpact} files depend on this`];
-    }
-    if (impact.riskLevel === 'high') {
-      return [`High impact: ${impact.totalImpact} files depend on this`];
-    }
-    if (impact.affectedModules.length > 0) {
-      return impact.affectedModules.slice(0, 5);
-    }
-
-    return [];
-  }
-
-  _buildWidgetString(analysis, fileName) {
-    const lines = [
-      '/**',
-      ` * ${this._toTitleCase(fileName)}`,
-      ' *',
-      ` * @purpose ${analysis.purpose}`,
-      ` * @module ${analysis.module}`,
-      ` * @layer ${analysis.layer}`
-    ];
-
-    if (analysis.importsFrom.length > 0) {
-      lines.push(` * @imports-from ${analysis.importsFrom.join(', ')}`);
-    }
-
-    if (analysis.exportsTo.length > 0) {
-      lines.push(` * @exports-to ${analysis.exportsTo.join(', ')}`);
-    }
-
-    lines.push(` * @side-effects ${analysis.sideEffects.join(', ')}`);
-
-    if (analysis.criticalFor.length > 0) {
-      lines.push(` * @critical-for ${analysis.criticalFor.join(', ')}`);
-    }
-
-    lines.push(' */');
-
-    return lines.join('\n');
-  }
-
-  _toTitleCase(str) {
-    return str
-      .replace(/[-_]/g, ' ')
-      .replace(/([A-Z])/g, ' $1')
-      .trim()
-      .split(' ')
-      .map(w => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase())
-      .join(' ');
-  }
-
-  async _applyWidget(filePath, content, widget) {
-    // Prepend widget to file content
-    const newContent = widget.widgetString + '\n\n' + content;
-
-    try {
-      fs.writeFileSync(filePath, newContent, 'utf8');
-      return true;
-    } catch (error) {
-      console.error(`[WIDGET-GENERATOR] Failed to write widget to ${filePath}:`, error.message);
-      return false;
-    }
-  }
-
-  async _discoverFiles(dir, files = []) {
-    const ignorePatterns = ['node_modules', '.git', 'dist', '.vite', '.orion'];
-
-    try {
-      const entries = fs.readdirSync(dir, { withFileTypes: true });
-
-      for (const entry of entries) {
-        if (ignorePatterns.some(p => entry.name === p || entry.name.startsWith(p))) {
-          continue;
-        }
-
-        const fullPath = path.join(dir, entry.name);
-
-        if (entry.isDirectory()) {
-          await this._discoverFiles(fullPath, files);
-        } else if (entry.isFile() && entry.name.endsWith('.js')) {
-          files.push(fullPath);
-        }
-      }
-    } catch (error) {
-      // Skip inaccessible directories
-    }
-
-    return files;
-  }
-}
-
-module.exports = WidgetGenerator;
+/**
+ * Sentinel Widget Generator
+ *
+ * Automatically generates widget contracts for files that don't have them.
+ * Uses dependency graph, code analysis, and file path heuristics to
+ * create meaningful @purpose, @module, @layer, etc. annotations.
+ *
+ * @purpose Generate widget contracts for undocumented files
+ * @module sentinel
+ * @layer infrastructure
+ * @imports-from dependency-graph, fs, path
+ * @exports-to sentinel-core, CLI tools
+ * @side-effects File system reads; optionally writes widgets to files
+ */
+
+const fs = require('fs');
+const path = require('path');
+const DependencyGraph = require('./dependency-graph');
+
+class WidgetGenerator {
+  constructor(config = {}) {
+    this.config = {
+      rootPath: config.rootPath || process.cwd(),
+      dryRun: config.dryRun !== false, // Default to dry run (don't write)
+      ...config
+    };
+
+    this.dependencyGraph = config.dependencyGraph || null;
+
+    // Module detection patterns
+    this.modulePatterns = {
+      'sentinel': /^sentinel[\\\/]/,
+      'citadel': /^citadel[\\\/]/,
+      'forge': /^forge[\\\/]/,
+      'server': /^server[\\\/]/,
+      'build-engine': /^build-engine[\\\/]/,
+      'autopilot': /^autopilot[\\\/]/,
+      'silverwings': /^silverwings[\\\/]/,
+      'output': /^output[\\\/]/
+    };
+
+    // Layer detection patterns
+    this.layerPatterns = {
+      'presentation': /routes|api|handlers|controllers|views/i,
+      'application': /service|manager|orchestrat|core|engine/i,
+      'domain': /model|entity|domain|types/i,
+      'infrastructure': /utils|helpers|lib|data|store|memory/i
+    };
+
+    // Side effect patterns
+    this.sideEffectPatterns = [
+      { pattern: /fs\.(write|append|unlink|mkdir|rmdir|rename)/i, effect: 'File system writes' },
+      { pattern: /fs\.read/i, effect: 'File system reads' },
+      { pattern: /fetch\(|axios\.|http\.|https\./i, effect: 'HTTP requests' },
+      { pattern: /process\.exit/i, effect: 'Process termination' },
+      { pattern: /child_process|spawn|exec\(/i, effect: 'Spawns child processes' },
+      { pattern: /console\.(log|error|warn)/i, effect: 'Console output' },
+      { pattern: /\.emit\(|EventEmitter/i, effect: 'Event emission' },
+      { pattern: /supabase|createClient/i, effect: 'Database operations' },
+      { pattern: /twilio|sendgrid|resend/i, effect: 'External API calls' }
+    ];
+
+    // Purpose detection from common patterns
+    this.purposePatterns = [
+      { pattern: /class\s+(\w+).*extends.*Router/i, purpose: (m) => `Express router for ${m[1]}` },
+      { pattern: /class\s+(\w+).*extends.*EventEmitter/i, purpose: (m) => `Event-driven ${m[1]} component` },
+      { pattern: /class\s+(\w+)/i, purpose: (m) => `${m[1]} class implementation` },
+      { pattern: /module\.exports\s*=\s*\{([^}]+)\}/i, purpose: (m) => `Exports: ${m[1].match(/\w+/g)?.slice(0, 5).join(', ')}` },
+      { pattern: /router\.(get|post|put|delete)/i, purpose: () => 'API route handlers' },
+      { pattern: /async function\s+(\w+)/i, purpose: (m) => `Provides ${m[1]} functionality` },
+      { pattern: /function\s+(\w+)/i, purpose: (m) => `Provides ${m[1]} functionality` }
+    ];
+  }
+
+  /**
+   * Generate widgets for all files missing them
+   */
+  async generateAll() {
+    console.log('[WIDGET-GENERATOR] Starting widget generation...');
+
+    // Build dependency graph if not provided
+    if (!this.dependencyGraph) {
+      this.dependencyGraph = new DependencyGraph({ rootPath: this.config.rootPath });
+      await this.dependencyGraph.build();
+    }
+
+    // Find files without widgets
+    const files = await this._discoverFiles(this.config.rootPath);
+    const results = {
+      total: files.length,
+      generated: 0,
+      skipped: 0,
+      alreadyHasWidget: 0,
+      widgets: []
+    };
+
+    for (const file of files) {
+      const content = fs.readFileSync(file, 'utf8');
+
+      // Skip if already has widget
+      if (this._hasWidget(content)) {
+        results.alreadyHasWidget++;
+        continue;
+      }
+
+      const widget = await this.generateWidget(file, content);
+      results.generated++;
+      results.widgets.push({
+        file,
+        relativePath: path.relative(this.config.rootPath, file),
+        widget
+      });
+
+      // Apply widget if not dry run
+      if (!this.config.dryRun) {
+        await this._applyWidget(file, content, widget);
+      }
+    }
+
+    console.log(`[WIDGET-GENERATOR] Generated ${results.generated} widgets (${results.alreadyHasWidget} already had widgets)`);
+    return results;
+  }
+
+  /**
+   * Generate widget for a single file
+   */
+  async generateWidget(filePath, content = null) {
+    if (!content) {
+      content = fs.readFileSync(filePath, 'utf8');
+    }
+
+    const relativePath = path.relative(this.config.rootPath, filePath);
+    const fileName = path.basename(filePath, path.extname(filePath));
+
+    // Analyze file
+    const analysis = {
+      purpose: this._detectPurpose(content, fileName, relativePath),
+      module: this._detectModule(relativePath),
+      layer: this._detectLayer(relativePath, content),
+      importsFrom: this._getImportsFrom(filePath),
+      exportsTo: this._getExportsTo(filePath),
+      sideEffects: this._detectSideEffects(content),
+      criticalFor: this._detectCriticalFor(filePath)
+    };
+
+    // Build widget string
+    const widget = this._buildWidgetString(analysis, fileName);
+
+    return {
+      analysis,
+      widgetString: widget,
+      fileName,
+      relativePath
+    };
+  }
+
+  /**
+   * Preview widgets for all files (dry run report)
+   */
+  async preview(limit = 20) {
+    const results = await this.generateAll();
+
+    console.log('\n' + '='.repeat(70));
+    console.log('WIDGET GENERATION PREVIEW');
+    console.log('='.repeat(70));
+    console.log(`Total files: ${results.total}`);
+    console.log(`Already have widgets: ${results.alreadyHasWidget}`);
+    console.log(`Will generate: ${results.generated}`);
+    console.log('');
+
+    for (const item of results.widgets.slice(0, limit)) {
+      console.log('-'.repeat(70));
+      console.log(`FILE: ${item.relativePath}`);
+      console.log('-'.repeat(70));
+      console.log(item.widget.widgetString);
+      console.log('');
+    }
+
+    if (results.widgets.length > limit) {
+      console.log(`... and ${results.widgets.length - limit} more files`);
+    }
+
+    return results;
+  }
+
+  /**
+   * Apply widgets to files (actually writes them)
+   */
+  async apply() {
+    this.config.dryRun = false;
+    const results = await this.generateAll();
+    console.log(`[WIDGET-GENERATOR] Applied ${results.generated} widgets to files`);
+    return results;
+  }
+
+  // Private methods
+
+  _hasWidget(content) {
+    // Check for existing widget with @purpose, @module, or @layer
+    const widgetPattern = /\/\*\*[\s\S]*?@(purpose|module|layer)[\s\S]*?\*\//;
+    return widgetPattern.test(content);
+  }
+
+  _detectPurpose(content, fileName, relativePath) {
+    // Try pattern matching first
+    for (const { pattern, purpose } of this.purposePatterns) {
+      const match = content.match(pattern);
+      if (match) {
+        return typeof purpose === 'function' ? purpose(match) : purpose;
+      }
+    }
+
+    // Fall back to file name analysis
+    const nameWords = fileName.replace(/[-_]/g, ' ').replace(/([A-Z])/g, ' $1').trim();
+
+    // Common suffixes
+    if (fileName.includes('route')) return `Route handlers for ${nameWords}`;
+    if (fileName.includes('api')) return `API endpoints for ${nameWords}`;
+    if (fileName.includes('service')) return `Service layer for ${nameWords}`;
+    if (fileName.includes('manager')) return `Manager for ${nameWords}`;
+    if (fileName.includes('store')) return `State store for ${nameWords}`;
+    if (fileName.includes('util')) return `Utility functions for ${nameWords}`;
+    if (fileName.includes('helper')) return `Helper functions for ${nameWords}`;
+    if (fileName.includes('test')) return `Tests for ${nameWords}`;
+    if (fileName.includes('config')) return `Configuration for ${nameWords}`;
+    if (fileName.includes('index')) return `Entry point for ${path.dirname(relativePath).split(path.sep).pop()}`;
+
+    return `Provides ${nameWords} functionality`;
+  }
+
+  _detectModule(relativePath) {
+    const normalized = relativePath.replace(/\\/g, '/');
+
+    for (const [module, pattern] of Object.entries(this.modulePatterns)) {
+      if (pattern.test(normalized)) {
+        return module;
+      }
+    }
+
+    // Use first directory as module
+    const parts = normalized.split('/');
+    return parts[0] || 'root';
+  }
+
+  _detectLayer(relativePath, content) {
+    // Check path patterns
+    for (const [layer, pattern] of Object.entries(this.layerPatterns)) {
+      if (pattern.test(relativePath)) {
+        return layer;
+      }
+    }
+
+    // Check content patterns
+    if (/router\.(get|post|put|delete)|app\.(get|post)/i.test(content)) {
+      return 'presentation';
+    }
+    if (/class.*Service|class.*Manager/i.test(content)) {
+      return 'application';
+    }
+    if (/class.*Model|schema|entity/i.test(content)) {
+      return 'domain';
+    }
+
+    return 'application'; // Default
+  }
+
+  _getImportsFrom(filePath) {
+    if (!this.dependencyGraph) return [];
+
+    const deps = this.dependencyGraph.getDependencies(filePath);
+    const imports = [];
+
+    for (const dep of deps.slice(0, 10)) { // Limit to 10
+      if (dep.resolved) {
+        const relPath = path.relative(this.config.rootPath, dep.resolved);
+        const moduleParts = relPath.split(path.sep);
+        const module = moduleParts[0];
+        const file = moduleParts[moduleParts.length - 1];
+        imports.push(`${module}/${file}`);
+      } else if (!dep.module.startsWith('.')) {
+        // External module
+        imports.push(dep.module);
+      }
+    }
+
+    return imports;
+  }
+
+  _getExportsTo(filePath) {
+    if (!this.dependencyGraph) return [];
+
+    const dependents = this.dependencyGraph.getDependents(filePath);
+    const exports = [];
+
+    for (const dep of dependents.slice(0, 10)) { // Limit to 10
+      const relPath = path.relative(this.config.rootPath, dep);
+      const moduleParts = relPath.split(path.sep);
+      const module = moduleParts[0];
+      exports.push(module);
+    }
+
+    // Deduplicate
+    return [...new Set(exports)];
+  }
+
+  _detectSideEffects(content) {
+    const effects = [];
+
+    for (const { pattern, effect } of this.sideEffectPatterns) {
+      if (pattern.test(content)) {
+        effects.push(effect);
+      }
+    }
+
+    return effects.length > 0 ? effects : ['None detected'];
+  }
+
+  _detectCriticalFor(filePath) {
+    if (!this.dependencyGraph) return [];
+
+    const impact = this.dependencyGraph.getImpactAnalysis(filePath);
+
+    if (impact.riskLevel === 'critical') {
+      return [`CRITICAL: ${impact.totalImpact} files depend on this`];
+    }
+    if (impact.riskLevel === 'high') {
+      return [`High impact: ${impact.totalImpact} files depend on this`];
+    }
+    if (impact.affectedModules.length > 0) {
+      return impact.affectedModules.slice(0, 5);
+    }
+
+    return [];
+  }
+
+  _buildWidgetString(analysis, fileName) {
+    const lines = [
+      '/**',
+      ` * ${this._toTitleCase(fileName)}`,
+      ' *',
+      ` * @purpose ${analysis.purpose}`,
+      ` * @module ${analysis.module}`,
+      ` * @layer ${analysis.layer}`
+    ];
+
+    if (analysis.importsFrom.length > 0) {
+      lines.push(` * @imports-from ${analysis.importsFrom.join(', ')}`);
+    }
+
+    if (analysis.exportsTo.length > 0) {
+      lines.push(` * @exports-to ${analysis.exportsTo.join(', ')}`);
+    }
+
+    lines.push(` * @side-effects ${analysis.sideEffects.join(', ')}`);
+
+    if (analysis.criticalFor.length > 0) {
+      lines.push(` * @critical-for ${analysis.criticalFor.join(', ')}`);
+    }
+
+    lines.push(' */');
+
+    return lines.join('\n');
+  }
+
+  _toTitleCase(str) {
+    return str
+      .replace(/[-_]/g, ' ')
+      .replace(/([A-Z])/g, ' $1')
+      .trim()
+      .split(' ')
+      .map(w => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase())
+      .join(' ');
+  }
+
+  async _applyWidget(filePath, content, widget) {
+    // Prepend widget to file content
+    const newContent = widget.widgetString + '\n\n' + content;
+
+    try {
+      fs.writeFileSync(filePath, newContent, 'utf8');
+      return true;
+    } catch (error) {
+      console.error(`[WIDGET-GENERATOR] Failed to write widget to ${filePath}:`, error.message);
+      return false;
+    }
+  }
+
+  async _discoverFiles(dir, files = []) {
+    const ignorePatterns = ['node_modules', '.git', 'dist', '.vite', '.orion'];
+
+    try {
+      const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+      for (const entry of entries) {
+        if (ignorePatterns.some(p => entry.name === p || entry.name.startsWith(p))) {
+          continue;
+        }
+
+        const fullPath = path.join(dir, entry.name);
+
+        if (entry.isDirectory()) {
+          await this._discoverFiles(fullPath, files);
+        } else if (entry.isFile() && entry.name.endsWith('.js')) {
+          files.push(fullPath);
+        }
+      }
+    } catch (error) {
+      // Skip inaccessible directories
+    }
+
+    return files;
+  }
+}
+
+module.exports = WidgetGenerator;