# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

RPG (Repository Planning Graph) is a TypeScript/Bun implementation of two research papers:
- **RPG-ZeroRepo**: Repository generation from specifications (Intent → Code)
- **RPG-Encoder**: Repository understanding via graph encoding (Code → Intent)

The core data structure is the **Repository Planning Graph (RPG)** - a hierarchical dual-view graph combining semantic features with structural metadata.

## Build & Development Commands

```bash
# Install dependencies
bun install

# Run in development mode (with watch)
bun run dev

# Build for production
bun run build

# Run all tests
bun run test

# Run unit tests only
bun run test:unit

# Run integration tests only
bun run test:integration

# Run single test file
bun run test tests/graph.test.ts

# Run specific test by name
bun run test -t "should create node"

# Watch mode for tests
bun run test:watch

# Test UI (browser-based)
bun run test:ui

# Test with coverage
bun run test:coverage

# Lint
bun run lint

# Lint and auto-fix
bun run lint:fix

# Format code
bun run format

# Type checking
bun run typecheck

# CLI (development)
bun run src/cli.ts encode ./my_project
```

## Architecture

### Core Concepts

**RPG Graph Structure** `G = (V, E)`:
- **Nodes (V)**: Each node contains `{ feature, metadata }` where feature = semantic description, metadata = code entity info
  - `HighLevelNode`: Architectural directories/modules
  - `LowLevelNode`: Atomic implementations (files, classes, functions)
- **Edges (E)**:
  - `FunctionalEdge`: Feature hierarchy (parent-child relationships)
  - `DependencyEdge`: Import/call relationships via AST analysis

### Module Responsibilities

| Module | Purpose |
|--------|---------|
| `src/graph/` | RPG data structures (Node, Edge, GraphStore interface, SQLiteStore, SurrealStore) |
| `src/encoder/` | Code → RPG extraction (semantic lifting, structural reorganization, artifact grounding) |
| `src/zerorepo/` | Intent → Code generation (proposal construction, implementation planning, code generation) |
| `src/tools/` | Agentic tools (SearchNode, FetchNode, ExploreRPG) for graph navigation |
| `src/utils/` | AST parser (tree-sitter), LLM interface (OpenAI/Anthropic), Vector DB (LanceDB) |

### Key Pipelines

**ZeroRepo (Generation)**:
1. Proposal-level: Feature tree → explore-exploit selection → goal-aligned refactoring
2. Implementation-level: File structure → data flow → interface design
3. Code generation: Topological traversal with test-driven validation

**Encoder (Understanding)**:
1. Encoding: Semantic lifting → structural reorganization → artifact grounding
2. Evolution: Commit-level incremental updates (add/modify/delete)
3. Operation: SearchNode, FetchNode, ExploreRPG tools

### GraphStore Implementations

The `GraphStore` interface (`src/graph/store.ts`) defines the storage API for RPG graphs. Two implementations exist:

| Store | Module | Engine | Search |
|-------|--------|--------|--------|
| `SQLiteStore` | `src/graph/sqlite-store.ts` | `better-sqlite3` (WAL mode) | FTS5 full-text search |
| `SurrealStore` | `src/graph/surreal-store.ts` | `surrealdb` + `@surrealdb/node` embedded | BM25 search |

**Import pattern** — store implementations are NOT re-exported from `src/graph/index.ts` to avoid transitive native module loading:
```typescript
// Correct: import directly
import { SQLiteStore } from './graph/sqlite-store'
import { SurrealStore } from './graph/surreal-store'

// Wrong: barrel import will fail in non-Bun environments
// import { SQLiteStore } from './graph'
```

### Key Libraries

