Grafo de contexto unificado

lean-ctx construye un grafo unificado que conecta código, commits, tests, conocimiento e issues - habilitando aprovisionamiento de contexto consciente de tareas y análisis de impacto profundo.

Tipos de nodo

El grafo contiene 8 tipos de nodo que representan diferentes aspectos de tu proyecto:

📄 File

Archivos fuente rastreados por el indexador

🔣 Symbol

Funciones, clases, tipos y variables

📦 Module

Agrupaciones lógicas (paquetes, crates, módulos)

📝 Commit

Commits de Git con mensaje y metadatos

🧪 Test

Funciones de test y archivos de test

🏗️ CIRun

Ejecuciones de pipeline CI/CD y resultados

🧠 Knowledge

Datos de conocimiento del proyecto desde ctx_session

🎫 Issue

Issues y tickets vinculados al código

Tipos de arista

Las aristas representan relaciones entre nodos. lean-ctx rastrea 11 tipos de arista:

Tipo de arista	Significado	Ejemplo
`Imports`	Archivo importa otro archivo	`A.ts → B.ts`
`Calls`	Función llama a otra función	`fn_a → fn_b`
`Defines`	Módulo define un símbolo	`mod → fn`
`TestedBy`	Archivo es probado por un archivo de test	`utils.rs → test_utils.rs`
`ChangedIn`	Archivo fue modificado en un commit	`file → commit`
`MentionedIn`	Archivo es mencionado en un dato de conocimiento	`file → knowledge`
`Affects`	Issue afecta a un archivo	`issue → file`
`Breaks`	Commit rompe un test	`commit → test`

Enriquecimiento del grafo

El enriquecimiento extiende el grafo de código con datos de Git, tests y conocimiento - creando una vista unificada del proyecto.

Indexador de historial Git

Analiza commits recientes de Git (por defecto: últimos 500) y crea nodos Commit con aristas ChangedIn hacia archivos afectados.

Indexador de tests

Detecta archivos de test por convención de nombres (test_, _test, _spec) y los enlaza a archivos fuente vía aristas TestedBy.

Puente de conocimiento

Vincula datos de conocimiento del proyecto registrados vía ctx_session a archivos referenciados usando aristas MentionedIn.

Comandos MCP

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.

Consultas de contexto

Usa consultas de contexto basadas en el grafo para encontrar los archivos más relevantes para cualquier tarea - aprovechando conexiones estructurales, históricas y semánticas.

Uso

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

Cómo funciona

Extrae palabras clave de la descripción de la tarea
Coincide palabras clave con nombres de archivo y mensajes de commit
Expande resultados vía aristas del grafo (imports, tests, conocimiento)
Devuelve una lista clasificada de archivos relevantes con contexto de relación

Exportación HTML interactiva

Exporte su grafo de dependencias como un archivo HTML único y autónomo. El archivo generado funciona completamente sin conexión - ábralo en cualquier navegador para explorar visualmente su código. Sin servidor, sin dependencias, solo un archivo HTML.

Uso

# 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

Funciones interactivas

🔍 Search

Escriba cualquier subcadena de ruta de archivo para resaltar los nodos coincidentes al instante

🖱️ Pan & Zoom

Haga clic y arrastre para desplazar, desplace la rueda para hacer zoom. Funciona como un mapa.

📋 Node Details

Haga clic en cualquier nodo para ver sus importaciones y dependientes en una barra lateral

🔗 Reverse Deps

Haga clic derecho en un nodo para resaltar todos los archivos que dependen de él (recorrido BFS)

🖼️ PNG Export

Descargue la vista actual del canvas como imagen PNG con un solo clic

📡 Offline

Sin dependencias externas. La aplicación completa está integrada en un solo archivo HTML.

Consejos

Use --max-nodes para mantener la visualización legible en proyectos grandes (50–200 es un buen rango)
Ejecute primero graph build para asegurarse de que el índice esté actualizado antes de exportar
El archivo HTML se puede compartir de forma segura con compañeros de equipo - no contiene código fuente, solo rutas de archivos y relaciones
El resaltado con clic derecho muestra la cadena completa de dependencias inversas, facilitando la evaluación del radio de impacto de los cambios

API del Dashboard

Endpoint	Descripción
`/api/graph/stats`	Conteo de nodos y aristas, ruta de base de datos
`/api/graph/enrich`	Activar enriquecimiento completo del grafo y devolver estadísticas