thuban 0.3.0

package/packages/scanner/dependency-graph.js

@@ -0,0 +1,539 @@
+/**
+ * Sentinel Dependency Graph
+ *
+ * Maps all file dependencies in the Orion codebase.
+ * Answers: "If I change X, what breaks?"
+ *
+ * @purpose Track and analyze file dependencies across codebase
+ * @module sentinel
+ * @layer infrastructure
+ * @exports-to sentinel-core, widget-generator
+ * @side-effects File system reads
+ */
+
+const fs = require('fs');
+const path = require('path');
+const EventEmitter = require('events');
+
+class DependencyGraph extends EventEmitter {
+  constructor(config = {}) {
+    super();
+
+    this.config = {
+      rootPath: config.rootPath || process.cwd(),
+      ignorePatterns: config.ignorePatterns || [
+        'node_modules', '.git', 'dist', '.vite', '.orion/snapshots'
+      ],
+      extensions: config.extensions || ['.js', '.ts', '.jsx', '.tsx'],
+      ...config
+    };
+
+    // The graph: file -> { imports: [], importedBy: [] }
+    this.graph = new Map();
+
+    // Module resolution cache
+    this.resolveCache = new Map();
+
+    // Statistics
+    this.stats = {
+      filesAnalyzed: 0,
+      totalImports: 0,
+      unresolvedImports: 0,
+      circularDependencies: []
+    };
+  }
+
+  /**
+   * Build the full dependency graph
+   */
+  async build() {
+    console.log('[DEPENDENCY-GRAPH] Building dependency graph...');
+    const startTime = Date.now();
+
+    // Clear existing graph
+    this.graph.clear();
+    this.resolveCache.clear();
+    this.stats = {
+      filesAnalyzed: 0,
+      totalImports: 0,
+      unresolvedImports: 0,
+      circularDependencies: []
+    };
+
+    // Discover all files
+    const files = await this._discoverFiles(this.config.rootPath);
+    console.log(`[DEPENDENCY-GRAPH] Found ${files.length} files to analyze`);
+
+    // First pass: extract all imports
+    for (const file of files) {
+      await this._analyzeFile(file);
+    }
+
+    // Second pass: build reverse dependencies (importedBy)
+    this._buildReverseDependencies();
+
+    // Third pass: detect circular dependencies
+    this._detectCircularDependencies();
+
+    const duration = Date.now() - startTime;
+    console.log(`[DEPENDENCY-GRAPH] Graph built in ${duration}ms`);
+    console.log(`[DEPENDENCY-GRAPH] ${this.stats.filesAnalyzed} files, ${this.stats.totalImports} imports, ${this.stats.unresolvedImports} unresolved`);
+
+    return this.getStats();
+  }
+
+  /**
+   * Get what a file depends on (imports)
+   */
+  getDependencies(filePath) {
+    const normalized = this._normalizePath(filePath);
+    const node = this.graph.get(normalized);
+    return node ? node.imports : [];
+  }
+
+  /**
+   * Get what depends on a file (dependents)
+   */
+  getDependents(filePath) {
+    const normalized = this._normalizePath(filePath);
+    const node = this.graph.get(normalized);
+    return node ? node.importedBy : [];
+  }
+
+  /**
+   * Get full dependency chain (recursive)
+   */
+  getFullDependencyChain(filePath, visited = new Set()) {
+    const normalized = this._normalizePath(filePath);
+    if (visited.has(normalized)) return []; // Prevent infinite loop
+
+    visited.add(normalized);
+    const deps = this.getDependencies(normalized);
+    const chain = [...deps];
+
+    for (const dep of deps) {
+      if (dep.resolved) {
+        chain.push(...this.getFullDependencyChain(dep.resolved, visited));
+      }
+    }
+
+    return chain;
+  }
+
+  /**
+   * IMPACT ANALYSIS: What could break if I change this file?
+   */
+  getImpactAnalysis(filePath) {
+    const normalized = this._normalizePath(filePath);
+    const result = {
+      file: normalized,
+      relativePath: path.relative(this.config.rootPath, normalized),
+      directDependents: [],
+      indirectDependents: [],
+      totalImpact: 0,
+      riskLevel: 'low',
+      affectedModules: new Set()
+    };
+
+    // Get direct dependents
+    result.directDependents = this.getDependents(normalized).map(d => ({
+      file: d,
+      relativePath: path.relative(this.config.rootPath, d)
+    }));
+
+    // Get indirect dependents (recursive)
+    const visited = new Set([normalized]);
+    const queue = [...result.directDependents.map(d => d.file)];
+
+    while (queue.length > 0) {
+      const current = queue.shift();
+      if (visited.has(current)) continue;
+      visited.add(current);
+
+      const dependents = this.getDependents(current);
+      for (const dep of dependents) {
+        if (!visited.has(dep)) {
+          result.indirectDependents.push({
+            file: dep,
+            relativePath: path.relative(this.config.rootPath, dep),
+            via: path.relative(this.config.rootPath, current)
+          });
+          queue.push(dep);
+        }
+      }
+    }
+
+    // Calculate total impact
+    result.totalImpact = result.directDependents.length + result.indirectDependents.length;
+
+    // Determine risk level
+    if (result.totalImpact === 0) {
+      result.riskLevel = 'none';
+    } else if (result.totalImpact <= 3) {
+      result.riskLevel = 'low';
+    } else if (result.totalImpact <= 10) {
+      result.riskLevel = 'medium';
+    } else if (result.totalImpact <= 25) {
+      result.riskLevel = 'high';
+    } else {
+      result.riskLevel = 'critical';
+    }
+
+    // Extract affected modules
+    for (const dep of [...result.directDependents, ...result.indirectDependents]) {
+      const parts = dep.relativePath.split(path.sep);
+      if (parts.length > 0) {
+        result.affectedModules.add(parts[0]);
+      }
+    }
+    result.affectedModules = Array.from(result.affectedModules);
+
+    return result;
+  }
+
+  /**
+   * Find most critical files (most dependents)
+   */
+  getMostCriticalFiles(limit = 20) {
+    const files = [];
+
+    for (const [filePath, node] of this.graph) {
+      files.push({
+        file: filePath,
+        relativePath: path.relative(this.config.rootPath, filePath),
+        dependentCount: node.importedBy.length,
+        dependencyCount: node.imports.length
+      });
+    }
+
+    return files
+      .sort((a, b) => b.dependentCount - a.dependentCount)
+      .slice(0, limit);
+  }
+
+  /**
+   * Find orphan files (no imports, no dependents)
+   */
+  getOrphanFiles() {
+    const orphans = [];
+
+    for (const [filePath, node] of this.graph) {
+      if (node.imports.length === 0 && node.importedBy.length === 0) {
+        orphans.push({
+          file: filePath,
+          relativePath: path.relative(this.config.rootPath, filePath)
+        });
+      }
+    }
+
+    return orphans;
+  }
+
+  /**
+   * Get module dependency summary
+   */
+  getModuleSummary() {
+    const modules = new Map();
+
+    for (const [filePath, node] of this.graph) {
+      const relativePath = path.relative(this.config.rootPath, filePath);
+      const parts = relativePath.split(path.sep);
+      const moduleName = parts[0];
+
+      if (!modules.has(moduleName)) {
+        modules.set(moduleName, {
+          name: moduleName,
+          files: [],
+          internalDeps: 0,
+          externalDeps: 0,
+          dependedOnBy: new Set()
+        });
+      }
+
+      const mod = modules.get(moduleName);
+      mod.files.push(relativePath);
+
+      // Count internal vs external dependencies
+      for (const imp of node.imports) {
+        if (imp.resolved) {
+          const impRelative = path.relative(this.config.rootPath, imp.resolved);
+          const impModule = impRelative.split(path.sep)[0];
+          if (impModule === moduleName) {
+            mod.internalDeps++;
+          } else {
+            mod.externalDeps++;
+          }
+        }
+      }
+
+      // Track which modules depend on this one
+      for (const depPath of node.importedBy) {
+        const depRelative = path.relative(this.config.rootPath, depPath);
+        const depModule = depRelative.split(path.sep)[0];
+        if (depModule !== moduleName) {
+          mod.dependedOnBy.add(depModule);
+        }
+      }
+    }
+
+    // Convert to array and calculate metrics
+    const result = [];
+    for (const [name, mod] of modules) {
+      result.push({
+        name,
+        fileCount: mod.files.length,
+        internalDeps: mod.internalDeps,
+        externalDeps: mod.externalDeps,
+        dependedOnByCount: mod.dependedOnBy.size,
+        dependedOnBy: Array.from(mod.dependedOnBy)
+      });
+    }
+
+    return result.sort((a, b) => b.fileCount - a.fileCount);
+  }
+
+  /**
+   * Get statistics
+   */
+  getStats() {
+    return {
+      ...this.stats,
+      totalFiles: this.graph.size,
+      circularCount: this.stats.circularDependencies.length
+    };
+  }
+
+  /**
+   * Export graph as JSON
+   */
+  toJSON() {
+    const data = {
+      generated: new Date().toISOString(),
+      rootPath: this.config.rootPath,
+      stats: this.getStats(),
+      files: {}
+    };
+
+    for (const [filePath, node] of this.graph) {
+      const relativePath = path.relative(this.config.rootPath, filePath);
+      data.files[relativePath] = {
+        imports: node.imports.map(i => ({
+          module: i.module,
+          resolved: i.resolved ? path.relative(this.config.rootPath, i.resolved) : null,
+          specifiers: i.specifiers
+        })),
+        importedBy: node.importedBy.map(p => path.relative(this.config.rootPath, p))
+      };
+    }
+
+    return data;
+  }
+
+  // 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);
+
+        // Check ignore patterns
+        if (this._shouldIgnore(entry.name)) {
+          continue;
+        }
+
+        if (entry.isDirectory()) {
+          await this._discoverFiles(fullPath, files);
+        } else if (entry.isFile()) {
+          const ext = path.extname(entry.name).toLowerCase();
+          if (this.config.extensions.includes(ext)) {
+            files.push(fullPath);
+          }
+        }
+      }
+    } catch (error) {
+      // Skip inaccessible directories
+    }
+
+    return files;
+  }
+
+  _shouldIgnore(name) {
+    return this.config.ignorePatterns.some(pattern =>
+      name === pattern || name.startsWith(pattern)
+    );
+  }
+
+  async _analyzeFile(filePath) {
+    try {
+      const content = fs.readFileSync(filePath, 'utf8');
+      const imports = this._extractImports(content, filePath);
+
+      this.graph.set(filePath, {
+        imports,
+        importedBy: [] // Will be filled in second pass
+      });
+
+      this.stats.filesAnalyzed++;
+      this.stats.totalImports += imports.length;
+      this.stats.unresolvedImports += imports.filter(i => !i.resolved).length;
+
+    } catch (error) {
+      // Skip files that can't be read
+    }
+  }
+
+  _extractImports(content, filePath) {
+    const imports = [];
+    const fileDir = path.dirname(filePath);
+
+    // CommonJS: require('module') or require("module")
+    const requireRegex = /(?:const|let|var)\s+(?:\{([^}]+)\}|(\w+))\s*=\s*require\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+    let match;
+
+    while ((match = requireRegex.exec(content)) !== null) {
+      const specifiers = match[1]
+        ? match[1].split(',').map(s => s.trim().split(':')[0].trim()).filter(Boolean)
+        : [match[2]];
+      const modulePath = match[3];
+
+      imports.push({
+        module: modulePath,
+        specifiers,
+        resolved: this._resolveModule(modulePath, fileDir),
+        type: 'require'
+      });
+    }
+
+    // Also catch: require('module') without assignment
+    const bareRequireRegex = /require\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+    while ((match = bareRequireRegex.exec(content)) !== null) {
+      const modulePath = match[1];
+      // Skip if already captured
+      if (!imports.some(i => i.module === modulePath)) {
+        imports.push({
+          module: modulePath,
+          specifiers: [],
+          resolved: this._resolveModule(modulePath, fileDir),
+          type: 'require'
+        });
+      }
+    }
+
+    // ES6: import ... from 'module'
+    const importRegex = /import\s+(?:(?:\{([^}]+)\}|(\w+)|\*\s+as\s+(\w+))(?:\s*,\s*)?)+\s+from\s+['"]([^'"]+)['"]/g;
+    while ((match = importRegex.exec(content)) !== null) {
+      const specifiers = [];
+      if (match[1]) specifiers.push(...match[1].split(',').map(s => s.trim().split(' as ')[0].trim()).filter(Boolean));
+      if (match[2]) specifiers.push(match[2]);
+      if (match[3]) specifiers.push(match[3]);
+      const modulePath = match[4];
+
+      imports.push({
+        module: modulePath,
+        specifiers,
+        resolved: this._resolveModule(modulePath, fileDir),
+        type: 'import'
+      });
+    }
+
+    return imports;
+  }
+
+  _resolveModule(modulePath, fromDir) {
+    // Check cache
+    const cacheKey = `${fromDir}:${modulePath}`;
+    if (this.resolveCache.has(cacheKey)) {
+      return this.resolveCache.get(cacheKey);
+    }
+
+    let resolved = null;
+
+    // Skip external modules (node_modules)
+    if (!modulePath.startsWith('.') && !modulePath.startsWith('/')) {
+      this.resolveCache.set(cacheKey, null);
+      return null;
+    }
+
+    // Try to resolve relative path
+    const basePath = path.resolve(fromDir, modulePath);
+    const extensions = ['', '.js', '.ts', '.jsx', '.tsx', '/index.js', '/index.ts'];
+
+    for (const ext of extensions) {
+      const tryPath = basePath + ext;
+      if (fs.existsSync(tryPath) && fs.statSync(tryPath).isFile()) {
+        resolved = tryPath;
+        break;
+      }
+    }
+
+    this.resolveCache.set(cacheKey, resolved);
+    return resolved;
+  }
+
+  _buildReverseDependencies() {
+    for (const [filePath, node] of this.graph) {
+      for (const imp of node.imports) {
+        if (imp.resolved && this.graph.has(imp.resolved)) {
+          const targetNode = this.graph.get(imp.resolved);
+          if (!targetNode.importedBy.includes(filePath)) {
+            targetNode.importedBy.push(filePath);
+          }
+        }
+      }
+    }
+  }
+
+  _detectCircularDependencies() {
+    const visited = new Set();
+    const recursionStack = new Set();
+
+    const dfs = (filePath, chain = []) => {
+      if (recursionStack.has(filePath)) {
+        // Found circular dependency
+        const cycleStart = chain.indexOf(filePath);
+        const cycle = chain.slice(cycleStart).map(p =>
+          path.relative(this.config.rootPath, p)
+        );
+        cycle.push(path.relative(this.config.rootPath, filePath));
+
+        // Only add if not already recorded
+        const cycleKey = cycle.sort().join(' -> ');
+        if (!this.stats.circularDependencies.some(c => c.sort().join(' -> ') === cycleKey)) {
+          this.stats.circularDependencies.push(cycle);
+        }
+        return;
+      }
+
+      if (visited.has(filePath)) return;
+
+      visited.add(filePath);
+      recursionStack.add(filePath);
+
+      const node = this.graph.get(filePath);
+      if (node) {
+        for (const imp of node.imports) {
+          if (imp.resolved) {
+            dfs(imp.resolved, [...chain, filePath]);
+          }
+        }
+      }
+
+      recursionStack.delete(filePath);
+    };
+
+    for (const filePath of this.graph.keys()) {
+      dfs(filePath);
+    }
+  }
+
+  _normalizePath(filePath) {
+    if (path.isAbsolute(filePath)) {
+      return filePath;
+    }
+    return path.resolve(this.config.rootPath, filePath);
+  }
+}
+
+module.exports = DependencyGraph;