arcvision 0.2.14 → 0.2.16

package/src/core/type-analyzer.js

@@ -0,0 +1,272 @@
+/**
+ * Type Dependency Analyzer
+ * 
+ * Tracks TypeScript type-only dependencies including:
+ * - Type-only imports
+ * - Interface extensions
+ * - Interface implementations
+ * - Generic type parameters
+ * - Return type dependencies
+ */
+
+const traverse = require('@babel/traverse').default;
+
+/**
+ * Extract type-only imports from AST
+ * @param {Object} ast - Babel AST
+ * @returns {Array} Array of type imports
+ */
+function extractTypeImports(ast) {
+    const typeImports = [];
+
+    if (!ast) return typeImports;
+
+    traverse(ast, {
+        ImportDeclaration(path) {
+            const node = path.node;
+
+            // Check if it's a type-only import: import type { ... }
+            if (node.importKind === 'type') {
+                const specifiers = [];
+                node.specifiers.forEach(spec => {
+                    if (spec.imported) {
+                        specifiers.push({
+                            imported: spec.imported.name || spec.imported.value,
+                            local: spec.local.name
+                        });
+                    }
+                });
+
+                typeImports.push({
+                    source: node.source.value,
+                    specifiers,
+                    importKind: 'type',
+                    loc: node.loc
+                });
+            }
+
+            // Check for individual type specifiers: import { type User } from '...'
+            else {
+                const typeSpecifiers = [];
+                node.specifiers.forEach(spec => {
+                    if (spec.importKind === 'type' && spec.imported) {
+                        typeSpecifiers.push({
+                            imported: spec.imported.name || spec.imported.value,
+                            local: spec.local.name
+                        });
+                    }
+                });
+
+                if (typeSpecifiers.length > 0) {
+                    typeImports.push({
+                        source: node.source.value,
+                        specifiers: typeSpecifiers,
+                        importKind: 'mixed',
+                        loc: node.loc
+                    });
+                }
+            }
+        }
+    });
+
+    return typeImports;
+}
+
+/**
+ * Extract interface dependencies (extends, implements)
+ * @param {Object} ast - Babel AST
+ * @returns {Array} Array of interface dependencies
+ */
+function extractInterfaceDependencies(ast) {
+    const interfaceDeps = [];
+
+    if (!ast) return interfaceDeps;
+
+    traverse(ast, {
+        // Interface extends
+        TSInterfaceDeclaration(path) {
+            const node = path.node;
+            const interfaceName = node.id.name;
+
+            if (node.extends && node.extends.length > 0) {
+                node.extends.forEach(ext => {
+                    const extendedInterface = extractTypeName(ext.expression);
+                    if (extendedInterface) {
+                        interfaceDeps.push({
+                            interface: interfaceName,
+                            extends: extendedInterface,
+                            type: 'interface_extends',
+                            loc: node.loc
+                        });
+                    }
+                });
+            }
+        },
+
+        // Class implements
+        ClassDeclaration(path) {
+            const node = path.node;
+            const className = node.id ? node.id.name : 'Anonymous';
+
+            if (node.implements && node.implements.length > 0) {
+                node.implements.forEach(impl => {
+                    const implementedInterface = extractTypeName(impl.expression);
+                    if (implementedInterface) {
+                        interfaceDeps.push({
+                            class: className,
+                            implements: implementedInterface,
+                            type: 'class_implements',
+                            loc: node.loc
+                        });
+                    }
+                });
+            }
+        }
+    });
+
+    return interfaceDeps;
+}
+
+/**
+ * Extract generic type dependencies
+ * @param {Object} ast - Babel AST
+ * @returns {Array} Array of generic type usages
+ */
+function extractGenericDependencies(ast) {
+    const genericDeps = [];
+
+    if (!ast) return genericDeps;
+
+    traverse(ast, {
+        // Function return types
+        FunctionDeclaration(path) {
+            const node = path.node;
+            const functionName = node.id ? node.id.name : 'anonymous';
+
+            if (node.returnType) {
+                const returnTypeName = extractComplexTypeName(node.returnType.typeAnnotation);
+                if (returnTypeName) {
+                    genericDeps.push({
+                        function: functionName,
+                        returnType: returnTypeName,
+                        type: 'return_type',
+                        loc: node.loc
+                    });
+                }
+            }
+        },
+
+        // Arrow function return types
+        ArrowFunctionExpression(path) {
+            const node = path.node;
+
+            if (node.returnType) {
+                const returnTypeName = extractComplexTypeName(node.returnType.typeAnnotation);
+                if (returnTypeName) {
+                    genericDeps.push({
+                        function: 'arrow_function',
+                        returnType: returnTypeName,
+                        type: 'return_type',
+                        loc: node.loc
+                    });
+                }
+            }
+        },
+
+        // Variable type annotations
+        VariableDeclarator(path) {
+            const node = path.node;
+            const varName = node.id.name;
+
+            if (node.id.typeAnnotation) {
+                const typeName = extractComplexTypeName(node.id.typeAnnotation.typeAnnotation);
+                if (typeName) {
+                    genericDeps.push({
+                        variable: varName,
+                        type: typeName,
+                        kind: 'variable_type',
+                        loc: node.loc
+                    });
+                }
+            }
+        }
+    });
+
+    return genericDeps;
+}
+
+/**
+ * Analyze all type dependencies in a file
+ * @param {Object} ast - Babel AST
+ * @returns {Object} All type dependencies
+ */
+function analyzeTypeDependencies(ast) {
+    if (!ast) {
+        return {
+            typeImports: [],
+            interfaceDependencies: [],
+            genericDependencies: []
+        };
+    }
+
+    return {
+        typeImports: extractTypeImports(ast),
+        interfaceDependencies: extractInterfaceDependencies(ast),
+        genericDependencies: extractGenericDependencies(ast)
+    };
+}
+
+/**
+ * Helper: Extract type name from TypeScript type node
+ */
+function extractTypeName(node) {
+    if (!node) return null;
+
+    if (node.type === 'Identifier') {
+        return node.name;
+    } else if (node.type === 'TSTypeReference' && node.typeName) {
+        if (node.typeName.type === 'Identifier') {
+            return node.typeName.name;
+        }
+    }
+
+    return null;
+}
+
+/**
+ * Helper: Extract complex type names (including generics)
+ */
+function extractComplexTypeName(node) {
+    if (!node) return null;
+
+    if (node.type === 'TSTypeReference' && node.typeName) {
+        let baseName = extractTypeName(node);
+
+        // Handle generic parameters
+        if (node.typeParameters && node.typeParameters.params) {
+            const params = node.typeParameters.params
+                .map(p => extractComplexTypeName(p))
+                .filter(Boolean)
+                .join(', ');
+            if (params) {
+                baseName += `<${params}>`;
+            }
+        }
+
+        return baseName;
+    } else if (node.type === 'Identifier') {
+        return node.name;
+    } else if (node.type === 'TSArrayType') {
+        const elementType = extractComplexTypeName(node.elementType);
+        return elementType ? `${elementType}[]` : null;
+    }
+
+    return null;
+}
+
+module.exports = {
+    extractTypeImports,
+    extractInterfaceDependencies,
+    extractGenericDependencies,
+    analyzeTypeDependencies
+};

