RaceLens

Make intermittent async bugs reproducible.

Your application works normally. RaceLens changes the timing of observable async boundaries in a bounded, deterministic session. If a stale response, duplicate mutation, cleanup error, or ordering assumption breaks, RaceLens records the evidence and gives you a seed to replay it.

What it provides

• A deterministic seed and scenario model (RL-XXXXXXXXXXXX).
• A core execution graph independent of VS Code.
• AST-based JavaScript, JSX, TypeScript, and TSX instrumentation with source maps.
• Browser runtime hooks for fetch, Axios, XMLHttpRequest, timers, await boundaries, events, and WebSocket metadata.
• React-aware metadata surfaces for state/effect instrumentation.
• Rule-based findings with confidence, evidence, source locations, and mitigations.
• VS Code Sessions and Findings views, diagnostics, CodeLens, status, and a CSP-protected timeline.
• Safe test runner detection for Vitest and Jest, with no shell interpolation.
• Local-only session storage, redaction, bounded writes, and workspace trust checks.

Demo scenario

Search "lu"
Search "luis"

Normal:   lu → luis ✅
Chaos:    luis → lu 🔥

Finding:  Stale Async Commit
Seed:     RL-8F71A2C4D930

Use the Command Palette:

RaceLens: Analyze Current File
RaceLens: Analyze Selection
RaceLens: Start Live Chaos Mode
RaceLens: Start Live Observation
RaceLens: Stop Live Session
RaceLens: Stress Test Suite (Experimental)
RaceLens: Open Timeline
RaceLens: Replay Seed
RaceLens: Generate Regression Test Scaffold
RaceLens: Verify Fix (Experimental)

The VSIX includes docs/usage.md with the complete workflow, result interpretation, Vite integration, Axios/XMLHttpRequest coverage, and limitations.

Honest scope

The extension is desktop-first because live and test modes execute local project processes. Observation and chaos are explicit actions; opening a workspace never starts npm, Node, Vite, Jest, Vitest, or a browser automatically. Safe chaos delays and reorders observable completions, but it does not duplicate destructive mutations by default.

RaceLens does not claim that no finding means no race exists. It means no race was detected under the schedules that were tested.

Development

The manifest uses the Marketplace publisher id LuisitoHabla.

npm ci
npm run typecheck
npm run lint
npm test
npm run build
npm run verify:release
npm run package

Press F5 in VS Code to launch the Extension Development Host.

Architecture

flowchart LR
  VSCode[VS Code Extension Host] --> Controller[Live/Test Controller]
  Controller --> Core[Core Engine]
  Core --> Scheduler[Deterministic Scheduler]
  Core --> Graph[Execution Graph]
  Core --> Findings[Finding Engine]
  Vite[Vite public plugin hooks] --> Browser[Browser Runtime]
  Node[Node preload/runtime] --> Graph
  Browser --> IPC[Loopback session transport]
  IPC --> Graph
  Findings --> Timeline[Local CSP Timeline]
  Graph --> Store[Global Storage JSONL sessions]

The VSIX includes docs/architecture.md, docs/protocol.md, docs/findings.md, PRIVACY.md, and SECURITY.md.

The verified boundary of this build is recorded in docs/feature-matrix.md. RaceLens does not present partially wired live/test orchestration as a confirmed finding.