CodeRadar v0.6.6

Live semantic graph of your codebase — incremental, queryable, LLM-writable.

CodeRadar maintains an incrementally updatable graph of your code's logical structure, enabling LLMs and developer tools to both query and safely rewrite code through a unified pipeline.

Why CodeRadar

CodeGraph pioneered the semantic code graph for agents — CodeRadar builds on that foundation with capabilities CodeGraph doesn't have:

The key insight: CodeGraph answers "what is this codebase?" — CodeRadar answers that and "what was it yesterday?" and "what would it look like if I changed X?" and "apply that change safely."

Performance

Head-to-head benchmarks (N=5 median, lower is better):

CodeRadar wins on small-to-medium Python/Rust projects due to zero runtime boot overhead. On large TypeScript codebases, CodeGraph's hand-written per-language Rust walkers and flat-buffer emission are still faster than the generic .scm-query engine, but the gap narrowed from 2.77× to 1.75×. See performance-roadmap.md for the optimization backlog.

Architecture

Python Layer (CLI, Visualizers, Framework Resolvers, GraphRAG, MCP Server)
        │
    PyO3 FFI  +  register_synthetic_edge() bridge
        │
Rust Core (ProjectedGraph, Tree-sitter 41-lang, Parallel Extraction,
           Resolution Cascade L1-L3, Query Engine, Mutation Engine, Smell Engine)
        │
    Macrame DB (bitemporal persistence with valid_from/valid_to timestamps)

Quick Start

pip install coderadar-rs

# Initial analysis (includes framework detection)
coderadar init src/

# Query
coderadar query "functions where is_async == true"

# Explore call flows
coderadar explore UserService.create --direction downstream

# Watch for changes
coderadar watch src/ --debounce 50

# Visualize
coderadar visualize module_graph --format graphviz src/

Python API

import coderadar

# Initial analysis
graph = coderadar.analyze("src/")

# Query
for cls in graph.query("classes where inherits_from contains 'BaseModel'"):
    print(cls.name, [m.name for m in cls.methods])

# Framework-aware exploration (Django/Flask/FastAPI/Go/Actix routes included)
flow = graph.explore(["UserService.create"], direction="downstream")

# Callers (includes framework edges: route → handler)
callers = graph.callers_of("views.py::user_detail")

# Update after file change
report = graph.update_file("src/core/engine.py")

# Mutation (LLM-driven)
plan = graph.plan_body_replacement(
    entity_id="src/auth.py::validate_user",
    new_body="    return bool(re.match(r'^[^@]+@[^@]+$', email))",
    dry_run=True
)

# Module children resolution
children = graph.module_children("src/auth.py::auth")
for cls in children["classes"]:
    print(cls["name"], cls["grammar_kind"])

# Temporal queries (Macrame bitemporal)
past = graph.as_of("2026-08-01T00:00:00Z")

Language Support

Resolution Cascade

Stack Graphs (L1 in v3.3 spec) was deferred to post-v1. CodeGraph ships 30+ languages at production scale with zero Stack Graphs dependency — compiler-grade scope disambiguation is not required for MCP agent use cases.

Framework Resolvers

CodeRadar detects and extracts framework-specific patterns that tree-sitter can't see:

Framework edges are registered in the Rust graph — agents can trace from URL patterns to handler functions via callers_of() / callees_of().

v0.6.6 Feature Highlights

• Base-resolution heuristics — language-family filtering (TypeScript/JavaScript treated as one inheritance family), import-aware base resolution, and @//~/ → src/ path-alias normalization. TypeScript import { X, type T } from '...' now parses correctly (previously misclassified as an empty module); ambiguous base candidates are surfaced via index_edge_stats (real-world: 4 → 0)
• Traversal honesty — traverse_unresolved + an MCP warning reveal targets the walk couldn't follow instead of silently truncating; all four mutation renderers emit a loud ⚠️ unverified_sites warning; traverse(as_of=<ts>) now reads the Macrame bitemporal ledger (downstream)
• Correctness fixes — edges were being asserted with the 9999 open sentinel as valid_from (breaking temporal reads); inline date math double-added the epoch offset (every timestamp was ~year 5910); Class.methods is now derived denormalization (query method_count returns real values); get_smells and as_of release the graph read lock before long-running work
• Smell golden tests — exact-signal snapshots for deep-nesting, brain-method, excessive-returns, and a positive god-class fixture
• 574 tests, 0 failures — 207 Rust + 367 Python

v0.6.5 Feature Highlights

