From c8a50b5c07fa5046c0a07a637a66095df88df1cd Mon Sep 17 00:00:00 2001 From: ajianaz Date: Thu, 23 Jul 2026 10:55:48 +0700 Subject: [PATCH] docs: add code-intelligence.md, update README + AGENT.md for Phase 1-3 --- AGENT.md | 67 +++++++---- README.md | 38 ++++-- docs/code-intelligence.md | 244 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 317 insertions(+), 32 deletions(-) create mode 100644 docs/code-intelligence.md diff --git a/AGENT.md b/AGENT.md index d1eeead..568bf88 100644 --- a/AGENT.md +++ b/AGENT.md @@ -2,8 +2,10 @@ ## Project Overview -**cora-code** is a Rust CLI tool for AI-powered code review. Bring Your Own Keys (BYOK) — -no managed API, no cloud service. Runs locally against diffs, scans, or branches. +**cora-code** is a Rust CLI for AI-powered code review and code intelligence. +Bring Your Own Keys (BYOK) — no managed API, no cloud service. Runs locally against +diffs, scans, or branches. Includes a built-in symbol index, call graph, and hybrid +semantic search engine (Brain Mode). - **License:** MIT - **Edition:** Rust 2024 (MSRV 1.85) @@ -17,8 +19,8 @@ no managed API, no cloud service. Runs locally against diffs, scans, or branches ```bash cargo build # Build (debug) cargo build --release # Build (release) -cargo test # Run all 567 tests -cargo clippy --all-targets -- -D warnings # Lint (strict) +cargo test # Run all 708 tests (default) / 714 (tree-sitter) +cargo clippy --all-targets -- -D warnings # Lint (strict -D warnings) cargo fmt --all -- --check # Format check ``` @@ -29,26 +31,37 @@ Always run `cargo fmt --all` before committing. CI runs all three checks. ``` src/ ├── main.rs # Entry point, CLI argument parsing +├── data_dir.rs # Global data directory (~/.codecora/cora-code/) ├── commands/ # Subcommand handlers -│ ├── mod.rs │ ├── review.rs # cora review (diff-based review) │ ├── scan.rs # cora scan (full-file scan) -│ ├── debt.rs # cora debt (tech debt report) │ ├── commit_cmd.rs # cora commit (review + commit message + commit) -├── index/ # Symbol index (v0.6 — Code Intelligence) -│ ├── mod.rs # Index engine (open, index_project, search) -│ ├── schema.rs # SQLite schema + FTS5 -│ ├── symbols.rs # SymbolKind, SymbolQuery, SearchResult -│ ├── extract.rs # Per-language definition + call extraction -│ └── graph.rs # Call graph (callers, impact, affected) +│ ├── debt.rs # cora debt (tech debt report) +│ ├── index_cmd.rs # cora index / explore / callers / impact / affected +│ ├── trace_cmd.rs # cora trace (call chain BFS traversal) +│ ├── arch_cmd.rs # cora arch (architecture overview) +│ ├── brain_cmd.rs # cora brain (hybrid semantic search) +│ ├── export_cmd.rs # cora export +│ ├── import_cmd.rs # cora import │ ├── config_cmd.rs # cora config (show/set/validate) │ ├── auth.rs # cora auth (API key management) │ ├── hook_cmd.rs # cora hook (pre-commit hook install/uninstall) │ ├── init.rs # cora init (project scaffolding) │ ├── upload.rs # cora upload (review upload) │ ├── completion.rs # Shell completion generation -│ ├── debt.rs # cora debt (tech debt report) │ └── providers.rs # cora providers (list providers) +├── index/ # Code Intelligence — symbol index + graph + vectors +│ ├── mod.rs # Index engine (open DB, index_project, FTS5 search) +│ ├── schema.rs # SQLite schema v4 + auto-migration (projects, symbols, edges) +│ ├── symbols.rs # SymbolKind, SymbolQuery, SearchResult types +│ ├── extract.rs # 15 language extractors (def + call extraction) +│ ├── graph.rs # Call graph (callers, impact, affected) +│ ├── brain.rs # Hybrid search: FTS5 + usearch KNN + graph BFS → RRF k=60 +│ └── vector.rs # CodeVectorIndex using usearch HNSW (256d, Cosine, F32) +├── embed/ # Embedding engine +│ ├── mod.rs # Re-exports +│ ├── tokens.rs # Static token embedding (256d, zero-dep bag-of-tokens) +│ └── token_vocab.rs # Token vocabulary (reserved for Phase 5 ONNX upgrade) ├── config/ │ ├── mod.rs │ ├── schema.rs # Config structs & defaults @@ -79,7 +92,7 @@ src/ │ ├── mod.rs │ ├── protocol.rs # JSON-RPC 2.0 types │ ├── server.rs # Stdio transport + request dispatch -│ └── tools.rs # 5 tool handlers +│ └── tools.rs # 15 tool handlers (review, search, brain, debt, ...) ├── formatters/ # Output format implementations │ ├── mod.rs │ ├── pretty.rs # Human-readable terminal output @@ -104,14 +117,19 @@ src/ | `config/loader.rs` | Config loading with full priority chain resolution | | `config/schema.rs` | All config structs, defaults, serde annotations | | `commands/init.rs` | Project scaffolding, `.cora.yaml` generation | +| `index/brain.rs` | Hybrid search orchestration (FTS5 + usearch + graph → RRF) | +| `index/vector.rs` | CodeVectorIndex — usearch HNSW wrapper, load/save/insert/search | +| `index/schema.rs` | SQLite schema v4, auto-migration, FTS5 virtual table | +| `embed/tokens.rs` | Static token embedding (256d, zero-dependency) | ## Testing ```bash -cargo test # 567 tests total - # 484 unit tests +cargo test # 708 tests (default) / 714 (tree-sitter) + # 637 unit tests # 16 CLI integration tests # 6 config tests + # 49 tree-sitter tests (opt-in) cargo test --no-verify # Skip pre-commit hooks (avoids timeout in hooks) ``` @@ -240,7 +258,7 @@ Missing any = release blocker. ### 1. Code - [ ] All target issues merged to `develop` -- [ ] `cargo test` — all 567+ tests pass +- [ ] `cargo test` — all 708+ tests pass - [ ] `cargo clippy --all-targets -- -D warnings` — clean - [ ] `cargo fmt --all -- --check` — clean - [ ] `cargo build --release` — no errors @@ -265,6 +283,7 @@ reality BEFORE version bump. | `docs/usage.md` | Review modes, output formats, exit codes up to date. New sections present | | `docs/examples.md` | CI examples work. Marketplace action reference correct. Multi-platform examples present | | `docs/providers.md` | Provider list, default models, env vars accurate | +| `docs/code-intelligence.md` | Index, brain, trace, arch, multi-project DB, data directory | | `docs/installation.md` | Version pin example uses latest. Platforms list accurate | | `AGENT.md` | Code structure tree current. Test count current. Key files table current | | `.agent.md` | Pre-release checklist current. CI checks count current. Module dependencies current | @@ -426,18 +445,18 @@ When submitting cora to directories, aggregators, or showcases (Trendshift, etc. > works with any OpenAI-compatible LLM. Runs locally via CLI, CI/CD, pre-commit hooks, or > as an MCP server for AI coding agents (Claude Code, Cursor, Copilot). > -> Features: diff-based review, static security scanning (11 regex patterns), quality gate -> with configurable thresholds, language-specific analyzers (Dart/Flutter, Svelte, -> TypeScript, Go, Rust, Python), secret detection, custom rule engine, quality profiles, -> auto-chunking for large PRs, and SARIF output for CI integration. +> Features: diff-based AI code review, static security scanning, quality gate, +> language-specific analyzers, secret detection, custom rule engine, code intelligence +> (symbol index, call graph, semantic search via Brain Mode), MCP server with 15 tools, +> SARIF output, and multi-project global database. ### Key Metrics to Mention -- Test count (495+) -- Lines of Rust code (16,800+) +- Test count (708+) +- Lines of Rust code (26,400+) - CI checks (10) - GitHub Marketplace action published -- MCP server with 5 tools +- MCP server with 15 tools - MIT license - Active development cadence diff --git a/README.md b/README.md index 8f04c08..221468b 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ --- -**Cora** is a fast, native CLI that uses any LLM to review your code — in your terminal, CI/CD, git hooks, or directly inside AI coding agents. Bring your own key, pick any model, review in seconds. +**Cora** is a fast, native CLI for AI-powered code review and code intelligence — in your terminal, CI/CD, git hooks, or directly inside AI coding agents. Bring your own key, pick any model, index your codebase, and search semantically. All local, zero cloud. ## Why Cora? @@ -28,7 +28,11 @@ - 📐 **Quality profiles** — strict, balanced, or lax presets for different project needs - 📏 **Custom rule engine** — write your own regex rules in `.cora.yaml` - ✂️ **Auto-chunking** — splits large PRs into reviewable chunks automatically -- 🔌 **MCP server** — expose rules and config to AI agents (Claude Code, Cursor, Copilot, Windsurf) +- 🔍 **Code Intelligence** — index symbols across 15 languages, call graph, trace, impact analysis +- 🧠 **Brain Mode** — hybrid semantic search (FTS5 + vector KNN + graph) with RRF fusion +- 🗄️ **Multi-project database** — one global index, search across all your repos at once +- 🌳 **tree-sitter** (opt-in) — AST-based call graph extraction for Rust, Go, Python, TypeScript +- 🔌 **MCP server** — 15 tools for AI agents (review, search, brain, debt, trace, ...) - 💾 **Diff-hash caching** — skip repeat reviews automatically - 🔧 **Configurable** — per-project `.cora.yaml`, global `~/.cora/config.yaml`, or env vars @@ -172,19 +176,37 @@ Works on **all CI platforms** — [Gitea, GitLab, Bitbucket →](https://codecor ## Commands +### Code Review + | Command | Description | |---------|-------------| -| `cora commit` | Review + generate commit message + commit | -| `cora review` | Review code changes | +| `cora review` | Review code changes (diff, branch, commit, file) | | `cora scan` | Scan files for issues | +| `cora commit` | Review + generate commit message + commit | +| `cora debt` | Show tech debt report from review history | + +### Code Intelligence + +| Command | Description | +|---------|-------------| +| `cora index` | Index project symbols, vectors, and call graph | +| `cora explore` | Search symbols by keyword (FTS5) | +| `cora brain` | Hybrid semantic search (FTS5 + vectors + graph → RRF) | +| `cora trace` | Trace call chains through the codebase | +| `cora arch` | Architecture overview (modules, edges, hotspots) | +| `cora callers` | Find all callers of a symbol | +| `cora impact` | Analyze blast radius of changing a symbol | +| `cora affected` | Find tests impacted by changed files | + +### Config & Setup + +| Command | Description | +|---------|-------------| | `cora init` | Create project config + hook | | `cora auth login` | Save API key | | `cora config show` | Show resolved config | | `cora providers` | List available LLM providers | -| `cora debt` | Show tech debt report from review history | -| `cora review --memory` | Recall project patterns from Uteke before review | -| `cora review --learn` | Recall + save findings to Uteke | -| `cora mcp` | Start MCP server for AI coding agents | +| `cora mcp` | Start MCP server (15 tools) for AI coding agents | | `cora hook install` | Install pre-commit hook | See **[CLI Reference →](https://codecora.dev/cli-reference.html)** for all flags and examples. diff --git a/docs/code-intelligence.md b/docs/code-intelligence.md new file mode 100644 index 0000000..90f7e85 --- /dev/null +++ b/docs/code-intelligence.md @@ -0,0 +1,244 @@ +--- +title: Code Intelligence & Brain Mode +--- + +# Code Intelligence & Brain Mode + +Cora includes a built-in symbol index, call graph, and hybrid semantic search engine. No external services required — everything runs locally. + +## Quick Start + +```bash +# 1. Index your project (extracts symbols, builds vector index) +cora index + +# 2. Search symbols (keyword) +cora explore "authenticate" + +# 3. Semantic search (hybrid: keyword + vector + graph) +cora brain "error handling pattern" + +# 4. Trace call chains +cora trace main + +# 5. View architecture overview +cora arch +``` + +## Indexing + +### `cora index` + +Scans your project, extracts symbol definitions (functions, structs, enums, traits, etc.), and builds: + +| Component | Technology | Storage | +-----------|-----------|---------| +| Symbol table | Regex extractors (15 languages) | SQLite FTS5 | +| Vector embeddings | Static token hashing (256d) | usearch HNSW index | +| Call graph | Regex scope tracking (+ tree-sitter opt-in) | SQLite `edges` table | + +```bash +cora index # Index current project (incremental) +cora index --rebuild # Drop and re-index from scratch +cora index --stats # Show index statistics +cora index --watch # Watch for file changes and auto-update +cora index --prune # Remove symbols from deleted files +``` + +### Supported Languages + +15 language extractors: Rust, Python, TypeScript/TSX, Go, Java, C, Ruby, PHP, Swift, Scala, Lua, Zig, Dart, Kotlin, JavaScript. + +### Multi-Project Index + +All projects share a **single global database**: + +``` +~/.codecora/cora-code/ +├── graph.db # SQLite — symbols, FTS5 index, call edges +└── cora_index.usearch # usearch HNSW — 256d vector embeddings +``` + +Index multiple repos and they all become searchable from any directory: + +```bash +cd ~/repos/my-api && cora index # Index Go project +cd ~/repos/my-app && cora index # Index Flutter project +cd ~/repos/my-lib && cora brain "auth" # Results from ALL indexed projects +``` + +### Environment Override + +```bash +CODECORA_HOME=/custom/path cora index # Use custom data directory +``` + +## Search Commands + +### `cora explore` — Keyword Search + +FTS5 full-text search over symbol names and signatures. + +```bash +cora explore "authenticate" # Search by name +cora explore --kind function # Filter by symbol kind +cora explore --lang rust # Filter by language +cora explore --limit 20 # Max results +cora explore --json # JSON output +``` + +### `cora brain` — Hybrid Semantic Search + +Combines three search signals into ranked results via **Reciprocal Rank Fusion (RRF, k=60)**: + +| Signal | Engine | What it finds | +--------|--------|--------------| +| FTS5 | SQLite keyword match | Exact name/signature matches | +| Vector KNN | usearch HNSW (cosine) | Semantically similar code | +| Graph BFS | Call graph traversal | Related symbols (callers/callees) | + +```bash +cora brain "error handling" # Top 20 results +cora brain "TokenEmbedding" --json # JSON output +cora brain "parsing" --limit 10 # Custom limit +``` + +#### JSON Output + +```json +[ + { + "symbol_id": 935, + "name": "normalize_error_handling", + "kind": "function", + "file": "src/engine/debt_tracker.rs", + "line": 685, + "score": 0.0164, + "signals": ["fts"] + } +] +``` + +The `signals` field shows which search signals matched: `"fts"`, `"vector"`, `"graph"`, or combinations like `["fts", "vector"]`. + +#### Embedding Engine + +Phase 3 uses **static token embeddings** — a zero-dependency bag-of-tokens hashing method that produces 256-dimensional vectors. No model download, no GPU, no external service. + +| Property | Value | +----------|-------| +| Dimensions | 256 (fixed) | +| Method | Bag-of-tokens hashing | +| Dependencies | None (pure Rust) | +| Quality | Good for near-duplicate detection and semantic grouping | + +Future phases will add optional higher-quality embedding models (see Roadmap). + +## Call Graph Commands + +### `cora callers` — Who Calls This? + +Find all symbols that call a given symbol. + +```bash +cora callers "authenticate" # Who calls authenticate? +cora callers --json # JSON output +cora callers --limit 50 # Max results +``` + +### `cora impact` — What Breaks? + +Analyze the blast radius of changing a symbol. + +```bash +cora impact "parse_response" # What depends on this? +cora impact "parse_response" --depth 3 # 3 levels up the call graph +cora impact --json # JSON output +``` + +### `cora trace` — Call Chain Tracing + +Trace execution paths through the call graph. + +```bash +cora trace "main" # Trace outward (callees) +cora trace "handle_request" --incoming # Trace inward (callers) +cora trace "process" --depth 4 # Limit traversal depth +cora trace --json # JSON output +``` + +Requires schema v3 edges table. Enable tree-sitter for AST-based edge extraction: + +```bash +cora index --rebuild # With tree-sitter feature compiled +``` + +### `cora arch` — Architecture Overview + +Display a high-level view of the codebase structure. + +```bash +cora arch # Human-readable overview +cora arch --json # JSON output +``` + +Shows: module breakdown, edge types (calls, imports), and top connector symbols. + +## Test Impact Analysis + +### `cora affected` + +Find tests that are impacted by changed files. + +```bash +cora affected # From git diff +cora affected src/auth.rs src/api.rs # Specific files +cora affected --test-glob "*test*" # Custom test file pattern +cora affected --json # JSON output +``` + +## MCP Integration + +All code intelligence features are available as MCP tools for AI coding agents: + +| Tool | Description | +------|-------------| +| `cora.search_symbols` | FTS5 symbol search | +| `cora.find_callers` | Find callers of a symbol | +| `cora.find_impact` | Impact analysis | +| `cora.find_affected_tests` | Test impact analysis | +| `cora.index_status` | Index statistics | +| `cora.brain_search` | Hybrid semantic search | + +## Data Directory + +``` +~/.codecora/cora-code/ +├── graph.db # SQLite database +│ ├── projects # One row per indexed project +│ ├── symbols # All symbols from all projects +│ ├── symbols_fts # FTS5 virtual table for keyword search +│ ├── edges # Call relationships (caller_id → callee_id) +│ └── reviews # Review history for tech debt tracking +└── cora_index.usearch # usearch HNSW vector index + ├── cora_index.usearch.keys # Key-to-symbol-id mapping + └── cora_index.usearch.lock # File lock (fs2) +``` + +To reset everything: + +```bash +rm -rf ~/.codecora/cora-code/* +cora index --rebuild +``` + +## Schema Versioning + +The database uses automatic migrations. Current schema version: **v4**. + +| Version | Changes | +---------|---------| +| v1 | Initial symbols table + FTS5 | +| v2 | Added language column | +| v3 | Added `edges` table for call graph | +| v4 | Added `embedding_tier`, `embedding_dims`, `embedding_model`, `last_embedded_at` to projects | \ No newline at end of file