📚 rust-relations-explorer — Rust Knowledge Graph System

🛠️ CI and Coverage

CI workflow: .github/workflows/ci.yml
- Runs format check, clippy (deny warnings), build, tests, docs.
Coverage workflow: .github/workflows/coverage.yml
- Installs cargo-tarpaulin and uploads lcov.info.

Run coverage locally:

cargo install cargo-tarpaulin --locked
cargo tarpaulin --engine llvm --out Lcov --timeout 600 --workspace --exclude-files benches/*,examples/*,target/*

📚 rust-relations-explorer — Rust Knowledge Graph System

A fast, lightweight tool to parse Rust projects into a knowledge graph and run insightful queries over code structure. Generate DOT/SVG visualizations, persist graphs to JSON, and explore code relationships via a clean CLI. ✨

⚡ Quick install

cargo install rust-relations-explorer

🔗 Links

crates.io: @web https://crates.io/crates/rust-relations-explorer
docs.rs: @web https://docs.rs/rust-relations-explorer
CI status: @web https://github.com/automataIA/rust-relations-explorer/actions/workflows/ci.yml
Releases: @web https://github.com/automataIA/rust-relations-explorer/releases

✨ Features

✅ Graph builder from source (KnowledgeGraph::build_from_directory)
✅ Incremental builds with cache (reuse unchanged files; --no-cache, --rebuild)
✅ Relationship analysis (imports, heuristics for calls)
✅ JSON persistence (save/load)
✅ DOT generation with styling (rankdir, splines, rounded, theme, clusters, legend)
✅ SVG enhancement (interactive highlights, clickable nodes)
✅ CLI powered by clap
✅ Queries
- connected-files — files related to a target file
- item-info — show item metadata, code, and relations by ItemId
- function-usage — callers/callees of a function
- cycles — detect file-level cycles
- path — shortest path between two files
- hubs — top-N files by degree centrality (in/out/total)
- module-centrality — top-N modules (directories) by degree centrality
- trait-impls — list types and files implementing a given trait
🚧 Pretty table output for terminal
🚧 Advanced analyses and config system

🧰 Installation

Install from crates.io:

cargo install rust-relations-explorer

Build from source:

# from repo root
cargo build --release

Run checks and tests:

cargo check
cargo test

🚀 Usage

Build a graph from a Rust project and export artifacts:

Defaults & name lookup (quick examples)

# Use env defaults (see Configuration section)
export RRE_PATH=/path/to/project
export RRE_FORMAT=json

# Name lookup without ItemId
rust-relations-explorer query item-info --path path/to/project --name createIcons --format text

# Short flags and defaults (local dev via cargo)
# Explicit short flags
cargo run -- query item-info -p src -n resolver -f text
# Using environment defaults (omit -p and -f)
export RRE_PATH=src
export RRE_FORMAT=text
cargo run -- query item-info -n resolver
# Increase verbosity (-v, -vv, -vvv)
rust-relations-explorer -vv query cycles

# Quiet mode suppresses non-essential logs
rust-relations-explorer -q query hubs --metric total --top 5 --format text
rust-relations-explorer -q query hubs --metric total --top 5

# Build and save artifacts (uses cache by default)
rust-relations-explorer build --path path/to/project \
  --json graph.json \
  --dot graph.dot \
  --svg graph.svg \
  --dot-rankdir LR --dot-splines curved --dot-rounded on \
  --dot-theme light --dot-clusters on --dot-legend on

# Force parsing all files without using cache
rust-relations-explorer build --path path/to/project --no-cache

# Rebuild cache from scratch (clears previous cache file)
rust-relations-explorer build --path path/to/project --rebuild

# Apply options from a configuration file
rust-relations-explorer build --path path/to/project --config rust-relations-explorer.toml --svg graph.svg

# Bypass ignore rules (include files even if ignored)
rust-relations-explorer build --path path/to/project --no-ignore

Run queries (builds the graph on-the-fly unless --graph is provided):

# Connected files for a given file (positional <file>)
rust-relations-explorer query connected-files --path path/to/project src/lib.rs --format text

# Show detailed info for an item by ItemId (text or JSON)
rust-relations-explorer query item-info --path path/to/project --item-id fn:createIcons:6 --format text
rust-relations-explorer query item-info --path path/to/project --item-id fn:createIcons:6 --format json

# Name-only lookup (no ItemId needed)
# Prefer current crate matches; if ambiguous, CLI lists candidates and hints how to disambiguate.
rust-relations-explorer query item-info --path path/to/project --name createIcons --format text

# Narrow by kind to avoid ambiguity (kinds: module|function|struct|enum|trait|impl|const|static|type|macro)
rust-relations-explorer query item-info --path path/to/project --name createIcons --kind function --format text

# Example disambiguation flow (pseudo):
# > Multiple items named 'createIcons' were found. Use --kind or --item-id to disambiguate.
# > Candidates:
# > - fn:createIcons:6  src/a.rs
# > - fn:createIcons:12 src/b.rs
# Then run with --kind function or the exact --item-id shown above.

# Function usage: who calls `foo` (callers) or who does `foo` call (callees)
rust-relations-explorer query function-usage --path path/to/project --function foo --direction callers --format json

# Detect cycles
rust-relations-explorer query cycles --path path/to/project --format text

# Shortest path between files
rust-relations-explorer query path --path path/to/project --from src/a.rs --to src/b.rs --format text

# Hubs: top-N by degree centrality
rust-relations-explorer query hubs --path path/to/project --metric total --top 10 --format text

# Module centrality: top-N modules by degree
rust-relations-explorer query module-centrality --path path/to/project --metric total --top 10 --format text

# Trait implementations for Display
rust-relations-explorer query trait-impls --path path/to/project --trait Display --format json

# Any query can also bypass ignore rules when building on-the-fly
rust-relations-explorer query cycles --path path/to/project --no-ignore --format text

Output controls (quiet/verbose, pagination)

Quiet mode suppresses non-essential stderr/info logs:

rust-relations-explorer -q query hubs --path path/to/project --format json

Increase verbosity with repeated -v (e.g., -v, -vv, -vvv). Defaults to concise output.
Paginate large result sets with --offset and --limit (supported by all queries except item-info):

# First page (10 rows)
rust-relations-explorer query hubs --path path/to/project --metric total --top 100 --offset 0 --limit 10 --format text

# Next page (rows 10..20)
rust-relations-explorer query hubs --path path/to/project --metric total --top 100 --offset 10 --limit 10 --format text

# JSON output is also paginated by the same flags
rust-relations-explorer query function-usage --path path/to/project --function foo --direction callers --offset 0 --limit 20 --format json

Use a prebuilt graph for faster queries:

rust-relations-explorer query hubs --graph graph.json --metric in --top 5 --format json

📎 Examples

Run the included examples to see the library API in action:

# Build all examples
cargo build --examples

# Basic graph build and stats
cargo run --example basic_build

# Print connected files to a target (defaults to src/lib.rs if present)
cargo run --example query_connected

Example sources:

examples/basic_build.rs
examples/query_connected.rs

🧭 Typical Workflows

Build and save graph to JSON

rust-relations-explorer build --path path/to/project --json graph.json
rust-relations-explorer query hubs --graph graph.json --metric total --top 10 --format json

Programmatic DOT/SVG generation
```
cargo run --example generate_svg
# Produces graph.dot and graph.svg
```
- Requires Graphviz dot executable on PATH. Install via your OS package manager.
- Options like clusters, theme, rankdir, splines are in visualization::DotOptions and visualization::SvgOptions.

Bypass ignore rules for one-off analyses

rust-relations-explorer build --path path/to/project --no-ignore --svg graph.svg

Save and load graph JSON

# Save
rust-relations-explorer build --path path/to/project --json graph.json

# Query using saved graph (faster)
rust-relations-explorer query hubs --graph graph.json --metric in --top 5 --format json

🚢 Releasing

Create a GitHub release using notes from CHANGELOG.md via GitHub CLI:

# Mark as latest and use notes from CHANGELOG.md [0.1.0]
scripts/release_from_changelog.sh 0.1.0 --latest

# Without marking latest
scripts/release_from_changelog.sh 0.1.1

Requirements:

GitHub CLI installed and authenticated:
- gh auth login -w
Existing tag v<version> pushed (e.g., v0.1.0).
CHANGELOG.md includes a section like ## [0.1.0] - YYYY-MM-DD.

Programmatic save/load JSON

use rust_relations_explorer::graph::KnowledgeGraph;
use rust_relations_explorer::utils::cache::CacheMode;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let root = std::path::Path::new(".");
    let graph = KnowledgeGraph::build_from_directory_with_cache_opts(root, CacheMode::Use, false)?;
    // Save
    let json = serde_json::to_string_pretty(&graph)?;
    std::fs::write("graph.json", json)?;
    // Load later
    let loaded: KnowledgeGraph = serde_json::from_str(&std::fs::read_to_string("graph.json")?)?;
    println!("Loaded files: {}", loaded.files.len());
    Ok(())
}

Note: KnowledgeGraph implements serde::Serialize/Deserialize.

🧪 CLI Quick Examples

Build graph with DOT and SVG outputs:

cargo run -- build --path path/to/project --json graph.json --dot graph.dot --svg graph.svg

Connected files for a target file (JSON):

cargo run -- query connected-files --path path/to/project src/lib.rs --format json

Function usage: callers of function foo (JSON):

cargo run -- query function-usage --path path/to/project --function foo --direction callers --format json

Shortest path between two files (JSON):

cargo run -- query path --path path/to/project --from src/a.rs --to src/b.rs --format json

Top hubs by total degree (top 10):

cargo run -- query hubs --path path/to/project --metric total --top 10 --offset 0 --limit 10 --format text

Top modules (directories) by in-degree (top 5):

cargo run -- query module-centrality --path path/to/project --metric in --top 5 --format text

Types implementing a trait (e.g., Display):

cargo run -- query trait-impls --path path/to/project --trait Display --offset 0 --limit 50 --format json

🧠 Caching Modes

Default (Use) — reuse unchanged files from .knowledge_cache.json and only reparse changed/added files.
--no-cache (Ignore) — do not reuse cache; parse all files, then write a fresh cache at end.
--rebuild (Rebuild) — remove existing cache file first, then parse all files and write a new cache.

Cache file location: .knowledge_cache.json at the project root passed to --path.

🗂️ Ignore Patterns

File discovery respects .gitignore and .ignore files. Parent directories are traversed, so nested ignore files apply.
Global git excludes are intentionally disabled for determinism.
This affects which .rs files are scanned and parsed by build and on-the-fly builds for query.

Determinism: The CLI now passes ignore behavior explicitly to the file walker. This removes reliance on ambient environment state during normal operation.

Examples:

# src/.ignore (or .gitignore)
ignored.rs

# Nested ignore (src/a/.ignore)
skip.rs

# Negation pattern (src/.gitignore)
*.rs
!keep.rs

Bypass ignores (use with care):

# Preferred: CLI flag (explicit)
rust-relations-explorer build --path path/to/project --no-ignore

# Optional: environment variable (legacy/compat)
# Still supported, but not required since the CLI now passes the flag directly.
KNOWLEDGE_RS_NO_IGNORE=1 rust-relations-explorer build --path path/to/project

⚙️ Configuration

You can provide a TOML config with --config <path> for both build and all query subcommands.

Precedence (highest to lowest):
- CLI flags
- Environment variables
- Config file (--config)
- Binary defaults

Notes:

Config only backfills when a value is still at its default. It never overwrites values provided by CLI flags or env vars.
Currently supported config keys: DOT/SVG options for build, and default query output format for all queries.

Example rust-relations-explorer.toml:

[dot]
clusters = true
legend = false
theme = "dark"      # "light" | "dark"
rankdir = "TB"      # "LR" | "TB"
splines = "ortho"   # "curved" | "ortho" | "polyline"
rounded = true

[svg]
interactive = true

[query]
default_format = "json" # "text" | "json"

Environment variables

RRE_PATH — default project root for all commands with --path
RRE_GRAPH — default graph JSON for query subcommands
RRE_FORMAT — default output format for queries (text or json)

Examples:

# Use a default project root and JSON output for queries
export RRE_PATH=/path/to/project
export RRE_FORMAT=json

# Point queries to a prebuilt graph by default
export RRE_GRAPH=/path/to/graph.json

# Now flags can be omitted
rust-relations-explorer query cycles --format json
rust-relations-explorer query hubs --metric total --top 10

🐚 Shell completions

Generate completion scripts with the built-in subcommand and install them in your shell's completion directory.

Bash (user-level):

rust-relations-explorer completions bash > ~/.local/share/bash-completion/completions/rust-relations-explorer
# If directory doesn't exist, create it and re-source bashrc
mkdir -p ~/.local/share/bash-completion/completions
source ~/.bashrc

System-wide (requires sudo):

sudo sh -c 'rust-relations-explorer completions bash > /etc/bash_completion.d/rust-relations-explorer'

Zsh:

rust-relations-explorer completions zsh > ~/.zsh/completions/_rust-relations-explorer
mkdir -p ~/.zsh/completions
fpath+=(~/.zsh/completions)
autoload -U compinit && compinit

Fish:

rust-relations-explorer completions fish > ~/.config/fish/completions/rust-relations-explorer.fish

PowerShell (Windows, current session):

rust-relations-explorer completions powershell | Out-String | Invoke-Expression

Persist for all sessions (PowerShell profile):

$path = "$HOME/.config/powershell/rust-relations-explorer.ps1"
rust-relations-explorer completions powershell > $path
Add-Content -Path $PROFILE -Value ". $path"

Elvish:

rust-relations-explorer completions elvish > ~/.elvish/lib/rust-relations-explorer.elv

To test without installing, you can print to stdout:

rust-relations-explorer completions zsh

📎 References

🤝 Contributing

Issues and PRs are welcome! Please run cargo fmt, cargo clippy, and cargo test before submitting.

📄 License

Licensed under either of

Apache License, Version 2.0, see LICENSE-APACHE
MIT license, see LICENSE-MIT

at your option.

Name		Name	Last commit message	Last commit date
Latest commit History 11 Commits
.cargo		.cargo
.github/workflows		.github/workflows
benches		benches
examples		examples
scripts		scripts
src		src
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE-APACHE		LICENSE-APACHE
LICENSE-MIT		LICENSE-MIT
README.md		README.md
builder.md		builder.md
clippy.toml		clippy.toml
example.md		example.md
heaptrack-summary.txt		heaptrack-summary.txt
heaptrack.knowledge-rs.469342.gz		heaptrack.knowledge-rs.469342.gz
lcov.info		lcov.info
rustfmt.toml		rustfmt.toml
tarpaulin-report.html		tarpaulin-report.html

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Licenses found

Uh oh!

Repository files navigation

🛠️ CI and Coverage

📚 rust-relations-explorer — Rust Knowledge Graph System

⚡ Quick install

🔗 Links

✨ Features

🧰 Installation

🚀 Usage

Defaults & name lookup (quick examples)

Output controls (quiet/verbose, pagination)

📎 Examples

🧭 Typical Workflows

🚢 Releasing

🧪 CLI Quick Examples

🧠 Caching Modes

🗂️ Ignore Patterns

⚙️ Configuration

Environment variables

🐚 Shell completions

📎 References

🤝 Contributing

📄 License

About

Licenses found

Uh oh!

Releases 4

Packages

Languages

License

Licenses found

automataIA/rust-relations-explorer

Folders and files

Latest commit

History

Repository files navigation

🛠️ CI and Coverage

📚 rust-relations-explorer — Rust Knowledge Graph System

⚡ Quick install

🔗 Links

✨ Features

🧰 Installation

🚀 Usage

Defaults & name lookup (quick examples)

Output controls (quiet/verbose, pagination)

📎 Examples

🧭 Typical Workflows

🚢 Releasing

🧪 CLI Quick Examples

🧠 Caching Modes

🗂️ Ignore Patterns

⚙️ Configuration

Environment variables

🐚 Shell completions

📎 References

🤝 Contributing

📄 License

About

Resources

License

Licenses found

Uh oh!

Stars

Watchers

Forks

Releases 4

Packages 0

Languages

Packages