• Native Rust code-smell engine — 9 structural smells (god-class, long-method, long-parameter-list, deep-nesting, data-class, high-cyclomatic-complexity, brain-method, excessive-returns, too-many-fields) with severity tiers, exposed via the codegraph_get_smells MCP tool (filter by entity_id and/or rule_id)
• AST metrics pass — cyclomatic complexity, nesting depth, and return count computed during single-pass extraction (Function.metrics), so the engine needs no source re-parse; class-level roll-ups (WMC, max-method cyclomatic, CBO) derived from the resolved graph
• Class-field extraction — class-level @field captures now populate Class.fields (previously always empty), unblocking the class-scope rules
• Generalized traverse binding — native-Rust BFS across all 4 edge kinds (calls, imports, extends, overrides) with py.allow_threads, replacing the pure-Python fallback
• Resolve back-fill — subclasses, importers, and overrides reverse indexes populated (previously silently empty); cross-file MRO; TS/JS extends/implements base capture; Module concepts emitted so IMPORTS edges persist to Macrame
• 556 tests, 0 failures — 200 Rust + 356 Python

v0.6.4 Feature Highlights

• Query engine fixed — Pest WHERE clauses now match (atomic path rule yielded Path([]), non-silent operand/value wrappers fell through to a string-literal arm; name == "x" / name contains "x" / caller_count > 0 all returned 0 rows). Fixed path parsing, operand/value recursion, and Int/Float mixed comparison arms.
• and/or chains fixed — boolean folds panicked (parts.remove(1) assumed the keyword was a pest pair, but string literals are silent); rewritten as left-associative folds.
• imports query fixed — target_kind is now derived from ImportResolution (function/class/module/import/external/wildcard/dynamic/unresolved) so imports where target_kind == "external" works.
• traverse edge filter fixed — codegraph_traverse returned "No neighbors" because the fallback filtered entity kind ("function") against edge types ("calls"); now matches the edge type case-insensitively.
• Anonymous functions skipped — anon callbacks no longer collapse to one empty-name "file::" entity; named functions stay accurate (calls still attributed to enclosing fn via stack frames).
• Query UX — single-quoted strings now parse; empty-query prompt shows even without a loaded graph.
• 531 tests, 0 failures — 180 Rust + 351 Python (extended E2E + TestQueryTool with real-row assertions)

v0.6.3 Feature Highlights

