@rpcajr/smart-graph-indexer 1.0.0

package/mcp_smart_indexer_implementation_spec.md

@@ -0,0 +1,366 @@
+# Especificação de Implementação: MCP Smart Code Indexer
+## Servidor MCP de Alta Performance, Git-Aware e Baixo Consumo de Contexto (Tokens)
+
+Este documento descreve detalhadamente as especificações arquiteturais, de design e os passos de implementação para construir o **MCP Smart Code Indexer**. Ele foi projetado para que ferramentas de IA de fronteira (como Claude Code, Google Antigravity CLI, Cursor, Cline) consigam interpretar, codificar e implantar o sistema completo de forma autônoma e incremental.
+
+---
+
+## 1. Visão Geral e Objetivos do Projeto
+
+### 1.1 O Problema
+Ao interagir com bases de código corporativas ou legadas gigantes (1M+ linhas de código), ferramentas de desenvolvimento baseadas em IA sofrem com:
+1. **Desperdício de Contexto (Token Bleeding):** Varreduras cegas via `grep` ou abertura de arquivos inteiros consomem dezenas de milhares de tokens desnecessários.
+2. **Invalidação Ineficiente de Cache:** Sistemas que exigem varredura completa a cada alteração travam a máquina do desenvolvedor e geram dados obsoletos rapidamente.
+3. **Falta de Contexto Semântico e Arquitetural:** A IA não compreende a hierarquia e o relacionamento (grafo) entre as classes, resultando em correções isoladas que quebram dependências indiretas.
+
+### 1.2 A Solução
+O **MCP Smart Code Indexer** atua como um intermediário de busca semântica, sintática e estrutural por meio de:
+* **AST (Abstract Syntax Tree) Skeletons:** Extração instantânea apenas de assinaturas e cabeçalhos de código (sem os blocos internos), reduzindo a leitura em até 95%.
+* **Git-Backed Delta Tracking:** Monitoramento em tempo real do sistema de arquivos alinhado à árvore de estados do Git, indexando incrementalmente apenas os deltas.
+* **Grafo de Dependências In-Memory:** Mapeamento em RAM dos relacionamentos do projeto.
+* **RAG Híbrido Local (Semântico + Léxico):** Mecanismo de busca ultraleve rodando embeddings de assinaturas localmente via CPU (ONNX), gerando economia drástica de tokens e respostas em milissegundos.
+
+---
+
+## 2. Visão de Arquitetura do Sistema
+
+O diagrama abaixo descreve a comunicação assíncrona orientada a eventos do sistema:
+
+```mermaid
+graph TD
+    User([Desenvolvedor / Git]) -->|Modifica Código| FS[Sistema de Arquivos / Git Status]
+    FS -->|FS Event / git diff| Watcher[Git-Aware Delta Engine]
+    Watcher -->|Somente Arquivos Modificados| Parser[Parser AST: Tree-sitter]
+    Parser -->|Assinaturas Públicas / Docstrings| Indexer[Incremental Indexer Engine]
+    
+    Indexer -->|Atualiza Grafo| Graph[In-Memory Dependency Graph]
+    Indexer -->|Vetoriza Assinaturas / ONNX| VectorStore[Local Vector Store]
+    
+    IA[Ferramenta de IA: Claude/Antigravity] -->|JSON-RPC via stdio| MCP[MCP Server]
+    MCP -->|Busca Semântica / Tags| VectorStore
+    MCP -->|Navegação de Relações| Graph
+    MCP -->|Extração JIT do Código| JIT[Just-In-Time Code Extractor]
+    JIT -->|Somente Linhas Solicitadas| IA
+```
+
+### 2.1 Decisões de Engenharia Críticas
+1. **Linguagem de Implementação:** **Rust** (Recomendado) ou **Go**. Se construído em **Rust**, utilizar empacotamento nativo. Rust garante inicialização em milissegundos, consumo de RAM desprezível (< 50MB para grafos grandes) e suporte perfeito a parseamento paralelo multitheading. *(Nota: Caso o ecossistema C# .NET 9 com Native AOT seja preferido pelo desenvolvedor, a mesma arquitetura se aplica usando C# nativo e pinvoke para Tree-Sitter).*
+2. **Parser Sintático:** **Tree-sitter** (bindings em C/Rust/Go). Evita a necessidade de compilação ou runtimes específicos das linguagens do projeto analisado.
+3. **Embeddings Locais:** **ONNX Runtime** rodando o modelo `all-MiniLM-L6-v2` (ou similar de ~22MB a 45MB de tamanho), gerando vetores de 384 dimensões diretamente na CPU.
+4. **Protocolo de Comunicação:** MCP (Model Context Protocol) usando transporte por entrada/saída padrão (`stdio`) baseado em JSON-RPC 2.0.
+
+---
+
+## 3. Estrutura de Pastas Sugerida (Rust)
+
+```text
+mcp-smart-indexer/
+├── Cargo.toml
+├── README.md
+├── build.rs                  # Para compilar e vincular gramáticas do tree-sitter
+├── models/
+│   └── all-miniLM-L6-v2.onnx  # Modelo de embedding local pré-baixado
+├── src/
+│   ├── main.rs               # Orquestrador do CLI e entrada principal
+│   ├── mcp/
+│   │   ├── mod.rs
+│   │   ├── protocol.rs       # Protocolo JSON-RPC do MCP
+│   │   └── tools.rs          # Implementação das Ferramentas MCP (schemas)
+│   ├── indexer/
+│   │   ├── mod.rs
+│   │   ├── watcher.rs        # Watcher FS integrado com Git
+│   │   ├── parser.rs         # Extração de Skeletons via Tree-sitter
+│   │   └── delta.rs          # Verificador de diferenças incrementais
+│   ├── search/
+│   │   ├── mod.rs
+│   │   ├── vector.rs         # Gerenciamento de vetores locais e ONNX
+│   │   └── graph.rs          # Grafo de dependências na memória RAM
+│   └── utils/
+│       ├── mod.rs
+│       └── git.rs            # Auxiliares de parsing de .gitignore e git diff
+```
+
+---
+
+## 4. Fases de Implementação (Passo a Passo)
+
+---
+
+### Fase 1: Scaffold do Projeto, CLI e Setup de Dependências
+
+#### Objetivo
+Criar o esqueleto do projeto em Rust, configurar as dependências cruciais de processamento assíncrono, parser e serialização, e implementar a interface CLI inicial.
+
+#### Dependências Necessárias (`Cargo.toml`)
+```toml
+[package]
+name = "mcp-smart-indexer"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+tokio = { version = "1.35", features = ["full"] }
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
+notify = "6.1"                # Monitoramento de arquivos nativo do OS
+tree-sitter = "0.20"          # Parser AST core
+# Adicionar gramáticas populares
+tree-sitter-c-sharp = "0.20"
+tree-sitter-typescript = "0.20"
+tree-sitter-python = "0.20"
+ort = { version = "1.16" }    # ONNX Runtime para embeddings locais na CPU
+ndarray = "0.15"              # Para manipular os tensores de embedding
+anyhow = "1.0"                # Tratamento amigável de erros
+clap = { version = "4.4", features = ["derive"] } # CLI Parser
+ignore = "0.4"                # Respeito rápido a regras do .gitignore
+petgraph = "0.6"              # Estrutura de dados de grafo em memória
+```
+
+#### Requisitos de Código (CLI)
+O binário deve aceitar os seguintes comandos via CLI:
+* `mcp-indexer start --path <diretorio>`: Inicia o servidor MCP via `stdio`.
+* `mcp-indexer index --path <diretorio>`: Executa apenas a indexação inicial do projeto de forma síncrona e exporta um report estrutural em formato JSON para debug.
+* O comando de inicialização deve ler o arquivo `.gitignore` do diretório-alvo e ignorar pastas não versionadas por padrão.
+
+#### Definição de Done (Fase 1)
+1. Executar `cargo build` com sucesso.
+2. Comando `mcp-indexer index --path .` executa sem crashar, listando caminhos de arquivos válidos respeitando o `.gitignore`.
+
+---
+
+### Fase 2: Git-Aware Delta Engine (Watcher Inteligente)
+
+#### Objetivo
+Criar um motor de monitoramento de alterações que consome zero recursos em repouso e sabe diferenciar arquivos modificados de arquivos novos usando o Git e eventos do Sistema de Arquivos (FS).
+
+#### Especificação Técnica
+1. **Mapeamento Base (Warm Start):**
+   * Ao iniciar no diretório, o MCP deve rodar `git status --porcelain` para identificar imediatamente arquivos alterados localmente (staged ou unstaged) em relação ao último commit.
+   * Se o projeto for um repositório Git limpo, o estado inicial de indexação é carregado a partir de um cache serializado rápido (`.mcp/cache.bin`).
+2. **FileSystem Watcher Ativo:**
+   * Instanciar um monitor dinâmico usando a crate `notify`.
+   * Sempre que um evento de escrita (`Write`) ou criação (`Create`) for detectado, o caminho do arquivo deve ser passado pela biblioteca `ignore` para checar se ele não está no `.gitignore`.
+   * O watcher não dispara reindexação imediata na primeira modificação de caractere. Ele deve aplicar um **debounce de 1.5 segundos**. Se novas escritas ocorrerem dentro desse intervalo, o cronômetro reinicia. Isso evita micro-reindexações durante a digitação ativa do desenvolvedor.
+3. **Invalidação de Cache:**
+   * O cache do arquivo alterado só é invalidado se o hash MD5 (ou SHA-1) do conteúdo atualizado diferir do hash armazenado no cache.
+
+#### Definição de Done (Fase 2)
+1. Modificar um arquivo ignorado pelo `.gitignore` não deve disparar nenhuma ação no console.
+2. Modificar um arquivo de código válido (`.cs`, `.ts`, `.py`) deve disparar o evento debounced de reindexação e atualizar o hash interno do arquivo em memória.
+
+---
+
+### Fase 3: Parser AST de Skeletons (Tree-sitter Engine)
+
+#### Objetivo
+Extrair a "casca" estrutural do código (nomes de classes, estruturas, métodos, propriedades, assinaturas e comentários/docstrings anexos) sem armazenar ou processar o bloco de implementação interno das funções.
+
+#### Estruturas de Dados (Modelos de Símbolos)
+```rust
+#[derive(Debug, Serialize, DeserializeClone)]
+pub struct SymbolSkeleton {
+    pub name: String,
+    pub kind: SymbolKind, // Enum: Class, Struct, Method, Property, Interface
+    pub signature: String, // Ex: "public void ProcessOrder(Order order, decimal discount)"
+    pub docstring: Option<String>, // Comentários acima do método/classe
+    pub start_line: usize,
+    pub end_line: usize, // Mapeia exatamente de onde a onde o método existe no arquivo original
+}
+
+#[derive(Debug, Serialize, Deserialize)]
+pub struct FileSkeleton {
+    pub file_path: String,
+    pub file_hash: String,
+    pub symbols: Vec<SymbolSkeleton>,
+    pub dependencies: Vec<String>, // Namespaces ou arquivos importados diretamente
+}
+```
+
+#### Regras de Parsing por Linguagem
+O Parser deve conter módulos de consulta (Queries AST do Tree-sitter) customizados para extrair símbolos das seguintes linguagens principais:
+
+##### 1. C# (`.cs`)
+* **Classes / Interfaces:** Capturar o cabeçalho `public class <Nome> : <Base>` ou `public interface <Nome>`.
+* **Métodos:** Capturar a assinatura completa excluindo o nó `block` (chaves `{ ... }`). Capturar comentários de documentação XML (`/// <summary>...`).
+
+##### 2. TypeScript/JavaScript (`.ts`, `.js`, `.tsx`)
+* **Classes / Funções Exportadas:** Capturar declarações `export class`, `export function`, `export const <ArrowFunction>`.
+* **Assinaturas:** Capturar os tipos de parâmetros e retornos. Capturar comentários JSDoc (`/** ... */`).
+
+##### 3. Python (`.py`)
+* **Classes / Funções:** Capturar `class <Nome>:` e `def <Nome>(...):`.
+* **Docstrings:** Capturar as strings literais triplas (`"""...""\``) imediatamente após a declaração.
+
+#### Definição de Done (Fase 3)
+* Um teste unitário que recebe um arquivo C# ou TS de 500 linhas e gera um `FileSkeleton` contendo apenas as assinaturas exatas, omitindo todo o corpo dos loops e condicionais internos dos métodos. As linhas de início e fim dos métodos devem bater perfeitamente com o arquivo original.
+
+---
+
+### Fase 4: Grafo de Dependências e RAG Semântico Local
+
+#### Objetivo
+Montar em memória RAM as conexões estruturais entre os arquivos indexados e criar um mecanismo de busca vetorial para permitir que a IA encontre símbolos por contexto conceitual sem precisar de buscas textuais de alto consumo de tokens.
+
+#### 1. O Grafo de Dependências (In-Memory Graph)
+* Utilizar `petgraph` para modelar o grafo direcionado do projeto.
+* **Vértices (Nodes):** Representam os arquivos do projeto (ex: `BillingService.cs`, `IUserRepository.cs`).
+* **Arestas (Edges):** Representam conexões de dependência através de diretivas de importação (ex: `using`, `import`, `require`).
+* O grafo permite buscar relações bidirecionais:
+  * **Dependências Diretas (Out-edges):** *"Quais arquivos este arquivo consome?"*
+  * **Dependentes (In-edges):** *"Se eu alterar a interface X, quais arquivos do projeto podem ser impactados por tabela?"*
+
+#### 2. Vector Store e Embedding Engine (ONNX Local)
+* **Inicialização:** No boot do MCP, instanciar a sessão `ort` com o modelo de embedding local `all-miniLM-L6-v2.onnx` rodando em threads dedicadas na CPU.
+* **Payload de Vetorização:** O texto que vai para a geração de embeddings de cada símbolo **NUNCA** é o código completo. Ele deve seguir o seguinte template sintético:
+  ```text
+  File: <Caminho> | Symbol: <Nome> (<Kind>) | Signature: <Assinatura> | Doc: <Docstring ou Comentário>
+  ```
+  *Exemplo:*
+  ```text
+  File: Src/Services/TaxService.cs | Symbol: CalculateVAT (Method) | Signature: public decimal CalculateVAT(Invoice invoice, Region region) | Doc: Calcula o imposto sobre valor agregado com base na regiao de faturamento
+  ```
+* **Armazenamento de Vetores:** Como o número de assinaturas em projetos gigantes raramente passa de 10.000 símbolos, armazenar os embeddings diretamente em um vetor plano em memória (`Vec<(SymbolId, Vec<f32>)>`). A busca por similaridade de cosseno (Cosine Similarity) para essa escala em memória leva menos de **5 milissegundos**.
+* **Busca Híbrida:** A busca semântica por cosseno deve ser opcionalmente combinada com busca textual exata e rápida (usando filtro de substring simples) para termos específicos e nomes exatos de métodos.
+
+#### Definição de Done (Fase 4)
+* Executar uma busca semântica pela frase *"cálculo de imposto"* e obter como primeiro resultado o símbolo `CalculateVAT` mesmo sem que o termo exato "VAT" tenha sido digitado no prompt de busca.
+
+---
+
+### Fase 5: Protocolo MCP JSON-RPC Server
+
+#### Objetivo
+Implementar o canal de comunicação via `stdio` que escuta as mensagens JSON-RPC 2.0 das ferramentas de IA clientes e executa as ações de busca e extração.
+
+#### Ferramentas (Tools) que o MCP DEVE Expor ao Cliente de IA
+
+O servidor MCP deve expor as seguintes ferramentas cruciais com os respectivos schemas JSON:
+
+##### 1. `search_symbols`
+* **Descrição:** Realiza busca híbrida (semântica via vetor + sintática por texto) sobre a base de assinaturas indexadas.
+* **Parâmetros:**
+  ```json
+  {
+    "type": "object",
+    "properties": {
+      "query": { "type": "string", "description": "Termo de busca ou descrição funcional da lógica que deseja encontrar" },
+      "limit": { "type": "integer", "default": 5, "description": "Número máximo de correspondências a retornar" }
+    },
+    "required": ["query"]
+  }
+  ```
+
+##### 2. `get_file_skeleton`
+* **Descrição:** Retorna a estrutura (esqueleto) completa de um arquivo específico sem as implementações internas. Permite à IA entender a estrutura do arquivo instantaneamente consumindo pouquíssimos tokens.
+* **Parâmetros:**
+  ```json
+  {
+    "type": "object",
+    "properties": {
+      "file_path": { "type": "string", "description": "Caminho relativo do arquivo no projeto" }
+    },
+    "required": ["file_path"]
+  }
+  ```
+
+##### 3. `get_dependencies`
+* **Descrição:** Consulta o grafo em memória e retorna o mapa de conexões de um arquivo específico. Auxilia a IA a entender o impacto arquitetural de uma alteração.
+* **Parâmetros:**
+  ```json
+  {
+    "type": "object",
+    "properties": {
+      "file_path": { "type": "string", "description": "Caminho do arquivo de origem" },
+      "direction": { "type": "string", "enum": ["incoming", "outgoing", "both"], "default": "both" }
+    },
+    "required": ["file_path"]
+  }
+  ```
+
+##### 4. `read_symbol_body`
+* **Descrição:** Extração JIT (Just-In-Time). Retorna o código-fonte real e completo de um método ou classe específico baseado nas linhas de início e fim fornecidas pelo esqueleto.
+* **Parâmetros:**
+  ```json
+  {
+    "type": "object",
+    "properties": {
+      "file_path": { "type": "string", "description": "Caminho relativo do arquivo" },
+      "symbol_name": { "type": "string", "description": "Nome exato da classe ou método a ler" }
+    },
+    "required": ["file_path", "symbol_name"]
+  }
+  ```
+
+#### Especificação de Resposta Segura
+Se o arquivo original foi alterado no disco após a indexação inicial, a chamada para `read_symbol_body` deve acionar uma re-validação rápida do hash do arquivo e re-parsear a árvore antes de ler a fatia de linhas correspondente, evitando entregar código incorreto ou desalinhado por offset de linhas.
+
+#### Definição de Done (Fase 5)
+* O processo MCP inicia e responde adequadamente à mensagem padrão de handshake do protocolo: `{"jsonrpc": "2.0", "method": "initialize", "params": {...}, "id": 1}` enviada via terminal (`stdin`).
+
+---
+
+## 5. Como Integrar e Testar em Diferentes Clientes
+
+As ferramentas de IA locais se comunicam de forma nativa com o executável gerado. Use estes arquivos de configuração de referência para testar o seu servidor MCP local.
+
+### 5.1 Testando com Google Antigravity IDE / CLI
+Crie ou adicione a configuração ao arquivo global de agentes do Antigravity (ex: `~/.config/antigravity/mcp_servers.json` ou local no projeto em `.antigravity/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "smart-code-indexer": {
+      "command": "/usr/local/bin/mcp-smart-indexer",
+      "args": ["start", "--path", "."],
+      "env": {
+        "RUST_LOG": "info"
+      }
+    }
+  }
+}
+```
+
+### 5.2 Testando com Claude Code (CLI)
+Para vincular diretamente o binário compilado no Claude Code global, execute o utilitário interativo:
+```bash
+claude mcp add smart-code-indexer -- /usr/local/bin/mcp-smart-indexer start --path .
+```
+Ou manualmente no seu arquivo de configuração `~/.claude.json`:
+```json
+{
+  "mcpServers": {
+    "smart-code-indexer": {
+      "command": "mcp-smart-indexer",
+      "args": ["start", "--path", "."],
+      "alwaysOn": true
+    }
+  }
+}
+```
+
+### 5.3 Testando com Cursor ou Cline (VS Code Extension)
+Adicione nas configurações de desenvolvedor MCP do Cursor ou no arquivo global `clinesettings.json`:
+```json
+{
+  "mcpServers": {
+    "smart-code-indexer": {
+      "command": "mcp-smart-indexer",
+      "args": ["start", "--path", "."],
+      "disabled": false,
+      "autoApprove": []
+    }
+  }
+}
+```
+
+---
+
+## 6. Checklist de Validação Final para a IA Executora
+
+Para considerar este projeto 100% implementado de forma automatizada, a ferramenta de IA que escrever o código deve validar os seguintes pontos de qualidade:
+
+- [ ] **Desempenho de Inicialização:** O servidor MCP no boot em um projeto de 1M de linhas de código deve responder ao handshake de inicialização em menos de **1 segundo**, realizando a vetorização em segundo plano (background thread pool).
+- [ ] **Consumo de Memória:** O consumo de RAM estático do processo MCP em background não deve exceder **100MB** em repouso.
+- [ ] **Robusteza do Watcher:** Ao criar um novo arquivo `.cs` contendo um método de teste, a busca semântica por `search_symbols` deve conseguir encontrá-lo em até **2 segundos** de forma assíncrona após salvar o arquivo no editor de código.
+- [ ] **Agnóstico de Plataforma:** O binário compila e roda sem quebras no Windows, Linux e macOS (Darwin) com comportamento consistente de leitura do sistema de arquivos.
+- [ ] **Resiliência a Erros Sintáticos:** Se o desenvolvedor salvar um arquivo com erros de compilação ou sintaxe quebrada no meio de uma refatoração, o parser AST (Tree-sitter) deve lidar de forma graciosa retornando os símbolos válidos anteriores em vez de crashar o indexador.

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@rpcajr/smart-graph-indexer",
+  "version": "1.0.0",
+  "description": "Smart Graph Code Indexer MCP server in TypeScript",
+  "main": "dist/index.js",
+  "bin": {
+    "graph-indexer": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc && copyfiles -u 0 \"wasm/*.wasm\" dist/",
+    "start": "node dist/index.js start",
+    "index": "node dist/index.js index",
+    "package": "pkg . --targets node18-win-x64,node18-macos-x64,node18-linux-x64 --out-path bin/"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.1",
+    "@xenova/transformers": "^2.17.2",
+    "chokidar": "^3.6.0",
+    "commander": "^11.1.0",
+    "ignore": "^5.3.1",
+    "tree-sitter-wasms": "^0.1.13",
+    "web-tree-sitter": "^0.20.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.24",
+    "copyfiles": "^2.4.1",
+    "pkg": "^5.8.1",
+    "typescript": "^5.3.3"
+  },
+  "pkg": {
+    "assets": [
+      "dist/wasm/*.wasm"
+    ]
+  }
+}

package/src/graph.ts

@@ -0,0 +1,93 @@
+export class DependencyGraph {
+  // Map of file relative path -> set of other files/namespaces this file imports (outgoing)
+  private adjacencyList: Map<string, Set<string>> = new Map();
+  // Map of file/namespace -> set of files that import it (incoming)
+  private reverseAdjacencyList: Map<string, Set<string>> = new Map();
+
+  constructor() {}
+
+  /**
+   * Adds or updates a file and its dependencies in the graph.
+   */
+  public updateFileDependencies(filePath: string, dependencies: string[]) {
+    // Clean old dependencies if file already existed
+    this.removeFile(filePath);
+
+    // Set outgoing dependencies
+    const outgoing = new Set(dependencies);
+    this.adjacencyList.set(filePath, outgoing);
+
+    // Set incoming dependencies
+    for (const dep of dependencies) {
+      if (!this.reverseAdjacencyList.has(dep)) {
+        this.reverseAdjacencyList.set(dep, new Set());
+      }
+      this.reverseAdjacencyList.get(dep)!.add(filePath);
+    }
+  }
+
+  /**
+   * Removes a file and its edges from the graph.
+   */
+  public removeFile(filePath: string) {
+    const oldDeps = this.adjacencyList.get(filePath);
+    if (oldDeps) {
+      for (const dep of oldDeps) {
+        const incoming = this.reverseAdjacencyList.get(dep);
+        if (incoming) {
+          incoming.delete(filePath);
+          if (incoming.size === 0) {
+            this.reverseAdjacencyList.delete(dep);
+          }
+        }
+      }
+      this.adjacencyList.delete(filePath);
+    }
+
+    // Also remove from reverse list (in case this file was imported by others)
+    this.reverseAdjacencyList.delete(filePath);
+    for (const [node, deps] of this.adjacencyList.entries()) {
+      if (deps.has(filePath)) {
+        deps.delete(filePath);
+      }
+    }
+  }
+
+  /**
+   * Clears the entire graph.
+   */
+  public clear() {
+    this.adjacencyList.clear();
+    this.reverseAdjacencyList.clear();
+  }
+
+  /**
+   * Gets direct dependencies (files/namespaces this file imports).
+   */
+  public getOutgoing(filePath: string): string[] {
+    return Array.from(this.adjacencyList.get(filePath) || []);
+  }
+
+  /**
+   * Gets dependants (files that import this file/namespace).
+   */
+  public getIncoming(filePathOrNamespace: string): string[] {
+    return Array.from(this.reverseAdjacencyList.get(filePathOrNamespace) || []);
+  }
+
+  /**
+   * Exports the entire graph for debugging/serialization.
+   */
+  public serialize() {
+    const serialized: Record<string, { imports: string[]; importedBy: string[] }> = {};
+    const allNodes = new Set([...this.adjacencyList.keys(), ...this.reverseAdjacencyList.keys()]);
+
+    for (const node of allNodes) {
+      serialized[node] = {
+        imports: this.getOutgoing(node),
+        importedBy: this.getIncoming(node),
+      };
+    }
+    return serialized;
+  }
+}