Unified Context Graph

lean-ctx builds a unified graph that connects your code, commits, tests, knowledge, and issues - enabling task-aware context provisioning and deep impact analysis.

Node Types

The graph contains 8 node types representing different aspects of your project:

📄 File

Source files tracked by the indexer

🔣 Symbol

Functions, classes, types, and variables

📦 Module

Logical groupings (packages, crates, modules)

📝 Commit

Git commits with message and metadata

🧪 Test

Test functions and test files

🏗️ CIRun

CI/CD pipeline runs and results

🧠 Knowledge

Project knowledge facts from ctx_session

🎫 Issue

Issues and tickets linked to code

Edge Types

Edges represent relationships between nodes. lean-ctx tracks 11 edge types:

Edge Type	Meaning	Example
`Imports`	File imports another file	`A.ts → B.ts`
`Calls`	Function calls another function	`fn_a → fn_b`
`Defines`	Module defines a symbol	`mod → fn`
`TestedBy`	File is tested by a test file	`utils.rs → test_utils.rs`
`ChangedIn`	File was modified in a commit	`file → commit`
`MentionedIn`	File is mentioned in a knowledge fact	`file → knowledge`
`Affects`	Issue affects a file	`issue → file`
`Breaks`	Commit breaks a test	`commit → test`

Graph Enrichment

Enrichment extends the code graph with data from Git, tests, and knowledge - creating a unified project view.

Git History Indexer

Parses recent git commits (default: last 500) and creates Commit nodes with ChangedIn edges to affected files.

Test Indexer

Detects test files by naming convention (test_, _test, _spec) and links them to source files via TestedBy edges.

Knowledge Bridge

Links project knowledge facts recorded via ctx_session to referenced files using MentionedIn edges.

MCP Commands

ctx_graph enrich              # Enrich graph with git, tests, knowledge
ctx_graph build               # Index code structure
ctx_graph status              # Show node/edge counts

Community Detection (Louvain)

The Louvain algorithm clusters files into communities based on their dependency relationships. Files that frequently import each other or share transitive dependencies are grouped together, enabling smarter context preloading and relevance scoring for task-driven queries.

PageRank

Computes file importance scores based on the dependency graph structure. Files imported by many others (structural hubs) receive higher PageRank, which is used by Spectral Relevance and Boltzmann Allocation to prioritize high-impact files during context assembly.

Context Queries

Use graph-based context queries to find the most relevant files for any task - leveraging structural, historical, and semantic connections.

Usage

ctx_graph context "fix auth bug"       # Find relevant files for task
ctx_graph related src/auth.rs          # Connected files
ctx_graph impact src/auth.rs           # Blast radius analysis
ctx_graph symbol src/auth.rs::verify   # Symbol definition/usages

How It Works

Extracts keywords from your task description
Matches keywords against file names and commit messages
Expands results via graph edges (imports, tests, knowledge)
Returns a ranked list of relevant files with relationship context

Interactive HTML Export

Export your dependency graph as a single, self-contained HTML file. The generated file works completely offline - open it in any browser to explore your codebase visually. No server, no dependencies, just one HTML file.

Usage

# Export full graph (all nodes)
lean-ctx graph export-html --out graph.html

# Limit to 100 most-connected nodes
lean-ctx graph export-html --out graph.html --max-nodes 100

# Custom project root
lean-ctx graph export-html --out graph.html --root /path/to/project

Interactive Features

🔍 Search

Type any file path substring to highlight matching nodes instantly

🖱️ Pan & Zoom

Click and drag to pan, scroll to zoom. Works like a map.

📋 Node Details

Click any node to see its imports and dependents in a sidebar

🔗 Reverse Deps

Right-click a node to highlight all files that depend on it (BFS traversal)

🖼️ PNG Export

Download the current canvas view as a PNG image with one click

📡 Offline

No external dependencies. The entire app is embedded in one HTML file.

Tips

Use --max-nodes to keep the visualization readable for large projects (50–200 is a good range)
Run graph build first to ensure the index is up to date before exporting
The HTML file is safe to share with teammates - it contains no source code, only file paths and relationships
Right-click highlighting shows the full reverse-dependency chain, making it easy to assess the blast radius of changes

Dashboard API

Endpoint	Description
`/api/graph/stats`	Node and edge counts, database path
`/api/graph/enrich`	Trigger full graph enrichment and return stats