The Problem AI‑assisted development tools struggle to reason about a codebase because they only see isolated files or raw token matches. Engineers end up prompting the model repeatedly, paying token costs, and still missing architectural context.

What This Does codegraph-rust builds a full‑text, type‑aware knowledge graph of a repository. The pipeline runs:

  1. AST + FastML parsing – crates/codegraph-core/src/integration/parser_graph.rs extracts syntax trees and fast‑ML patterns.
  2. LSP resolution – optional, driven by crates/codegraph-core/src/integration/graph_vector.rs when the balanced or full tier is selected.
  3. Enrichment & edge creation – crates/codegraph-mcp/src/indexer.rs adds module‑level import edges, data‑flow links (defines, uses, mutates) and documentation nodes.
  4. Storage – the enriched graph is persisted in SurrealDB via crates/codegraph-graph/src/surrealdb_storage.rs.

The result is a searchable graph where a query returns a function plus its callers, dependencies, and related docs, enabling true architectural reasoning.

How It Is Wired

  • Entry points
  • main in crates/codegraph-graph/src/bin/surreal_smoke_test.rs – a smoke‑test that loads the graph, calls surrealdb_storage::initialize_schema, then traverses ~399 functions.
  • execute in crates/codegraph-mcp-autoagents/src/autoagents/agent_builder.rs:692 – builds an agent context and runs a full indexing pass, reaching 266 functions.
  • Core call flow (illustrated by the internal call graph) 1. execute → create (filesystem via OpenOptions::new().read(true).write(true)). 2. create → index_project (in crates/codegraph-mcp/src/analyzers/lsp.rs) → is_empty (called 190 times). 3. walk (the graph traversal helper) calls insert (143 callers) and node_text (83 callers) repeatedly to build edges. 4. insert populates the in‑memory arena defined in crates/codegraph-core/src/memory/arena.rs (the most‑referenced type, touched by 72 files).
  • External side‑effects
  • Filesystem – creation of index caches (OpenOptions::new().create(true).append(true)) in execute and the smoke test.
  • Database – SurrealDB queries (self.db.query(...).await) in crates/codegraph-mcp/src/indexer.rs and surrealdb_storage.rs.
  • LLM inference – 35 call sites invoke model providers (anthropic_provider.rs, openai_llm_provider.rs) which send HTTP requests.
  • Network – 5 outbound calls for LSP servers or remote model endpoints.
  • Blast‑radius hubs
  • is_empty, insert, and Err are each invoked from >140 locations; changes here ripple widely.
  • The arena module (crates/codegraph-core/src/memory/arena.rs) is imported by 72 files, so API changes must be coordinated.

How To Use It

# Clone and build
git clone https://github.com/moses-y/codegraph-rust
cd codegraph-rust
cargo build --release          # pulls all crates, builds the binary

# Example: run the smoke‑test (validates DB connection & graph load)
cargo run --bin surreal_smoke_test

# Index a project (fast tier)
CODEGRAPH_INDEX_TIER=fast cargo run --bin codegraph \
    -- index --path /path/to/your/repo

Configuration – copy the example files and edit as needed:

cp .env.example .env
cp config/example.toml config/.codegraph.toml

Key settings live in config/.codegraph.toml.example (e.g., indexing.tier, surrealdb.url). No additional scripts are required.

Real‑World Use A CI pipeline can invoke the codegraph binary after each merge to refresh the SurrealDB graph. An internal LLM‑assistant then queries the graph (SELECT * FROM function WHERE name='process_data') to retrieve the function, its callers, and associated documentation, allowing the assistant to suggest impact‑aware changes without re‑parsing the repo.

Code Health & Issues

  • High – GitHub Actions use mutable tags (.github/workflows/*.yml). Pin each action to a commit SHA.
  • High – Several dependencies have published CVEs (e.g., rmcp@0.12.0, crossbeam-utils@0.8). Upgrade to the fixed versions and commit the updated Cargo.lock.
  • High – No LICENSE file; default is “all rights reserved”. Add an MIT or Apache‑2.0 license at the repo root.
  • High – Critical steps in CI discard exit codes (ci-enhanced.yml lines 125, 352). Preserve failures to avoid silent errors.
  • Medium – GITHUB_TOKEN permissions are not scoped; declare least‑privilege permissions.
  • Medium – Large binary (crates/codegraph-vector/tokenizers/qwen2.5-coder.json, 6.7 MiB) should be moved to Git LFS or external storage.
  • Medium – Checkout action retains credentials; set persist-credentials: false.
  • Low – Workflow jobs lack timeout-minutes; add reasonable limits.

No critical findings were reported, but the high‑severity items affect security and legal reuse.

The Bottom Line codegraph-rust delivers a complete, LSP‑enhanced code graph with SurrealDB persistence, enabling agents to reason about architecture rather than raw text. The core is functional and well‑tested, but the repo needs immediate remediation of security‑related CI settings, dependency upgrades, and licensing before production deployment. Suitable for teams that require deep code‑base awareness for AI‑driven tooling.