• Mutation safety hardened — stale-write rejection (every edit carries an xxh3_64 content hash of its span, verified before any write → RejectedStale on mismatch) and automatic rollback on tainted updates (backup → atomic write → tree-sitter post-parse → restore on introduced syntax errors)
• WriteGuard wired up — mutation writes are suppressed in a shared process-wide guard so the file watcher doesn't re-index the engine's own writes
• create_entity fixed — language-aware code rendering (Python/Rust/Go/JS/TS/Java/C#/PHP/Ruby), real byte spans for top/end anchors, project-relative path canonicalization
• Honest error reporting — update_file surfaces fully_applied=False instead of swallowing failures; search_similar caches the embedding model
• 524 tests, 0 failures — 176 Rust + 348 Python

v0.6.0 Feature Highlights

• 17 MCP tools — full query surface: explore, search, node, affected, resolve, query (Pest), search_similar (embeddings), module_children, as_of (temporal), traverse (graph walk), replace_body, update_signature, rename, create_entity, compute_embeddings, reindex, update_file
• Embeddings pipeline — compute + store + search_similar across ALL entity types (functions, classes, modules, imports, constants, type aliases); fastembed/BGE-small, xxHash dedup, auto-trigger on first search_similar call
• Mutation pipeline — plan-review-apply via dry_run toggle; rename cascades to all references; create_entity with language-aware placement
• 13 framework resolvers — Django, Flask, FastAPI, Go, Actix, Express, Spring Boot, Laravel, ASP.NET, Rails, NestJS, Vue Router, React Router
• 41 languages — 12 Tier 1, 29 Tier 2, 330+ Tier 3 via tree-sitter-language-pack 1.14
• 509 tests, 0 failures — 168 Rust + 341 Python, full E2E and MCP coverage

v0.5.7 Feature Highlights

• 13 framework resolvers — Django, Flask, FastAPI, Go, Actix, Express, Spring Boot, Laravel, ASP.NET, Rails, NestJS, Vue Router, React Router — detect route registrations, model associations, controller callbacks, and navigation links across 7 languages
• 10 new languages — Bash, Dart, Protobuf, Dockerfile, SQL, HCL, CMake, GraphQL, Erlang, Haskell (28 languages total across 3 tiers)
• QueryPlanner — natural-language intent classifier routing to MacrameQuery primitives
• 476 tests, 0 failures — 163 Rust + 313 Python, full E2E coverage

v0.5.6 Feature Highlights

• 9 framework resolvers — Django, Flask, FastAPI, Go, Actix, Express, Spring Boot, Laravel, ASP.NET — detect route registrations and synthesize handler edges across 6 languages
• 10 new languages — Bash, Dart, Protobuf, Dockerfile, SQL, HCL, CMake, GraphQL, Erlang, Haskell (28 languages total across 3 tiers)
• QueryPlanner — natural-language intent classifier routing to MacrameQuery primitives
• 451 tests, 0 failures — 163 Rust + 288 Python, full E2E coverage

v0.5.4 Feature Highlights

• Single-pass cursor-driven extraction — QueryCursor directly drives entity emission, eliminating the two-pass tag→walk pipeline. Inline fn-ref subtree scanning during function emission. 37% faster on real-world TypeScript codebases.
• Parallel extraction pipeline — 3-phase design: collect → parallel parse/tag/walk (fragment merge) → sequential projection commit.
• 18-language query files — per-language .scm queries with automated compile validation. C/C++ and TypeScript/JavaScript query files split to eliminate grammar mismatches.
• Query compilation caching — CompiledQuery wraps pre-compiled queries + pre-indexed capture tags; compiles once per language, not per file.
• grammar_kind field — raw tree-sitter node kind on every Class entity (e.g. class_declaration/struct for Swift)
• Function-as-value capture — detects self.on_click = handler, callback assignments, return values, kwargs
• Cross-file fn-ref — resolves imported names across module boundaries
• Noise filtering — builtin type filter (70+ types), literal receiver filter, name stoplist (12 names)
• Docstring extraction — preceding comment runs for all languages, not just @docstring captures
• Elixir def/defp — precise extraction via predicate queries
• __all__ detection — =, +=, .extend(), .append() patterns
• module.children() — resolves child entity IDs to full dicts
• Parameter annotations — type annotations extracted and filtered for builtins
• Live file watcher — notify-based debounced watcher with incremental re-indexing
• Graphviz visualizer — call graph rendering with SCC cycle highlighting
• Scoped call resolution — per-file resolution with caller/callee tracking
• Benchmark pipeline — balanced (50 modules × 1000 calls) and heavy (100 modules × 4000 calls) correctness tests

Project Structure

core_indexer/              # Rust core
  queries/                 # 18 .scm query files (one per language)
  src/
    extract/               # Tree-sitter: tagger (query cursor) + walker (hierarchy) + docstring + decorators
    update/                # Incremental diff + patch + WAL
    resolve/               # Resolution cascade (import_graph, orchestrator, signature, cache, stack_graph stub)
    query/                 # Pest grammar + execution engine
    mutation/              # AST-aware refactoring (rope, indent, WriteGuard)
    fs/                    # File watcher (notify) + git integration
    graph.rs               # In-memory ProjectedGraph + parallel extraction + reverse indexes
    smells/                # Native code-smell engine (metrics pass, 9 rules, engine, registry)
    storage.rs             # Macrame concept/edge persistence
    lib.rs                 # PyO3 FFI bindings

py_agent/src/coderadar/    # Python layer
    resolvers/             # 13 framework resolvers: Django, Flask, FastAPI, Go, Actix, Express, Spring Boot, Laravel, ASP.NET, Rails, NestJS, Vue Router, React Router
    embedding/             # Content-addressed dedup
    agent/                 # GraphRAG query pipeline
    lsp/                   # Persistent LSP warm pool
    mutation/              # Tool router for LLM
    mcp/                   # MCP server (explore, node, search, affected, get_smells, …)
    query/                 # Query planner + templates + cache
    visualizers/           # Mermaid + Graphviz (SCC cycle highlighting)

docs/                      # Specifications + code review + performance roadmap
tests/                     # 356 Python tests (E2E, MCP, smells, framework resolvers, benchmarks)

Configuration

# .coderadar.toml
[project]
languages = ["python"]
roots = ["src/", "tests/"]

[resolution]
min_confidence = 0.3

[macrame]
db_path = ".coderadar/store/coderadar.db"

[mutation]
enabled = true
default_dry_run = true

[performance]
worker_threads = 4
debounce_ms = 50

License

MIT — incorporates techniques from CodeGraph (MIT License).