红龙代码执行引擎

Prerequisites

• Python >= 3.10
• Poetry
• JDK 17+ (COBOL frontend only)
• Maven (COBOL frontend only)

1. Python dependencies

poetry install

2. ProLeap COBOL bridge (requires JDK 17+ and Maven)

cd proleap-bridge && ./build.sh && cd ..

Ollama requires no API key (runs locally at localhost:11434)

```

LLM resolver: deterministic frontend + LLM resolves external/missing dependencies

result.whole_program_graph — whole-program dependency graph

Example: dependency graph

a = 1
b = 2
c = a + b
d = a * b
e = c + d
f = e - a

def square(x):
    return x * x

g = square(c)
h = g + f
total = h + e + b

Diamond dependencies (c and d both depend on a and b), function calls (g = square(c)), and multi-operand expressions (total = h + e + b). The direct dependency graph (docs/graph.md):

total directly depends on h, e, and b. The transitive closure adds a, c, d, f, and g. See scripts/demo_dataflow.py for the full pipeline (lowering → CFG → reaching definitions → dependency graph → Mermaid visualisation).

Multi-file project — compile directory, browse import graph, debug across modules

poetry run python -m viz project tests/fixtures/projects/python_basic -l python poetry run python -m viz project /path/to/java/project -l java -s 500 ```

Six synchronized panels: Source (span-highlighted), AST (collapsible tree, toggle a), IR (grouped by CFG block), VM State (heap/stack/registers with diff highlighting), CFG (box-drawing graph, toggle g), and Step (delta summary). Arrow keys step forward/backward, space toggles auto-play, d toggles Dataflow mode (replaces AST/VM/CFG with call-graph summaries and whole-program dependency graph, cross-highlights source and IR on function selection), q quits.

The project mode (viz project) compiles an entire directory via compile_directory() and presents a two-phase experience. Phase 1 (Project Overview) shows a box-drawing import DAG and an entry-point picker grouped by module. Select a function or top-level execution to proceed. Phase 2 (Execution) reuses all standard panels with module-aware source switching: as execution crosses module boundaries, the Source and AST panels automatically swap to the active module's content, and the Source title updates to show the current file path. Press p to return to the project overview.

The pipeline result also includes interprocedural analysis (call graph, function summaries, and whole-program dependency graph) when the source contains function definitions. The Dataflow Summary panel (viz/panels/dataflow_summary_panel.py) renders this as a collapsible tree: each function shows its callers, callees, and merged data-flow summaries across call contexts. The Dataflow Graph panel (viz/panels/dataflow_graph_panel.py) renders interprocedural data flow as a collapsible call-chain tree. Top-level call sites are discovered via find_top_level_call_sites, then build_call_chain recursively constructs a per-parameter flow tree for each callee: each parameter's data flows to return endpoints, field writes, or through inner call sites (with argument mapping) into recursive subtrees, with cycle detection via immutable visited sets. The tree widget replaces the previous flat edge list, making multi-level call chains navigable. The legacy annotate_endpoint and render_graph_lines functions remain available for programmatic use.

The lowering trace mode shows four panels: source with highlighted spans, a collapsible tree of handler invocations (which handler processed which AST node), handler details (emitted IR, dispatch type, module), and the full IR output. Click any node in the trace tree to see its handler, emitted instructions, and source location.

The coverage matrix mode displays a cross-language grid showing which AST node types each frontend handles, distinguishing language-specific handlers (✓) from shared/common handlers (✓*). Supports filtering by node type name.

Setup

Full build (including COBOL)

