arcvision 0.2.17 → 0.2.20

package/src/core/feature-manager.js

@@ -0,0 +1,218 @@
+const fs = require('fs');
+const path = require('path');
+
+class FeatureManager {
+  /**
+   * Determines which ArcVision features are available based on existing artifacts
+   */
+  static getAvailableFeatures(projectPath) {
+    const artifacts = this.checkArtifacts(projectPath);
+    
+    const features = {
+      basic_analysis: artifacts.context_exists,
+      invariant_checking: artifacts.invariants_exists,
+      authority_governance: artifacts.ledger_exists,
+      advanced_reporting: artifacts.readme_exists,
+      context_visualization: artifacts.context_exists,
+      architectural_health: artifacts.context_exists && artifacts.invariants_exists
+    };
+    
+    return {
+      available: Object.entries(features)
+        .filter(([_, available]) => available)
+        .map(([feature, _]) => feature),
+      all: features,
+      artifacts: artifacts
+    };
+  }
+
+  /**
+   * Checks for the presence of key artifacts
+   */
+  static checkArtifacts(projectPath) {
+    return {
+      context_exists: fs.existsSync(path.join(projectPath, 'arcvision_context', 'arcvision.context.json')),
+      invariants_exists: fs.existsSync(path.join(projectPath, '.arcvision', 'invariants.json')),
+      ledger_exists: fs.existsSync(path.join(projectPath, 'arcvision_context', 'architecture.authority.ledger.json')),
+      readme_exists: fs.existsSync(path.join(projectPath, 'arcvision_context', 'README.md')),
+      arcvision_dir_exists: fs.existsSync(path.join(projectPath, '.arcvision')),
+      context_dir_exists: fs.existsSync(path.join(projectPath, 'arcvision_context'))
+    };
+  }
+
+  /**
+   * Generates recommendations based on missing features
+   */
+  static getRecommendations(projectPath) {
+    const artifacts = this.checkArtifacts(projectPath);
+    const recommendations = [];
+
+    if (!artifacts.invariants_exists) {
+      recommendations.push({
+        type: 'SETUP',
+        priority: 'HIGH',
+        message: 'Define architectural invariants for governance',
+        action: 'arcvision init-invariants',
+        description: 'Create custom rules to govern your architectural decisions'
+      });
+    }
+
+    if (!artifacts.context_exists) {
+      recommendations.push({
+        type: 'ANALYSIS',
+        priority: 'HIGH',
+        message: 'Generate structural context',
+        action: 'arcvision scan',
+        description: 'Analyze your codebase to understand its structure'
+      });
+    }
+
+    if (!artifacts.ledger_exists) {
+      recommendations.push({
+        type: 'GOVERNANCE',
+        priority: 'MEDIUM',
+        message: 'Enable authority ledger',
+        action: 'arcvision acig',
+        description: 'Track architectural decisions and violations'
+      });
+    }
+
+    if (!artifacts.readme_exists) {
+      recommendations.push({
+        type: 'DOCUMENTATION',
+        priority: 'LOW',
+        message: 'Generate documentation',
+        action: 'arcvision scan',
+        description: 'Create contextual documentation for your architecture'
+      });
+    }
+
+    return recommendations;
+  }
+
+  /**
+   * Generates next steps for users
+   */
+  static getNextSteps(projectPath) {
+    const features = this.getAvailableFeatures(projectPath);
+    const recommendations = this.getRecommendations(projectPath);
+    
+    const steps = [];
+    
+    if (features.available.length === 0) {
+      steps.push({
+        order: 1,
+        action: 'arcvision scan',
+        description: 'Start by scanning your project to generate structural context'
+      });
+    } else if (!features.all.invariant_checking) {
+      steps.push({
+        order: 1,
+        action: 'arcvision init-invariants',
+        description: 'Create invariants to govern your architecture'
+      });
+      steps.push({
+        order: 2,
+        action: 'arcvision acig',
+        description: 'Evaluate your code against the defined invariants'
+      });
+    } else {
+      steps.push({
+        order: 1,
+        action: 'arcvision acig',
+        description: 'Check your code against defined architectural invariants'
+      });
+    }
+    
+    return steps;
+  }
+
+  /**
+   * Gets feature status summary
+   */
+  static getStatusSummary(projectPath) {
+    const features = this.getAvailableFeatures(projectPath);
+    const recommendations = this.getRecommendations(projectPath);
+    const artifacts = this.checkArtifacts(projectPath);
+    
+    return {
+      projectPath,
+      featureCount: features.available.length,
+      availableFeatures: features.available,
+      missingFeatures: Object.entries(features.all)
+        .filter(([_, available]) => !available)
+        .map(([feature, _]) => feature),
+      recommendations: recommendations,
+      artifacts: artifacts,
+      readinessLevel: this.calculateReadinessLevel(features.available.length),
+      nextSteps: this.getNextSteps(projectPath)
+    };
+  }
+
+  /**
+   * Calculates readiness level based on available features
+   */
+  static calculateReadinessLevel(featureCount) {
+    if (featureCount === 0) return 'STARTER';
+    if (featureCount <= 2) return 'BEGINNER';
+    if (featureCount <= 4) return 'INTERMEDIATE';
+    return 'ADVANCED';
+  }
+
+  /**
+   * Generates user-friendly report
+   */
+  static generateUserReport(projectPath) {
+    const status = this.getStatusSummary(projectPath);
+    
+    let report = `🎯 ArcVision Project Status Report\n`;
+    report += `====================================\n\n`;
+    report += `Project: ${path.basename(projectPath)}\n`;
+    report += `Readiness Level: ${status.readinessLevel}\n`;
+    report += `Available Features: ${status.featureCount}/6\n\n`;
+    
+    report += `📋 Available Features:\n`;
+    status.availableFeatures.forEach(feature => {
+      report += `  • ${this.formatFeatureName(feature)}\n`;
+    });
+    
+    if (status.missingFeatures.length > 0) {
+      report += `\n⚠️  Missing Features:\n`;
+      status.missingFeatures.forEach(feature => {
+        report += `  • ${this.formatFeatureName(feature)}\n`;
+      });
+    }
+    
+    if (status.recommendations.length > 0) {
+      report += `\n💡 Recommendations:\n`;
+      status.recommendations.forEach(rec => {
+        report += `  • [${rec.priority}] ${rec.message}\n`;
+        report += `    Run: ${rec.action}\n`;
+      });
+    }
+    
+    report += `\n🚀 Next Steps:\n`;
+    status.nextSteps.forEach(step => {
+      report += `  ${step.order}. ${step.action}\n     ${step.description}\n`;
+    });
+    
+    return report;
+  }
+
+  /**
+   * Formats feature names for display
+   */
+  static formatFeatureName(feature) {
+    const names = {
+      'basic_analysis': 'Basic Code Analysis',
+      'invariant_checking': 'Invariant Checking',
+      'authority_governance': 'Authority Governance',
+      'advanced_reporting': 'Advanced Reporting',
+      'context_visualization': 'Context Visualization',
+      'architectural_health': 'Architectural Health Assessment'
+    };
+    return names[feature] || feature.replace(/_/g, ' ').replace(/\b\w/g, l => l.toUpperCase());
+  }
+}
+
+module.exports = { FeatureManager };