package/src/core/watcher.js

@@ -0,0 +1,18 @@
+const chokidar = require('chokidar');
+
+function watch(directory, callback) {
+    const watcher = chokidar.watch(directory, {
+        ignored: [/(^|[\/\\])\../, '**/node_modules/**'], // ignore dotfiles
+        persistent: true,
+        ignoreInitial: true
+    });
+
+    watcher
+        .on('add', path => callback('add', path))
+        .on('change', path => callback('change', path))
+        .on('unlink', path => callback('unlink', path));
+
+    return watcher;
+}
+
+module.exports = { watch };

package/src/core/workspace-scanner.js

@@ -0,0 +1,88 @@
+const fs = require('fs');
+const path = require('path');
+const { loadTSConfig } = require('./tsconfig-utils');
+
+/**
+ * Scans the workspace to build a map of package names to their locations
+ * and loads tsconfig configurations.
+ */
+class WorkspaceScanner {
+  constructor(rootPath) {
+    this.rootPath = path.resolve(rootPath);
+    this.workspaceMap = new Map(); // packageName -> absolutePath
+    this.tsconfigMap = new Map();  // workspaceRoot -> tsconfig object
+  }
+
+  /**
+   * Performs the scan and returns the context.
+   * @returns {Object} { workspaceMap, tsconfigMap }
+   */
+  scan() {
+    console.log(`Starting workspace scan at ${this.rootPath}`);
+    this._scanRecursively(this.rootPath);
+    
+    // Sort maps for determinism in output/debugging
+    const sortedWorkspaceMap = new Map([...this.workspaceMap.entries()].sort());
+    const sortedTsconfigMap = new Map([...this.tsconfigMap.entries()].sort());
+
+    console.log(`Workspace scan complete. Found ${sortedWorkspaceMap.size} packages.`);
+    return {
+      workspaceMap: sortedWorkspaceMap,
+      tsconfigMap: sortedTsconfigMap
+    };
+  }
+
+  _scanRecursively(currentPath) {
+    let entries;
+    try {
+      entries = fs.readdirSync(currentPath, { withFileTypes: true });
+    } catch (e) {
+      console.error(`Failed to read directory ${currentPath}: ${e.message}`);
+      return;
+    }
+
+    // Sort entries for deterministic scanning order
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+
+    // Check for tsconfig in this directory
+    // We check this for every directory we visit.
+    const tsConfig = loadTSConfig(currentPath);
+    if (tsConfig) {
+      this.tsconfigMap.set(currentPath, tsConfig);
+    }
+
+    for (const entry of entries) {
+      const fullPath = path.join(currentPath, entry.name);
+
+      if (entry.isDirectory()) {
+         // Skip node_modules and hidden directories (starting with .)
+        if (entry.name === 'node_modules' || entry.name.startsWith('.')) {
+          continue;
+        }
+        this._scanRecursively(fullPath);
+      } else if (entry.name === 'package.json') {
+        this._processPackageJson(fullPath);
+      }
+    }
+  }
+
+  _processPackageJson(packageJsonPath) {
+    try {
+      const content = fs.readFileSync(packageJsonPath, 'utf-8');
+      const pkg = JSON.parse(content);
+      
+      if (pkg.name) {
+        if (this.workspaceMap.has(pkg.name)) {
+          // console.warn(`Duplicate package name found: ${pkg.name} at ${packageJsonPath}. Keeping ${this.workspaceMap.get(pkg.name)}`);
+        } else {
+          this.workspaceMap.set(pkg.name, path.dirname(packageJsonPath));
+        }
+      }
+    } catch (e) {
+      // Failures logged, never fatal
+      console.warn(`Failed to parse package.json at ${packageJsonPath}: ${e.message}`);
+    }
+  }
+}
+
+module.exports = { WorkspaceScanner };

