Skip to content

COMPILATION_STRATEGY.md

Latest commit

 

History

History
416 lines (315 loc) · 9.82 KB

COMPILATION_STRATEGY.md

File metadata and controls

416 lines (315 loc) · 9.82 KB

Compilation Strategy - User-Controlled Optional Feature

Purpose: Explains when and why compilation happens in V9 analysis Created: October 2, 2025 Status: Architecture Decision

🎯 Key Principle

Compilation is a USER-CONTROLLED OPTIONAL FEATURE, not a requirement.

Users choose between:

  1. Fast analysis (~30s) - No compilation, 4 tools
  2. Deep analysis (~110s) - With compilation, 5 tools (includes SpotBugs)

⚡ Performance Trade-offs

Option 1: Fast Analysis (Default)

Time: ~27-32 seconds
Tools: 4/5 (80% coverage)

✅ PMD (22s)           - Static analysis, code quality
✅ Checkstyle (<1s)    - Code style violations
✅ Semgrep (5s)        - Security vulnerabilities
✅ Dependency-Check (5s) - CVE detection
❌ SpotBugs (SKIPPED)  - Requires compilation

Use Cases:
- Quick PR reviews
- CI/CD pipelines with tight time budgets
- Initial analysis before deep dive
- Repositories without build tools

Option 2: Deep Analysis (Optional)

Time: ~110 seconds (77s compile + 33s analysis)
Tools: 5/5 (100% coverage)

⏱️  COMPILATION (77s) - ONE-TIME COST
✅ PMD (22s)
✅ Checkstyle (<1s)
✅ Semgrep (5s)
✅ SpotBugs (5s)       - Bytecode-level bug detection
✅ Dependency-Check (5s)

Use Cases:
- Comprehensive security audits
- Pre-release validation
- Critical bug hunting
- Production deployment reviews

🔧 User Configuration

Configuration Example

interface AnalysisConfig {
  // Tool enablement
  tools: {
    pmd: boolean;              // Default: true
    checkstyle: boolean;       // Default: true
    semgrep: boolean;          // Default: true
    dependencyCheck: boolean;  // Default: true
    spotbugs: boolean;         // Default: false ← USER CHOOSES
  };

  // Compilation settings
  compilation: {
    enabled: boolean;          // Default: false ← USER CHOOSES
    timeout: number;           // Default: 300000 (5 minutes)
    cacheEnabled: boolean;     // Default: true
  };
}

User Workflow

User opens PR for review:

┌─────────────────────────────────────┐
│ "Analyze this PR"                   │
│                                     │
│ Quick Analysis (30s)  [Start] ◄─── Default
│ Deep Analysis (110s)  [Start]      │
│                                     │
│ ☑ Include SpotBugs (requires       │
│   compilation: +80 seconds)        │
└─────────────────────────────────────┘

If user selects Deep Analysis:
  ✅ Compilation happens ONCE
  ✅ All agents (Security, Quality, Performance) use compiled classes
  ✅ SpotBugs enabled for all agents

🏗️ V9ToolOrchestrator Implementation

Decision Flow

class V9ToolOrchestrator {
  async analyzePR(
    prUrl: string,
    config: AnalysisConfig
  ): Promise<AnalysisResult> {

    // 1. Clone repository
    const repoPath = await this.cloneRepository(prUrl);

    // 2. Detect build tools (always detect, even if not compiling)
    const buildInfo = await detectBuildTools(repoPath);
    logger.info(`Build tool detected: ${buildInfo.buildTool.tool}`);
    logger.info(`Supports SpotBugs: ${buildInfo.supportsSpotBugs}`);

    // 3. Decide on compilation
    const shouldCompile =
      config.compilation.enabled &&           // User wants it
      config.tools.spotbugs &&                // SpotBugs enabled
      buildInfo.supportsSpotBugs &&           // Repository supports it
      buildInfo.compilationRequired;          // Java/compiled language

    let compilationResult = null;

    if (shouldCompile) {
      logger.info('🔨 User requested SpotBugs - compiling repository...');
      logger.info(`⏱️  Expected time: ~${this.estimateCompilationTime(buildInfo)}s`);

      compilationResult = await compileRepository(repoPath, buildInfo);

      if (compilationResult.success) {
        logger.info(`✅ Compilation successful in ${compilationResult.duration}ms`);
      } else {
        logger.warn(`❌ Compilation failed - SpotBugs will be skipped`);
        logger.warn(`   Error: ${compilationResult.error}`);
        config.tools.spotbugs = false;  // Disable SpotBugs
      }
    } else {
      logger.info('⏭️  Skipping compilation (SpotBugs not requested)');
    }

    // 4. Run analysis with appropriate tools
    const javaOrchestrator = new JavaToolOrchestrator(config);
    const results = await javaOrchestrator.orchestrate(
      repoPath,
      'pr',
      buildInfo,
      compilationResult
    );

    return results;
  }

  private estimateCompilationTime(buildInfo: RepositoryBuildInfo): number {
    // Rough estimates based on build tool
    const estimates = {
      gradle: 60,   // ~60 seconds average
      maven: 45,    // ~45 seconds average
      ant: 30,      // ~30 seconds average
      bazel: 90     // ~90 seconds average (larger projects)
    };

    return estimates[buildInfo.buildTool.tool] || 60;
  }
}

