arcvision 0.2.28 → 0.2.29

package/src/core/call-resolver.js

@@ -71,19 +71,21 @@ class CallResolver {
                                 // Better: SymbolIndexer ensure 'default' is the name for default exports.
                             }
                             
-                            // Additional attempts for common patterns
-                            // Attempt 3: Try with common function prefixes
-                            const commonPatterns = [
-                                `${targetFileId}::use${targetSymbolName.charAt(0).toUpperCase() + targetSymbolName.slice(1)}`,
-                                `${targetFileId}::get${targetSymbolName.charAt(0).toUpperCase() + targetSymbolName.slice(1)}`,
-                                `${targetFileId}::create${targetSymbolName.charAt(0).toUpperCase() + targetSymbolName.slice(1)}`,
-                                `${targetFileId}::_${targetSymbolName}`, // underscore prefix
-                                `${targetFileId}::${targetSymbolName}Impl`, // implementation suffix
-                                `${targetFileId}::${targetSymbolName}Handler` // handler suffix
-                            ];
-                            
-                            for (const patternId of commonPatterns) {
-                                if (this.symbolIndex.has(patternId)) return patternId;
+                            // Additional attempts for common function-prefix patterns
+                            // Guard: skip if targetSymbolName is falsy (e.g. undefined from a star import)
+                            if (targetSymbolName && typeof targetSymbolName === 'string' && targetSymbolName.length > 0) {
+                                const cap = targetSymbolName.charAt(0).toUpperCase() + targetSymbolName.slice(1);
+                                const commonPatterns = [
+                                    `${targetFileId}::use${cap}`,
+                                    `${targetFileId}::get${cap}`,
+                                    `${targetFileId}::create${cap}`,
+                                    `${targetFileId}::_${targetSymbolName}`,
+                                    `${targetFileId}::${targetSymbolName}Impl`,
+                                    `${targetFileId}::${targetSymbolName}Handler`
+                                ];
+                                for (const patternId of commonPatterns) {
+                                    if (this.symbolIndex.has(patternId)) return patternId;
+                                }
                             }
                         }
                     }
@@ -97,17 +99,20 @@ class CallResolver {
             }
             
             // Additional local patterns
