arcvision 0.2.14 → 0.2.15

package/src/core/scanner.js

@@ -0,0 +1,289 @@
+const path = require('path');
+const { loadTSConfig } = require('./tsconfig-utils');
+const { WorkspaceScanner } = require('./workspace-scanner');
+
+// Import new engine passes
+const { executePass1 } = require('../engine/pass1_facts');
+const { executePass2 } = require('../engine/pass2_semantics');
+const { executePass3 } = require('../engine/pass3_lifter');
+const { executePass4 } = require('../engine/pass4_signals');
+
+// Import authority core detection
+const { detectAuthorityCores, detectHiddenCoupling, detectArchitecturalArchetype } = require('./authority-core-detector');
+
+// Import structural context ownership
+const { generateAuthoritativeContext } = require('./structural-context-owner');
+
+// Import invariant detector
+const { InvariantDetector } = require('./invariant-detector');
+
+// Import invariant analyzer
+const { InvariantAnalyzer } = require('./invariant-analyzer');
+
+// Import git utilities
+const { spawnSync } = require('child_process');
+
+const { buildContext } = require('./context_builder');
+const { validateContext } = require('../engine/context_validator');
+const { sortContext } = require('../engine/context_sorter');
+
+/**
+ * Main Scanner Entry Point
+ * Orchestrates the 4-pass structural analysis
+ */
+async function scan(directory) {
+    console.log(`\n🚀 ARCVISION STRUCTURAL ENGINE (4-PASS)`);
+    console.log(`   Target: ${directory}\n`);
+
+    try {
+        const start = Date.now();
+
+        // --- PRE-SCAN: WORKSPACE DISCOVERY ---
+        // Establish global resolution context
+        const workspaceScanner = new WorkspaceScanner(directory);
+        const workspaceContext = workspaceScanner.scan();
+
+        // --- PASS 1: FACTS ---
+        // Extract raw syntactic facts from files
+        const rawNodes = await executePass1(directory);
+
+        // --- PASS 2: SEMANTICS ---
+        // Resolve dependencies, DI, and method calls
+        const semanticData = await executePass2(rawNodes, directory, workspaceContext);
+
+        // --- PASS 3: LIFTING ---
+        // Infer structural roles (Service, Store, etc.)
+        const liftedData = await executePass3(semanticData);
+
+        // --- PASS 4: SIGNALS ---
+        // Compute graph metrics (Blast Radius, etc.)
+        const structuralContext = await executePass4(liftedData);
+
+        const { nodes, edges, contextSurface, symbols, invariants, ownership, failure_modes, decision_guidance } = structuralContext;
+
+        console.log(`\n🔍 Analysis Complete (${Date.now() - start}ms)`);
+        console.log(`   Nodes: ${nodes.length}`);
+        console.log(`   Edges: ${edges.length}`);
+        console.log(`   Symbols: ${symbols ? symbols.length : 0}`);
+        
+        // Report parsing errors if any occurred
+        if (global.parserErrors && global.parserErrors.length > 0) {
+            const uniqueErrors = new Map();
+            global.parserErrors.forEach(err => {
+                const key = `${err.error}`;
+                if (!uniqueErrors.has(key)) {
+                    uniqueErrors.set(key, { count: 0, examples: [] });
+                }
+                const errorGroup = uniqueErrors.get(key);
+                errorGroup.count++;
+                if (errorGroup.examples.length < 3) {
+                    errorGroup.examples.push(`${err.file}:${err.line}:${err.column}`);
+                }
+            });
+            
+            console.log(`\n⚠️  Parsing Issues Detected (${global.parserErrors.length} files affected):`);
+            uniqueErrors.forEach((info, errorType) => {
+                console.log(`   ${info.count} files: ${errorType}`);
+                info.examples.forEach(example => {
+                    console.log(`     - ${example}`);
+                });
+                if (info.examples.length < info.count) {
+                    console.log(`     ... and ${info.count - info.examples.length} more`);
+                }
+            });
+            
+            // Clear errors for next run
+            delete global.parserErrors;
+        }
+
+        // --- AUTHORITATIVE STRUCTURAL CONTEXT GENERATION ---
+        
+        // Generate the canonical structural context that ArcVision owns
+        const authoritativeContext = generateAuthoritativeContext(structuralContext, {
+            projectName: path.basename(directory),
+            rootPath: path.resolve(directory),
+            commitHash: getGitCommitHash(directory),
+            timestamp: new Date().toISOString(),
+            version: process.env.npm_package_version || '0.1.0'
+        });
+        
+        // Extract specific insights from authoritative context
+        const authorityCores = authoritativeContext.structural_context.authority_cores;
+        const structuralHubs = authoritativeContext.structural_context.structural_hubs;
+        const couplingPatterns = authoritativeContext.structural_context.coupling_patterns;
+        const architecturalBoundaries = authoritativeContext.structural_context.architectural_boundaries;
+        const structuralInvariants = authoritativeContext.structural_context.structural_invariants;
+        
+        // Legacy format for backward compatibility
+        const hiddenCoupling = couplingPatterns;
+        const archetype = authoritativeContext.system_identity.architectural_archetype || {
+            type: 'general_purpose',
+            confidence: 'low',
+            description: 'General purpose application',
+            authorityPattern: 'distributed_authority'
+        };
+        const completenessMetrics = authoritativeContext.reliability_indicators.analysis_coverage;
+
+        // --- DETECT SYSTEM INVARIANTS ---
+        
+        // Detect invariants in the scanned repository
+        const invariantDetector = new InvariantDetector();
+        const detectedInvariants = await invariantDetector.detectInvariants(
+            { nodes, edges }, 
+            directory
+        );
+        
+        // Only analyze if we found invariants
+        let invariantAnalysis = null;
+        let architecturalHealth = null;
+        
+        if (detectedInvariants && detectedInvariants.length > 0) {
+            // Analyze the detected invariants
+            const invariantAnalyzer = new InvariantAnalyzer();
+            invariantAnalysis = invariantAnalyzer.analyzeInvariants(detectedInvariants, {
+                directory,
+                projectName: path.basename(directory),
+                nodeCount: nodes.length,
+                edgeCount: edges.length
+            });
+            
+            // Assess architectural health based on invariants
+            architecturalHealth = invariantAnalyzer.assessArchitecturalHealth(detectedInvariants, {
+                directory,
+                projectName: path.basename(directory)
+            });
+        } else {
+            // Even if no invariants are detected, create a baseline analysis
+            const invariantAnalyzer = new InvariantAnalyzer();
+            invariantAnalysis = invariantAnalyzer.analyzeInvariants([], {
+                directory,
+                projectName: path.basename(directory),
+                nodeCount: nodes.length,
+                edgeCount: edges.length
+            });
+            
+            architecturalHealth = invariantAnalyzer.assessArchitecturalHealth([], {
+                directory,
+                projectName: path.basename(directory)
+            });
+        }
+        
+        // --- FINAL BUILD & VALIDATION ---
+
+        // Build the final context object conforming to the schema
+        const contextOptions = {
+            directory: directory,
+            projectName: path.basename(directory),
+            contextSurface: contextSurface,
+            arcvisionVersion: process.env.npm_package_version || '0.1.0',  // Pass version from package.json
+            authorityCores,
+            hiddenCoupling,
+            archetype,
+            completenessMetrics,
+            // New authoritative context fields
+            structuralHubs,
+            architecturalBoundaries,
+            structuralInvariants,
+            authoritativeContext,
+            // Include detected invariants
+            detectedInvariants,
+            // Include invariant analysis results
+            invariantAnalysis,
+            // Include architectural health assessment
+            architecturalHealth,
+            // Pass additional metadata
+            commitHash: getGitCommitHash(directory),
+            rootPath: path.resolve(directory)
+        };
+
+        // Prepare context options without archetype initially
+        const { archetype: originalArchetype, ...otherContextOptions } = contextOptions;
+        
+        const finalContextOptions = {
+            directory: directory,
+            projectName: path.basename(directory),
+            language: 'javascript',
+            // Include symbols in options
+            symbols: symbols,
+            ...otherContextOptions,
+            // Include new canonical sections from Pass 4
+            invariants,
+            ownership,
+            failure_modes,
+            decision_guidance
+        };
+        
+        // Explicitly set archetype to ensure it's a proper object
+        if (originalArchetype && typeof originalArchetype === 'object' && 
+            originalArchetype.type && originalArchetype.confidence) {
+            finalContextOptions.archetype = originalArchetype;
+        } else {
+            finalContextOptions.archetype = {
+                type: 'general_purpose',
+                confidence: 'low',
+                description: 'General purpose application',
+                authorityPattern: 'distributed_authority'
+            };
+        }
+        
+        // Build context and ensure archetype is properly set
+        let context = buildContext(nodes, edges, finalContextOptions);
+        
+        // Make sure archetype is set properly in the system section
+        if (!context.system.archetype || context.system.archetype === null) {
+            context.system.archetype = finalContextOptions.archetype || {
+                type: 'general_purpose',
+                confidence: 'low',
+                description: 'General purpose application',
+                authorityPattern: 'distributed_authority'
+            };
+        }
+
+        console.log('   Validating structural context...');
+
+        // Validate against JSON schema
+        let validation = validateContext(context);
+
+        if (!validation.valid) {
+            console.warn('   ⚠️  Validation Issues Found:');
+            validation.errors.forEach(e => console.warn('    -', e));
+            console.warn('   ⚠️  Proceeding despite validation issues to see results');
+            // Continue processing instead of throwing error
+            // throw new Error("Context validation failed");
+        }
+
+        // Deterministic sort for consistent hashing/snapshots
+        const sortedContext = sortContext(context);
+
+        console.log('   ✅ Context Verified & Ready');
+
+        return sortedContext;
+
+    } catch (err) {
+        console.error('❌ Scanner Failed:', err);
+        throw err;
+    }
+}
+
+/**
+ * Get git commit hash for the repository
+ * @param {string} directory - Repository directory
+ * @returns {string} Commit hash or 'unknown'
+ */
+function getGitCommitHash(directory) {
+    try {
+        const result = spawnSync('git', ['rev-parse', 'HEAD'], {
+            cwd: directory,
+            stdio: ['pipe', 'pipe', 'pipe']
+        });
+        
+        if (result.status === 0) {
+            return result.stdout.toString().trim();
+        }
+        return 'unknown';
+    } catch (error) {
+        return 'unknown';
+    }
+}
+
+module.exports = { scan, getGitCommitHash };

