@equilateral_ai/mindmeld 3.1.2 → 3.2.0

package/scripts/repo-analyzer.js

@@ -0,0 +1,870 @@
+#!/usr/bin/env node
+
+/**
+ * MindMeld Repository Analyzer
+ *
+ * Rich repository analysis for CLI onboarding. Detects:
+ * - Technology stack (languages, frameworks, build systems)
+ * - Project structure and architecture patterns
+ * - Security anti-patterns (linked to remediation standards)
+ * - Existing documentation and standards
+ *
+ * Based on EquilateralAgents analysis patterns.
+ */
+
+const fs = require('fs').promises;
+const path = require('path');
+
+// ============================================================================
+// SECURITY ANTI-PATTERNS (from securityScanner.js)
+// Each links to relevant standards for remediation
+// ============================================================================
+
+const SECURITY_PATTERNS = {
+  critical: [
+    {
+      name: 'Hardcoded AWS Credentials',
+      pattern: /(?:AWS_ACCESS_KEY_ID|AWS_SECRET_ACCESS_KEY)\s*=\s*["'][A-Z0-9]{20,}["']/gi,
+      description: 'AWS credentials hardcoded in source code',
+      recommendation: 'Use environment variables or AWS Secrets Manager',
+      cwe: 'CWE-798',
+      standardsLink: 'serverless-saas-aws/security/secrets_management.md'
+    },
+    {
+      name: 'Hardcoded API Keys',
+      pattern: /(?:api[_-]?key|apikey|api[_-]?secret)\s*=\s*["'][a-zA-Z0-9_\-]{20,}["']/gi,
+      description: 'API keys hardcoded in source code',
+      recommendation: 'Store API keys in environment variables or secure secret management',
+      cwe: 'CWE-798',
+      standardsLink: 'serverless-saas-aws/security/secrets_management.md'
+    },
+    {
+      name: 'Hardcoded Private Keys',
+      pattern: /-----BEGIN (?:RSA |EC )?PRIVATE KEY-----/gi,
+      description: 'Private cryptographic key found in source code',
+      recommendation: 'Never commit private keys. Use secure key management',
+      cwe: 'CWE-798',
+      standardsLink: 'serverless-saas-aws/security/secrets_management.md'
+    },
+    {
+      name: 'SQL Injection Risk',
+      pattern: /(?:execute|query)\s*\(\s*["'](?:SELECT|INSERT|UPDATE|DELETE)[^"']*["']\s*\+/gi,
+      description: 'SQL query using string concatenation',
+      recommendation: 'Use parameterized queries or prepared statements',
+      cwe: 'CWE-89',
+      standardsLink: 'serverless-saas-aws/backend_handler_standards.md'
+    },
+    {
+      name: 'Command Injection Risk',
+      pattern: /(?:exec|spawn|system)\s*\([^)]*\$\{[^}]+\}[^)]*\)/gi,
+      description: 'Command execution with template literal interpolation',
+      recommendation: 'Validate and sanitize all input before command execution',
+      cwe: 'CWE-78',
+      standardsLink: 'serverless-saas-aws/security/input_validation.md'
+    }
+  ],
+  high: [
+    {
+      name: 'Hardcoded Passwords',
+      pattern: /(?:password|passwd|pwd)\s*=\s*["'][^"']{8,}["']/gi,
+      description: 'Password hardcoded in source code',
+      recommendation: 'Use environment variables or secure credential management',
+      cwe: 'CWE-798',
+      standardsLink: 'serverless-saas-aws/security/secrets_management.md'
+    },
+    {
+      name: 'Weak Hash - MD5',
+      pattern: /createHash\s*\(\s*["']md5["']\s*\)/gi,
+      description: 'MD5 hash algorithm used (cryptographically broken)',
+      recommendation: 'Use SHA-256 or stronger for security-critical operations',
+      cwe: 'CWE-327',
+      standardsLink: 'serverless-saas-aws/security/cryptography.md'
+    },
+    {
+      name: 'Weak Hash - SHA1',
+      pattern: /createHash\s*\(\s*["']sha1["']\s*\)/gi,
+      description: 'SHA1 hash algorithm used (cryptographically weak)',
+      recommendation: 'Use SHA-256 or stronger for security-critical operations',
+      cwe: 'CWE-327',
+      standardsLink: 'serverless-saas-aws/security/cryptography.md'
+    },
+    {
+      name: 'Insecure Random',
+      pattern: /Math\.random\(\)/gi,
+      description: 'Math.random() used (not cryptographically secure)',
+      recommendation: 'Use crypto.randomBytes() for security-sensitive operations',
+      cwe: 'CWE-338',
+      standardsLink: 'serverless-saas-aws/security/cryptography.md'
+    },
+    {
+      name: 'Path Traversal Risk',
+      pattern: /(?:readFile|writeFile|unlink|rmdir)\s*\([^)]*\.\.[\/\\]/gi,
+      description: 'Potential path traversal vulnerability',
+      recommendation: 'Validate paths with path.normalize() and check bounds',
+      cwe: 'CWE-22',
+      standardsLink: 'serverless-saas-aws/security/input_validation.md'
+    }
+  ],
+  medium: [
+    {
+      name: 'eval() Usage',
+      pattern: /\beval\s*\(/gi,
+      description: 'eval() can execute arbitrary code',
+      recommendation: 'Avoid eval(). Use JSON.parse() for JSON or safer alternatives',
+      cwe: 'CWE-95',
+      standardsLink: 'serverless-saas-aws/security/input_validation.md'
+    },
+    {
+      name: 'Insecure Deserialization',
+      pattern: /(?:unserialize|pickle\.loads|yaml\.load\()/gi,
+      description: 'Insecure deserialization pattern',
+      recommendation: 'Use safe deserialization methods and validate input',
+      cwe: 'CWE-502',
+      standardsLink: 'serverless-saas-aws/security/input_validation.md'
+    },
+    {
+      name: 'HTTP instead of HTTPS',
+      pattern: /["']http:\/\/(?!localhost|127\.0\.0\.1)/gi,
+      description: 'HTTP URL found (unencrypted communication)',
+      recommendation: 'Use HTTPS for all external communications',
+      cwe: 'CWE-319',
+      standardsLink: 'serverless-saas-aws/security/transport.md'
+    },
+    {
+      name: 'Disabled Certificate Validation',
+      pattern: /rejectUnauthorized\s*:\s*false/gi,
+      description: 'SSL/TLS certificate validation disabled',
+      recommendation: 'Enable certificate validation for HTTPS connections',
+      cwe: 'CWE-295',
+      standardsLink: 'serverless-saas-aws/security/transport.md'
+    }
+  ],
+  low: [
+    {
+      name: 'Console.log in Production',
+      pattern: /console\.(log|debug|info)\(/gi,
+      description: 'Console logging may expose sensitive information',
+      recommendation: 'Use proper logging frameworks, avoid logging sensitive data',
+      cwe: 'CWE-532',
+      standardsLink: 'serverless-saas-aws/logging_standards.md'
+    },
+    {
+      name: 'Security TODO Comments',
+      pattern: /\/\/\s*(?:TODO|FIXME).*(?:security|password|key|token|auth)/gi,
+      description: 'Security-related TODO/FIXME comment found',
+      recommendation: 'Address security TODOs before production deployment',
+      cwe: 'CWE-1188',
+      standardsLink: null
+    }
+  ]
+};
+
+// ============================================================================
+// TECHNOLOGY DETECTION (from PatternHarvestingAgent.js)
+// ============================================================================
+
+const TECH_SIGNATURES = {
+  // Languages
+  javascript: {
+    extensions: ['.js', '.mjs', '.cjs'],
+    configFiles: ['package.json', 'jsconfig.json'],
+    frameworks: {
+      react: { indicators: ['react', 'react-dom'], configFiles: [] },
+      vue: { indicators: ['vue'], configFiles: ['vue.config.js'] },
+      angular: { indicators: ['@angular/core'], configFiles: ['angular.json'] },
+      express: { indicators: ['express'], configFiles: [] },
+      nest: { indicators: ['@nestjs/core'], configFiles: ['nest-cli.json'] },
+      next: { indicators: ['next'], configFiles: ['next.config.js', 'next.config.mjs'] },
+      gatsby: { indicators: ['gatsby'], configFiles: ['gatsby-config.js'] }
+    }
+  },
+  typescript: {
+    extensions: ['.ts', '.tsx'],
+    configFiles: ['tsconfig.json'],
+    frameworks: {} // Same as JS
+  },
+  python: {
+    extensions: ['.py'],
+    configFiles: ['requirements.txt', 'pyproject.toml', 'setup.py', 'Pipfile'],
+    frameworks: {
+      django: { indicators: ['django'], configFiles: ['manage.py'] },
+      flask: { indicators: ['flask'], configFiles: [] },
+      fastapi: { indicators: ['fastapi'], configFiles: [] }
+    }
+  },
+  java: {
+    extensions: ['.java'],
+    configFiles: ['pom.xml', 'build.gradle', 'build.gradle.kts'],
+    frameworks: {
+      spring: { indicators: ['springframework', 'spring-boot'], configFiles: [] }
+    }
+  },
+  csharp: {
+    extensions: ['.cs'],
+    configFiles: ['*.csproj', '*.sln'],
+    frameworks: {
+      aspnet: { indicators: ['Microsoft.AspNetCore'], configFiles: [] }
+    }
+  },
+  go: {
+    extensions: ['.go'],
+    configFiles: ['go.mod', 'go.sum'],
+    frameworks: {}
+  },
+  rust: {
+    extensions: ['.rs'],
+    configFiles: ['Cargo.toml'],
+    frameworks: {}
+  }
+};
+
+// Build systems and infrastructure
+const INFRASTRUCTURE_SIGNATURES = {
+  docker: {
+    configFiles: ['Dockerfile', 'docker-compose.yml', 'docker-compose.yaml', '.dockerignore']
+  },
+  kubernetes: {
+    configFiles: ['*.yaml', '*.yml'],
+    patterns: [/kind:\s*(?:Deployment|Service|Pod|ConfigMap)/]
+  },
+  terraform: {
+    configFiles: ['*.tf', 'terraform.tfvars']
+  },
+  sam: {
+    configFiles: ['template.yaml', 'template.yml', 'samconfig.toml']
+  },
+  serverless: {
+    configFiles: ['serverless.yml', 'serverless.yaml']
+  },
+  cloudformation: {
+    configFiles: ['cloudformation.yaml', 'cloudformation.yml', 'cfn-*.yaml']
+  }
+};
+
+// ============================================================================
+// PROJECT STRUCTURE PATTERNS (from ProjectStructureDiscoveryAgent.js)
+// ============================================================================
+
+const DIRECTORY_PATTERNS = {
+  backend: ['src/backend', 'backend', 'server', 'api', 'src/server', 'lambda', 'functions'],
+  handlers: ['src/handlers', 'handlers', 'api/handlers', 'lambda/handlers', 'functions'],
+  helpers: ['src/helpers', 'helpers', 'utils', 'lib', 'common', 'shared'],
+  frontend: ['src/frontend', 'frontend', 'client', 'web', 'ui', 'app', 'src/pages', 'src/components'],
+  database: ['database', 'db', 'migrations', 'prisma', 'sql', 'schemas'],
+  tests: ['tests', 'test', '__tests__', 'spec', 'e2e', 'integration'],
+  deployment: ['deployment', 'deploy', 'infrastructure', '.aws-sam', 'cloudformation', 'terraform', 'k8s'],
+  standards: ['.equilateral-standards', '.clinerules', 'standards', '.standards'],
+  docs: ['docs', 'documentation', 'doc']
+};
+
+// ============================================================================
+// DOCUMENTATION PATTERNS (from LibrarianAgent.js)
+// ============================================================================
+
+const DOC_PATTERNS = {
+  readme: {
+    patterns: [/^readme/i, /^README/],
+    description: 'Project README'
+  },
+  adr: {
+    patterns: [/adr[-_]?\d+/i, /decision[-_]record/i, /architecture[-_]decision/i],
+    description: 'Architecture Decision Records'
+  },
+  standards: {
+    patterns: [/standards/i, /guidelines/i, /conventions/i, /coding[-_]style/i],
+    description: 'Coding standards/guidelines'
+  },
+  api: {
+    patterns: [/^api/i, /swagger/i, /openapi/i],
+    description: 'API documentation'
+  },
+  contributing: {
+    patterns: [/contributing/i, /contribution/i],
+    description: 'Contribution guidelines'
+  },
+  changelog: {
+    patterns: [/changelog/i, /history/i, /releases/i],
+    description: 'Change log'
+  }
+};
+
+// ============================================================================
+// SCANNABLE FILES CONFIG
+// ============================================================================
+
+const SCANNABLE_EXTENSIONS = [
+  '.js', '.jsx', '.ts', '.tsx', '.py', '.java', '.go', '.rb', '.php',
+  '.cpp', '.c', '.h', '.cs', '.swift', '.kt', '.rs', '.scala'
+];
+
+const SKIP_DIRECTORIES = [
+  'node_modules', '.git', 'dist', 'build', 'coverage', '.next',
+  'target', 'vendor', '__pycache__', '.gradle', 'bin', 'obj',
+  '.aws-sam', '.serverless', '.terraform'
+];
+
+// ============================================================================
+// ANALYZER CLASS
+// ============================================================================
+
+class RepoAnalyzer {
+  constructor(projectPath) {
+    this.projectPath = projectPath;
+    this.results = {
+      timestamp: new Date().toISOString(),
+      projectPath,
+      projectName: path.basename(projectPath),
+      techStack: {
+        languages: [],
+        frameworks: [],
+        buildSystems: [],
+        infrastructure: []
+      },
+      structure: {
+        type: 'unknown',
+        directories: {},
+        hasTests: false,
+        hasDocs: false,
+        hasStandards: false
+      },
+      documentation: [],
+      securityFindings: {
+        critical: [],
+        high: [],
+        medium: [],
+        low: [],
+        summary: {}
+      },
+      recommendations: []
+    };
+  }
+
+  /**
+   * Run full repository analysis
+   */
+  async analyze(options = {}) {
+    const {
+      scanSecurity = true,
+      maxFiles = 500,
+      verbose = false
+    } = options;
+
+    console.log(`\n🔍 Analyzing repository: ${this.results.projectName}`);
+    console.log('─'.repeat(50));
+
+    try {
+      // 1. Detect technology stack
+      if (verbose) console.log('\n📊 Detecting technology stack...');
+      await this.detectTechStack();
+
+      // 2. Analyze project structure
+      if (verbose) console.log('📁 Analyzing project structure...');
+      await this.analyzeStructure();
+
+      // 3. Discover documentation
+      if (verbose) console.log('📚 Discovering documentation...');
+      await this.discoverDocumentation();
+
+      // 4. Scan for security anti-patterns
+      if (scanSecurity) {
+        if (verbose) console.log('🔒 Scanning for security anti-patterns...');
+        await this.scanSecurity(maxFiles);
+      }
+
+      // 5. Generate recommendations
+      if (verbose) console.log('💡 Generating recommendations...');
+      this.generateRecommendations();
+
+      return this.results;
+    } catch (error) {
+      // Preserve full error context for debugging
+      this.results.error = {
+        message: error.message,
+        code: error.code || 'UNKNOWN',
+        phase: 'analysis'
+      };
+      console.error('Analysis error:', error.message);
+      return this.results;
+    }
+  }
+
+  /**
+   * Detect languages, frameworks, and build systems
+   */
+  async detectTechStack() {
+    const files = await this.getAllFiles(this.projectPath, 2); // Shallow scan first
+    const fileCounts = {};
+    const detectedFrameworks = new Set();
+    const detectedInfra = new Set();
+
+    // Count files by extension
+    for (const file of files) {
+      const ext = path.extname(file).toLowerCase();
+      fileCounts[ext] = (fileCounts[ext] || 0) + 1;
+    }
+
+    // Detect languages
+    for (const [language, config] of Object.entries(TECH_SIGNATURES)) {
+      const hasExtensions = config.extensions.some(ext => fileCounts[ext] > 0);
+      const hasConfig = await this.hasAnyFile(config.configFiles);
+
+      if (hasExtensions || hasConfig) {
+        const count = config.extensions.reduce((sum, ext) => sum + (fileCounts[ext] || 0), 0);
+        this.results.techStack.languages.push({
+          name: language,
+          fileCount: count,
+          hasConfig
+        });
+
+        // Check for frameworks
+        for (const [framework, fwConfig] of Object.entries(config.frameworks || {})) {
+          const hasFramework = await this.detectFramework(framework, fwConfig);
+          if (hasFramework) {
+            detectedFrameworks.add(framework);
+          }
+        }
+      }
+    }
+
+    // Detect infrastructure
+    for (const [infra, config] of Object.entries(INFRASTRUCTURE_SIGNATURES)) {
+      const hasInfra = await this.hasAnyFile(config.configFiles);
+      if (hasInfra) {
+        detectedInfra.add(infra);
+      }
+    }
+
+    this.results.techStack.frameworks = Array.from(detectedFrameworks);
+    this.results.techStack.infrastructure = Array.from(detectedInfra);
+
+    // Sort languages by file count
+    this.results.techStack.languages.sort((a, b) => b.fileCount - a.fileCount);
+  }
+
+  /**
+   * Detect a specific framework
+   */
+  async detectFramework(name, config) {
+    // Check config files
+    if (config.configFiles?.length) {
+      const hasConfig = await this.hasAnyFile(config.configFiles);
+      if (hasConfig) return true;
+    }
+
+    // Check package.json dependencies
+    if (config.indicators?.length) {
+      const packageJson = await this.readPackageJson();
+      if (packageJson) {
+        const allDeps = {
+          ...(packageJson.dependencies || {}),
+          ...(packageJson.devDependencies || {})
+        };
+        return config.indicators.some(ind => allDeps[ind]);
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Analyze project structure
+   */
+  async analyzeStructure() {
+    const discovered = {};
+
+    for (const [category, patterns] of Object.entries(DIRECTORY_PATTERNS)) {
+      for (const pattern of patterns) {
+        const fullPath = path.join(this.projectPath, pattern);
+        try {
+          const stats = await fs.stat(fullPath);
+          if (stats.isDirectory()) {
+            if (!discovered[category]) {
+              discovered[category] = [];
+            }
+            discovered[category].push(pattern);
+          }
+        } catch (error) {
+          // Expected: directory doesn't exist (ENOENT) or not accessible (EACCES)
+          if (error.code !== 'ENOENT' && error.code !== 'EACCES') {
+            console.error(`Unexpected error checking ${pattern}:`, error.message);
+          }
+        }
+      }
+    }
+
+    this.results.structure.directories = discovered;
+    this.results.structure.hasTests = !!discovered.tests?.length;
+    this.results.structure.hasDocs = !!discovered.docs?.length;
+    this.results.structure.hasStandards = !!discovered.standards?.length;
+
+    // Detect project type
+    this.results.structure.type = this.detectProjectType(discovered);
+  }
+
+  /**
+   * Detect project type based on structure
+   */
+  detectProjectType(directories) {
+    const hasBackend = !!directories.backend?.length || !!directories.handlers?.length;
+    const hasFrontend = !!directories.frontend?.length;
+    const hasInfra = this.results.techStack.infrastructure.length > 0;
+
+    if (hasBackend && hasFrontend) return 'fullstack';
+    if (hasBackend && hasInfra) return 'serverless-backend';
+    if (hasBackend) return 'backend';
+    if (hasFrontend) return 'frontend';
+    return 'library';
+  }
+
+  /**
+   * Discover existing documentation
+   */
+  async discoverDocumentation() {
+    const docs = [];
+
+    // Scan root and docs directories
+    const dirsToScan = [this.projectPath];
+    if (this.results.structure.directories.docs) {
+      for (const docDir of this.results.structure.directories.docs) {
+        dirsToScan.push(path.join(this.projectPath, docDir));
+      }
+    }
+
+    for (const dir of dirsToScan) {
+      try {
+        const entries = await fs.readdir(dir);
+        for (const entry of entries) {
+          if (entry.endsWith('.md') || entry.endsWith('.txt')) {
+            const docType = this.categorizeDoc(entry);
+            if (docType) {
+              docs.push({
+                path: path.join(dir, entry),
+                relativePath: path.relative(this.projectPath, path.join(dir, entry)),
+                name: entry,
+                type: docType.type,
+                description: docType.description
+              });
+            }
+          }
+        }
+      } catch (error) {
+        // Expected: directory doesn't exist or not readable
+        if (error.code !== 'ENOENT' && error.code !== 'EACCES') {
+          console.error(`Unexpected error scanning ${dir}:`, error.message);
+        }
+      }
+    }
+
+    this.results.documentation = docs;
+  }
+
+  /**
+   * Categorize a documentation file
+   */
+  categorizeDoc(filename) {
+    for (const [type, config] of Object.entries(DOC_PATTERNS)) {
+      if (config.patterns.some(p => p.test(filename))) {
+        return { type, description: config.description };
+      }
+    }
+    // Generic markdown
+    if (filename.endsWith('.md')) {
+      return { type: 'other', description: 'Documentation' };
+    }
+    return null;
+  }
+
+  /**
+   * Scan for security anti-patterns
+   */
+  async scanSecurity(maxFiles = 500) {
+    const files = await this.getAllFiles(this.projectPath, 10);
+    const scannableFiles = files
+      .filter(f => SCANNABLE_EXTENSIONS.includes(path.extname(f).toLowerCase()))
+      .slice(0, maxFiles);
+
+    let scanned = 0;
+    for (const file of scannableFiles) {
+      try {
+        const content = await fs.readFile(file, 'utf8');
+        const lines = content.split('\n');
+        const relativePath = path.relative(this.projectPath, file);
+
+        for (const [severity, patterns] of Object.entries(SECURITY_PATTERNS)) {
+          for (const pattern of patterns) {
+            const regex = new RegExp(pattern.pattern.source, pattern.pattern.flags);
+
+            lines.forEach((line, lineIndex) => {
+              if (regex.test(line)) {
+                this.results.securityFindings[severity].push({
+                  file: relativePath,
+                  line: lineIndex + 1,
+                  finding: pattern.name,
+                  description: pattern.description,
+                  recommendation: pattern.recommendation,
+                  cwe: pattern.cwe,
+                  standardsLink: pattern.standardsLink,
+                  snippet: line.trim().substring(0, 100)
+                });
+              }
+            });
+          }
+        }
+        scanned++;
+      } catch (error) {
+        // Expected: file not readable or binary file
+        if (error.code !== 'ENOENT' && error.code !== 'EACCES' && !error.message.includes('encoding')) {
+          console.error(`Unexpected error scanning ${file}:`, error.message);
+        }
+      }
+    }
+
+    // Summary
+    this.results.securityFindings.summary = {
+      filesScanned: scanned,
+      critical: this.results.securityFindings.critical.length,
+      high: this.results.securityFindings.high.length,
+      medium: this.results.securityFindings.medium.length,
+      low: this.results.securityFindings.low.length,
+      total: this.results.securityFindings.critical.length +
+             this.results.securityFindings.high.length +
+             this.results.securityFindings.medium.length +
+             this.results.securityFindings.low.length
+    };
+  }
+
+  /**
+   * Generate recommendations based on analysis
+   */
+  generateRecommendations() {
+    const recs = [];
+
+    // Tech stack recommendations
+    const primaryLang = this.results.techStack.languages[0]?.name;
+    if (primaryLang) {
+      recs.push({
+        category: 'standards',
+        priority: 'high',
+        title: `${primaryLang} Standards Available`,
+        description: `Apply ${primaryLang} coding standards and best practices`,
+        standardsPack: `${primaryLang}-standards`
+      });
+    }
+
+    // Infrastructure recommendations
+    if (this.results.techStack.infrastructure.includes('sam')) {
+      recs.push({
+        category: 'standards',
+        priority: 'high',
+        title: 'AWS SAM Standards Available',
+        description: 'Apply serverless Lambda handler patterns and SAM template standards',
+        standardsPack: 'serverless-saas-aws'
+      });
+    }
+
+    // Security recommendations
+    const secSummary = this.results.securityFindings.summary;
+    if (secSummary.critical > 0 || secSummary.high > 0) {
+      recs.push({
+        category: 'security',
+        priority: 'critical',
+        title: 'Security Issues Detected',
+        description: `Found ${secSummary.critical} critical and ${secSummary.high} high severity security issues`,
+        action: 'Review security findings and apply recommended fixes'
+      });
+    }
+
+    // Structure recommendations
+    if (!this.results.structure.hasTests) {
+      recs.push({
+        category: 'quality',
+        priority: 'medium',
+        title: 'No Test Directory Found',
+        description: 'Consider adding automated tests',
+        standardsPack: 'testing-standards'
+      });
+    }
+
+    if (!this.results.structure.hasStandards && !this.results.structure.hasDocs) {
+      recs.push({
+        category: 'documentation',
+        priority: 'low',
+        title: 'No Standards or Documentation Found',
+        description: 'Consider documenting coding standards and architecture decisions',
+        action: 'MindMeld can inject standards based on your tech stack'
+      });
+    }
+
+    this.results.recommendations = recs;
+  }
+
+  // ============================================================================
+  // HELPER METHODS
+  // ============================================================================
+
+  /**
+   * Get all files in a directory recursively
+   */
+  async getAllFiles(dirPath, maxDepth = 10, currentDepth = 0) {
+    const files = [];
+    if (currentDepth >= maxDepth) return files;
+
+    try {
+      const entries = await fs.readdir(dirPath, { withFileTypes: true });
+
+      for (const entry of entries) {
+        const fullPath = path.join(dirPath, entry.name);
+
+        if (entry.isDirectory()) {
+          if (!SKIP_DIRECTORIES.includes(entry.name)) {
+            files.push(...await this.getAllFiles(fullPath, maxDepth, currentDepth + 1));
+          }
+        } else {
+          files.push(fullPath);
+        }
+      }
+    } catch (error) {
+      // Expected: directory not readable or doesn't exist
+      if (error.code !== 'ENOENT' && error.code !== 'EACCES') {
+        console.error(`Unexpected error reading ${dirPath}:`, error.message);
+      }
+    }
+
+    return files;
+  }
+
+  /**
+   * Check if any of the given files exist
+   */
+  async hasAnyFile(patterns) {
+    for (const pattern of patterns) {
+      if (pattern.includes('*')) {
+        // Glob pattern - simplified check
+        const dir = path.dirname(pattern) || '.';
+        const ext = path.extname(pattern);
+        try {
+          const entries = await fs.readdir(path.join(this.projectPath, dir));
+          if (entries.some(e => e.endsWith(ext))) return true;
+        } catch (error) {
+          // Expected: directory doesn't exist
+          if (error.code !== 'ENOENT' && error.code !== 'EACCES') {
+            console.error(`Unexpected error checking ${dir}:`, error.message);
+          }
+        }
+      } else {
+        try {
+          await fs.access(path.join(this.projectPath, pattern));
+          return true;
+        } catch (error) {
+          // Expected: file doesn't exist
+          if (error.code !== 'ENOENT' && error.code !== 'EACCES') {
+            console.error(`Unexpected error checking ${pattern}:`, error.message);
+          }
+        }
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Read package.json if it exists
+   */
+  async readPackageJson() {
+    try {
+      const content = await fs.readFile(path.join(this.projectPath, 'package.json'), 'utf8');
+      return JSON.parse(content);
+    } catch (error) {
+      // Expected: package.json doesn't exist or is invalid JSON
+      if (error.code !== 'ENOENT' && !(error instanceof SyntaxError)) {
+        console.error('Unexpected error reading package.json:', error.message);
+      }
+      return null;
+    }
+  }
+
+  /**
+   * Generate a human-readable summary
+   */
+  getSummary() {
+    const r = this.results;
+    const lines = [];
+
+    lines.push(`\n📦 Project: ${r.projectName}`);
+    lines.push(`   Type: ${r.structure.type}`);
+
+    if (r.techStack.languages.length) {
+      const langs = r.techStack.languages.map(l => `${l.name}(${l.fileCount})`).join(', ');
+      lines.push(`\n🔧 Languages: ${langs}`);
+    }
+
+    if (r.techStack.frameworks.length) {
+      lines.push(`   Frameworks: ${r.techStack.frameworks.join(', ')}`);
+    }
+
+    if (r.techStack.infrastructure.length) {
+      lines.push(`   Infrastructure: ${r.techStack.infrastructure.join(', ')}`);
+    }
+
+    if (r.documentation.length) {
+      lines.push(`\n📚 Documentation found: ${r.documentation.length} files`);
+      for (const doc of r.documentation.slice(0, 5)) {
+        lines.push(`   - ${doc.relativePath} (${doc.description})`);
+      }
+    }
+
+    const sec = r.securityFindings.summary;
+    if (sec.total > 0) {
+      lines.push(`\n🔒 Security findings:`);
+      if (sec.critical) lines.push(`   ⛔ Critical: ${sec.critical}`);
+      if (sec.high) lines.push(`   🔴 High: ${sec.high}`);
+      if (sec.medium) lines.push(`   🟡 Medium: ${sec.medium}`);
+      if (sec.low) lines.push(`   🟢 Low: ${sec.low}`);
+    } else if (sec.filesScanned > 0) {
+      lines.push(`\n✅ No security issues found in ${sec.filesScanned} files scanned`);
+    }
+
+    if (r.recommendations.length) {
+      lines.push(`\n💡 Recommendations:`);
+      for (const rec of r.recommendations) {
+        const icon = rec.priority === 'critical' ? '⛔' : rec.priority === 'high' ? '🔶' : '💡';
+        lines.push(`   ${icon} ${rec.title}`);
+      }
+    }
+
+    return lines.join('\n');
+  }
+}
+
+// ============================================================================
+// CLI ENTRY POINT
+// ============================================================================
+
+async function main() {
+  const args = process.argv.slice(2);
+  const verbose = args.includes('--verbose') || args.includes('-v');
+  const json = args.includes('--json');
+
+  // Filter out flags to get the path
+  const pathArg = args.find(a => !a.startsWith('-'));
+  const projectPath = pathArg || process.cwd();
+
+  const analyzer = new RepoAnalyzer(projectPath);
+  const results = await analyzer.analyze({ verbose });
+
+  if (json) {
+    console.log(JSON.stringify(results, null, 2));
+  } else {
+    console.log(analyzer.getSummary());
+  }
+}
+
+// Export for use as module
+module.exports = { RepoAnalyzer, SECURITY_PATTERNS, TECH_SIGNATURES, DIRECTORY_PATTERNS };
+
+// Run if called directly
+if (require.main === module) {
+  main().catch(error => {
+    console.error('Fatal error:', error.message);
+    process.exit(1);
+  });
+}