understand-rs

Turn any codebase into a searchable knowledge graph.

A Rust reimplementation of Understand-Anything that parses source code using tree-sitter, builds a knowledge graph with petgraph, and supports fuzzy search, dependency analysis, and multiple export formats.

Why This Exists

The original Understand-Anything is a TypeScript-based Claude Code plugin that turns codebases into interactive knowledge graphs. It's powerful, but it requires an LLM for analysis, depends on a running React dashboard, and is tied to the Claude Code ecosystem.

understand-rs strips this down to the essential: a standalone CLI tool that builds a knowledge graph from raw AST parsing. No LLM required. No browser needed. Just pipe it into your existing tools.

	Understand-Anything (TS)	understand-rs (Rust)
Parsing	tree-sitter + LLM agents	tree-sitter only (pure static)
Runtime	Node.js + React dashboard	Single binary, no runtime
Speed	~seconds per file (LLM calls)	~0.1s for entire project
Languages	26+ file types	Rust, Go, TypeScript, JavaScript, Python
Export	JSON + HTML dashboard	JSON, DOT, Mermaid, CSV
Dependencies	npm ecosystem	Zero runtime deps
LLM Required	Yes (multi-agent pipeline)	No
Architecture Detection	LLM-based	Pattern-based heuristics

Features

• Multi-language parsing: Rust, Go, TypeScript, JavaScript, Python via tree-sitter
• Knowledge graph: Nodes (files, functions, classes, structs, traits, imports) + Edges (calls, imports, extends, implements, contains)
• Architecture layer detection: Automatically classifies nodes as API, Service, Data, UI, Utility, Config, or Test
• Fuzzy search: Find any symbol by name with fuzzy matching
• Structured queries: callers:foo, callees:bar, kind:struct, layer:api, lang:rust, deps:Config, rdeps:Handler
• Shortest path: Find dependency chains between any two nodes
• 4 export formats: JSON, DOT (Graphviz), Mermaid, CSV
• Self-analyzing: Can analyze its own source code

Installation

cargo install --path .

Or build from source:

git clone https://github.com/JSLEEKR/understand-rs.git
cd understand-rs
cargo build --release

Usage

Analyze a codebase

# Analyze current directory, output JSON to stdout
understand-rs analyze

# Analyze a specific directory with DOT export
understand-rs analyze ./my-project -f dot -o graph.dot

# Show stats only
understand-rs analyze ./my-project --stats

Query the knowledge graph

# Fuzzy search
understand-rs query "Config" -p ./my-project

# Find all structs
understand-rs query "kind:struct" -p ./my-project

# Find all API layer nodes
understand-rs query "layer:api" -p ./my-project

# Find all callers of a function
understand-rs query "callers:handle_request" -p ./my-project

# Find all callees of a function
understand-rs query "callees:main" -p ./my-project

# Find all imports
understand-rs query "imports:http" -p ./my-project

# Find dependency chain
understand-rs query "deps:Server" -p ./my-project

# Find reverse dependencies
understand-rs query "rdeps:Config" -p ./my-project

# Find shortest path between two nodes
understand-rs query "path: Config -> Server" -p ./my-project

# Filter by language
understand-rs query "lang:rust" -p ./my-project

# Show stats
understand-rs query "stats" -p ./my-project

Export the graph

# Export as JSON
understand-rs export ./my-project -f json -o graph.json

# Export as DOT (for Graphviz)
understand-rs export ./my-project -f dot -o graph.dot
dot -Tpng graph.dot -o graph.png

# Export as Mermaid
understand-rs export ./my-project -f mermaid -o graph.mmd

# Export as CSV
understand-rs export ./my-project -f csv -o graph.csv

Show statistics

understand-rs stats ./my-project

Output:

  Knowledge Graph Statistics

  Root:  ./my-project
  Version:  1.0.0
  Duration:  0.14s

  Nodes
  Total                   735
  Files                    13
  Functions               507
  ...

  Languages
  rust                    735

  Architecture Layers
  api                       5
  service                  12
  utility                  38
  ...

Knowledge Graph Schema

The JSON export follows this schema:

{
  "metadata": {
    "root_path": "./my-project",
    "languages": ["rust", "go"],
    "total_files": 13,
    "total_nodes": 735,
    "total_edges": 1731,
    "analysis_duration_ms": 140,
    "version": "1.0.0"
  },
  "nodes": [
    {
      "id": "src/lib.rs::CodeGraph",
      "name": "CodeGraph",
      "kind": "struct",
      "file_path": "src/lib.rs",
      "line_range": { "start": 15, "end": 28 },
      "layer": "unknown",
      "language": "rust",
      "visibility": "pub",
      "signature": "pub struct CodeGraph {"
    }
  ],
  "edges": [
    {
      "source": "src/lib.rs",
      "target": "src/lib.rs::CodeGraph",
      "kind": "contains"
    }
  ]
}

Node Kinds

Kind	Description
file	Source file
function	Standalone function
method	Method on a type
class	Class (TS/JS/Python)
struct	Struct (Rust/Go)
enum	Enum
interface	Interface (TS/Go)
trait	Trait (Rust)
import	Import statement
export	Export statement
constant	Constant value
variable	Variable declaration
type_alias	Type alias
module	Module/package declaration

Edge Kinds

Kind	Description
contains	File contains a symbol
imports	File imports a module
calls	Function calls another function
extends	Class/struct extends another
implements	Type implements a trait/interface
exports	File exports a symbol
references	Symbol references another
type_dependency	Type depends on another type

Architecture Layers

Layer	Detection Pattern
api	api/, routes/, handlers/, controllers/
service	services/, domain/, core/, business/
data	models/, db/, repository/, schema/
ui	components/, views/, pages/, .tsx
utility	utils/, helpers/, lib/, constants
config	config/, settings/, env/
test	tests/, _test., spec/, __tests__/

Architecture

src/
  lib.rs          -- Public API
  main.rs         -- CLI entry point (clap)
  types.rs        -- Core types (CodeNode, CodeEdge, NodeKind, EdgeKind, etc.)
  error.rs        -- Error types (thiserror)
  parser/
    mod.rs        -- MultiParser dispatcher
    rust_parser.rs    -- Rust tree-sitter parser
    go_parser.rs      -- Go tree-sitter parser
    typescript_parser.rs  -- TypeScript/JavaScript parser
    python_parser.rs  -- Python tree-sitter parser
  graph/
    mod.rs        -- CodeGraph (petgraph-backed knowledge graph)
  query/
    mod.rs        -- Query engine (fuzzy search, structured queries)
  layer/
    mod.rs        -- Architecture layer detection
  export/
    mod.rs        -- Export to JSON, DOT, Mermaid, CSV

Testing

# Run all tests (167 tests)
cargo test

# Run specific test module
cargo test parser::rust_parser
cargo test parser::go_parser
cargo test parser::typescript_parser
cargo test parser::python_parser
cargo test graph
cargo test query
cargo test export
cargo test layer

# Run integration tests
cargo test --test integration_test

License

MIT