mirror of https://github.com/compiler-explorer/compiler-explorer.git synced 2025-12-27 11:44:09 -05:00

Files

Matt Godbolt 50ec53d0e7 Add comprehensive Cypress E2E tests for Claude Explain feature (#7751 )

- Add comprehensive test suite covering all Claude Explain functionality:
  - Basic pane opening and consent flow
  - no-ai directive detection
  - API interactions and error handling
  - Options/customization features
  - Caching behavior and persistence
  - Compilation state handling
  - State persistence across page loads

- Fix caching bug in explain-view.ts:
  - Cache was incorrectly implemented as instance variable, losing cached explanations when panes were closed/reopened
  - Made cache static to persist across all pane instances (matches consent persistence pattern)
  - Fixes failing "Caching and reload" Cypress test
  - Aligns implementation with documented behavior: "shared across all explain views in the session"

- Add test utilities and helpers:
  - Monaco editor content manipulation using clipboard events
  - Claude Explain specific helpers moved to test file
  - General utilities remain in utils.ts

- Performance optimizations:
  - Clear Cypress intercepts in afterEach to prevent O(n²) degradation
  - Use :visible selectors to avoid GoldenLayout template elements
  - Proper mock setup timing to prevent race conditions

- Add comprehensive README with lessons learned and best practices

All tests use fake test data (test_first, focus_a, etc.) to clearly distinguish from production values and prevent accidental API calls.

2025-08-05 16:42:48 -05:00

4.7 KiB

Raw Permalink Blame History

Claude Explain

Claude Explain uses Claude AI to provide natural language explanations of assembly code generation, helping users understand how their source code is translated into assembly and what compiler optimizations are applied.

How It Works

Click the "Explain" button in the compiler toolbar to open a dedicated explanation pane
After compilation completes:
- Failed compilations show "Cannot explain: Compilation failed"
- Code with no-ai directive shows a special message
- Otherwise, users consent to sending code and compilation output to the Claude API
Customize explanations by selecting audience level (beginner/intermediate/expert) and explanation type (assembly/source/optimization)
Once consent is given (persisted for the session), Claude analyzes the code and assembly relationship
The markdown-formatted explanation appears with syntax highlighting
Responses are cached client-side (LRU, 200KB limit) and server-side to reduce API costs
Use the reload button to bypass caches and get fresh explanations

Configuration

Add the API endpoint URL to compiler-explorer.*.properties:

explainApiEndpoint=https://api.compiler-explorer.com/explain

The explain button appears automatically when configured.

Privacy Notice

Source code and compilation output are sent to Anthropic's Claude API after explicit user consent
Consent is remembered for the browser session (not stored in cookies/localStorage)
Anthropic does not use the data for model training
Code containing no-ai (case-insensitive) is never sent to the API
Compiler Explorer's privacy policy covers Claude Explain usage

Technical Implementation

Server-side: Single property configuration (API endpoint). Server code: https://github.com/compiler-explorer/explain

Client-side:

ExplainView class (static/panes/explain-view.ts) handles UI, consent, API requests, and caching
explain-view-utils.ts contains testable business logic (validation, formatting, request building)
Uses marked library for markdown rendering with syntax highlighting
LRU cache (200KB limit) shared across all explain views in the session
Theme-aware styling with responsive layout and font scaling

Features:

Loading states with animated spinner
Error handling with helpful messages
Audience/explanation type selectors with Bootstrap popovers
Status bar showing model, token usage, cost estimates, and cache status
Session-persistent consent and user preferences
Reload button to bypass all caches

Testing:

Comprehensive Cypress E2E tests covering UI interactions, consent flow, API mocking, caching behavior, and error handling
Tests verify explain pane functionality, theme persistence, and proper handling of compilation states

API Integration

GET / - Fetch available options:

{
  "audience": [
    {"value": "beginner", "description": "Simple language, explains technical terms"},
    {"value": "intermediate", "description": "Focuses on compiler behavior and choices"},
    {"value": "expert", "description": "Technical terminology, advanced optimizations"}
  ],
  "explanation": [
    {"value": "assembly", "description": "Explains assembly instructions and purpose"},
    {"value": "source", "description": "Maps source code constructs to assembly"},
    {"value": "optimization", "description": "Explains compiler optimizations and transformations"}
  ]
}

POST / - Generate explanation:

{
  "language": "c++",
  "compiler": "GCC 13.2",
  "code": "Source code",
  "compilationOptions": ["-O2", "-std=c++20"],
  "instructionSet": "amd64",
  "asm": ["Assembly output lines"],
  "audience": "intermediate",
  "explanation": "optimization",
  "bypassCache": false
}

Optional fields: audience (default: "beginner"), explanation (default: "assembly"), bypassCache (default: false)

Response:

{
  "status": "success",
  "explanation": "Markdown-formatted explanation",
  "model": "claude-3-sonnet",
  "usage": {"inputTokens": 500, "outputTokens": 300, "totalTokens": 800},
  "cost": {"inputCost": 0.0015, "outputCost": 0.0045, "totalCost": 0.006},
  "cached": false
}

Caching

Multi-level caching reduces API costs and improves response times:

Client-side: LRU cache, cache key from request payload hash
Server-side: Shared cache across users, indicated by cached: true in response
Cache bypass: Reload button sends bypassCache: true for fresh generation
Status display: Shows cache state, models, token usage and cost estimates

Limitations

May not explain every compiler optimization or assembly pattern
Large assemblies may be truncated before sending to API
Requires internet connection for external API access
One explain view per compiler at a time

4.7 KiB Raw Permalink Blame History