package/src/core/semantic-analyzer.js

@@ -0,0 +1,204 @@
+/**
+ * Semantic Analyzer
+ * 
+ * Builds cross-file symbol resolution and tracks actual usage of imported symbols.
+ * This enables detection of which files actually USE imported functions/classes,
+ * not just which files import them.
+ */
+
+/**
+ * Build a global symbol table from all file exports
+ * @param {Array} nodes - All scanned file nodes with metadata
+ * @returns {Map} Symbol table mapping symbol names to their source files
+ */
+function buildSymbolTable(nodes) {
+    const symbolTable = new Map();
+    
+    nodes.forEach(node => {
+        const filePath = node.id;
+        const metadata = node.metadata;
+        
+        if (!metadata) return;
+        
+        // Register all exports from this file
+        if (metadata.exports && Array.isArray(metadata.exports)) {
+            metadata.exports.forEach(exp => {
+                const symbolName = exp.name;
+                if (!symbolTable.has(symbolName)) {
+                    symbolTable.set(symbolName, []);
+                }
+                symbolTable.get(symbolName).push({
+                    file: filePath,
+                    type: exp.type,
+                    loc: exp.loc
+                });
+            });
+        }
+        
+        // Register all functions
+        if (metadata.functions && Array.isArray(metadata.functions)) {
+            metadata.functions.forEach(func => {
+                const symbolName = func.name;
+                if (!symbolTable.has(symbolName)) {
+                    symbolTable.set(symbolName, []);
+                }
+                symbolTable.get(symbolName).push({
+                    file: filePath,
+                    type: 'function',
+                    loc: func.loc
+                });
+            });
+        }
+        
+        // Register all classes
+        if (metadata.classes && Array.isArray(metadata.classes)) {
+            metadata.classes.forEach(cls => {
+                const symbolName = cls.name;
+                if (!symbolTable.has(symbolName)) {
+                    symbolTable.set(symbolName, []);
+                }
+                symbolTable.get(symbolName).push({
+                    file: filePath,
+                    type: 'class',
+                    loc: cls.loc
+                });
+            });
+        }
+    });
+    
+    return symbolTable;
+}
+
+/**
+ * Resolve symbol usage to their definitions
+ * @param {Object} node - File node with metadata
+ * @param {Map} symbolTable - Global symbol table
+ * @returns {Array} Array of resolved symbol usages
+ */
+function resolveSymbolUsage(node, symbolTable) {
+    const resolvedUsages = [];
+    const metadata = node.metadata;
+    
+    if (!metadata) return resolvedUsages;
+    
+    // Track which symbols this file imports
+    const importedSymbols = new Map();
+    if (metadata.imports && Array.isArray(metadata.imports)) {
+        metadata.imports.forEach(imp => {
+            if (imp.specifiers && Array.isArray(imp.specifiers)) {
+                imp.specifiers.forEach(spec => {
+                    const localName = spec.local || spec.imported || spec;
+                    const importedName = spec.imported || spec.local || spec;
+                    importedSymbols.set(localName, {
+                        source: imp.source,
+                        originalName: importedName
+                    });
+                });
+            }
+        });
+    }
+    
+    // Check function calls against imported symbols
+    if (metadata.functionCalls && Array.isArray(metadata.functionCalls)) {
+        metadata.functionCalls.forEach(call => {
+            const callName = call.name;
+            if (importedSymbols.has(callName)) {
+                const importInfo = importedSymbols.get(callName);
+                resolvedUsages.push({
+                    type: 'function_call',
+                    symbol: callName,
+                    source: importInfo.source,
+                    loc: call.loc
+                });
+            }
+        });
+    }
+    
+    // Check constructor calls against imported symbols
+    if (metadata.constructorCalls && Array.isArray(metadata.constructorCalls)) {
+        metadata.constructorCalls.forEach(call => {
+            const className = call.className;
+            if (importedSymbols.has(className)) {
+                const importInfo = importedSymbols.get(className);
+                resolvedUsages.push({
+                    type: 'constructor_call',
+                    symbol: className,
+                    source: importInfo.source,
+                    loc: call.loc
+                });
+            }
+        });
+    }
+    
+    // Check component usage (React/JSX)
+    if (metadata.componentUsage && Array.isArray(metadata.componentUsage)) {
+        metadata.componentUsage.forEach(comp => {
+            const componentName = comp.component;
+            if (importedSymbols.has(componentName)) {
+                const importInfo = importedSymbols.get(componentName);
+                resolvedUsages.push({
+                    type: 'component_usage',
+                    symbol: componentName,
+                    source: importInfo.source,
+                    loc: comp.loc
+                });
+            }
+        });
+    }
+    
+    return resolvedUsages;
+}
+
+/**
+ * Track cross-file references and build usage edges
+ * @param {Array} nodes - All scanned file nodes
+ * @param {Map} symbolTable - Global symbol table
+ * @returns {Array} Array of usage edges
+ */
+function trackCrossFileReferences(nodes, symbolTable) {
+    const usageEdges = [];
+    
+    nodes.forEach(node => {
+        const filePath = node.id;
+        const resolvedUsages = resolveSymbolUsage(node, symbolTable);
+        
+        resolvedUsages.forEach(usage => {
+            // Create an edge from this file to the source of the symbol
+            usageEdges.push({
+                source: filePath,
+                target: usage.source,
+                type: usage.type,
+                symbol: usage.symbol,
+                loc: usage.loc
+            });
+        });
+    });
+    
+    return usageEdges;
+}
+
+/**
+ * Analyze semantic relationships in the codebase
+ * @param {Array} nodes - All scanned file nodes
+ * @returns {Object} Semantic analysis results
+ */
+function analyzeSemantics(nodes) {
+    const symbolTable = buildSymbolTable(nodes);
+    const usageEdges = trackCrossFileReferences(nodes, symbolTable);
+    
+    return {
+        symbolTable,
+        usageEdges,
+        stats: {
+            totalSymbols: symbolTable.size,
+            totalUsages: usageEdges.length
+        }
+    };
+}
+
+module.exports = {
+    buildSymbolTable,
+    resolveSymbolUsage,
+    trackCrossFileReferences,
+    analyzeSemantics
+};