simulate_execution
Simulate code execution using LLM to trace paths without running code. Validate documentation examples by predicting behavior, detecting issues like null references or type mismatches, and comparing against expected results.
Instructions
Simulate code execution using LLM to trace execution paths without running the code. Validates documentation examples by predicting behavior, detecting potential issues (null references, type mismatches, unreachable code), and comparing against expected results. Supports building call graphs for complex execution path analysis.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| exampleCode | Yes | The code example to simulate (from documentation) | |
| implementationCode | No | The actual implementation code to trace against (if not using implementationPath) | |
| implementationPath | No | Path to the implementation file (alternative to implementationCode) | |
| entryPoint | No | Function name to start tracing from (auto-detected if not provided) | |
| expectedBehavior | No | Description of expected behavior for validation | |
| options | No |
Implementation Reference
- src/tools/simulate-execution.ts:127-255 (handler)Main execution handler for the 'simulate_execution' tool. Processes inputs, simulates execution using LLM/static analysis, generates trace, validation, summary, and recommendations.export async function handleSimulateExecution( args: SimulateExecutionInput, context?: any, ): Promise<SimulateExecutionResult> { await context?.info?.("đŦ Starting execution simulation..."); const { exampleCode, implementationCode, implementationPath, entryPoint, expectedBehavior, options, } = args; // Get implementation code let implCode = implementationCode; if (!implCode && implementationPath) { try { implCode = await fs.readFile(implementationPath, "utf-8"); await context?.info?.( `đ Loaded implementation from ${path.basename(implementationPath)}`, ); } catch (error) { return { success: false, trace: createEmptyTrace(), summary: `Failed to load implementation file: ${implementationPath}`, recommendations: [ "Verify the implementation path exists and is readable", ], }; } } if (!implCode) { // Use example code as implementation if none provided implCode = exampleCode; await context?.info?.("âšī¸ No implementation provided, using example code"); } // Create simulator const simulator = createExecutionSimulator(options); const isLLMAvailable = simulator.isLLMAvailable(); if (!isLLMAvailable) { await context?.info?.( "â ī¸ LLM not available, using static analysis fallback", ); } try { // Perform simulation await context?.info?.("đ Simulating execution..."); const trace = await simulator.simulateExecution( exampleCode, implCode, entryPoint, ); // Validate against expected behavior if provided let validation: ExampleValidationResult | undefined; if (expectedBehavior) { await context?.info?.("đ Validating against expected behavior..."); validation = await simulator.validateExample( exampleCode, implCode, expectedBehavior, ); } // Build call graph if requested let callGraph: CallGraph | undefined; if (options?.includeCallGraph !== false && implementationPath) { await context?.info?.("đŗ Building call graph..."); try { const astAnalyzer = new ASTAnalyzer(); await astAnalyzer.initialize(); const analysis = await astAnalyzer.analyzeFile(implementationPath); if (analysis && trace.entryPoint) { callGraph = await simulator.buildCallGraph( trace.entryPoint, analysis, ); } } catch (error) { // Call graph is optional, don't fail on error await context?.info?.("â ī¸ Could not build call graph"); } } // Generate summary and recommendations const summary = generateSummary(trace, validation, isLLMAvailable); const recommendations = generateRecommendations(trace, validation); const issueCount = trace.potentialIssues.length; const confidencePercent = Math.round(trace.confidenceScore * 100); const status = issueCount === 0 ? "â No issues found" : `â ī¸ ${issueCount} issue(s) detected`; await context?.info?.(`${status} (${confidencePercent}% confidence)`); return { success: true, trace, validation, callGraph, summary, recommendations, }; } catch (error) { const errorMessage = error instanceof Error ? error.message : "Unknown error"; await context?.info?.(`â Simulation failed: ${errorMessage}`); return { success: false, trace: createEmptyTrace(), summary: `Simulation failed: ${errorMessage}`, recommendations: [ "Check that the code is valid TypeScript/JavaScript", "Verify the implementation is available", "Try with a simpler code example", ], }; } }
- src/tools/simulate-execution.ts:47-122 (registration)Tool registration/definition including name, description, and complete input schema for MCP integration.export const simulateExecution: Tool = { name: "simulate_execution", description: "Simulate code execution using LLM to trace execution paths without running the code. " + "Validates documentation examples by predicting behavior, detecting potential issues " + "(null references, type mismatches, unreachable code), and comparing against expected results. " + "Supports building call graphs for complex execution path analysis.", inputSchema: { type: "object", properties: { exampleCode: { type: "string", description: "The code example to simulate (from documentation)", }, implementationCode: { type: "string", description: "The actual implementation code to trace against (if not using implementationPath)", }, implementationPath: { type: "string", description: "Path to the implementation file (alternative to implementationCode)", }, entryPoint: { type: "string", description: "Function name to start tracing from (auto-detected if not provided)", }, expectedBehavior: { type: "string", description: "Description of expected behavior for validation", }, options: { type: "object", properties: { maxDepth: { type: "number", description: "Maximum call depth to trace (default: 10)", }, maxSteps: { type: "number", description: "Maximum execution steps to simulate (default: 100)", }, timeoutMs: { type: "number", description: "Timeout for simulation in milliseconds (default: 30000)", }, includeCallGraph: { type: "boolean", description: "Include call graph in results (default: true)", }, detectNullRefs: { type: "boolean", description: "Detect potential null/undefined references (default: true)", }, detectTypeMismatches: { type: "boolean", description: "Detect type mismatches (default: true)", }, detectUnreachableCode: { type: "boolean", description: "Detect unreachable code (default: true)", }, confidenceThreshold: { type: "number", description: "Minimum confidence threshold (0-1, default: 0.7)", }, }, }, }, required: ["exampleCode"], }, };
- TypeScript interfaces defining input and output schemas for the tool.export interface SimulateExecutionInput { exampleCode: string; implementationCode?: string; implementationPath?: string; entryPoint?: string; expectedBehavior?: string; options?: SimulationOptions; } /** * Result type for execution simulation */ export interface SimulateExecutionResult { success: boolean; trace: ExecutionTrace; validation?: ExampleValidationResult; callGraph?: CallGraph; summary: string; recommendations: string[]; }
- Helper function to create empty trace for error cases.function createEmptyTrace(): ExecutionTrace { return { exampleId: "error", entryPoint: "unknown", executionSteps: [], variablesAccessed: {}, potentialIssues: [], confidenceScore: 0, executionPath: [], reachedEnd: false, simulationDuration: 0, }; }
- Helper to generate summary from simulation results.function generateSummary( trace: ExecutionTrace, validation?: ExampleValidationResult, isLLMAvailable?: boolean, ): string { const parts: string[] = []; // Analysis mode parts.push( isLLMAvailable ? "Execution simulated using LLM-based analysis" : "Execution analyzed using static analysis (LLM unavailable)", ); // Execution overview parts.push(`Traced ${trace.executionSteps.length} execution step(s)`); parts.push( `${Object.keys(trace.variablesAccessed).length} variable(s) tracked`, ); // Confidence const confidencePercent = Math.round(trace.confidenceScore * 100); let confidenceLabel = "low"; if (confidencePercent >= 80) confidenceLabel = "high"; else if (confidencePercent >= 50) confidenceLabel = "moderate"; parts.push(`Confidence: ${confidencePercent}% (${confidenceLabel})`); // Completion status if (trace.reachedEnd) { parts.push("Execution completed normally"); } else { parts.push( "Execution did not complete (possible early termination or error)", ); } // Issues if (trace.potentialIssues.length > 0) { const errors = trace.potentialIssues.filter( (i) => i.severity === "error", ).length; const warnings = trace.potentialIssues.filter( (i) => i.severity === "warning", ).length; const infos = trace.potentialIssues.filter( (i) => i.severity === "info", ).length; const issueParts: string[] = []; if (errors > 0) issueParts.push(`${errors} error(s)`); if (warnings > 0) issueParts.push(`${warnings} warning(s)`); if (infos > 0) issueParts.push(`${infos} info(s)`); parts.push(`Issues detected: ${issueParts.join(", ")}`); } else { parts.push("No issues detected"); } // Validation result if (validation) { parts.push( validation.isValid ? "Example validation: PASSED" : "Example validation: FAILED", ); if (validation.matchesDocumentation) { parts.push("Behavior matches documentation"); } } return parts.join(". ") + "."; }