package/src/core/feedback-generator.js

@@ -0,0 +1,260 @@
+const fs = require('fs');
+const path = require('path');
+
+class FeedbackGenerator {
+  /**
+   * Generates comprehensive scan report with structured feedback
+   */
+  static generateScanReport(analysisResults, artifactsCreated, projectPath) {
+    const { FeatureManager } = require('./feature-manager');
+    const features = FeatureManager.getAvailableFeatures(projectPath);
+    
+    return {
+      status: 'SUCCESS',
+      timestamp: new Date().toISOString(),
+      artifacts: {
+        created: artifactsCreated,
+        existing: analysisResults.existingArtifacts,
+        total: artifactsCreated.length + (analysisResults.existingArtifacts?.length || 0)
+      },
+      analysis: {
+        nodes: analysisResults.nodes?.length || 0,
+        edges: analysisResults.edges?.length || 0,
+        symbols: analysisResults.symbols?.length || 0,
+        scanTimeMs: analysisResults.scanTimeMs || 0
+      },
+      features: features,
+      recommendations: this.getRecommendations(analysisResults, projectPath),
+      nextSteps: this.getNextSteps(analysisResults, projectPath),
+      summary: this.generateSummary(analysisResults, artifactsCreated)
+    };
+  }
+
+  /**
+   * Generates recommendations based on analysis results
+   */
+  static getRecommendations(analysisResults, projectPath) {
+    const { FeatureManager } = require('./feature-manager');
+    const recommendations = FeatureManager.getRecommendations(projectPath);
+    
+    // Add specific analysis-based recommendations
+    if (analysisResults.nodes && analysisResults.nodes.length > 100) {
+      recommendations.unshift({
+        type: 'ARCHITECTURE',
+        priority: 'HIGH',
+        message: 'Large codebase detected - consider defining architectural invariants',
+        action: 'arcvision init-invariants',
+        description: 'Protect your architecture as it grows in complexity'
+      });
+    }
+    
+    if (analysisResults.edges && analysisResults.edges.length > 0) {
+      const avgDependencies = analysisResults.edges.length / (analysisResults.nodes?.length || 1);
+      if (avgDependencies > 5) {
+        recommendations.push({
+          type: 'DEPENDENCY',
+          priority: 'MEDIUM',
+          message: 'High average dependencies per file detected',
+          action: 'arcvision acig',
+          description: 'Check for potential architectural violations'
+        });
+      }
+    }
+    
+    return recommendations;
+  }
+
+  /**
+   * Generates next steps based on analysis
+   */
+  static getNextSteps(analysisResults, projectPath) {
+    const { FeatureManager } = require('./feature-manager');
+    const baseSteps = FeatureManager.getNextSteps(projectPath);
+    
+    // Add analysis-specific steps
+    if (analysisResults.nodes && analysisResults.nodes.length > 0) {
+      baseSteps.push({
+        order: baseSteps.length + 1,
+        action: 'arcvision acig',
+        description: 'Evaluate your codebase against architectural invariants'
+      });
+    }
+    
+    return baseSteps;
+  }
+
+  /**
+   * Generates a summary of the scan results
+   */
+  static generateSummary(analysisResults, artifactsCreated) {
+    const nodeCount = analysisResults.nodes?.length || 0;
+    const edgeCount = analysisResults.edges?.length || 0;
+    const symbolCount = analysisResults.symbols?.length || 0;
+    
+    let summary = `Scan completed successfully!\n`;
+    summary += `- Analyzed ${nodeCount} files\n`;
+    summary += `- Found ${edgeCount} dependencies\n`;
+    summary += `- Processed ${symbolCount} symbols\n`;
+    summary += `- Created ${artifactsCreated.length} new artifacts\n`;
+    
+    if (nodeCount > 100) {
+      summary += `- Large project detected (${nodeCount} files)\n`;
+    } else if (nodeCount > 20) {
+      summary += `- Medium-sized project detected\n`;
+    } else {
+      summary += `- Small project detected\n`;
+    }
+    
+    return summary;
+  }
+
+  /**
+   * Generates feedback for ACIG evaluation
+   */
+  static generateAcigReport(evaluation, artifactsUsed) {
+    const decision = evaluation.decision;
+    
+    let report = {
+      decision: decision,
+      timestamp: new Date().toISOString(),
+      artifacts: artifactsUsed,
+      violations: evaluation.violations?.length || 0,
+      affectedFiles: evaluation.changedFiles?.length || 0,
+      invariantCount: evaluation.invariants?.length || 0,
+      message: this.generateAcigMessage(decision, evaluation),
+      details: evaluation.details || {}
+    };
+    
+    return report;
+  }
+
+  /**
+   * Generates user-friendly message for ACIG decision
+   */
+  static generateAcigMessage(decision, evaluation) {
+    switch(decision) {
+      case 'ALLOWED':
+        return '✅ Change allowed - No critical violations detected';
+      case 'RISKY':
+        return `⚠️  Change is risky - ${evaluation.violations?.length || 0} warnings issued`;
+      case 'BLOCKED':
+        return `❌ Change blocked - ${evaluation.violations?.length || 0} critical violations detected`;
+      default:
+        return 'ℹ️  Evaluation completed with neutral result';
+    }
+  }
+
+  /**
+   * Generates structured feedback for CLI commands
+   */
+  static generateCliFeedback(command, result, context = {}) {
+    const timestamp = new Date().toISOString();
+    
+    switch(command) {
+      case 'scan':
+        return {
+          command: 'scan',
+          status: result.success ? 'SUCCESS' : 'FAILURE',
+          timestamp,
+          details: {
+            directory: context.directory,
+            filesProcessed: result.analysis?.nodes?.length,
+            artifactsCreated: result.artifacts?.created?.length,
+            durationMs: result.durationMs
+          },
+          message: result.success 
+            ? `✅ Scan completed successfully in ${result.durationMs}ms` 
+            : `❌ Scan failed: ${result.error}`
+        };
+        
+      case 'acig':
+        return {
+          command: 'acig',
+          status: result.success ? 'SUCCESS' : 'FAILURE',
+          timestamp,
+          details: {
+            decision: result.decision,
+            violations: result.violations?.length,
+            filesEvaluated: result.changedFiles?.length
+          },
+          message: result.success 
+            ? `🔒 ACIG evaluation: ${result.decision}`
+            : `❌ ACIG evaluation failed: ${result.error}`
+        };
+        
+      default:
+        return {
+          command,
+          status: 'UNKNOWN',
+          timestamp,
+          message: `Command ${command} executed`
+        };
+    }
+  }
+
+  /**
+   * Generates progress indicators for long-running operations
+   */
+  static generateProgressIndicator(current, total, operation = 'Processing') {
+    const percentage = Math.round((current / total) * 100);
+    const barLength = 30;
+    const filledLength = Math.round((current / total) * barLength);
+    const bar = '█'.repeat(filledLength) + '░'.repeat(barLength - filledLength);
+    
+    return {
+      percentage,
+      bar,
+      message: `${operation}: ${current}/${total} (${percentage}%)`,
+      isComplete: current >= total
+    };
+  }
+
+  /**
+   * Generates error feedback with actionable information
+   */
+  static generateErrorFeedback(error, operation, context = {}) {
+    return {
+      type: 'ERROR',
+      operation,
+      timestamp: new Date().toISOString(),
+      error: {
+        message: error.message,
+        stack: error.stack,
+        name: error.name
+      },
+      context,
+      suggestion: this.getErrorSuggestion(error, operation)
+    };
+  }
+
+  /**
+   * Provides actionable suggestions for common errors
+   */
+  static getErrorSuggestion(error, operation) {
+    const message = error.message?.toLowerCase() || '';
+    
+    if (message.includes('no such file') || message.includes('enoent')) {
+      return 'Ensure the specified directory exists and contains code files.';
+    }
+    
+    if (message.includes('permission') || message.includes('eacces')) {
+      return 'Check directory permissions and ensure you have read/write access.';
+    }
+    
+    if (message.includes('memory') || message.includes('heap out of memory')) {
+      return 'Try scanning a smaller subset of your project or increase Node.js memory limit.';
+    }
+    
+    if (operation === 'scan' && message.includes('property') && message.includes('undefined')) {
+      return 'This may be a parsing issue with certain file types. Try excluding problematic files.';
+    }
+    
+    if (operation === 'acig' && message.includes('invariant')) {
+      return 'Check your invariants file (.arcvision/invariants.json) for correct format.';
+    }
+    
+    return 'Review the error message above and check the ArcVision documentation for troubleshooting tips.';
+  }
+}
+
+module.exports = { FeedbackGenerator };