package/src/engine/context_builder.js

@@ -0,0 +1,280 @@
+const path = require('path');
+const crypto = require('crypto');
+const { stableId } = require('./id-generator');
+
+/**
+ * Generate integrity hash for the context
+ * @param {Array} nodes - List of nodes
+ * @param {Array} edges - List of edges
+ * @returns {string} SHA256 hash
+ */
+function generateIntegrityHash(nodes, edges) {
+    const content = JSON.stringify({
+        nodes: nodes.map(n => ({
+            id: n.id,
+            path: n.path,
+            role: n.role
+        })).sort((a, b) => a.id.localeCompare(b.id)),
+        edges: edges.map(e => ({
+            from: e.from,
+            to: e.to,
+            relation: e.relation
+        })).sort((a, b) => {
+            if (a.from !== b.from) return a.from.localeCompare(b.from);
+            return a.to.localeCompare(b.to);
+        })
+    });
+    
+    return crypto.createHash('sha256').update(content).digest('hex');
+}
+
+/**
+ * Build the context object that conforms to the Arcvision schema
+ * @param {Array} files - List of files from scanner
+ * @param {Array} edges - List of edges from scanner
+ * @param {Object} options - Options including directory path and project name
+ * @returns {Object} - Context object conforming to schema
+ */
+function buildContext(files, edges, options = {}) {
+    const {
+        directory = '.',
+        projectName = 'arcvision',
+        language = 'javascript'
+    } = options;
+
+    // Build nodes from files
+    const nodes = files.map(file => {
+        // Use the node's id field which is already the normalized relative path
+        const normalizedPath = file.id;
+
+        // Determine role based on multiple factors for better accuracy
+        const hasFunctions = file.metadata.functions && file.metadata.functions.length > 0;
+        const hasClasses = file.metadata.classes && file.metadata.classes.length > 0;
+        const hasExports = file.metadata.exports && file.metadata.exports.length > 0;
+        const hasApiCalls = file.metadata.apiCalls && file.metadata.apiCalls.length > 0;
+
+        let role = 'Structure';
+        if (hasFunctions || hasClasses || hasApiCalls) {
+            role = 'Implementation';
+        } else if (hasExports) {
+            role = 'Interface';
+        }
+
+        // Extract dependencies more accurately and remove duplicates
+        const dependencies = [];
+        const uniqueDeps = new Set();
+        if (file.metadata.imports && Array.isArray(file.metadata.imports)) {
+            file.metadata.imports.forEach(imp => {
+                if (imp.source && typeof imp.source === 'string') {
+                    // Only add unique dependencies
+                    if (!uniqueDeps.has(imp.source)) {
+                        uniqueDeps.add(imp.source);
+                        dependencies.push(imp.source);
+                    }
+                }
+            });
+        }
+
+        return {
+            id: stableId(normalizedPath),
+            type: 'file',
+            path: normalizedPath,
+            role: role,
+            dependencies: dependencies,
+            blast_radius: file.metadata.blast_radius || 0
+        };
+    });
+
+    // Build edges from dependencies
+    const schemaEdges = [];
+    for (const edge of edges) {
+        // Find source and target nodes to get their stable IDs
+        const sourceNode = nodes.find(n => n.path === edge.source);
+        const targetNode = nodes.find(n => n.path === edge.target);
+
+        // Include edges where source exists (even if target doesn't exist as a node)
+        if (sourceNode) {
+            // Normalize the edge type to fit the schema
+            let relationType = 'imports';
+
+            // Handle import-related types
+            if (edge.type === 'imports' || edge.type === 'require' || edge.type === 'export-from' ||
+                edge.type === 'export-all' || edge.type === 'dynamic-import' || edge.type === 'require-assignment') {
+                relationType = 'imports';
+            }
+            // Handle call-related types (NEW)
+            else if (edge.type === 'function_call' || edge.type === 'method_call') {
+                relationType = 'calls';
+            }
+            // Handle constructor calls (NEW) - map to calls for schema compliance
+            else if (edge.type === 'constructor_call') {
+                relationType = 'calls';
+            }
+            // Handle component usage (NEW) - map to imports for schema compliance
+            else if (edge.type === 'component_usage' || edge.type === 'jsx_component' || edge.type === 'jsx_member_component') {
+                relationType = 'imports';
+            }
+            // Handle existing types
+            else if (edge.type === 'calls') {
+                relationType = 'calls';
+            } else if (edge.type === 'owns') {
+                relationType = 'owns';
+            } else if (edge.type === 'depends_on') {
+                relationType = 'depends_on';
+            } else {
+                // Default to 'imports' for any unknown edge types to ensure schema compliance
+                relationType = 'imports';
+            }
+
+            if (targetNode) {
+                // Both source and target nodes exist
+                schemaEdges.push({
+                    from: sourceNode.id,
+                    to: targetNode.id,
+                    relation: relationType
+                });
+            } else {
+                // Source exists but target doesn't (external dependency like node_modules)
+                // We'll still include the edge to preserve the relationship
+                // However, since the schema requires valid node IDs, we'll only add if the target is a known node
+                // For now, we'll skip edges to non-existent targets to maintain schema compliance
+            }
+        }
+    }
+
+    // Calculate metrics
+    const metrics = {
+        total_files: nodes.length,
+        total_nodes: nodes.length,
+        total_edges: schemaEdges.length,
+        total_imports: schemaEdges.filter(edge => edge.relation === 'imports').length,
+        total_calls: schemaEdges.filter(edge => edge.relation === 'calls').length,
+        total_owns: schemaEdges.filter(edge => edge.relation === 'owns').length,
+        total_depends_on: schemaEdges.filter(edge => edge.relation === 'depends_on').length,
+        files_with_functions: nodes.filter(n => n.role === 'Implementation').length
+    };
+
+    // Build and return the context object
+    const context = {
+        schema_version: '1.0.0',
+        generated_at: new Date().toISOString(),
+        system: {
+            name: projectName,
+            root_path: path.resolve(directory),
+            language: language,
+            archetype: options.archetype || {
+                type: 'general_purpose',
+                confidence: 'low',
+                description: 'General purpose application',
+                authorityPattern: 'distributed_authority'
+            }
+        },
+        nodes,
+        edges: schemaEdges,
+        symbols: options.symbols || [],
+        metrics,
+        contextSurface: options.contextSurface || {},
+        
+        // Authority core detection results
+        authority_cores: options.authorityCores || [],
+        hidden_coupling: options.hiddenCoupling || [],
+        
+        // Completeness metrics
+        completeness_metrics: options.completenessMetrics || {
+            totalFilesFound: nodes.length,
+            filesAnalyzed: nodes.length,
+            coveragePercentage: 100,
+            missingCriticalFiles: []
+        },
+        
+        // Assumptions about analysis limitations
+        assumptions: [
+            'Analysis excludes node_modules and build artifacts',
+            'TypeScript declaration files (.d.ts) are excluded from analysis',
+            'Circular dependencies may not be fully detected',
+            'Dynamic imports may not be fully resolved'
+        ],
+        
+        // Source repository information
+        source: {
+            repo: options.rootPath || path.resolve(directory),
+            commit: options.commitHash || 'unknown',
+            generated_at: new Date().toISOString(),
+            arcvision_version: options.arcvisionVersion || '1.0.0'
+        },
+        
+        // Integrity hash
+        integrity: {
+            sha256: generateIntegrityHash(nodes, edges)
+        },
+        
+        // Structural layers analysis
+        structural_layers: {
+            runtime_code: {
+                status: 'included',
+                description: 'JavaScript/TypeScript source files'
+            },
+            execution_scripts: {
+                status: 'included',
+                description: 'Lua execution scripts'
+            },
+            infrastructure_scripts: {
+                status: 'excluded',
+                description: 'Infrastructure scripts (bash, shell, etc.)'
+            },
+            configuration: {
+                status: 'included',
+                description: 'Configuration files (JSON, YAML, etc.)'
+            },
+            documentation: {
+                status: 'excluded',
+                description: 'Documentation files'
+            },
+            assets: {
+                status: 'excluded',
+                description: 'Asset files (images, fonts, etc.)'
+            }
+        },
+        
+        // Project envelope
+        project_envelope: {
+            configuration_files: nodes
+                .filter(n => n.path && (n.path.endsWith('.json') || n.path.endsWith('.yaml') || n.path.endsWith('.yml') || n.path.includes('config')))
+                .map(n => ({
+                    path: n.path,
+                    role: 'configuration'
+                })),
+            documentation: [],
+            build_tools: []
+        },
+        
+        // Diff summary placeholder
+        diff_summary: null
+    };
+
+    // Add additional computed metrics
+    context.metrics.files_with_functions = nodes.filter(n => n.role === 'Implementation').length;
+    context.metrics.files_with_high_blast_radius = nodes.filter(n => n.blast_radius > 5).length;
+    context.metrics.total_dependencies = schemaEdges.length;
+    
+    // Add new canonical sections if provided in options
+    if (options.invariants !== undefined) {
+        context.invariants = options.invariants;
+    }
+    
+    if (options.ownership !== undefined) {
+        context.ownership = options.ownership;
+    }
+    
+    if (options.failure_modes !== undefined) {
+        context.failure_modes = options.failure_modes;
+    }
+    
+    if (options.decision_guidance !== undefined) {
+        context.decision_guidance = options.decision_guidance;
+    }
+
+    return context;
+}
+
+module.exports = { buildContext };