📊 Compilation Caching

Cache Strategy

Compilation results are cached to avoid re-compiling the same code:

class CompilationCache {
  private cache = new Map<string, {
    commitHash: string;
    compiledAt: Date;
    outputDir: string;
  }>();

  async getOrCompile(
    repoPath: string,
    buildInfo: RepositoryBuildInfo
  ): Promise<CompilationResult> {

    const commitHash = await this.getCommitHash(repoPath);
    const cached = this.cache.get(repoPath);

    // Use cache if same commit
    if (cached?.commitHash === commitHash) {
      const age = Date.now() - cached.compiledAt.getTime();
      logger.info(`✅ Using cached compilation (age: ${Math.round(age / 1000)}s)`);

      return {
        success: true,
        duration: 0,  // No compilation time
        cached: true
      };
    }

    // Compile and cache
    logger.info('🔨 Compiling (no cache available)...');
    const result = await compileRepository(repoPath, buildInfo);

    if (result.success) {
      this.cache.set(repoPath, {
        commitHash,
        compiledAt: new Date(),
        outputDir: buildInfo.buildTool.outputDir!
      });
    }

    return result;
  }
}

Cache Benefits

Same PR, Multiple Analyses:

First analysis:  77s compilation + 33s analysis = 110s
Second analysis:  0s compilation + 33s analysis =  33s ✅
Third analysis:   0s compilation + 33s analysis =  33s ✅

Different PRs, Same Repository:

PR #123 (commit abc123): 77s compilation
PR #124 (commit abc123): 0s compilation (CACHE HIT) ✅
PR #125 (commit def456): 77s compilation (different commit)

🎯 Development Phases (Current Roadmap)

Phase 1: ✅ V9 Java Analysis (CURRENT)

Status: In Development Environment: Oracle Cloud (development/testing) Goal: Complete Java tool integration

Completed:

  • ✅ Docker v6.0 migration (all 5 tools)
  • ✅ Build tool detection
  • ✅ Oracle Cloud validation

Remaining:

  • ⏳ Integrate into V9ToolOrchestrator
  • ⏳ Add compilation caching
  • ⏳ End-to-end testing
  • ⏳ Documentation

NOT doing yet:

  • ❌ Production deployment
  • ❌ API service
  • ❌ Web interface
  • ❌ Production environment setup

Phase 2: ⏳ Python Analysis

After Phase 1 complete

Tools:

  • pylint (code quality)
  • bandit (security)
  • safety (CVE detection)
  • mypy (type checking)

No compilation needed - faster than Java!

Phase 3: ⏳ JavaScript/TypeScript Analysis

After Phase 2 complete

Tools:

  • ESLint (quality + security)
  • npm audit (CVE detection)
  • TypeScript compiler (optional)

Phase 4: ⏳ API Service

After all languages complete

Features:

  • REST API for PR analysis
  • Authentication/authorization
  • Rate limiting
  • Webhook support

Phase 5: ⏳ Web Application

After API complete

Features:

  • Dashboard
  • PR review interface
  • Reports
  • Analytics

Phase 6: ⏳ Production Environment

Final step

Setup:

  • Kubernetes cluster
  • CI/CD pipelines
  • Monitoring & alerts
  • Backup & disaster recovery

🧪 Testing Strategy

Current Focus (Development Phase)

Oracle Cloud = Development/Testing Environment

# Test on Oracle Cloud (development)
ssh opc@oracle-dev "cd /home/opc/codequal && ./test-kafka-analysis.sh"

Results:
- Validates tool functionality
- Measures performance
- Proves architecture works
- NOT production deployment

Local Testing (MacBook)

# Quick validation on local machine
cd /Users/alpinro/Code\ Prjects/codequal/packages/agents
npx tsx /tmp/test-kafka-quick.ts

Results:
- Fast feedback loop
- No PostgreSQL (Dependency-Check skipped)
- 3/5 tools validated
- Perfect for development

Future Testing (Production Phase)

Will add:

  • Load testing
  • Stress testing
  • Security testing
  • Performance benchmarking
  • High availability testing

But not yet - we're still building V9!

📝 Summary

Key Decisions

  1. Compilation is OPTIONAL

    • User chooses: Fast (30s) vs Deep (110s)
    • Not a requirement, not automatic
    • Clear trade-offs presented to user

  2. Cache Everything

    • Same commit = skip re-compilation
    • Shared cache across all agents
    • Significant time savings

  3. Clear Separation

    • V9ToolOrchestrator: Manages compilation
    • JavaToolOrchestrator: Uses compiled classes
    • Agents: Don't know about compilation

  4. Development First

    • Focus on V9 Java completion
    • Validate on Oracle Cloud (dev environment)
    • Production deployment comes LAST

Current Phase

Building V9 Java Analysis

  • ✅ All 5 tools working
  • ✅ Build detection implemented
  • ⏳ Integration in progress
  • ❌ NOT deploying to production yet

After V9 Complete

  • Python tools
  • JavaScript tools
  • API service
  • Web application
  • THEN production

Last Updated: October 2, 2025 Phase: V9 Java Development (1 of 6 phases) Next: Complete V9 integration, then move to Python