Grafo de contexto unificado

O lean-ctx constrói um grafo unificado que conecta código, commits, testes, conhecimento e issues - permitindo provisionamento de contexto baseado em tarefas e análise de impacto profunda.

Tipos de nó

O grafo contém 8 tipos de nó representando diferentes aspectos do seu projeto:

📄 File

Arquivos fonte rastreados pelo indexador

🔣 Symbol

Funções, classes, tipos e variáveis

📦 Module

Agrupamentos lógicos (pacotes, crates, módulos)

📝 Commit

Commits do Git com mensagem e metadados

🧪 Test

Funções de teste e arquivos de teste

🏗️ CIRun

Execuções de pipeline CI/CD e resultados

🧠 Knowledge

Fatos de conhecimento do projeto via ctx_session

🎫 Issue

Issues e tickets vinculados ao código

Tipos de aresta

Arestas representam relações entre nós. O lean-ctx rastreia 11 tipos de aresta:

Tipo de aresta	Significado	Exemplo
`Imports`	Arquivo importa outro arquivo	`A.ts → B.ts`
`Calls`	Função chama outra função	`fn_a → fn_b`
`Defines`	Módulo define um símbolo	`mod → fn`
`TestedBy`	Arquivo é testado por um arquivo de teste	`utils.rs → test_utils.rs`
`ChangedIn`	Arquivo foi modificado em um commit	`file → commit`
`MentionedIn`	Arquivo é mencionado em um fato de conhecimento	`file → knowledge`
`Affects`	Issue afeta um arquivo	`issue → file`
`Breaks`	Commit quebra um teste	`commit → test`

Enriquecimento do grafo

O enriquecimento estende o grafo de código com dados do Git, testes e conhecimento - criando uma visão unificada do projeto.

Indexador de histórico Git

Analisa commits recentes do Git (padrão: últimos 500) e cria nós Commit com arestas ChangedIn para arquivos afetados.

Indexador de testes

Detecta arquivos de teste por convenção de nomes (test_, _test, _spec) e os vincula a arquivos fonte via arestas TestedBy.

Ponte de conhecimento

Vincula fatos de conhecimento do projeto registrados via ctx_session a arquivos referenciados usando arestas 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

Use consultas de contexto baseadas no grafo para encontrar os arquivos mais relevantes para qualquer tarefa - aproveitando conexões estruturais, históricas e 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

Como funciona

Extrai palavras-chave da descrição da tarefa
Combina palavras-chave com nomes de arquivo e mensagens de commit
Expande resultados via arestas do grafo (imports, testes, conhecimento)
Retorna uma lista classificada de arquivos relevantes com contexto de relação

Exportação HTML interativa

Exporte seu grafo de dependências como um arquivo HTML único e autossuficiente. O arquivo gerado funciona completamente offline - abra-o em qualquer navegador para explorar visualmente sua base de código. Sem servidor, sem dependências, apenas um arquivo 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

Funcionalidades interativas

🔍 Search

Digite qualquer substring de caminho de arquivo para destacar os nós correspondentes instantaneamente

🖱️ Pan & Zoom

Clique e arraste para mover, role para ampliar. Funciona como um mapa.

📋 Node Details

Clique em qualquer nó para ver suas importações e dependentes em uma barra lateral

🔗 Reverse Deps

Clique com o botão direito em um nó para destacar todos os arquivos que dependem dele (travessia BFS)

🖼️ PNG Export

Baixe a visualização atual do canvas como imagem PNG com um clique

📡 Offline

Sem dependências externas. A aplicação inteira está incorporada em um único arquivo HTML.

Dicas

Use --max-nodes para manter a visualização legível em projetos grandes (50–200 é uma boa faixa)
Execute graph build primeiro para garantir que o índice esteja atualizado antes de exportar
O arquivo HTML pode ser compartilhado com segurança com colegas de equipe - ele não contém código-fonte, apenas caminhos de arquivos e relacionamentos
O destaque por clique direito mostra a cadeia completa de dependências inversas, facilitando a avaliação do raio de impacto das alterações

API do Dashboard

Endpoint	Descrição
`/api/graph/stats`	Contagem de nós e arestas, caminho do banco de dados
`/api/graph/enrich`	Acionar enriquecimento completo do grafo e retornar estatísticas