Coder.Rs

Local Deterministic AI Architect for Rust and Go

Modern AI assistants for code review suffer from three systemic flaws: they demand massive context windows, are highly prone to hallucinations due to fuzzy knowledge stored in their weights, and generate an excessive amount of text "noise."

coder.rs solves this problem by radically decoupling the Reasoning Engine (a small, local LLM) from the Rule Book (an embedded knowledge base). The model does not invent rules on the fly; instead, it acts as a forensic expert matching code against a strict engineering code of law.

---

1. Core Axioms

• Axiom 1: Logic over Erudition. The model does not need broad world knowledge. It relies on a small local model (7B–8B parameters, quantized via IQ3_K_XS or using a native ternary 1.58-bit architecture) optimized for advanced engineering reasoning (Chain-of-Thought), algorithmic logic, and software architecture.
• Axiom 2: Deterministic Knowledge Base. Best practices, anti-patterns, style guides, and dependency nuances are extracted directly from a database, not from the model's weights. Knowledge is completely decoupled: swapping the underlying database instantly shifts the tool's context from Rust to Go.
• Axiom 3: Dense Context and Multi-Pass Execution. The model never analyzes an entire repository in a single pass. The architecture uses a hierarchical execution tree (Active-Harness), where each step operates on a surgically precise, isolated snippet of code paired with one specific rule.
• Axiom 4: Balanced Evaluation Polarity. The goal of a code review is not purely criticism. The system is designed to look for hidden architectural landmines (minuses) while equally highlighting elegant, idiomatic solutions (pluses) to reinforce excellent engineering practices across the team.
• Axiom 5: Complete Autonomy and Statelessness. The utility runs locally and privately without leaving a footprint on disk. The reference knowledge base and the transient AST graph are spun up entirely in-memory (Kuzu DB) upon invocation and wiped clean instantly on exit.

---

2. Technology Stack

Component	Technology	Role in the System
Core & Orchestration	Rust (tokio, serde)	Delivers speed, type safety, concurrency, and deterministic control over VRAM/RAM allocation.
Syntax Engine	Tree-sitter (Queries)	Provides lightning-fast, fault-tolerant code indexing, extracting functions, structs, and imports even from uncompilable code.
Local Storage	Kuzu DB (In-Memory Mode)	An embedded graph database running entirely in RAM to host the active code layout alongside the expert rule registry.
AI Reasoning Engine	mistral.rs / llama.cpp	Drives local model inference with strict support for Prompt Caching (optimized for models like DeepSeek-R1-Distill / Qwen-2.5-Coder).

---

3. The Active-Harness Pipeline

The engine processes code changes through four strictly isolated phases:

[Git Diff / Source Code]
        │
        ▼ (Step 1: Deterministic)
[Tree-sitter Parser] ──> Populate Kuzu Graph in RAM (Modules, Structs, Functions, Calls)
                          │
                          ▼ (Step 2: Structural Triage)
[Cypher Queries over Rule Templates] ──> Generates Suspicion Map
                                           │
      ┌────────────────────────────────────┘
      ▼ (Step 3: Semantic Pass)
[Parallel LLM Lenses (mistral.rs)] ──> Logic Verification & CoT Reasoning
                                        │
                                        ▼ (Step 4: Synthesis)
[Generate Compact Report (Pluses / Minuses)]

1. Indexing: Tree-sitter parses the modified files (determined via git diff). A transient structural map of the codebase is instantiated inside the in-memory Kuzu instance.
2. Structural Triage: Fast, low-overhead Cypher queries scan the graph for patterns matching known violations (e.g., locking runtimes or wasteful loop allocations). This builds a "suspicion map." The LLM remains completely asleep during this step.
3. Semantic Verification (LLM Lenses): For every flagged point of interest, the Active-Harness extracts a dense context frame (the function's code + the text rule + reference examples). The small model verifies the engineering logic and outputs a binary verdict. Thanks to Prompt Caching, the core theory is retrieved from memory instantly with 0ms overhead.
4. Aggregation: Validated signals are compiled into a highly predictable, syntax-light report, completely stripping out conversational filler or model navel-gazing.

---

4. Distribution and Cargo Integration

The project is compiled into a single monolithic binary. All pre-compiled engineering presets (Rust/Go idioms, extracts from foundational literature like Effective Rust, and official runtime documentations) are baked directly into the executable as serialized Parquet payloads using Rust compilation macros.

Native Cargo Subcommand Integration

The project is distributed as a native plugin for the Rust package manager under the binary name cargo-coder. The developer does not need to configure custom global paths or shell aliases. It seamlessly intercepts commands from the workspace root:

• cargo coder init – Verifies local environment readiness, model weights, and verifies cache states.
• cargo coder review – Automatically detects working tree deltas relative to HEAD or the default branch and runs the analysis.
• cargo coder review --branch main – Explicitly forces code comparison against a specific target branch.

---

5. Sample Terminal Output

$ cargo coder review

[+] INDEXING: 2 files changed, 14 functions mapped. Kuzu graph built in RAM in 12ms.
[*] TRIAGE: 3 structural rule triggers tripped. Launching parallel AI Lenses...
[=] ANALYSIS COMPLETE (mistral.rs + DeepSeek-R1-7B). Elapsed: 4.2s.

--- [ src/wallet.rs ] ---------------------------------------------------------

▲ MINUS | Safety | Line 42 | ID: ASYNC_01
Function: fn transfer_funds
Context: Detected an active std::sync::MutexGuard held across an .await point.
Risk: Causes thread starvation in the Tokio runtime under high concurrent loads.
Remedy: Restrict the lock's lifetime using a block scope { ... } before calling 
        the async boundary, or swap to an asynchronous tokio::sync::Mutex.

▼ PLUS  | Idiomatics | Line 89 | ID: RUST_IDM_04
Function: fn verify_signature
Context: Excellent implementation of the Typestate pattern for transaction validation.
Effect: Guarantees that moving a transaction to a "Sent" state without verification 
        is physically uncompilable. A textbook zero-cost abstraction.

-------------------------------------------------------------------------------
SUMMARY: Critical Issues: 1 | Commendable Patterns: 1 | Cognitive Load: Normal.