package/src/core/invariant-analyzer.js

@@ -77,7 +77,17 @@ class InvariantAnalyzer {
       }
       
       if (invariant.scope) {
-        const scopeKey = invariant.scope.toLowerCase();
+        // Handle both old string format and new object format for scope
+        let scopeKey;
+        if (typeof invariant.scope === 'string') {
+          scopeKey = invariant.scope.toLowerCase();
+        } else if (typeof invariant.scope === 'object' && invariant.scope.files) {
+          // For object format with files array, categorize based on presence of files
+          scopeKey = 'module'; // Default to module for file-based scopes
+        } else {
+          scopeKey = 'module'; // Default fallback
+        }
+        
         if (categorized.by_scope[scopeKey]) {
           categorized.by_scope[scopeKey].push(invariant);
         }
@@ -253,7 +263,17 @@ class InvariantAnalyzer {
     score += Math.min(criticalCount * 10, 30); // Up to 30 points for critical invariants
     
     // Boost for system scope invariants
-    const systemCount = invariants.filter(inv => inv.scope === 'system').length;
+    const systemCount = invariants.filter(inv => {
+      if (typeof inv.scope === 'string') {
+        return inv.scope === 'system';
+      } else if (typeof inv.scope === 'object') {
+        // Consider as system scope if it has system-level characteristics
+        return inv.scope.files && Array.isArray(inv.scope.files) && inv.scope.files.some(file => 
+          file && typeof file === 'string' && (file.includes('/core/') || file.includes('/lib/') || file.includes('/shared/'))
+        );
+      }
+      return false;
+    }).length;
     score += Math.min(systemCount * 5, 20); // Up to 20 points for system invariants
     
     // Cap the score