arcvision 0.2.12 → 0.2.15

package/src/core/react-nextjs-detector.js

@@ -0,0 +1,245 @@
+/**
+ * React/Next.js Pattern Detector
+ * 
+ * Detects framework-specific patterns including:
+ * - Component composition (JSX usage)
+ * - Server/Client component boundaries
+ * - API route dependencies
+ * - Middleware dependencies
+ * - Next.js specific imports (Image, Link, etc.)
+ */
+
+const traverse = require('@babel/traverse').default;
+
+/**
+ * Detect JSX component usage
+ * @param {Object} ast - Babel AST
+ * @returns {Array} Array of component usages
+ */
+function detectComponentUsage(ast) {
+    const componentUsages = [];
+
+    if (!ast) return componentUsages;
+
+    traverse(ast, {
+        JSXElement(path) {
+            const openingElement = path.node.openingElement;
+            let componentName = null;
+
+            // Simple component: <Button />
+            if (openingElement.name.type === 'JSXIdentifier') {
+                componentName = openingElement.name.name;
+
+                // Only track components (start with uppercase)
+                if (/^[A-Z]/.test(componentName)) {
+                    componentUsages.push({
+                        component: componentName,
+                        type: 'jsx_component',
+                        loc: path.node.loc
+                    });
+                }
+            }
+
+            // Member expression: <Icons.Check />
+            else if (openingElement.name.type === 'JSXMemberExpression') {
+                const object = openingElement.name.object.name;
+                const property = openingElement.name.property.name;
+                componentName = `${object}.${property}`;
+
+                componentUsages.push({
+                    component: componentName,
+                    type: 'jsx_member_component',
+                    loc: path.node.loc
+                });
+            }
+        }
+    });
+
+    return componentUsages;
+}
+
+/**
+ * Detect server/client component boundaries
+ * @param {string} content - File content as string
+ * @returns {Object} Boundary markers
+ */
+function detectServerClientBoundaries(content) {
+    const boundaries = {
+        isClientComponent: false,
+        isServerComponent: false,
+        isServerAction: false
+    };
+
+    if (!content) return boundaries;
+
+    // Check for 'use client' directive
+    if (/['"]use client['"]/.test(content)) {
+        boundaries.isClientComponent = true;
+    }
+
+    // Check for 'use server' directive
+    if (/['"]use server['"]/.test(content)) {
+        boundaries.isServerAction = true;
+    }
+
+    // Server components are the default in Next.js App Router
+    // If no 'use client', it's a server component
+    if (!boundaries.isClientComponent && !boundaries.isServerAction) {
+        boundaries.isServerComponent = true;
+    }
+
+    return boundaries;
+}
+
+/**
+ * Detect API route dependencies
+ * @param {Object} ast - Babel AST
+ * @returns {Array} Array of API route dependencies
+ */
+function detectAPIRouteDependencies(ast) {
+    const apiDeps = [];
+
+    if (!ast) return apiDeps;
+
+    traverse(ast, {
+        // Detect Next.js API route handlers: export async function GET/POST/etc
+        ExportNamedDeclaration(path) {
+            const node = path.node;
+
+            if (node.declaration && node.declaration.type === 'FunctionDeclaration') {
+                const funcName = node.declaration.id ? node.declaration.id.name : null;
+
+                // Check if it's a Next.js route handler
+                if (['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS'].includes(funcName)) {
+                    apiDeps.push({
+                        handler: funcName,
+                        type: 'api_route_handler',
+                        loc: node.loc
+                    });
+                }
+            }
+        },
+
+        // Detect fetch calls and database queries within API routes
+        CallExpression(path) {
+            const callee = path.node.callee;
+
+            // Database queries
+            if (callee.type === 'MemberExpression') {
+                const objectName = callee.object.name;
+                const methodName = callee.property.name || callee.property.value;
+
+                // Supabase queries
+                if (objectName === 'supabase' || /supabase/i.test(objectName)) {
+                    apiDeps.push({
+                        service: 'supabase',
+                        method: methodName,
+                        type: 'database_query',
+                        loc: path.node.loc
+                    });
+                }
+
+                // Prisma queries
+                if (objectName === 'prisma' || /prisma/i.test(objectName)) {
+                    apiDeps.push({
+                        service: 'prisma',
+                        method: methodName,
+                        type: 'database_query',
+                        loc: path.node.loc
+                    });
+                }
+            }
+        }
+    });
+
+    return apiDeps;
+}
+
+/**
+ * Detect middleware dependencies
+ * @param {Object} ast - Babel AST
+ * @param {string} filePath - File path to check if it's middleware
+ * @returns {Array} Array of middleware dependencies
+ */
+function detectMiddlewareDependencies(ast, filePath = '') {
+    const middlewareDeps = [];
+
+    // Check if this is a middleware file
+    const isMiddleware = /middleware\.(ts|js)$/.test(filePath);
+
+    if (!isMiddleware || !ast) return middlewareDeps;
+
+    traverse(ast, {
+        // Detect middleware function export
+        ExportNamedDeclaration(path) {
+            const node = path.node;
+
+            if (node.declaration && node.declaration.type === 'FunctionDeclaration') {
+                const funcName = node.declaration.id ? node.declaration.id.name : null;
+
+                if (funcName === 'middleware') {
+                    middlewareDeps.push({
+                        function: funcName,
+                        type: 'middleware_function',
+                        loc: node.loc
+                    });
+                }
+            }
+        },
+
+        // Detect auth checks and redirects
+        CallExpression(path) {
+            const callee = path.node.callee;
+
+            if (callee.type === 'MemberExpression') {
+                const methodName = callee.property.name || callee.property.value;
+
+                // Auth verification
+                if (methodName === 'getUser' || methodName === 'getSession') {
+                    middlewareDeps.push({
+                        service: 'auth',
+                        method: methodName,
+                        type: 'auth_check',
+                        loc: path.node.loc
+                    });
+                }
+
+                // Redirects
+                if (methodName === 'redirect' || methodName === 'rewrite') {
+                    middlewareDeps.push({
+                        service: 'next',
+                        method: methodName,
+                        type: 'middleware_action',
+                        loc: path.node.loc
+                    });
+                }
+            }
+        }
+    });
+
+    return middlewareDeps;
+}
+
+/**
+ * Detect all React/Next.js patterns
+ * @param {Object} ast - Babel AST
+ * @param {string} content - File content
+ * @param {string} filePath - File path
+ * @returns {Object} All detected patterns
+ */
+function detectReactNextJSPatterns(ast, content = '', filePath = '') {
+    return {
+        componentUsages: detectComponentUsage(ast),
+        boundaries: detectServerClientBoundaries(content),
+        apiDependencies: detectAPIRouteDependencies(ast),
+        middlewareDependencies: detectMiddlewareDependencies(ast, filePath)
+    };
+}
+
+module.exports = {
+    detectComponentUsage,
+    detectServerClientBoundaries,
+    detectAPIRouteDependencies,
+    detectMiddlewareDependencies,
+    detectReactNextJSPatterns
+};

package/src/core/readme-generator.js

@@ -0,0 +1,167 @@
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+/**
+ * Get the current git commit hash
+ * @returns {string} Commit hash or 'unknown' if git is not available
+ */
+function getCommitHash() {
+    try {
+        const result = spawnSync('git', ['rev-parse', 'HEAD'], {
+            stdio: ['pipe', 'pipe', 'pipe']
+        });
+        
+        if (result.status === 0) {
+            return result.stdout.toString().trim();
+        }
+        return 'unknown';
+    } catch (error) {
+        return 'unknown';
+    }
+}
+
+/**
+ * Generate the README content for the ArcVision system context artifact
+ * @param {string} commitHash - Git commit hash
+ * @param {string} timestamp - Generation timestamp
+ * @param {string} toolVersion - ArcVision tool version
+ * @param {Object} blastRadiusData - Blast radius analysis data
+ * @returns {string} Formatted README content
+ */
+function generateReadmeContent(commitHash, timestamp, toolVersion, blastRadiusData = null) {
+    let content = `# ArcVision System Context Artifact
+
+
+## What This Is [arcvision.context.json](./arcvision.context.json)
+
+This file is the **canonical structural context** of this codebase.
+It represents how the system actually works — not how it is described.
+
+It is generated directly from source code by ArcVision.
+
+## What This Replaces
+
+This artifact replaces:
+- Manual repository scanning
+- Tribal knowledge held by senior engineers
+- Re-explaining the system to new developers
+- Re-prompting LLMs with partial or incorrect context
+- Guessing blast radius of changes
+
+## When You Must Use This
+
+Use this artifact when:
+- Onboarding a new developer
+- Prompting an AI assistant about this codebase
+- Making architectural changes
+- Investigating unexpected behavior
+- Assessing risk before modifying core modules
+
+## What This Artifact Contains
+
+- Canonical module and dependency graph
+- Execution and data flow relationships
+- Structural roles (service, store, boundary, etc.)
+- Invariants inferred from the system
+- Impact metrics (blast radius, coupling)
+- Authority core identification
+- Hidden coupling detection
+- Architectural archetype classification
+- Analysis completeness metrics
+
+## Determinism & Trust
+
+- Generated from commit: ${commitHash}
+- Generation timestamp: ${timestamp}
+- Tool version: ${toolVersion}
+- Deterministic: same input → same output
+- Explicit assumptions listed inside the artifact
+
+If this artifact conflicts with human memory, **trust the artifact**.`;
+
+    // Add blast radius information if available
+    if (blastRadiusData && blastRadiusData.topFiles && blastRadiusData.topFiles.length > 0) {
+        content += `
+
+## Structural Context Hubs
+
+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) {
+                warningMessage = 'Changes here may silently propagate across the system.';
+            } else if (index === 1) {
+                warningMessage = 'Acts as a coordination layer between components.';
+            } else {
+                warningMessage = 'Modifications can cause widespread inconsistencies.';
+            }
+            
+            content += `- **${item.file}**
+  - Blast Radius: ${item.blastRadius} files (${item.percentOfGraph}% of codebase)
+  - Risk: ${warningMessage}
+
+`;
+        });
+    } else {
+        content += `
+
+## Structural Context Hubs
+
+No high-structure files detected based on import dependencies.`;
+    }
+    
+    content += `
+
+## How to Use With AI
+
+When prompting AI tools, include this file as system context.
+Do not ask the AI to infer architecture without it.
+
+## When to Regenerate
+
+Regenerate this artifact when:
+- Core modules change
+- New services are added
+- Dependency structure shifts
+
+Run:
+
+\`\`\`
+arcvision scan --upload
+\`\`\`
+
+## Source of Truth
+
+This artifact is the **source of truth** for system structure.
+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`;
+    
+    return content;
+}
+
+/**
+ * Generate and save the README file
+ * @param {string} outputDir - Directory to save the README
+ * @param {string} toolVersion - ArcVision tool version
+ * @param {Object} blastRadiusData - Blast radius analysis data
+ */
+function generateReadme(outputDir, toolVersion, blastRadiusData = null) {
+    const commitHash = getCommitHash();
+    const timestamp = new Date().toISOString();
+    const readmeContent = generateReadmeContent(commitHash, timestamp, toolVersion, blastRadiusData);
+    
+    const readmePath = path.join(outputDir, 'README.md');
+    fs.writeFileSync(readmePath, readmeContent);
+    
+    console.log(`✅ System context README generated at ${readmePath}`);
+}
+
+module.exports = { generateReadme, generateReadmeContent, getCommitHash };
+
+

package/src/core/retry-handler.js

@@ -0,0 +1,57 @@
+const chalk = require('chalk');
+
+class RetryHandler {
+  constructor(maxRetries = 3, baseDelay = 1000, backoffMultiplier = 2) {
+    this.maxRetries = maxRetries;
+    this.baseDelay = baseDelay;
+    this.backoffMultiplier = backoffMultiplier;
+  }
+
+  async executeWithRetry(operation, context = '') {
+    let lastError;
+    
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      try {
+        if (attempt > 0) {
+          const delay = this.baseDelay * Math.pow(this.backoffMultiplier, attempt - 1);
+          console.log(chalk.yellow(`Retry attempt ${attempt}/${this.maxRetries} for ${context} after ${delay}ms delay...`));
+          
+          // Wait before retrying
+          await this.sleep(delay);
+        }
+        
+        const result = await operation(attempt);
+        return { success: true, result, attempts: attempt + 1 };
+      } catch (error) {
+        lastError = error;
+        
+        // Don't log error on final attempt since caller will handle it
+        if (attempt < this.maxRetries) {
+          console.log(chalk.red(`Attempt ${attempt + 1} failed for ${context}: ${error.message}`));
+        }
+      }
+    }
+    
+    return { success: false, error: lastError, attempts: this.maxRetries + 1 };
+  }
+
+  sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+
+  // Specific retry for network requests
+  async executeNetworkRequest(url, options, context = 'network request') {
+    return this.executeWithRetry(async (attempt) => {
+      const response = await fetch(url, options);
+      
+      if (!response.ok) {
+        const errorText = await response.text().catch(() => 'Unknown error');
+        throw new Error(`HTTP ${response.status}: ${errorText}`);
+      }
+      
+      return await response.json();
+    }, context);
+  }
+}
+
+module.exports = RetryHandler;