CodeScope — Understand Code From the Inside Out

An interactive JavaScript code intelligence lab, visual time-travel debugger, memory universe inspector, and AI-free programming laboratory.

---

What is CodeScope?

CodeScope transforms JavaScript programs into interactive execution experiences. Rather than merely stepping over lines in a conventional debugger, CodeScope allows developers, students, and educators to observe memory, control-flow graphs, variable mutations, and causal chains from the inside out.

• Execution Replay & Time Travel: Step backward and forward through recorded execution, restoring historical snapshots, variable states, and call stacks.
• Predict Before You Run: Predict a variable's value, a loop's iteration count, or a branch decision before execution runs, then compare against the actual engine trace.
• Branch Coverage Explorer: Interactive SVG Control-Flow Graph (CFG) displaying executed branches, loops, and unreached paths.
• Live Memory Universe: Real-time visualization of lexical scopes, variables, and the heap. Accurately exposes object references, aliasing (let b = a), and in-place property mutations.
• Code Change Impact Analyzer: Side-by-side comparison of two code revisions, analyzing source diffs, AST changes, and behavioral execution differences.
• Bug Detective: Select any variable or output to inspect a chronological chain of causal assignments and hypothesis branch conditions.
• Interactive Learning Arena: Built-in curriculum covering closures, shadowing, memory aliasing, and control flow with puzzles and local mastery tracking.
• Shareable Debugging Sessions: Export and import validated .codescope.json trace files with zero remote dependencies or accounts required.

---

Quick Start

1. Prerequisites

• Node.js 18+ (tested on Node.js v24)
• npm or yarn

2. Installation

git clone https://github.com/your-username/CodeScope.git
cd CodeScope
npm install

3. Start Development Server

npm run dev

Open your browser at http://localhost:5173/ to start exploring!

4. Run Test Suite

npm test

Executes the comprehensive Vitest suite covering the AST interpreter, state reconstruction, control flow, bug detective, and session serialization.

5. Production Build

npm run build

---

Architectural Highlights

• AST-Based Stepping Runtime (src/engine/AstInterpreter.ts): Controlled execution engine using Acorn AST parsing, eliminating arbitrary eval() and new Function() for sandboxed safety.
• Explicit Heap Representation (src/engine/Heap.ts): Stable reference identifiers (obj_1, arr_2) tracking object aliasing and mutations across scopes.
• Snapshot Reconstruction (src/history/StateReconstructor.ts): O(1) time-travel scrubber restoring complete scope and heap state at any historical step.
• Deterministic Explanations (src/explanations/DeterministicExplainer.ts): Explains why branches were taken or variables mutated without requiring external language models.

---

Documentation

• Architecture & Design Details
• Supported JavaScript Grammar & Diagnostics
• Security & Sandbox Model
• Trace Schema Specification (codescope-v1)

---

License

MIT License. Crafted for ambitious open-source developer tooling and computer science education.