```bash git clone --recurse-submodules https://github.com/avishek-sen-gupta/red-dragon.git cd red-dragon

Minimal build (without COBOL)

git clone https://github.com/avishek-sen-gupta/red-dragon.git
cd red-dragon
poetry install
poetry run python -m pytest tests/unit/ -x -q

All 15 tree-sitter frontends and the LLM frontends work without JDK/Maven. COBOL integration tests skip gracefully when the ProLeap JAR is not present.

Build a CFG (optionally scoped to a single function)

cfg = build_cfg_from_source(source, function_name="factorial")

LLM frontend: the LLM acts as a compiler frontend, lowering source to IR

ProLeap bridge standalone usage

cat myprogram.cbl | java -jar proleap-bridge/target/proleap-bridge-0.1.0-shaded.jar
java -jar proleap-bridge/target/proleap-bridge-0.1.0-shaded.jar myprogram.cbl
java -jar proleap-bridge/target/proleap-bridge-0.1.0-shaded.jar -format TANDEM myprogram.cbl

Usage

poetry run python interpreter.py myfile.py -v            # run on a file
poetry run python interpreter.py myfile.py --ir-only      # inspect IR only
poetry run python interpreter.py myfile.py --cfg-only     # inspect CFG only
poetry run python interpreter.py example.js -l javascript  # non-Python source
poetry run python interpreter.py myfile.py -f llm -v       # LLM frontend
poetry run python interpreter.py myfile.py -f chunked_llm  # chunked LLM frontend
poetry run python interpreter.py example.cob -l cobol         # COBOL via ProLeap bridge
export PROLEAP_BRIDGE_JAR=/path/to/bridge.jar                 # optional: custom bridge JAR path
poetry run python interpreter.py myfile.py --mermaid        # output CFG as Mermaid flowchart
poetry run python interpreter.py myfile.py --mermaid --function foo  # CFG for a single function

Example: CFG

def classify(x):
    if x > 0:
        label = "positive"
    else:
        label = "negative"
    return label

Function bodies appear as subgraphs with dashed call edges (-.->|"call"|) connecting CALL_FUNCTION sites to function entry blocks. Blocks with more than 6 instructions are collapsed to show the first 4 lines, an ... (N more) placeholder, and the terminator — keeping CFG diagrams readable without hiding critical branch/return instructions. All 15 frontends produce the same CFG shape for equivalent logic.

Example: deterministic execution (0 LLM calls)

def factorial(n):
    if n <= 1:
        return 1
    else:
        return n * factorial(n - 1)

result = factorial(5)

[step 4]  call factorial(5) → dispatch to func_factorial_0
[step 53] binop 1 <= 1 = True   ← base case
[step 56] return 1               ← unwind begins
[step 57] 2 * 1 = 2 → 3 * 2 = 6 → 4 * 6 = 24 → 5 * 24 = 120
[step 65] store_var result 120

Final state: result = 120  (67 steps, 0 LLM calls)

The VM also handles — all deterministically:

• Classes & Arrays — heap allocation via Pointer(base, offset) with parameterized types (Pointer[ClassName], Pointer[ElementType]), method dispatch with overload resolution (arity + type + subtype-aware scoring via TypeGraph), field access
• Closures — shared mutable environments (capture-by-reference); mutations persist across calls and are visible to sibling closures
• Byte-addressed memory regions — ALLOC_REGION/WRITE_REGION/LOAD_REGION for COBOL-style REDEFINES overlays
• Named continuations — SET_CONTINUATION/RESUME_CONTINUATION for COBOL PERFORM return semantics
• Data layout preservation — COBOL field names, offsets, lengths, and type metadata attached to VMState.data_layout after execution
• Builtins — len, range, print, int, str, slice, arrayOf/listOf, byte-manipulation primitives, etc. Method builtins (subList, substring, slice, length/size/Length, toString) dispatch through METHOD_TABLE for cross-language collection and string operations. All builtins return a BuiltinResult(value, new_objects, heap_writes) (defined in vm_types.py) instead of raw values — no builtin directly mutates vm.heap. Heap mutations are expressed as data in the result and applied uniformly via StateUpdate, keeping builtins pure and side-effect-free.

The execution engine is split into focused modules under interpreter/vm/: vm_types.py, vm.py, executor.py (34 opcode handlers), builtins.py, unresolved_call.py, and field_fallback.py. Supporting modules: cfg_types.py, run_types.py, registry.py, and cobol/ (COBOL type system, EBCDIC tables, IR encoder/decoder builders).

LLM API keys (optional)

Only needed for --frontend llm or when execution encounters symbolic values:

```bash export ANTHROPIC_API_KEY=sk-... # for Claude (default) export OPENAI_API_KEY=sk-... # for OpenAI export HUGGING_FACE_API_TOKEN=hf_... # for HuggingFace Inference Endpoints

Configurable unresolved call resolution

When the VM encounters a call to an unresolved function (e.g., math.sqrt(16)), the default behavior creates symbolic values that propagate through subsequent computation. The UnresolvedCallStrategy enum controls this:

• SYMBOLIC (default) — creates symbolic placeholders: math.sqrt(16) → sym_N, subsequent sym_N + 1 → sym_M (precision death)
• LLM — makes a lightweight LLM call to get a plausible concrete value: math.sqrt(16) → 4.0, subsequent 4.0 + 1 = 5.0 (precision preserved), with support for side effects via heap_writes/var_writes

from interpreter.run import run
from interpreter.run_types import UnresolvedCallStrategy

vm = run(source, language="python", unresolved_call_strategy=UnresolvedCallStrategy.LLM)

Programmatic API

All CLI pipelines are available as composable functions — no argparse required.

Deterministic (no LLM calls)

```python from interpreter import lower_source, lower_and_infer, dump_ir, build_cfg_from_source, dump_cfg, dump_mermaid, extract_function_source, ir_stats, run from interpreter.constants import Language

source = """ def factorial(n): if n <= 1: return n return n * factorial(n - 1) result = factorial(6) """

Pipeline visualisation

Built-in pipeline visualizer

An interactive TUI for stepping through the full pipeline (source → AST → IR → CFG → execution) is included in viz/:

```bash

Full pipeline: parse → lower → CFG → execute (deterministic, 0 LLM calls)

vm = run(source, language=Language.PYTHON, verbose=True) frame = vm.call_stack[0] print(frame.local_vars["result"]) # 720

#### With LLM calls

result.call_graph — cross-module call graph

Exercism integration suite

The Exercism suite (tests/unit/exercism/) pulls canonical test data from Exercism's problem-specifications and runs solutions in all 15 languages. Each exercise is parametrized across all canonical test cases.

<details> <summary><strong>Exercism exercise breakdown</strong> (click to expand)</summary>

Compare mode — side-by-side across languages

poetry run python -m viz compare c:viz/examples/pointer_demo.c rust:viz/examples/pointer_demo.rs