thuban 0.3.0

package/packages/scanner/drift-detector.js

@@ -0,0 +1,425 @@
+/**
+ * Sentinel Drift Detector
+ *
+ * Detects architectural drift by comparing code against declared contracts.
+ * Checks for mismatches between:
+ * - File widgets (declared purpose, imports, exports)
+ * - Actual code structure
+ * - Module relationships
+ */
+
+const fs = require('fs');
+const path = require('path');
+const EventEmitter = require('events');
+
+class DriftDetector extends EventEmitter {
+  constructor(config = {}) {
+    super();
+
+    this.config = {
+      rootPath: config.rootPath || process.cwd(),
+      widgetPattern: config.widgetPattern || /\/\*\*[\s\S]*?@(purpose|module|layer|imports-from|exports-to|depends-on|critical-for)[\s\S]*?\*\//,
+      ignorePatterns: config.ignorePatterns || [
+        'node_modules/**',
+        '.git/**',
+        'dist/**',
+        '.orion/snapshots/**'
+      ],
+      ...config
+    };
+
+    // Cache for file analysis results
+    this.analysisCache = new Map();
+  }
+
+  /**
+   * Detect drift across all files
+   */
+  async detectAll() {
+    console.log('[DRIFT-DETECTOR] Starting drift detection...');
+    const startTime = Date.now();
+
+    const result = {
+      filesAnalyzed: 0,
+      filesWithWidgets: 0,
+      filesWithoutWidgets: 0,
+      issues: [],
+      moduleMap: {},
+      duration: 0
+    };
+
+    try {
+      const files = await this._discoverFiles(this.config.rootPath);
+
+      for (const file of files) {
+        const analysis = await this.analyzeFile(file);
+        result.filesAnalyzed++;
+
+        if (analysis.hasWidget) {
+          result.filesWithWidgets++;
+        } else {
+          result.filesWithoutWidgets++;
+          // Missing widget is itself drift
+          result.issues.push({
+            file,
+            category: 'drift',
+            severity: 'info',
+            id: 'DRIFT001',
+            name: 'Missing Widget',
+            message: 'File has no widget declaration - add @purpose, @module, @layer etc.'
+          });
+        }
+
+        // Check for specific drift issues
+        result.issues.push(...analysis.issues);
+
+        // Build module map
+        if (analysis.module) {
+          if (!result.moduleMap[analysis.module]) {
+            result.moduleMap[analysis.module] = [];
+          }
+          result.moduleMap[analysis.module].push(file);
+        }
+      }
+
+      // Cross-file analysis for circular dependencies and broken references
+      result.issues.push(...this._analyzeCrossFile(result.moduleMap));
+
+      result.duration = Date.now() - startTime;
+      console.log(`[DRIFT-DETECTOR] Detection complete: ${result.filesAnalyzed} files, ${result.issues.length} drift issues`);
+
+      return result;
+    } catch (error) {
+      console.error('[DRIFT-DETECTOR] Detection failed:', error.message);
+      result.error = error.message;
+      return result;
+    }
+  }
+
+  /**
+   * Analyze a single file for drift
+   */
+  async analyzeFile(filePath) {
+    const result = {
+      file: filePath,
+      hasWidget: false,
+      widget: null,
+      actualExports: [],
+      actualImports: [],
+      module: null,
+      issues: []
+    };
+
+    try {
+      const content = fs.readFileSync(filePath, 'utf8');
+
+      // Parse widget if present
+      result.widget = this._parseWidget(content);
+      result.hasWidget = !!result.widget;
+
+      // Analyze actual code structure
+      result.actualExports = this._extractExports(content);
+      result.actualImports = this._extractImports(content);
+
+      // If widget exists, check for drift
+      if (result.widget) {
+        result.module = result.widget.module;
+        result.issues.push(...this._compareWidgetToCode(filePath, result.widget, {
+          exports: result.actualExports,
+          imports: result.actualImports
+        }));
+      }
+
+      // Cache the analysis
+      this.analysisCache.set(filePath, result);
+
+      return result;
+    } catch (error) {
+      result.issues.push({
+        file: filePath,
+        category: 'drift',
+        severity: 'error',
+        id: 'DRIFT000',
+        message: `Failed to analyze file: ${error.message}`
+      });
+      return result;
+    }
+  }
+
+  /**
+   * Check if a specific file has drifted from its widget
+   */
+  async checkFileDrift(filePath) {
+    const analysis = await this.analyzeFile(filePath);
+    return {
+      hasDrift: analysis.issues.length > 0,
+      issues: analysis.issues,
+      widget: analysis.widget
+    };
+  }
+
+  /**
+   * Generate suggested widget for a file
+   */
+  async suggestWidget(filePath) {
+    try {
+      const content = fs.readFileSync(filePath, 'utf8');
+      const exports = this._extractExports(content);
+      const imports = this._extractImports(content);
+
+      // Determine module from path
+      const relativePath = path.relative(this.config.rootPath, filePath);
+      const pathParts = relativePath.split(path.sep);
+      const module = pathParts[0];
+
+      // Determine layer from path/content
+      let layer = 'application';
+      if (relativePath.includes('routes') || relativePath.includes('api')) {
+        layer = 'presentation';
+      } else if (relativePath.includes('core') || relativePath.includes('engine')) {
+        layer = 'infrastructure';
+      } else if (relativePath.includes('model') || relativePath.includes('domain')) {
+        layer = 'domain';
+      }
+
+      // Generate purpose from exports
+      const purpose = exports.length > 0
+        ? `Provides ${exports.join(', ')}`
+        : 'Unknown purpose - needs description';
+
+      return {
+        purpose,
+        module,
+        layer,
+        importsFrom: imports.map(i => `${i.module} - ${i.specifiers.join(', ')}`),
+        exportsTo: 'To be determined',
+        dataFlow: 'To be documented',
+        sideEffects: content.includes('fs.') ? 'File system operations' : 'None documented',
+        criticalFor: 'To be documented'
+      };
+    } catch (error) {
+      return { error: error.message };
+    }
+  }
+
+  // Private methods
+
+  async _discoverFiles(dir, files = []) {
+    try {
+      const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+      for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        const relativePath = path.relative(this.config.rootPath, fullPath);
+
+        if (this._shouldIgnore(relativePath)) {
+          continue;
+        }
+
+        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;
+  }
+
+  _shouldIgnore(relativePath) {
+    const normalized = relativePath.replace(/\\/g, '/');
+
+    // Always ignore any path containing these directories (anywhere in path)
+    const alwaysIgnore = ['node_modules', '.git', 'dist', '.vite'];
+    for (const dir of alwaysIgnore) {
+      if (normalized.includes('/' + dir + '/') ||
+          normalized.startsWith(dir + '/') ||
+          normalized === dir ||
+          normalized.endsWith('/' + dir)) {
+        return true;
+      }
+    }
+
+    for (const pattern of this.config.ignorePatterns) {
+      const normalizedPattern = pattern.replace(/\\/g, '/');
+
+      // Extract base directory from pattern (e.g., 'node_modules' from 'node_modules/**')
+      const baseDir = normalizedPattern.split('/')[0].replace(/\*/g, '');
+
+      // Check if path IS the ignored directory or starts with it
+      if (baseDir && (normalized === baseDir || normalized.startsWith(baseDir + '/'))) {
+        return true;
+      }
+
+      // Simple glob matching for more complex patterns
+      let regexPattern = normalizedPattern
+        .replace(/\./g, '\\.')
+        .replace(/\*\*/g, '.*')
+        .replace(/\*/g, '[^/]*');
+
+      if (new RegExp('^' + regexPattern).test(normalized)) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  _parseWidget(content) {
+    // Look for widget comment block at top of file
+    const widgetMatch = content.match(/\/\*\*[\s\S]*?\*\//);
+    if (!widgetMatch) return null;
+
+    const widgetBlock = widgetMatch[0];
+    const widget = {};
+
+    // Parse each @ field
+    const fields = [
+      'purpose', 'module', 'layer', 'imports-from', 'exports-to',
+      'data-flow', 'side-effects', 'depends-on-env', 'critical-for',
+      'known-issues', 'last-audit', 'last-modified'
+    ];
+
+    for (const field of fields) {
+      const fieldMatch = widgetBlock.match(new RegExp(`@${field}\\s+(.+?)(?=\\n\\s*\\*\\s*@|\\n\\s*\\*\\/|$)`, 's'));
+      if (fieldMatch) {
+        const key = field.replace(/-/g, '_');
+        widget[key] = fieldMatch[1].trim().replace(/\n\s*\*\s*/g, ' ').trim();
+      }
+    }
+
+    return Object.keys(widget).length > 0 ? widget : null;
+  }
+
+  _extractExports(content) {
+    const exports = [];
+
+    // module.exports = { ... }
+    const objectExportMatch = content.match(/module\.exports\s*=\s*\{([^}]+)\}/);
+    if (objectExportMatch) {
+      const items = objectExportMatch[1].match(/\w+/g) || [];
+      exports.push(...items);
+    }
+
+    // module.exports = function/class
+    const directExportMatch = content.match(/module\.exports\s*=\s*(class\s+)?(\w+)/);
+    if (directExportMatch && directExportMatch[2]) {
+      exports.push(directExportMatch[2]);
+    }
+
+    // exports.name = ...
+    const namedExports = content.match(/exports\.(\w+)\s*=/g) || [];
+    for (const exp of namedExports) {
+      const name = exp.match(/exports\.(\w+)/);
+      if (name) exports.push(name[1]);
+    }
+
+    return [...new Set(exports)];
+  }
+
+  _extractImports(content) {
+    const imports = [];
+
+    // require statements
+    const requireMatches = content.matchAll(/(?:const|let|var)\s+(?:\{([^}]+)\}|(\w+))\s*=\s*require\(['"]([^'"]+)['"]\)/g);
+
+    for (const match of requireMatches) {
+      const specifiers = match[1]
+        ? match[1].split(',').map(s => s.trim().split(':')[0].trim())
+        : [match[2]];
+
+      imports.push({
+        module: match[3],
+        specifiers: specifiers.filter(Boolean)
+      });
+    }
+
+    return imports;
+  }
+
+  _compareWidgetToCode(filePath, widget, actual) {
+    const issues = [];
+
+    // Check exports drift
+    if (widget.exports_to) {
+      const declaredExports = widget.exports_to.split(',').map(e => e.trim().split(' ')[0]);
+      const missingExports = declaredExports.filter(e =>
+        !actual.exports.some(ae => ae.toLowerCase().includes(e.toLowerCase()))
+      );
+
+      if (missingExports.length > 0) {
+        issues.push({
+          file: filePath,
+          category: 'drift',
+          severity: 'warning',
+          id: 'DRIFT002',
+          name: 'Missing Declared Export',
+          message: `Widget declares exports not found in code: ${missingExports.join(', ')}`
+        });
+      }
+    }
+
+    // Check imports drift
+    if (widget.imports_from) {
+      const declaredImports = widget.imports_from.split(',').map(i => i.trim().split(' ')[0]);
+      const actualModules = actual.imports.map(i => i.module);
+
+      const missingImports = declaredImports.filter(d =>
+        !actualModules.some(am => am.includes(d) || d.includes(am.split('/').pop()))
+      );
+
+      if (missingImports.length > 0) {
+        issues.push({
+          file: filePath,
+          category: 'drift',
+          severity: 'warning',
+          id: 'DRIFT003',
+          name: 'Missing Declared Import',
+          message: `Widget declares imports not found in code: ${missingImports.join(', ')}`
+        });
+      }
+    }
+
+    // Check for undeclared side effects
+    const hasFsOperations = /fs\.(write|append|unlink|mkdir|rmdir)/i.test(fs.readFileSync(filePath, 'utf8'));
+    if (hasFsOperations && (!widget.side_effects || widget.side_effects === 'None')) {
+      issues.push({
+        file: filePath,
+        category: 'drift',
+        severity: 'warning',
+        id: 'DRIFT004',
+        name: 'Undeclared Side Effects',
+        message: 'File has file system operations but widget declares no side effects'
+      });
+    }
+
+    return issues;
+  }
+
+  _analyzeCrossFile(moduleMap) {
+    const issues = [];
+
+    // Check for orphaned modules (single file)
+    for (const [module, files] of Object.entries(moduleMap)) {
+      if (files.length === 1) {
+        issues.push({
+          file: files[0],
+          category: 'drift',
+          severity: 'info',
+          id: 'DRIFT005',
+          name: 'Orphaned Module',
+          message: `Module "${module}" only has one file - verify module organization`
+        });
+      }
+    }
+
+    // Would also check for circular dependencies here if we had full import graph
+
+    return issues;
+  }
+}
+
+module.exports = DriftDetector;