feat: Add execution simulator for LLM-based code tracing

[tosin2013]

Overview

Implement an execution simulator that uses LLM to trace code execution paths without actually running the code. This enables validation of documentation examples by simulating their behavior.

Background

This enhancement supports ADR-010: Executable Documentation Examples from the DocuMCP Orchestrator project. The execution simulator will work with the Call Graph Builder (Issue #72) to trace execution paths through code examples.

Requirements

Core Functionality

• Simulate function calls using LLM reasoning
• Track variable states through execution paths
• Identify potential runtime errors (null refs, type mismatches)
• Generate execution traces for documentation validation

Integration Points

• Consume call graphs from the Call Graph Builder
• Integrate with existing validateCodeExamples() in validate-content.ts
• Provide results to drift detection system

Pydantic Models (from ADR-010)

class ExecutionTrace(BaseModel):
    """Trace of simulated code execution."""
    example_id: str
    entry_point: str
    execution_steps: List[ExecutionStep]
    variables_accessed: Dict[str, VariableState]
    potential_issues: List[str]
    confidence_score: float

class ExecutionStep(BaseModel):
    """Single step in execution trace."""
    line_number: int
    operation: str
    state_changes: Dict[str, Any]
    calls_made: List[str]

Acceptance Criteria

• LLM can simulate execution of TypeScript/JavaScript code examples
• Identifies unreachable code paths
• Detects potential null/undefined access
• Provides confidence scores for simulation accuracy
• Integrates with existing validation pipeline

Dependencies

• Requires: Issue feat: Add LLM integration layer for semantic code analysis #71 (LLM Integration Layer)
• Requires: Issue feat: Add call graph builder for execution path tracing #72 (Call Graph Builder)

Related

• ADR-010: Executable Documentation Examples
• src/tools/validate-content.ts - existing validation infrastructure