thuban 0.3.2 → 0.3.3

package/packages/scanner/sentinel-knowledge.js

@@ -1,322 +1,322 @@
-/**
- * Sentinel Knowledge Interface
- *
- * Provides a unified API for other Orion systems to query codebase knowledge.
- * Used by: Astra (voice queries), CITADEL (enforcement), Forge (auto-widgets)
- *
- * @purpose Unified codebase knowledge API for Orion systems
- * @module sentinel
- * @layer infrastructure
- * @imports-from sentinel/dependency-graph.js, sentinel/widget-generator.js, sentinel/code-scanner.js
- * @exports-to astra-service, citadel/enforcer, forge, server
- * @side-effects File system reads
- * @critical-for System-wide codebase awareness
- */
-
-const path = require('path');
-const fs = require('fs');
-const DependencyGraph = require('./dependency-graph');
-const WidgetGenerator = require('./widget-generator');
-const CodeScanner = require('./code-scanner');
-
-// Singleton instances
-let dependencyGraph = null;
-let widgetGenerator = null;
-let codeScanner = null;
-let initialized = false;
-let rootPath = null;
-
-/**
- * Initialize Sentinel Knowledge (call once at startup)
- */
-async function initialize(config = {}) {
-  rootPath = config.rootPath || process.cwd();
-
-  console.log('[SENTINEL-KNOWLEDGE] Initializing codebase knowledge...');
-
-  // Initialize dependency graph
-  dependencyGraph = new DependencyGraph({ rootPath });
-  await dependencyGraph.build();
-
-  // Initialize widget generator (with graph)
-  widgetGenerator = new WidgetGenerator({
-    rootPath,
-    dependencyGraph,
-    dryRun: true  // Default to dry run
-  });
-
-  // Initialize code scanner
-  codeScanner = new CodeScanner({ rootPath });
-
-  initialized = true;
-  console.log('[SENTINEL-KNOWLEDGE] Codebase knowledge ready');
-
-  return getStats();
-}
-
-/**
- * Ensure initialized
- */
-async function ensureInitialized() {
-  if (!initialized) {
-    await initialize();
-  }
-}
-
-// ============================================================
-// QUERY FUNCTIONS (for Astra and other systems)
-// ============================================================
-
-/**
- * Get impact analysis for a file
- * "What will break if I change this file?"
- */
-async function getImpact(filePath) {
-  await ensureInitialized();
-
-  const fullPath = path.isAbsolute(filePath)
-    ? filePath
-    : path.join(rootPath, filePath);
-
-  return dependencyGraph.getImpactAnalysis(fullPath);
-}
-
-/**
- * Get what a file depends on
- */
-async function getDependencies(filePath) {
-  await ensureInitialized();
-
-  const fullPath = path.isAbsolute(filePath)
-    ? filePath
-    : path.join(rootPath, filePath);
-
-  const deps = dependencyGraph.getDependencies(fullPath);
-  return deps.map(d => ({
-    module: d.module,
-    resolved: d.resolved ? path.relative(rootPath, d.resolved) : null
-  }));
-}
-
-/**
- * Get what depends on a file
- */
-async function getDependents(filePath) {
-  await ensureInitialized();
-
-  const fullPath = path.isAbsolute(filePath)
-    ? filePath
-    : path.join(rootPath, filePath);
-
-  const deps = dependencyGraph.getDependents(fullPath);
-  return deps.map(d => path.relative(rootPath, d));
-}
-
-/**
- * Get most critical files in the codebase
- */
-async function getCriticalFiles(limit = 10) {
-  await ensureInitialized();
-  return dependencyGraph.getMostCriticalFiles(limit);
-}
-
-/**
- * Get module summary
- */
-async function getModules() {
-  await ensureInitialized();
-  return dependencyGraph.getModuleSummary();
-}
-
-/**
- * Get orphan files (potential dead code)
- */
-async function getOrphans() {
-  await ensureInitialized();
-  return dependencyGraph.getOrphanFiles();
-}
-
-/**
- * Get overall codebase stats
- */
-async function getStats() {
-  await ensureInitialized();
-  return {
-    ...dependencyGraph.getStats(),
-    initialized,
-    rootPath
-  };
-}
-
-/**
- * Natural language query handler (for Astra)
- */
-async function query(question) {
-  await ensureInitialized();
-
-  const q = question.toLowerCase();
-
-  // Impact queries
-  if (q.includes('break') || q.includes('impact') || q.includes('affect')) {
-    const fileMatch = question.match(/['"]?([a-zA-Z0-9\-_./\\]+\.js)['"]?/);
-    if (fileMatch) {
-      const impact = await getImpact(fileMatch[1]);
-      return {
-        type: 'impact',
-        file: fileMatch[1],
-        result: impact,
-        summary: `Changing ${fileMatch[1]} could affect ${impact.totalImpact} files. Risk level: ${impact.riskLevel.toUpperCase()}.`
-      };
-    }
-  }
-
-  // Dependency queries
-  if (q.includes('depend') || q.includes('import') || q.includes('use')) {
-    const fileMatch = question.match(/['"]?([a-zA-Z0-9\-_./\\]+\.js)['"]?/);
-    if (fileMatch) {
-      if (q.includes('on') || q.includes('import')) {
-        // What does X depend on?
-        const deps = await getDependencies(fileMatch[1]);
-        return {
-          type: 'dependencies',
-          file: fileMatch[1],
-          result: deps,
-          summary: `${fileMatch[1]} depends on ${deps.length} files: ${deps.slice(0, 5).map(d => d.module).join(', ')}${deps.length > 5 ? '...' : ''}`
-        };
-      } else {
-        // What depends on X?
-        const deps = await getDependents(fileMatch[1]);
-        return {
-          type: 'dependents',
-          file: fileMatch[1],
-          result: deps,
-          summary: `${deps.length} files depend on ${fileMatch[1]}: ${deps.slice(0, 5).join(', ')}${deps.length > 5 ? '...' : ''}`
-        };
-      }
-    }
-  }
-
-  // Critical files query
-  if (q.includes('critical') || q.includes('important') || q.includes('core')) {
-    const critical = await getCriticalFiles(10);
-    return {
-      type: 'critical',
-      result: critical,
-      summary: `Top critical files: ${critical.slice(0, 5).map(f => f.relativePath).join(', ')}`
-    };
-  }
-
-  // Module query
-  if (q.includes('module') || q.includes('system') || q.includes('component')) {
-    const modules = await getModules();
-    return {
-      type: 'modules',
-      result: modules,
-      summary: `Codebase has ${modules.length} modules. Largest: ${modules.slice(0, 3).map(m => `${m.name} (${m.fileCount} files)`).join(', ')}`
-    };
-  }
-
-  // Orphan/dead code query
-  if (q.includes('orphan') || q.includes('dead') || q.includes('unused')) {
-    const orphans = await getOrphans();
-    return {
-      type: 'orphans',
-      result: orphans,
-      summary: `Found ${orphans.length} potentially unused files: ${orphans.slice(0, 5).map(o => o.relativePath).join(', ')}${orphans.length > 5 ? '...' : ''}`
-    };
-  }
-
-  // Stats query
-  if (q.includes('stat') || q.includes('overview') || q.includes('summary')) {
-    const stats = await getStats();
-    return {
-      type: 'stats',
-      result: stats,
-      summary: `Codebase: ${stats.totalFiles} files, ${stats.totalImports} imports, ${stats.circularCount} circular dependencies`
-    };
-  }
-
-  // Default
-  return {
-    type: 'unknown',
-    result: null,
-    summary: 'I can answer questions about: file impact, dependencies, critical files, modules, orphan/dead code, and codebase stats.'
-  };
-}
-
-// ============================================================
-// WIDGET FUNCTIONS (for CITADEL and Forge)
-// ============================================================
-
-/**
- * Check if a file has a valid widget
- */
-function hasWidget(filePath) {
-  try {
-    const fullPath = path.isAbsolute(filePath)
-      ? filePath
-      : path.join(rootPath, filePath);
-
-    const content = fs.readFileSync(fullPath, 'utf8');
-    const widgetPattern = /\/\*\*[\s\S]*?@(purpose|module|layer)[\s\S]*?\*\//;
-    return widgetPattern.test(content);
-  } catch (e) {
-    return false;
-  }
-}
-
-/**
- * Generate widget for a file (returns string, doesn't write)
- */
-async function generateWidget(filePath, content = null) {
-  await ensureInitialized();
-
-  const fullPath = path.isAbsolute(filePath)
-    ? filePath
-    : path.join(rootPath, filePath);
-
-  const widget = await widgetGenerator.generateWidget(fullPath, content);
-  return widget.widgetString;
-}
-
-/**
- * Generate and prepend widget to content
- */
-async function addWidgetToContent(filePath, content) {
-  const widgetString = await generateWidget(filePath, content);
-  return widgetString + '\n\n' + content;
-}
-
-/**
- * Refresh the dependency graph (call after files change)
- */
-async function refresh() {
-  if (dependencyGraph) {
-    await dependencyGraph.build();
-  }
-}
-
-// ============================================================
-// EXPORT
-// ============================================================
-
-module.exports = {
-  // Initialization
-  initialize,
-  refresh,
-
-  // Query functions (for Astra)
-  query,
-  getImpact,
-  getDependencies,
-  getDependents,
-  getCriticalFiles,
-  getModules,
-  getOrphans,
-  getStats,
-
-  // Widget functions (for CITADEL/Forge)
-  hasWidget,
-  generateWidget,
-  addWidgetToContent
-};
+/**
+ * Sentinel Knowledge Interface
+ *
+ * Provides a unified API for other Orion systems to query codebase knowledge.
+ * Used by: Astra (voice queries), CITADEL (enforcement), Forge (auto-widgets)
+ *
+ * @purpose Unified codebase knowledge API for Orion systems
+ * @module sentinel
+ * @layer infrastructure
+ * @imports-from sentinel/dependency-graph.js, sentinel/widget-generator.js, sentinel/code-scanner.js
+ * @exports-to astra-service, citadel/enforcer, forge, server
+ * @side-effects File system reads
+ * @critical-for System-wide codebase awareness
+ */
+
+const path = require('path');
+const fs = require('fs');
+const DependencyGraph = require('./dependency-graph');
+const WidgetGenerator = require('./widget-generator');
+const CodeScanner = require('./code-scanner');
+
+// Singleton instances
+let dependencyGraph = null;
+let widgetGenerator = null;
+let codeScanner = null;
+let initialized = false;
+let rootPath = null;
+
+/**
+ * Initialize Sentinel Knowledge (call once at startup)
+ */
+async function initialize(config = {}) {
+  rootPath = config.rootPath || process.cwd();
+
+  console.log('[SENTINEL-KNOWLEDGE] Initializing codebase knowledge...');
+
+  // Initialize dependency graph
+  dependencyGraph = new DependencyGraph({ rootPath });
+  await dependencyGraph.build();
+
+  // Initialize widget generator (with graph)
+  widgetGenerator = new WidgetGenerator({
+    rootPath,
+    dependencyGraph,
+    dryRun: true  // Default to dry run
+  });
+
+  // Initialize code scanner
+  codeScanner = new CodeScanner({ rootPath });
+
+  initialized = true;
+  console.log('[SENTINEL-KNOWLEDGE] Codebase knowledge ready');
+
+  return getStats();
+}
+
+/**
+ * Ensure initialized
+ */
+async function ensureInitialized() {
+  if (!initialized) {
+    await initialize();
+  }
+}
+
+// ============================================================
+// QUERY FUNCTIONS (for Astra and other systems)
+// ============================================================
+
+/**
+ * Get impact analysis for a file
+ * "What will break if I change this file?"
+ */
+async function getImpact(filePath) {
+  await ensureInitialized();
+
+  const fullPath = path.isAbsolute(filePath)
+    ? filePath
+    : path.join(rootPath, filePath);
+
+  return dependencyGraph.getImpactAnalysis(fullPath);
+}
+
+/**
+ * Get what a file depends on
+ */
+async function getDependencies(filePath) {
+  await ensureInitialized();
+
+  const fullPath = path.isAbsolute(filePath)
+    ? filePath
+    : path.join(rootPath, filePath);
+
+  const deps = dependencyGraph.getDependencies(fullPath);
+  return deps.map(d => ({
+    module: d.module,
+    resolved: d.resolved ? path.relative(rootPath, d.resolved) : null
+  }));
+}
+
+/**
+ * Get what depends on a file
+ */
+async function getDependents(filePath) {
+  await ensureInitialized();
+
+  const fullPath = path.isAbsolute(filePath)
+    ? filePath
+    : path.join(rootPath, filePath);
+
+  const deps = dependencyGraph.getDependents(fullPath);
+  return deps.map(d => path.relative(rootPath, d));
+}
+
+/**
+ * Get most critical files in the codebase
+ */
+async function getCriticalFiles(limit = 10) {
+  await ensureInitialized();
+  return dependencyGraph.getMostCriticalFiles(limit);
+}
+
+/**
+ * Get module summary
+ */
+async function getModules() {
+  await ensureInitialized();
+  return dependencyGraph.getModuleSummary();
+}
+
+/**
+ * Get orphan files (potential dead code)
+ */
+async function getOrphans() {
+  await ensureInitialized();
+  return dependencyGraph.getOrphanFiles();
+}
+
+/**
+ * Get overall codebase stats
+ */
+async function getStats() {
+  await ensureInitialized();
+  return {
+    ...dependencyGraph.getStats(),
+    initialized,
+    rootPath
+  };
+}
+
+/**
+ * Natural language query handler (for Astra)
+ */
+async function query(question) {
+  await ensureInitialized();
+
+  const q = question.toLowerCase();
+
+  // Impact queries
+  if (q.includes('break') || q.includes('impact') || q.includes('affect')) {
+    const fileMatch = question.match(/['"]?([a-zA-Z0-9\-_./\\]+\.js)['"]?/);
+    if (fileMatch) {
+      const impact = await getImpact(fileMatch[1]);
+      return {
+        type: 'impact',
+        file: fileMatch[1],
+        result: impact,
+        summary: `Changing ${fileMatch[1]} could affect ${impact.totalImpact} files. Risk level: ${impact.riskLevel.toUpperCase()}.`
+      };
+    }
+  }
+
+  // Dependency queries
+  if (q.includes('depend') || q.includes('import') || q.includes('use')) {
+    const fileMatch = question.match(/['"]?([a-zA-Z0-9\-_./\\]+\.js)['"]?/);
+    if (fileMatch) {
+      if (q.includes('on') || q.includes('import')) {
+        // What does X depend on?
+        const deps = await getDependencies(fileMatch[1]);
+        return {
+          type: 'dependencies',
+          file: fileMatch[1],
+          result: deps,
+          summary: `${fileMatch[1]} depends on ${deps.length} files: ${deps.slice(0, 5).map(d => d.module).join(', ')}${deps.length > 5 ? '...' : ''}`
+        };
+      } else {
+        // What depends on X?
+        const deps = await getDependents(fileMatch[1]);
+        return {
+          type: 'dependents',
+          file: fileMatch[1],
+          result: deps,
+          summary: `${deps.length} files depend on ${fileMatch[1]}: ${deps.slice(0, 5).join(', ')}${deps.length > 5 ? '...' : ''}`
+        };
+      }
+    }
+  }
+
+  // Critical files query
+  if (q.includes('critical') || q.includes('important') || q.includes('core')) {
+    const critical = await getCriticalFiles(10);
+    return {
+      type: 'critical',
+      result: critical,
+      summary: `Top critical files: ${critical.slice(0, 5).map(f => f.relativePath).join(', ')}`
+    };
+  }
+
+  // Module query
+  if (q.includes('module') || q.includes('system') || q.includes('component')) {
+    const modules = await getModules();
+    return {
+      type: 'modules',
+      result: modules,
+      summary: `Codebase has ${modules.length} modules. Largest: ${modules.slice(0, 3).map(m => `${m.name} (${m.fileCount} files)`).join(', ')}`
+    };
+  }
+
+  // Orphan/dead code query
+  if (q.includes('orphan') || q.includes('dead') || q.includes('unused')) {
+    const orphans = await getOrphans();
+    return {
+      type: 'orphans',
+      result: orphans,
+      summary: `Found ${orphans.length} potentially unused files: ${orphans.slice(0, 5).map(o => o.relativePath).join(', ')}${orphans.length > 5 ? '...' : ''}`
+    };
+  }
+
+  // Stats query
+  if (q.includes('stat') || q.includes('overview') || q.includes('summary')) {
+    const stats = await getStats();
+    return {
+      type: 'stats',
+      result: stats,
+      summary: `Codebase: ${stats.totalFiles} files, ${stats.totalImports} imports, ${stats.circularCount} circular dependencies`
+    };
+  }
+
+  // Default
+  return {
+    type: 'unknown',
+    result: null,
+    summary: 'I can answer questions about: file impact, dependencies, critical files, modules, orphan/dead code, and codebase stats.'
+  };
+}
+
+// ============================================================
+// WIDGET FUNCTIONS (for CITADEL and Forge)
+// ============================================================
+
+/**
+ * Check if a file has a valid widget
+ */
+function hasWidget(filePath) {
+  try {
+    const fullPath = path.isAbsolute(filePath)
+      ? filePath
+      : path.join(rootPath, filePath);
+
+    const content = fs.readFileSync(fullPath, 'utf8');
+    const widgetPattern = /\/\*\*[\s\S]*?@(purpose|module|layer)[\s\S]*?\*\//;
+    return widgetPattern.test(content);
+  } catch (e) {
+    return false;
+  }
+}
+
+/**
+ * Generate widget for a file (returns string, doesn't write)
+ */
+async function generateWidget(filePath, content = null) {
+  await ensureInitialized();
+
+  const fullPath = path.isAbsolute(filePath)
+    ? filePath
+    : path.join(rootPath, filePath);
+
+  const widget = await widgetGenerator.generateWidget(fullPath, content);
+  return widget.widgetString;
+}
+
+/**
+ * Generate and prepend widget to content
+ */
+async function addWidgetToContent(filePath, content) {
+  const widgetString = await generateWidget(filePath, content);
+  return widgetString + '\n\n' + content;
+}
+
+/**
+ * Refresh the dependency graph (call after files change)
+ */
+async function refresh() {
+  if (dependencyGraph) {
+    await dependencyGraph.build();
+  }
+}
+
+// ============================================================
+// EXPORT
+// ============================================================
+
+module.exports = {
+  // Initialization
+  initialize,
+  refresh,
+
+  // Query functions (for Astra)
+  query,
+  getImpact,
+  getDependencies,
+  getDependents,
+  getCriticalFiles,
+  getModules,
+  getOrphans,
+  getStats,
+
+  // Widget functions (for CITADEL/Forge)
+  hasWidget,
+  generateWidget,
+  addWidgetToContent
+};