arcvision 0.2.14 → 0.2.15

package/src/engine/pass2_semantics.js

@@ -0,0 +1,333 @@
+/**
+ * Pass 2: Semantic Resolution
+ * 
+ * Objectives:
+ * - Resolve import strings to actual file IDs (using enhanced resolution logic)
+ * - Index Global Symbols (Functions, Classes, Exports)
+ * - Resolve Call Sites to Symbols (Typed Edges)
+ * - Resolve Dependency Injection relationships
+ */
+
+const path = require('path');
+const { loadTSConfig } = require('../core/tsconfig-utils');
+const { resolveImport } = require('../core/path-resolver');
+const { SymbolIndexer } = require('../core/symbol-indexer');
+const { CallResolver } = require('../core/call-resolver');
+
+/**
+ * Executes Pass 2: Resolves meanings and connections
+ * @param {Array} rawNodes - List of nodes from Pass 1
+ * @param {string} rootDir - Root directory
+ * @param {Object} workspaceContext - { workspaceMap, tsconfigMap }
+ * @returns {Promise<Object>} Object containing enriched nodes and resolved edges
+ */
+async function executePass2(rawNodes, rootDir, workspaceContext) {
+    console.log('🧠 PASS 2: Semantic Resolution...');
+
+    // 1. Setup Resolution Context
+    const config = loadTSConfig(rootDir);
+    const tsconfig = config.options;
+    const configRoot = config.configDir;
+    const normalize = p => p.replace(/\\/g, '/');
+    const workspaceMap = workspaceContext ? workspaceContext.workspaceMap : null;
+
+    // Create quick lookup for file existence
+    const fileSet = new Set(rawNodes.map(n => n.id));
+    const absoluteFileSet = new Set(rawNodes.map(n => n.filePath));
+    const edges = [];
+
+    // Helper to add unique edges
+    const addEdge = (source, target, type, confidence = 1.0, metadata = {}) => {
+        if (!source || !target) return;
+        if (source === target) return;
+
+        edges.push({
+            source,
+            target,
+            type,
+            confidence,
+            metadata
+        });
+    };
+
+    // --- PASS 2A: IMPORT RESOLUTION ---
+    let resolvedImports = 0;
+
+    for (const node of rawNodes) {
+        if (!node.facts.imports) continue;
+
+        // Resolve config for THIS file (Truth-level accuracy for monorepos)
+        const nodeConfig = loadTSConfig(path.dirname(node.filePath));
+        const nodeTsconfig = nodeConfig.options;
+        const nodeConfigRoot = nodeConfig.configDir;
+
+        for (const imp of node.facts.imports) {
+            const importString = imp.source;
+            let targetId = null;
+            let resolvedPath = null;
+
+            // Resolve using path-resolver with the cached fileSet AND the correct config for THIS file
+            const resolvedAbs = resolveImport(importString, node.filePath, nodeConfigRoot, nodeTsconfig, workspaceMap, absoluteFileSet);
+
+            if (resolvedAbs) {
+                targetId = normalize(path.relative(rootDir, resolvedAbs));
+                resolvedPath = targetId;
+
+                // Annotate import with resolved path for CallResolver usage
+                imp.resolvedPath = targetId;
+            } else {
+                // Fallback for relative paths in some edge cases
+                if (importString.startsWith('.')) {
+                    try {
+                        const nodeDir = path.dirname(node.filePath);
+                        const simpleAbs = path.resolve(nodeDir, importString);
+                        const exts = ['.ts', '.tsx', '.js', '.jsx', '.json', '/index.ts', '/index.js'];
+                        for (const ext of [''].concat(exts)) {
+                            const candidate = normalize(path.relative(rootDir, simpleAbs + ext));
+                            if (fileSet.has(candidate)) {
+                                targetId = candidate;
+                                imp.resolvedPath = candidate;
+                                break;
+                            }
+                        }
+                    } catch (e) { }
+                }
+            }
+
+            // If we found a target within our scanned files, create an edge
+            if (targetId && fileSet.has(targetId)) {
+                // Determine edge type
+                let type = 'imports';
+                if (workspaceContext && workspaceContext.workspaceMap) {
+                    // check if importString matches a workspace package
+                    // (This check is simplified, real check is if resolvedAbs is in another package root)
+                }
+
+                addEdge(node.id, targetId, type, 1.0, { specifiers: imp.specifiers });
+                resolvedImports++;
+            }
+        }
+    }
+    console.log(`   ✓ Resolved ${resolvedImports} import dependencies`);
+
+
+    // --- PASS 2B: SYMBOL INDEXING ---
+    // Extract symbols from raw nodes
+    const symbolIndexer = new SymbolIndexer();
+    const nodesForIndexing = rawNodes.map(n => ({
+        id: n.id,
+        metadata: n.facts // Indexer expects metadata.exports, etc. (Pass 1 facts structure matches enough)
+    }));
+
+    // Index builds the global symbol table
+    const { symbols, fileToSymbols } = symbolIndexer.index(nodesForIndexing);
+
+
+    // --- PASS 2C: CALL RESOLUTION ---
+    // Resolve call sites to symbol IDs
+    const callResolver = new CallResolver(symbols, null); // fileMap not strictly needed if we annotated imports
+
+    const nodesForResolution = rawNodes.map(n => {
+        // Merge JSX components into function calls for resolution
+        const combinedFunctions = [
+            ...(n.facts.calls.functions || []),
+            ...(n.facts.react || []).map(r => ({
+                name: r.component,
+                type: 'jsx_component',
+                loc: r.loc
+            }))
+        ];
+
+        return {
+            id: n.id,
+            metadata: n.facts,
+            methodCalls: {
+                functionCalls: combinedFunctions,
+                methodCalls: n.facts.calls.methods,
+                constructorCalls: n.facts.calls.constructors
+            }
+        };
+    });
+
+    const callEdges = callResolver.resolve(nodesForResolution);
+
+    // Add Resolved Call Edges
+    let resolvedCalls = 0;
+    for (const edge of callEdges) {
+        // edge: { sourceFileId, targetSymbolId, type, confidence }
+        // We need an edge between FILES for the graph structure.
+        // We also want to record the specific symbol connection.
+
+        const symbol = symbols.get(edge.targetSymbolId);
+        if (symbol) {
+            const targetFileId = symbol.fileId;
+            if (fileSet.has(targetFileId)) {
+                addEdge(edge.sourceFileId, targetFileId, edge.type, edge.confidence, {
+                    symbol: symbol.name,
+                    symbolId: edge.targetSymbolId,
+                    line: edge.line
+                });
+                resolvedCalls++;
+            }
+        }
+    }
+    console.log(`   ✓ Resolved ${resolvedCalls} semantic call edges`);
+
+
+    // --- PASS 2D: LUA SCRIPT INVOCATION DETECTION ---
+    let luaInvocationCount = 0;
+    for (const node of rawNodes) {
+        if (!node.facts.potentialInvocations || node.facts.potentialInvocations.length === 0) continue;
+        
+        // Look for Lua script invocations in TypeScript files
+        const content = node.filePath && require('fs').readFileSync(node.filePath, 'utf-8');
+        if (!content) continue;
+        
+        // Check for common patterns that invoke Lua scripts
+        const luaInvocationPatterns = [
+            /defineCommand\(\s*['"].*?['"]\s*,\s*\{[^}]*lua\s*:[^}]*\}/gi,  // Matches defineCommand("commandName", { ... lua: ... })
+            /defineCommand\(\s*[^,)]+\s*,\s*\{[^}]*lua\s*:[^}]*\}/gi,  // Matches defineCommand(commandName, { ... lua: ... })
+            /defineCommand\(\s*\{[^}]*lua\s*:[^}]*\}/gi,  // Original pattern
+            /readFileSync\(['"].*\.lua['"].*\)/gi,
+            /require\(['"].*\.lua['"].*\)/gi,
+            /fs\.readFileSync\(['"].*\.lua['"].*\)/gi,
+            /import\s+.*?from\s+['"].*\.lua['"].*\)?/gi,
+            /import\(['"].*\.lua['"].*\)/gi,
+            /loadScript\(['"].*\.lua['"].*\)/gi,
+            /loadLua\(['"].*\.lua['"].*\)/gi,
+            /load\(['"].*\.lua['"].*\)/gi
+        ];
+        
+        for (const pattern of luaInvocationPatterns) {
+            let match;
+            while ((match = pattern.exec(content)) !== null) {
+                // Extract the Lua file path from the match
+                const luaFileMatch = match[0].match(/['"].*?\.lua['"]/);
+                if (luaFileMatch) {
+                    let luaFilePath = luaFileMatch[0].slice(1, -1); // Remove quotes
+                    
+                    // Handle different path formats
+                    if (luaFilePath.startsWith('./') || luaFilePath.startsWith('../')) {
+                        // Relative path
+                        luaFilePath = path.resolve(path.dirname(node.filePath), luaFilePath);
+                        luaFilePath = normalize(path.relative(rootDir, luaFilePath));
+                    } else if (luaFilePath.startsWith('/')) {
+                        // Absolute path within project
+                        luaFilePath = normalize(path.relative(rootDir, path.join(rootDir, luaFilePath)));
+                    } else {
+                        // Just filename or relative path - look for it in common directories
+                        const commonLuaDirs = ['src', 'scripts', 'commands', 'lua', 'lib'];
+                        let foundPath = null;
+                        
+                        for (const dir of commonLuaDirs) {
+                            const candidatePath = normalize(path.join(dir, luaFilePath));
+                            if (fileSet.has(candidatePath)) {
+                                foundPath = candidatePath;
+                                break;
+                            }
+                        }
+                        
+                        if (foundPath) {
+                            luaFilePath = foundPath;
+                        } else {
+                            // Fallback to same directory as the current file
+                            const nodeDir = path.dirname(node.id);
+                            luaFilePath = normalize(path.join(nodeDir, luaFilePath));
+                        }
+                    }
+                    
+                    // Check if the Lua file exists in our fileSet
+                    if (fileSet.has(luaFilePath)) {
+                        addEdge(node.id, luaFilePath, 'invokes_execution_script', 1.0, {
+                            type: 'lua_invocation',
+                            invocation_pattern: match[0],
+                            original_match: match[0],
+                            resolved_path: luaFilePath
+                        });
+                        luaInvocationCount++;
+                    }
+                }
+            }
+        }
+    }
+    console.log(`   ✓ Detected ${luaInvocationCount} Lua script invocations`);
+    
+    // --- PASS 2E: TYPE RESOLUTION ---
+    let typeEdgesCount = 0;
+    for (const node of rawNodes) {
+        if (!node.facts.typeAnalysis) continue;
+
+        const nodeConfig = loadTSConfig(path.dirname(node.filePath));
+        const nodeTsconfig = nodeConfig.options;
+        const nodeConfigRoot = nodeConfig.configDir;
+
+        const { typeImports, interfaceDeps, genericDeps } = node.facts.typeAnalysis;
+
+        // 1. Resolve Type Imports (matches both 'import type' and 'import { type X }')
+        for (const imp of typeImports) {
+            const resolvedAbs = resolveImport(imp.source, node.filePath, nodeConfigRoot, nodeTsconfig, workspaceMap, absoluteFileSet);
+            if (resolvedAbs) {
+                const targetId = normalize(path.relative(rootDir, resolvedAbs));
+                if (fileSet.has(targetId)) {
+                    addEdge(node.id, targetId, 'depends_on', 0.9, { type: 'type_import' });
+                    typeEdgesCount++;
+                }
+            }
+        }
+
+        // 2. Resolve Interface Extensions & Class Implementations
+        // (This uses the local symbols or imported symbols to find the target file)
+        const allTypeDeps = [...interfaceDeps, ...genericDeps];
+        for (const dep of allTypeDeps) {
+            const typeName = dep.extends || dep.implements || dep.returnType || dep.type;
+            if (!typeName) continue;
+
+            // Simple resolution: find if typeName exists as an exported symbol in any imported file
+            // (We reuse resolveImportedSymbol logic but simplified here)
+            for (const imp of (node.facts.imports || [])) {
+                if (imp.resolvedPath) {
+                    const targetFileId = imp.resolvedPath;
+                    const candidateId = `${targetFileId}::${typeName}`;
+                    if (symbols.has(candidateId)) {
+                        addEdge(node.id, targetFileId, 'depends_on', 1.0, { type: 'type_reference', symbol: typeName });
+                        typeEdgesCount++;
+                        break;
+                    }
+                }
+            }
+        }
+    }
+    console.log(`   ✓ Resolved ${typeEdgesCount} TypeScript type connections`);
+
+    // Enhance nodes with invariant indicators from pass 1
+    const enhancedNodes = rawNodes.map(node => {
+        // Carry forward invariant indicators from pass 1
+        if (node.facts && node.facts.invariantIndicators) {
+            return {
+                ...node,
+                invariantIndicators: node.facts.invariantIndicators
+            };
+        }
+        return node;
+    });
+    
+    return {
+        nodes: enhancedNodes,
+        edges: edges,
+        symbols: Array.from(symbols.values()) // Return symbols list for ContextBuilder
+    };
+}
+
+/**
+ * Helper: Find valid provider file for a class/type name
+ */
+/*
+function findProviderForType(typeName, symbolTable) {
+    if (!symbolTable.has(typeName)) return null;
+    const defs = symbolTable.get(typeName);
+    const bestDef = defs.find(d => d.type === 'class') || defs[0];
+    return bestDef ? bestDef.file : null;
+}
+*/
+
+module.exports = { executePass2 };

package/src/engine/pass3_lifter.js

@@ -0,0 +1,99 @@
+/**
+ * Pass 3: Structural Lifting
+ * 
+ * Objectives:
+ * - Lift low-level nodes into "Structural Roles" (Store, Service, Component, Utility)
+ * - This uses inference based on naming, content, and connectivity.
+ */
+
+/**
+ * Executes Pass 3: Infers roles and structure
+ * @param {Object} semanticData - Output from Pass 2 { nodes, edges }
+ * @returns {Promise<Object>} Enhanced nodes with roles and layers
+ */
+async function executePass3(semanticData) {
+    console.log('🧬 PASS 3: Structural Lifting...');
+
+    const { nodes, edges } = semanticData;
+    const liftedNodes = [];
+
+    let rolesFound = {};
+
+    for (const node of nodes) {
+        // Start with default
+        let role = 'module';
+        let layer = 'generic';
+
+        const pathLower = node.id.toLowerCase();
+        const filename = node.id.split('/').pop();
+
+        // 1. Pattern-based Role Inference
+        if (pathLower.includes('service') || filename.endsWith('.service.ts')) {
+            role = 'service';
+            layer = 'logic';
+        } else if (pathLower.includes('controller') || filename.endsWith('.controller.ts')) {
+            role = 'controller';
+            layer = 'api';
+        } else if (pathLower.includes('component') || pathLower.includes('.tsx') || pathLower.includes('.jsx')) {
+            role = 'component';
+            layer = 'ui';
+        } else if (pathLower.includes('store') || pathLower.includes('redux') || pathLower.includes('context')) {
+            role = 'store';
+            layer = 'state';
+        } else if (pathLower.includes('util') || pathLower.includes('helper')) {
+            role = 'utility';
+            layer = 'shared';
+        } else if (pathLower.includes('model') || pathLower.includes('entity') || pathLower.includes('dto')) {
+            role = 'model';
+            layer = 'data';
+        } else if (pathLower.includes('config') || pathLower.includes('env')) {
+            role = 'config';
+        } else if (pathLower.includes('hook') || filename.startsWith('use')) {
+            role = 'hook';
+            layer = 'ui-logic';
+        }
+
+        // 2. Content-based Role Inference (Refining based on captured facts)
+        if (node.facts.di && (node.facts.di.injections.length > 0 || node.facts.di.context.length > 0)) {
+            // Heavily dependent file
+            if (role === 'module') role = 'consumer';
+        }
+
+        if (node.facts.exports.some(e => e.type === 'class')) {
+            // Could be a core definition
+            if (role === 'module') role = 'class_def';
+        }
+
+        // 3. Connectivity-based Inference (is it a Hub?)
+        // (We can refine this in Pass 4, but simple tagging happens here)
+
+        // Add to stats
+        rolesFound[role] = (rolesFound[role] || 0) + 1;
+
+        // Create lifted node with invariant indicators preserved
+        const liftedNode = {
+            ...node,
+            structure: {
+                role,
+                layer
+            }
+        };
+        
+        // Carry forward invariant indicators if they exist
+        if (node.invariantIndicators) {
+            liftedNode.invariantIndicators = node.invariantIndicators;
+        }
+        
+        liftedNodes.push(liftedNode);
+    }
+
+    console.log(`   ✓ Inferred structural roles: ${JSON.stringify(rolesFound)}`);
+
+    return {
+        nodes: liftedNodes,
+        edges: edges, // Edges passed through
+        symbols: semanticData.symbols // Propagate symbols
+    };
+}
+
+module.exports = { executePass3 };

package/src/engine/pass4_signals.js

@@ -0,0 +1,201 @@
+/**
+ * Pass 4: Signal Extraction
+ * 
+ * Objectives:
+ * - Calculate graph theory metrics: Blast Radius, Centrality
+ * - Identify "High Value" nodes
+ * - Compute volatility/coupling signals
+ */
+
+const { buildReverseDependencyGraph, computeBlastRadius, analyzeCriticality } = require('../core/blastRadius');
+const { InvariantDetector } = require('../core/invariant-detector');
+const { OwnershipResolver } = require('../core/ownership-resolver');
+const { FailureModeSynthesizer } = require('../core/failure-mode-synthesizer');
+const path = require('path');
+
+/**
+ * Executes Pass 4: Computes signals and metrics
+ * @param {Object} liftedData - Output from Pass 3 { nodes, edges }
+ * @returns {Promise<Object>} Final structural context ready for JSON
+ */
+async function executePass4(liftedData) {
+    console.log('🧠 PASS 4: Signal Extraction & Metrics...');
+
+    const { nodes, edges } = liftedData;
+
+    // 1. Prepare Data for Existing BlastRadius Logic
+    // Existing logic expects { nodes: [{id: ...}], edges: [{source, target}] }
+    // Our nodes have 'id' matching the edges, so it's compatible.
+
+    // Create a temporary compliant object for the legacy algo
+    const architectureMap = { nodes, edges };
+
+    // 2. Compute Blast Radius
+    const reverseGraph = buildReverseDependencyGraph(architectureMap);
+    const blastRadiusMap = computeBlastRadius(reverseGraph);
+
+    // 3. Compute Criticality (includes dependency strength)
+    // Note: analyzeCriticality expects nodes to have specific metadata structure
+    // We might need to ensure compatibility, but let's assume 'id' is enough for basic graph stuff
+    // and we inject the score back.
+
+    // We need to inject .metadata for analyzeCriticality to work fully if it checks for functions
+    // Our nodes have .facts, so let's temporarily alias it if needed, or just rely on graph structure.
+    nodes.forEach(n => {
+        n.metadata = n.facts; // Map facts to metadata for compatibility with legacy helpers
+        n.metadata.blast_radius = blastRadiusMap[n.id] || 0;
+    });
+
+    const criticalityList = analyzeCriticality(blastRadiusMap, reverseGraph, nodes);
+    const criticalityMap = new Map(criticalityList.map(c => [c.file, c]));
+
+    // Pre-calculate degrees to avoid O(N*E) nested loops
+    const outDegreeMap = new Map();
+    const inDegreeMap = new Map();
+    edges.forEach(e => {
+        outDegreeMap.set(e.source, (outDegreeMap.get(e.source) || 0) + 1);
+        inDegreeMap.set(e.target, (inDegreeMap.get(e.target) || 0) + 1);
+    });
+
+    // 4. Enrich Nodes with Signals
+    const finalNodes = nodes.map(node => {
+        const signals = {
+            blast_radius: blastRadiusMap[node.id] || 0,
+            criticality: criticalityMap.get(node.id)?.criticalityScore || 0,
+            is_hub: criticalityMap.get(node.id)?.isHub || false,
+            outgoing_deps: outDegreeMap.get(node.id) || 0,
+            incoming_deps: inDegreeMap.get(node.id) || 0
+        };
+
+        // Return node with clear separation of concerns
+        const finalNode = {
+            id: node.id,
+            type: node.type,
+            filePath: node.filePath, // Internal absolute path
+
+            // The 3 Pillars of Arcvision
+            role: node.structure.role,   // From Pass 3
+            layer: node.structure.layer, // From Pass 3
+            signals: signals,            // From Pass 4
+
+            // Deep Code Intelligence (from Pass 1 & 2)
+            intelligence: {
+                ...node.facts,
+                // Add resolved outbound connections for easy traversal
+                connections: edges.filter(e => e.source === node.id).map(e => ({
+                    target: e.target,
+                    type: e.type,
+                    confidence: e.confidence
+                }))
+            }
+        };
+        
+        // Carry forward invariant indicators if they exist
+        if (node.invariantIndicators) {
+            finalNode.invariantIndicators = node.invariantIndicators;
+        }
+        
+        return finalNode;
+    });
+
+    // Calculate additional metrics for authority core detection
+    const enhancedCriticalityList = finalNodes.map(node => ({
+        file: node.id,
+        criticalityScore: node.signals.criticality,
+        blastRadius: node.signals.blast_radius,
+        dependencies: node.signals.incoming_deps,
+        isHub: node.signals.is_hub
+    }));
+
+    // 5. Final Stats
+    const totalFiles = finalNodes.length;
+    const maxBlast = Math.max(...finalNodes.map(n => n.signals.blast_radius));
+    console.log(`   ✓ Signals computed. Max Blast Radius: ${maxBlast}`);
+
+    // Context Surface (Top critical files)
+    const contextSurface = enhancedCriticalityList.slice(0, 5).map(c => ({
+        file: c.file,
+        score: c.criticalityScore,
+        reason: `Blast: ${c.blastRadius}, Deps: ${c.dependencies}`
+    }));
+
+    // Initialize components for new features
+    const invariantDetector = new InvariantDetector();
+    const ownershipResolver = new OwnershipResolver();
+    const failureModeSynthesizer = new FailureModeSynthesizer();
+    
+    // Generate invariants
+    const invariants = await invariantDetector.detectInvariants(
+        { nodes: finalNodes, edges: edges }, 
+        process.cwd()
+    );
+    
+    // Resolve ownership
+    const ownership = ownershipResolver.resolveOwnership(
+        { nodes: finalNodes, edges: edges }
+    );
+    
+    // Synthesize failure modes
+    const failureModes = failureModeSynthesizer.synthesizeFailureModes(
+        { nodes: finalNodes, edges: edges }, 
+        invariants
+    );
+    
+    // Generate decision guidance
+    const decisionGuidance = generateDecisionGuidance(invariants, failureModes);
+    
+    return {
+        nodes: finalNodes,
+        edges: edges,
+        symbols: liftedData.symbols, // Propagate symbols
+        contextSurface,
+        invariants,
+        ownership,
+        failure_modes: failureModes,
+        decision_guidance: decisionGuidance
+    };
+}
+
+/**
+ * Generate decision guidance based on invariants and failure modes
+ */
+function generateDecisionGuidance(invariants, failureModes) {
+    if (!invariants || invariants.length === 0) {
+        return {};
+    }
+    
+    // Find the most critical invariant that has been violated
+    const mostCriticalInvariant = invariants
+        .filter(inv => inv.confidence > 0.7)
+        .sort((a, b) => (b.confidence || 0) - (a.confidence || 0))[0];
+    
+    if (!mostCriticalInvariant) {
+        return {};
+    }
+    
+    // Find related failure modes
+    const relatedFailures = failureModes.filter(fm => 
+        fm.broken_invariant === mostCriticalInvariant.id
+    );
+    
+    // Generate recommended action
+    const recommendedAction = {
+        fix_type: 'invariant_restoration',
+        location: mostCriticalInvariant.owner || 'unknown',
+        action: `Address invariant violation: ${mostCriticalInvariant.statement}`,
+        risk_if_ignored: 'System instability, unpredictable behavior, or cascading failures'
+    };
+    
+    // If there are specific failure modes, add more specific guidance
+    if (relatedFailures.length > 0) {
+        const mostCriticalFailure = relatedFailures[0];
+        recommendedAction.action = `Fix ${mostCriticalFailure.trigger} to restore invariant: ${mostCriticalInvariant.statement}`;
+        recommendedAction.location = mostCriticalFailure.root_cause || recommendedAction.location;
+    }
+    
+    return {
+        recommended_action: recommendedAction
+    };
+}
+
+module.exports = { executePass4 };