- **tree-sitter**: AST parsing for multiple languages
- **lancedb**: Vector DB for semantic search (Bun-native, disk-based)
- **surrealdb** + **@surrealdb/node**: Embedded graph database (mem:// or surrealkv://)
- **@huggingface/transformers**: Local embedding with MongoDB LEAF models
- **zod**: Schema validation for graph data
- **commander**: CLI framework
- **vitest**: Testing framework (Jest-compatible, for MCP compatibility)

## Reference Papers

- RPG-ZeroRepo: https://arxiv.org/abs/2509.16198
- RPG-Encoder: https://arxiv.org/abs/2602.02084
- Paper source files in `docs/arXiv-*/` for implementation details

## MCP Server

RPG provides an MCP (Model Context Protocol) server for Claude Code integration.

### Running the MCP Server

```bash
# Development mode
bun run mcp <rpg-file.json>

# Example with sample fixture
bun run mcp tests/fixtures/sample-rpg.json
```

### Available MCP Tools

| Tool | Description |
|------|-------------|
| `rpg_search` | Semantic code search by features or file patterns |
| `rpg_fetch` | Retrieve entity details, source code, and feature paths |
| `rpg_explore` | Traverse the graph along functional/dependency edges |
| `rpg_encode` | Convert a repository into an RPG |
| `rpg_stats` | Get graph statistics (node/edge counts) |

### Claude Code Configuration

Add to your Claude Code settings (`.claude/settings.json` or `~/.config/claude/settings.json`):

```json
{
  "mcpServers": {
    "rpg": {
      "command": "bun",
      "args": ["run", "/path/to/rpg/src/mcp/server.ts", "/path/to/rpg-file.json"],
      "env": {}
    }
  }
}
```

Or with the installed package:

```json
{
  "mcpServers": {
    "rpg": {
      "command": "rpg-mcp",
      "args": ["/path/to/rpg-file.json"]
    }
  }
}
```

## Design Decisions

- **Vitest over Bun Test**: Jest compatibility for planned MCP server development
- **LanceDB over ChromaDB**: No external server required, Bun-native, disk-based persistence
- **Paper-based implementation**: Original implementation based on research papers, not forked from Microsoft code
- **Dual GraphStore backends**: SQLiteStore (better-sqlite3) and SurrealStore (native graph relations) for evaluation

## Known Gotchas

### better-sqlite3 native bindings
If `better-sqlite3` native bindings are compiled for a different Node.js version, run `npm rebuild better-sqlite3` to recompile them.

### SurrealDB embedded engine limitations
- **No transactions**: `mem://` and `surrealkv://` engines do not support `beginTransaction()`. Use sequential operations instead.
- **option\<T\> fields**: SCHEMAFULL tables with `option<T>` fields reject JS `null`. Omit the field entirely from the content object.
- **ORDER BY**: Fields used in `ORDER BY` must also appear in the `SELECT` clause.
- **No LIKE operator**: Use application-level regex filtering instead.
- **update().patch()**: Expects RFC 6902 JSON Patch operations, not plain objects. Use `UPDATE SET` queries for partial updates.
- **SDK imports**: Use `createNodeEngines` from `@surrealdb/node` and `RecordId`, `Table`, `Surreal` from `surrealdb`.

### Vitest CLI
- `--include` is not a valid CLI option; use positional arguments (`vitest run 'pattern'`) or workspace projects (`--project=unit`)
- Test file naming: `*.integration.test.ts` for integration tests, `*.test.ts` for unit tests

## Semantic Extraction

RPG encoding uses LLM for semantic feature extraction. Options:

| Mode | Performance | Cost | Use Case |
|------|-------------|------|----------|
| `useLLM: true` + Gemini 3 Flash | Best (78% SWE-bench) | Free tier | Recommended default |
| `useLLM: true` + Claude Haiku 4.5 | High (73% SWE-bench) | $1/$5 per 1M | Production fallback |
| `useLLM: true` + GPT-4o | High (70% SWE-bench) | $3/$10 per 1M | Paper baseline |
| `useLLM: false` (heuristic) | ~15% lower | Free | Offline/testing |

## Embedding Options

| Provider | Model | Dimension | Cost |
|----------|-------|-----------|------|
| HuggingFace (local) | MongoDB/mdbr-leaf-ir | 768 | Free |
| HuggingFace (local) | MongoDB/mdbr-leaf-mt | 1024 | Free |
| OpenAI | text-embedding-3-small | 1536 | $0.02/1M |
| OpenAI | text-embedding-3-large | 3072 | $0.13/1M |

### Alternative Embedding Models (Not Yet Implemented)

| Provider | Model | Dimension | Cost | Notes |
|----------|-------|-----------|------|-------|
| Voyage AI | voyage-code-3 | 1024 | $0.18/1M | Code retrieval SOTA |
| Voyage AI | voyage-4 | 1024 | $0.10/1M | Shared embedding space, MoE |
| Google | gemini-embedding-001 | 3072 | Free | MTEB Multilingual #1 |
| Jina AI | jina-embeddings-v3 | 1024 | $0.02/1M | Paper baseline (Agentless) |