-            const localPatterns = [
-                `${fileId}::use${symbolName.charAt(0).toUpperCase() + symbolName.slice(1)}`,
-                `${fileId}::get${symbolName.charAt(0).toUpperCase() + symbolName.slice(1)}`,
-                `${fileId}::create${symbolName.charAt(0).toUpperCase() + symbolName.slice(1)}`,
-                `${fileId}::_${symbolName}`, // underscore prefix
-                `${fileId}::${symbolName}Impl`, // implementation suffix
-                `${fileId}::${symbolName}Handler` // handler suffix
-            ];
-            
-            for (const patternId of localPatterns) {
-                if (this.symbolIndex.has(patternId)) return patternId;
+            // Guard: skip if symbolName is falsy
+            if (symbolName && typeof symbolName === 'string' && symbolName.length > 0) {
+                const cap = symbolName.charAt(0).toUpperCase() + symbolName.slice(1);
+                const localPatterns = [
+                    `${fileId}::use${cap}`,
+                    `${fileId}::get${cap}`,
+                    `${fileId}::create${cap}`,
+                    `${fileId}::_${symbolName}`,
+                    `${fileId}::${symbolName}Impl`,
+                    `${fileId}::${symbolName}Handler`
+                ];
+                for (const patternId of localPatterns) {
+                    if (this.symbolIndex.has(patternId)) return patternId;
+                }
             }
 
             return null;

package/src/core/context_builder.js

@@ -2,6 +2,7 @@ const path = require('path');
 const { spawnSync } = require('child_process');
 const crypto = require('crypto');
 const { stableId } = require('../engine/id-generator');
+const { emptyIntelligenceBlock } = require('../engine/pass5_intelligence');
 
 /**
  * Build the context object that conforms to the Arcvision schema
@@ -40,7 +41,7 @@ function buildContext(fileNodes, edges, symbols, options = {}) {
         if (file.intelligence && file.intelligence.connections) {
             file.intelligence.connections.forEach(c => addDep(c.target));
         }
-        
+
         // Add dependencies from metadata if intelligence is not available
         if (!file.intelligence && file.metadata && file.metadata.imports) {
             file.metadata.imports.forEach(imp => {
@@ -191,14 +192,17 @@ function buildContext(fileNodes, edges, symbols, options = {}) {
         architectural_boundaries: options.architecturalBoundaries || {},
         structural_invariants: options.structuralInvariants || [],
         // Include detected invariants from the current scan - these should conform to the schema specification
-        invariants: Array.isArray(options.autoDetectedInvariants) && options.autoDetectedInvariants.length > 0 ? options.autoDetectedInvariants : 
-                   Array.isArray(options.detectedInvariants) && options.detectedInvariants.length > 0 ? options.detectedInvariants : 
-                   [],
+        invariants: Array.isArray(options.autoDetectedInvariants) && options.autoDetectedInvariants.length > 0 ? options.autoDetectedInvariants :
+            Array.isArray(options.detectedInvariants) && options.detectedInvariants.length > 0 ? options.detectedInvariants :
+                [],
         // Include invariant analysis results
         invariant_analysis: options.invariantAnalysis || null,
         // Include architectural health assessment
         architectural_health: options.architecturalHealth || null,
-        authoritative_context: options.authoritativeContext || null
+        authoritative_context: options.authoritativeContext || null,
+        // Intelligence block — always populated, never null
+        // This is the canonical architecture intelligence layer from Pass 5.
+        intelligence: options.intelligence || emptyIntelligenceBlock()
     };
 
     // Phase 2 requirement: Artifact Hash (Trust Anchor)
@@ -206,7 +210,7 @@ function buildContext(fileNodes, edges, symbols, options = {}) {
     const contextWithoutIntegrity = { ...context };
     delete contextWithoutIntegrity.integrity;
     const hash = crypto.createHash('sha256').update(JSON.stringify(contextWithoutIntegrity)).digest('hex');
-    
+
     // Now add the integrity field
     context.integrity = {
         sha256: hash
@@ -226,7 +230,7 @@ function getGitInfo() {
         const originResult = spawnSync('git', ['remote', 'get-url', 'origin'], {
             stdio: ['pipe', 'pipe', 'pipe']
         });
-        
+
         let repoUrl = 'unknown';
         if (originResult.status === 0) {
             let url = originResult.stdout.toString().trim();
@@ -239,17 +243,17 @@ function getGitInfo() {
             }
             repoUrl = url;
         }
-        
+
         // Get the current commit hash
         const commitResult = spawnSync('git', ['rev-parse', 'HEAD'], {
             stdio: ['pipe', 'pipe', 'pipe']
         });
-        
+
         let commitHash = 'unknown';
         if (commitResult.status === 0) {
             commitHash = commitResult.stdout.toString().trim();
         }
-        
+
         return {
             repo: repoUrl,
             commit: commitHash
@@ -274,7 +278,7 @@ function calculateIntegrityHash(obj) {
         if (objCopy.integrity) {
             delete objCopy.integrity;
         }
-        
+
         const jsonString = JSON.stringify(objCopy);
         return crypto.createHash('sha256').update(jsonString).digest('hex');
     } catch (error) {
@@ -323,35 +327,35 @@ function generateStructuralLayers() {
 function generateAdaptiveStructuralLayers(directory) {
     const fs = require('fs');
     const path = require('path');
-    
+
     // Analyze project characteristics to determine adaptive layers
     const hasPackageJson = fs.existsSync(path.join(directory, 'package.json'));
-    const hasConfigFiles = fs.existsSync(path.join(directory, 'tsconfig.json')) || 
-                          fs.existsSync(path.join(directory, 'config')) ||
-                          fs.existsSync(path.join(directory, 'webpack.config.js'));
+    const hasConfigFiles = fs.existsSync(path.join(directory, 'tsconfig.json')) ||
+        fs.existsSync(path.join(directory, 'config')) ||
+        fs.existsSync(path.join(directory, 'webpack.config.js'));
     const hasSrcDir = fs.existsSync(path.join(directory, 'src'));
     const hasTestDir = fs.existsSync(path.join(directory, 'test')) || fs.existsSync(path.join(directory, 'tests'));
     const hasDocsDir = fs.existsSync(path.join(directory, 'docs'));
-    
+
     // Count different file types to determine project size and type
     let totalFiles = 0;
     let jsFiles = 0;
     let tsFiles = 0;
     let luaFiles = 0;
     let configFiles = 0;
-    
+
     function walk(dir, depth = 0) {
         if (depth > 3) return; // Limit depth to avoid performance issues
-        
+
         if (!fs.existsSync(dir)) return;
-        
+
         const items = fs.readdirSync(dir, { withFileTypes: true });
-        
+
         for (const item of items) {
             const fullPath = path.join(dir, item.name);
-            
+
             if (item.isDirectory()) {
-                if (!item.name.startsWith('.') && item.name !== 'node_modules' && 
+                if (!item.name.startsWith('.') && item.name !== 'node_modules' &&
                     item.name !== 'dist' && item.name !== 'build' && item.name !== '.git') {
                     walk(fullPath, depth + 1);
                 }
@@ -360,20 +364,20 @@ function generateAdaptiveStructuralLayers(directory) {
                 if (item.name.endsWith('.js')) jsFiles++;
                 if (item.name.endsWith('.ts')) tsFiles++;
                 if (item.name.endsWith('.lua')) luaFiles++;
-                if (['.json', '.yaml', '.yml', '.toml', '.config.js', '.config.ts', '.rc'].some(ext => 
+                if (['.json', '.yaml', '.yml', '.toml', '.config.js', '.config.ts', '.rc'].some(ext =>
                     item.name.endsWith(ext))) configFiles++;
             }
         }
     }
-    
+
     walk(directory);
-    
+
     // Determine if this is a Lua-heavy project (like BullMQ)
     const isLuaProject = luaFiles > 0 && (luaFiles / totalFiles) > 0.1; // More than 10% Lua files
-    
+
     // Determine project size
     const isLargeProject = totalFiles > 1000;
-    
+
     // Adjust structural layers based on project characteristics
     const layers = {
         "runtime_code": {
@@ -413,7 +417,7 @@ function generateAdaptiveStructuralLayers(directory) {
             "description": "Static assets with no effect on execution semantics"
         }
     };
-    
+
     // Add project-specific metadata
     layers.project_metadata = {
         "size_category": isLargeProject ? "large" : (totalFiles > 100 ? "medium" : "small"),
@@ -429,7 +433,7 @@ function generateAdaptiveStructuralLayers(directory) {
         "has_tests": hasTestDir,
         "is_lua_intensive": isLuaProject
     };
-    
+
     return layers;
 }
 
@@ -441,13 +445,13 @@ function generateAdaptiveStructuralLayers(directory) {
 function generateProjectEnvelope(directory) {
     const fs = require('fs');
     const path = require('path');
-    
+
     const envelope = {
         configuration_files: [],
         documentation: [],
         build_tools: []
     };
-    
+
     // Common configuration files
     const configFiles = [
         'package.json',
@@ -497,7 +501,7 @@ function generateProjectEnvelope(directory) {
         'remix.config.js',
         'remix.config.ts'
     ];
-    
+
     // Common documentation files
     const docFiles = [
         'README.md',
@@ -521,7 +525,7 @@ function generateProjectEnvelope(directory) {
         'CITATION.cff',
         'CITATION.bib'
     ];
-    
+
     // Common build tool files
     const buildToolFiles = [
         'typedoc.config.cjs',
@@ -537,18 +541,18 @@ function generateProjectEnvelope(directory) {
         'compodoc.json',
         'documentation.yml'
     ];
-    
+
     // Function to find files recursively
     function findFilesRecursively(dir, fileNames, results, maxDepth = 3, currentDepth = 0) {
         if (currentDepth > maxDepth) return;
-        
+
         if (!fs.existsSync(dir)) return;
-        
+
         const items = fs.readdirSync(dir, { withFileTypes: true });
-        
+
         for (const item of items) {
             const fullPath = path.join(dir, item.name);
-            
+
             if (item.isDirectory()) {
                 if (!item.name.startsWith('.') && item.name !== 'node_modules' && item.name !== 'dist' && item.name !== 'build') {
                     findFilesRecursively(fullPath, fileNames, results, maxDepth, currentDepth + 1);
@@ -564,53 +568,53 @@ function generateProjectEnvelope(directory) {
             }
         }
     }
-    
+
     // Find all configuration files
     const foundConfigFiles = [];
     findFilesRecursively(directory, configFiles, foundConfigFiles);
-    
+
     foundConfigFiles.forEach(fileObj => {
         envelope.configuration_files.push({
             path: fileObj.path,
             role: getRoleForConfigFile(fileObj.name)
         });
     });
-    
+
     // Find all documentation files
     const foundDocFiles = [];
     findFilesRecursively(directory, docFiles, foundDocFiles);
-    
+
     foundDocFiles.forEach(fileObj => {
         envelope.documentation.push({
             path: fileObj.path,
             role: getRoleForDocFile(fileObj.name)
         });
     });
-    
+
     // Find all build tool files
     const foundBuildToolFiles = [];
     findFilesRecursively(directory, buildToolFiles, foundBuildToolFiles);
-    
+
     foundBuildToolFiles.forEach(fileObj => {
         envelope.build_tools.push({
             path: fileObj.path,
             role: getRoleForBuildToolFile(fileObj.name)
         });
     });
-    
+
     // Remove duplicates based on path
     envelope.configuration_files = envelope.configuration_files.filter((file, index, self) =>
         index === self.findIndex(f => f.path === file.path)
     );
-    
+
     envelope.documentation = envelope.documentation.filter((file, index, self) =>
         index === self.findIndex(f => f.path === file.path)
     );
-    
+
     envelope.build_tools = envelope.build_tools.filter((file, index, self) =>
         index === self.findIndex(f => f.path === file.path)
     );
-    
+
     return envelope;
 }
 

package/src/core/invariant-detector.js

@@ -31,7 +31,7 @@ class InvariantDetector {
 
       console.log('\n🔍 Starting Invariant Detection Analysis');
       console.log(`   Analyzing ${scanResult.nodes.length} nodes and ${scanResult.edges.length} relationships`);
-      
+
       // Analyze the structural context for potential invariants
       await this.analyzeNodesForInvariants(scanResult.nodes, directory);
       await this.analyzeEdgesForInvariants(scanResult.edges);
@@ -49,7 +49,7 @@ class InvariantDetector {
 
       console.log(`\n🛡️  Invariant Detection Complete`);
       console.log(`   Found ${this.detectedInvariants.length} potential system invariants`);
-      
+
       // Log summary of invariant types
       const typeCounts = {};
       this.detectedInvariants.forEach(inv => {
@@ -344,7 +344,7 @@ class InvariantDetector {
       { pattern: /range.*check/gi, description: 'Range check', critical: true },
       { pattern: /within.*bounds/gi, description: 'Bounds check', critical: true },
       { pattern: /validat(e|ion)/gi, description: 'Validation pattern', critical: false },
-      { pattern: /guard/i, description: 'Guard pattern', critical: true },
+      { pattern: /guard/gi, description: 'Guard pattern', critical: true },
 
       // Access control and security patterns
       { pattern: /access.*control/gi, description: 'Access control', critical: true },
@@ -429,15 +429,27 @@ class InvariantDetector {
    */
   async findInvariantRelatedFiles(directory) {
     const invariantFiles = [];
+    const MAX_FILES = 200; // Cap to avoid OOM on giant monorepos
+
+    // Directories to skip — mirrors the Pass 1 exclusion list
+    const SKIP_DIRS = new Set([
+      'node_modules', '.git', 'dist', 'build', '.next', '.turbo',
+      'coverage', '.cache', '__pycache__', 'vendor', 'out',
+      'target', '.yarn', '.pnp', 'arcvision_context'
+    ]);
 
     const walk = async (dir) => {
+      if (invariantFiles.length >= MAX_FILES) return; // Early exit if cap reached
       try {
         const entries = await fs.readdir(dir, { withFileTypes: true });
 
         for (const entry of entries) {
+          if (invariantFiles.length >= MAX_FILES) return;
           const fullPath = path.join(dir, entry.name);
 
           if (entry.isDirectory()) {
+            // Skip heavy or irrelevant directories
+            if (SKIP_DIRS.has(entry.name) || entry.name.startsWith('.')) continue;
             await walk(fullPath);
           } else if (entry.isFile()) {
             const fileName = entry.name.toLowerCase();

package/src/core/readme-generator.js

@@ -11,7 +11,7 @@ function getCommitHash() {
         const result = spawnSync('git', ['rev-parse', 'HEAD'], {
             stdio: ['pipe', 'pipe', 'pipe']
         });
-        
+
         if (result.status === 0) {
             return result.stdout.toString().trim();
         }
@@ -27,9 +27,10 @@ function getCommitHash() {
  * @param {string} timestamp - Generation timestamp
  * @param {string} toolVersion - ArcVision tool version
  * @param {Object} blastRadiusData - Blast radius analysis data
+ * @param {Object} intelligenceData - Architecture intelligence block from Pass 5
  * @returns {string} Formatted README content
  */
-function generateReadmeContent(commitHash, timestamp, toolVersion, blastRadiusData = null) {
+function generateReadmeContent(commitHash, timestamp, toolVersion, blastRadiusData = null, intelligenceData = null) {
     let content = `# ArcVision System Context Artifact
 
 
@@ -89,7 +90,7 @@ If this artifact conflicts with human memory, **trust the artifact**.`;
 The following files have the highest blast radius and represent critical structural hubs in the system:
 
 `;
-        
+
         blastRadiusData.topFiles.forEach((item, index) => {
             let warningMessage = '';
             if (index === 0) {
@@ -99,7 +100,7 @@ The following files have the highest blast radius and represent critical structu
             } else {
                 warningMessage = 'Modifications can cause widespread inconsistencies.';
             }
-            
+
             content += `- **${item.file}**
   - Blast Radius: ${item.blastRadius} files (${item.percentOfGraph}% of codebase)
   - Risk: ${warningMessage}
@@ -113,7 +114,7 @@ The following files have the highest blast radius and represent critical structu
 
 No high-structure files detected based on import dependencies.`;
     }
-    
+
     content += `
 
 ## How to Use With AI
@@ -141,7 +142,58 @@ All explanations, decisions, and AI reasoning should reference it.
 
 Some execution script invocations are dynamically assembled at runtime and may not be statically traceable; such scripts are included 
 as execution boundaries without guaranteed call-site resolution`;
-    
+
+    // Add architecture intelligence summary if available
+    if (intelligenceData) {
+        const intel = intelligenceData;
+        const centrality = intel.centrality || {};
+        const hotspots = intel.hotspots || {};
+        const risk = intel.risk_assessment || {};
+        const recs = intel.recommendations || [];
+        const fragility = intel.fragility || {};
+        const path = require('path');
+
+        content += `
+
+## Architecture Intelligence Summary
+
+_Generated by ArcVision — derived from structural graph analysis._
+
+`;
+        if (centrality.most_central) {
+            const top = centrality.top_files && centrality.top_files[0];
+            const score = top ? ` (centrality score: ${top.score})` : '';
+            content += `- **Most Central Module**: \`${centrality.most_central}\`${score}\n`;
+        }
+
+        const clusters = hotspots.clusters || [];
+        const topCluster = clusters.find(c => c.cycle_count > 0) || clusters[0];
+        if (topCluster && topCluster.files && topCluster.files.length > 0) {
+            const names = topCluster.files.slice(0, 3).map(f => path.basename(f)).join(' + ');
+            const cycleInfo = topCluster.cycle_count > 0 ? ` (${topCluster.cycle_count} cycle(s))` : '';
+            content += `- **Coupling Hotspot**: ${names}${cycleInfo}\n`;
+        } else {
+            content += `- **Coupling Hotspot**: None detected\n`;
+        }
+
+        if (risk.risk_score !== undefined) {
+            content += `- **Risk Score**: ${risk.risk_score.toFixed(1)} / 10 [${risk.risk_level}]\n`;
+        }
+
+        if (intel.entropy) {
+            content += `- **Architectural Entropy**: ${intel.entropy.score} [${intel.entropy.level.toUpperCase()}]\n`;
+        }
+
+        if (fragility.most_fragile) {
+            const frag = fragility.most_fragile;
+            content += `- **Most Fragile Module**: \`${path.basename(frag.file)}\` — fragility score: ${frag.score}\n`;
+        }
+
+        if (recs.length > 0) {
+            content += `- **Top Recommendation**: ${recs[0]}\n`;
+        }
+    }
+
     return content;
 }
 
@@ -150,16 +202,17 @@ as execution boundaries without guaranteed call-site resolution`;
  * @param {string} outputDir - Directory to save the README
  * @param {string} toolVersion - ArcVision tool version
  * @param {Object} blastRadiusData - Blast radius analysis data
+ * @param {Object} intelligenceData - Architecture intelligence block from Pass 5
  */
-function generateReadme(outputDir, toolVersion, blastRadiusData = null) {
+function generateReadme(outputDir, toolVersion, blastRadiusData = null, intelligenceData = null) {
     const commitHash = getCommitHash();
     const timestamp = new Date().toISOString();
-    const readmeContent = generateReadmeContent(commitHash, timestamp, toolVersion, blastRadiusData);
-    
+    const readmeContent = generateReadmeContent(commitHash, timestamp, toolVersion, blastRadiusData, intelligenceData);
+
     const readmePath = path.join(outputDir, 'README.md');
     fs.writeFileSync(readmePath, readmeContent);
-    
-    console.log(`✅ System context README generated at ${readmePath}`);
+
+    console.log(`\u2705 README generated at ${readmePath}`);
 }
 
 module.exports = { generateReadme, generateReadmeContent, getCommitHash };

package/src/core/scanner.js

@@ -7,6 +7,7 @@ const { executePass1 } = require('../engine/pass1_facts');
 const { executePass2 } = require('../engine/pass2_semantics');
 const { executePass3 } = require('../engine/pass3_lifter');
 const { executePass4 } = require('../engine/pass4_signals');
+const { executePass5 } = require('../engine/pass5_intelligence');
 
 // Import authority core detection
 const { detectAuthorityCores, detectHiddenCoupling, detectArchitecturalArchetype } = require('./authority-core-detector');
@@ -64,6 +65,11 @@ async function scan(directory) {
 
         const { nodes, edges, contextSurface, symbols } = structuralContext;
 
+        // --- PASS 5: INTELLIGENCE SYNTHESIS ---
+        // Interprets the graph already computed — no new file scanning.
+        // Computes centrality, hotspots, fragility, boundary violations, risk, and recommendations.
+        const { intelligence } = executePass5({ nodes, edges });
+
         console.log(`\n🔍 Analysis Complete (${Date.now() - start}ms)`);
         console.log(`   Nodes: ${nodes.length}`);
         console.log(`   Edges: ${edges.length}`);
@@ -181,7 +187,7 @@ async function scan(directory) {
                 existingIds.add(existingInv.id);
             }
         }
-        
+
         // Ensure all invariants have statement fields as fallback
         console.log(`🔍 Ensuring all ${allInvariants.length} invariants have statement fields...`);
         for (let i = 0; i < allInvariants.length; i++) {
@@ -221,7 +227,7 @@ async function scan(directory) {
         // Synthesize failure modes
         let failure_modes = [];
         try {
-            console.log('🔍 Synthesizing failure modes for ${allInvariants.length} invariants...');
+            console.log(`🔍 Synthesizing failure modes for ${allInvariants.length} invariants...`);
             failure_modes = failureModeSynthesizer.synthesizeFailureModes(
                 { nodes, edges },
                 allInvariants
@@ -359,7 +365,9 @@ async function scan(directory) {
             invariants: allInvariants,
             ownership,
             failure_modes,
-            decision_guidance
+            decision_guidance,
+            // Intelligence block from Pass 5
+            intelligence
         };
 
         // Explicitly set archetype to ensure it's a proper object
@@ -423,7 +431,7 @@ async function scan(directory) {
         try {
             fs.writeFileSync(contextFilePath, JSON.stringify(sortedContext, null, 2));
             console.log('✅ Context file written successfully');
-            
+
             // Verify file was written
             if (fs.existsSync(contextFilePath)) {
                 const stats = fs.statSync(contextFilePath);