CodeGraph

Synaptic

O Synaptic é uma plataforma de manutenção de código fundamentada na fonte, construída em torno de três sistemas conectados: manutenção de API, memória de repositório e um grafo de conhecimento persistente. Juntos, eles permitem que um engenheiro ou assistente de IA entenda o que o código faz, lembre-se do que aconteceu com ele e faça reparos limitados sem adivinhar.

1. Manutenção de API mantém dependências externas e SDKs seguros para alterar. Bots de dependência podem informar que uma nova versão existe; o Synaptic inventaria as APIs que seu código realmente usa, detecta mudanças de quebra fundamentadas na fonte, encontra os locais de chamada afetados, planeja um reparo limitado em uma árvore de trabalho isolada, verifica invariantes do grafo e testes selecionados, e só publica um PR de rascunho quando as evidências estão completas.
2. Memória de repositório preserva o histórico que normalmente vive em pessoas, conversas, branches com falhas, notas de incidentes e PRs antigos. Ela registra mudanças anteriores, regressões, decisões, procedimentos, resultados de verificação e artefatos externos como evidências vinculadas à fonte, e então recupera essa memória por meio da CLI ou do servidor MCP para que o trabalho futuro comece com contexto em vez de arqueologia.
3. O grafo de conhecimento é o mapa estrutural por trás de tudo. O Synaptic transforma qualquer pasta, monorepo ou conjunto federado de repositórios em um grafo persistente e consultável de símbolos, arquivos, recursos, chamadas, imports, herança, uso de SQL, riscos de despacho dinâmico e arestas entre repositórios em mais de 30 linguagens com tree-sitter.

O grafo responde a perguntas arquiteturais, rastreia impacto reverso ("o que essa mudança quebraria?"), prevê e executa especulativamente mudanças antes de você fazê-las, planeja refatorações seguras, compara arquitetura ao longo do histórico do git e audita SQL para desempenho e segurança. A memória adiciona o que o grafo não consegue inferir apenas da árvore atual. A manutenção de API usa ambos para transformar mudanças upstream em planos de reparo baseados em evidências. O mecanismo e o fluxo de trabalho de terminal são entregues como um único binário Rust estático (synaptic) sem runtime ou interpretador. Um addon nativo opcional synaptic-ui fornece visualização de repositório único, federação de workspaces e configuração de MCP, além de uma visualização de Ferramentas pesquisável para cada tarefa do Synaptic no Windows, Linux e macOS. O Synaptic escreve grafos legíveis por máquina junto com relatórios legíveis por humanos e visualizações 2D/3D/SVG, e expõe um servidor MCP para que um assistente de codificação de IA possa usar esses sistemas antes de fazer grep ou ler arquivos.

Explorador de arquitetura

Transforme um graph.json existente em um mapa de arquitetura offline e autocontido:

synaptic chart

A visão geral classifica comunidades fundamentadas na fonte e suas relações exatas mais fortes. Pesquise, alterne temas ou abra qualquer subsistema sem reconstruir o grafo.

Dentro de um subsistema, selecione um símbolo para isolar suas dependências reais de um salto. O inspetor mostra relações de entrada e saída, e cada linha continua diretamente para o símbolo conectado.

A tela App do aplicativo de desktop verifica o Release do GitHub publicado pelo fluxo de trabalho de release, baixa o arquivo correspondente, verifica sua soma de verificação publicada e atualiza os executáveis incluídos. Adicionar aos aplicativos instala para o usuário atual e o torna pesquisável no menu Iniciar do Windows, em Aplicativos do macOS ou no menu de aplicativos do Linux sem acesso de administrador. Remover a instalação do desktop não afeta dados do projeto, grafos, configurações ou uma CLI instalada separadamente.

O aplicativo de desktop segue a preferência de tema claro ou escuro do sistema operacional no primeiro início e salva a escolha do usuário depois disso.

Se alguém baixar apenas synaptic-ui, a tela de primeira execução baixa automaticamente as ferramentas de comando verificadas do Release mais recente do GitHub e as coloca ao lado do aplicativo. Nenhum terminal, alteração de PATH ou instalação em todo o sistema é necessária.

Se você não quiser executar o servidor MCP você mesmo, o Synaptic Cloud é um serviço MCP hospedado pago para usar o Synaptic com seus projetos: synapticgraph.com. Para sincronização de grafo acionada por commit e reparos de rascunho verificados de API ou dependência, siga o guia de automação do GitHub.

Use o Synaptic com um projeto

Comece a partir da raiz de qualquer repositório. O Synaptic escreve seu índice e relatórios em synaptic-out/ e mantém a configuração específica do projeto em .synaptic/.

O caminho mais fácil é pedir ao seu agente de codificação de IA para instalar e configurar o Synaptic para o repositório atual, e então pedir que ele siga os guias de Instalação, Início rápido e Integração com assistente. Se você preferir fazer você mesmo, o caminho manual é:

# 1. Install the binary from this repository
cargo install --path bin/synaptic

# Or download a prebuilt binary from GitHub Releases, then confirm it works
synaptic --version

# Optional: install and launch the native setup UI
cargo install --path bin/synaptic-ui
synaptic-ui

# 2. Build the first graph for your project
cd path/to/your/project
synaptic extract .

# 3. Ask structural questions without rereading the whole codebase
synaptic query "authentication flow"
synaptic affected parse_config
synaptic search --pattern god-class

# 4. Keep the graph current as the project changes
synaptic update
synaptic watch
synaptic hook install

Para uma configuração normal de projeto, adicione um .synapticignore se houver caminhos gerados, fornecidos por terceiros ou sensíveis que você não deseja indexar; extract também respeita .gitignore e ignora segredos comuns como .env e arquivos de chave. Use synaptic hook install quando quiser que commits do Git, checkouts e mesclagens de grafo mantenham synaptic-out/graph.json atualizado automaticamente.

Depois que o grafo existir, ative os sistemas de nível superior conforme necessário:

# Repository memory: ingest history, docs, decisions, and outcomes
synaptic memory refresh --root .
synaptic memory search "previous auth migration"

# API maintenance: configure monitored APIs and check real usage
synaptic api init
synaptic api discover --json
synaptic api coverage --json
synaptic api scan --offline --json

# AI assistant integration: serve the graph and memory over MCP
synaptic serve
synaptic install codex --global

O modelo mental mais seguro: execute extract primeiro, use query / affected / search para explorar, adicione hooks ou watch quando o projeto estiver ativo, e então habilite os fluxos de trabalho memory e api quando quiser que o Synaptic preserve o histórico ou mantenha contratos externos.

---

Por quê

• Clareza estrutural. Nós gigantes, conexões surpreendentes entre módulos, ciclos de import e estrutura de comunidades são calculados para você.
• Impacto e previsão. Impacto reverso, previsão de mudanças e execuções de teste especulativas respondem "o que depende disso?" e "o que essa mudança quebraria?" antes de você tocar no código.
• Economia de tokens. Consultar um grafo compacto custa uma fração de alimentar arquivos brutos para um LLM, então um assistente pode responder a essas perguntas sem carregar o repositório.
• Confiança auditável. Cada relação inferida é marcada como EXTRACTED, INFERRED ou AMBIGUOUS.
• Escala além de um repositório. Um workspace pode federar muitos repositórios com resolução real de arestas entre repositórios (superfícies de exportação mais aliases de import / tsconfig / module-federation).
• Offline por padrão. Um corpus apenas de código nunca faz uma chamada de rede. A passagem semântica opcional sobre documentação e artigos é o único recurso que precisa de uma chave de API.

Destaques

• Mais de 30 idiomas via tree-sitter, cada um compilado e testado isoladamente no CI, além de extratores baseados em regex para alguns formatos e extração de script para Vue/Svelte/Astro e Razor/Blazor. Veja Languages.
• Um comando para um grafo completo além de visualizações 2D, 3D e SVG, um relatório Markdown e exportações GraphML / Cypher / DOT / Obsidian / wiki. Veja Output Formats.
• Consultas de grafo: busca de subgrafo relevante, caminho mais curto, explicação de nó, impacto reverso ("o que depende disso"), encontrar todas as referências (synaptic references / a ferramenta find_references: em todos os lugares onde um símbolo é usado, incluindo imports e herança que uma visão somente de chamador perde), e esboços de símbolos por arquivo. Veja Querying.
• Consciência de despacho dinâmico: barramentos de eventos (Node EventEmitter, DOM CustomEvent, eventos C#) e IPC do Electron vinculam um publicador ao seu assinante por meio de um nó de canal, de modo que um manipulador alcançado apenas através do barramento não é um chamador fantasma de 0. Reflexão e despacho dinâmico que não podem ser resolvidos estaticamente (buscas por nome, tabelas de despacho, eval, import dinâmico, reflexão .NET/Python/JVM) são catalogados para que uma resposta de "0 dependentes" nunca seja confundida com "seguro para alterar": synaptic hazards (e a ferramenta MCP dynamic_hazards) listam os locais, e affected anexa uma ressalva quando um símbolo é alcançável apenas dinamicamente.
• Diff de viagem no tempo: synaptic diff <rev1> [rev2] (ou --since <date>) relata como o grafo mudou entre duas revisões git, dependências adicionadas/removidas, APIs removidas, deriva arquitetural, novos ciclos e pontos críticos, com um relatório Markdown ou HTML autocontido.
• Busca arquitetural (SYNQL): synaptic search executa uma pequena linguagem de consulta inspirada em Cypher sobre o grafo, combinando por estrutura (tipo, visibilidade, LOC, fan-in/out, caminhos de comprimento variável) com agregação count(...), --explain, consultas salvas e uma biblioteca de padrões nomeados (singleton, factory, observer, service-locator, god-class). Não é busca de texto. synaptic search --file <path> lista todos os símbolos definidos em um arquivo, ordenados por linha, sem necessidade de consulta.
• Refatoração segura: synaptic refactor rename / move / extract emitem um plano de execução com pontuação de confiança (plan.json + plan.md) para um agente de IA aplicar, então refactor verify reconstrói e verifica se o grafo se manteve (a definição foi movida/renomeada, nenhuma referência foi perdida, nenhum novo ciclo). O Synaptic nunca edita o código-fonte diretamente.
• Previsão de mudanças e execução especulativa: synaptic predict prevê o raio de impacto de uma mudança, APIs públicas em risco, testes em risco, novos ciclos, pontuação de risco e uma lista de verificação antes de você editar (--edit "<kind>:<symbol>" prevê uma edição descrita antes de qualquer código ser escrito); synaptic speculate então aplica a mudança em um worktree git descartável e realmente executa os testes em risco além de um build/type-check, relatando aprovação/reprovação real — a metade da verdade fundamental da previsão; e synaptic eval replay reproduz o histórico para pontuar a qualidade da previsão contra a verdade fundamental do git (testes co-editados, APIs removidas), transformando a precisão da previsão em uma métrica passível de CI. Veja Commands.
• Auditoria de desempenho e segurança SQL: synaptic sql audit sinaliza lacunas de segurança em nível de linha, concessões excessivamente amplas, provável injeção de SQL, índices ausentes em colunas de filtro/chave estrangeira, SELECT *, predicados não-sargáveis, padrões N+1 e chaves primárias ausentes sobre o grafo ciente de SQL (a extração agora modela colunas, índices, políticas RLS e concessões, e vincula consultas de aplicativos às tabelas que elas tocam). synaptic sql advise --query "<sql>" critica uma consulta candidata antes de você escrevê-la, referenciada cruzadamente com as tabelas/índices/RLS do grafo. Veja SQL Auditing.
• Grafo de recursos (universal, ativado por padrão): arquivos de dados/recursos (JSON de dados e .mcmeta sob assets/, data/ e diretórios gerados) são indexados como nós do grafo, e strings semelhantes a referências dentro deles vinculam-se ao arquivo, recurso (por id derivado de caminho como ns:path) ou símbolo de código que nomeiam — então affected e query_graph abrangem código e recursos. Um recurso gerado que duplica um criado manualmente no mesmo caminho lógico recebe uma aresta shadows (superficializada por readiness_audit). Independente de framework — um ResourceLocation do Minecraft é apenas uma instância da forma de id lógico. JSON de localização também contribui com um conjunto limitado de aliases de busca somente por chave (nunca prosa traduzida), para que catálogos de mensagens sejam descobertos sem um nó de grafo por tradução. extract --no-resources restaura o grafo somente de código.
• Auditoria de portabilidade/prontidão: synaptic audit readiness classifica prováveis bloqueadores de portabilidade a partir de sinais de grafo, código-fonte e configuração: retornos de sentinela de framework, placeholders/stubs, ruído de recursos gerados e metadados de projeto. A ferramenta MCP readiness_audit expõe o mesmo relatório estruturado.
• Servidor MCP (protocolo stateless 2026-07-28 com compatibilidade legada até 2025-11-25) expondo 30 ferramentas principais, cinco ferramentas de vulnerabilidade e cinco ferramentas de memória de repositório somente leitura via stdio ou HTTP: busca de subgrafo, leitura de código-fonte, impacto reverso, encontrar todas as referências, riscos de despacho dinâmico, raio de impacto de PR/árvore de trabalho, previsão de mudanças, seleção preditiva de testes, previsão de impacto de edição, busca estrutural, diff de viagem no tempo, renomeação somente de plano e auditoria/aconselhamento SQL, além de prompts, conclusões, assinaturas de recursos e saída de ferramenta estruturada. Veja MCP Server.
• Memória de repositório fundamentada no código-fonte: uma sobreposição temporal para mudanças anteriores, tentativas falhas, regressões, decisões, procedimentos, verificação, artefatos externos de issue/PR/CI/incidente, resumos semânticos de comunidade e linhagem de arquivo/símbolo ciente de revisão. Ganchos git capturam commits exatos e atualizam o conhecimento; política principal, armazenamentos compactos/federados, pacotes de equipe com soma de verificação, benchmarks de recuperação e evidências de impacto agregadas são incorporados à superfície CLI e MCP. Veja Repository Memory.
• Fluxos de trabalho de API automantidos: synaptic api inventaria versões de SDK, descobre contratos, registra lacunas de cobertura, detecta mudanças de quebra fundamentadas no código-fonte, localiza locais de chamada afetados e prepara reparos limitados em um worktree isolado. A verificação falha fechada em evidências incompletas, e somente o estágio explícito publish pode criar ou atualizar um PR de rascunho idempotente. Veja API maintenance.
• Gerenciamento de vulnerabilidades de dependências: synaptic vuln lê todos os lockfiles em um repositório em 12 ecossistemas de pacotes, combina versões resolvidas contra um corpus OSV e decide se cada aviso realmente se aplica aqui em vez de parar em uma correspondência de versão. As descobertas carregam uma escada de evidências, um caminho de dependência, uma prioridade derivada de CVSS, locais de chamada e exposição de ponto de entrada apoiados por grafo, e um plano de remediação; descobertas aplicáveis com um alvo corrigido podem se tornar reparos limitados e isolados cuja resolução de dependência corrigida e testes de repositório devem passar antes que o Synaptic possa criar um PR de rascunho determinístico no GitHub ou MR no GitLab. Exportação/importação com soma de verificação mantém reparo e credenciais de provedor separados, e o Synaptic nunca aprova ou mescla. Riscos aceitos são limitados no tempo e expiram por conta própria. Cinco ferramentas MCP permitem que assistentes verifiquem pacotes, executem uma varredura apoiada por grafo, inspecionem evidências de exposição e solicitem um reparo limitado de transferência. Varreduras de repositório inteiro permanecem locais por padrão; um agente deve optar antes que a lista de dependências seja enviada ao OSV. Veja Vulnerability Management.
• Reconstruções incrementais, observação de arquivos e ganchos git mantêm o grafo atualizado. Veja Incremental Updates.
• Painel de PR ciente de grafo com detecção de raio de impacto e conflito de ordem de mesclagem. Veja PR Dashboard.

---

Economia de tokens

Um benefício central de consultar um grafo compacto é ler uma resposta pequena em vez do código-fonte inteiro. query_graph usa por padrão uma lista concisa e classificada dos símbolos mais relevantes (algumas centenas de tokens); passe full=true para o subgrafo inteiro com suas arestas. As figuras abaixo medem uma resposta de subgrafo completa (com um orçamento de 2.000 tokens) no próprio código-fonte do Synaptic (199 arquivos Rust, 56.408 linhas, 510.966 tokens cl100k) — uma dessas respostas a uma pergunta estrutural é ~1.950 tokens, versus ler os arquivos de código-fonte que ela realmente toca:

Em seis perguntas abrangendo diferentes subsistemas, consultar o grafo usou 27-38x menos tokens (cerca de 31x no geral) do que ler os arquivos que a resposta referencia:

Pergunta	Resposta da consulta	Ler os arquivos	Menos tokens
tratamento de requisição http	1.804	48.803	27x
criação / coleta de sessão	1.974	65.578	33x
subgrafo query_graph	2.011	53.759	27x
walker de extração	1.977	70.443	36x
busca / classificação de PR	1.926	73.231	38x
mesclagem incremental	2.010	53.440	27x

Uma resposta de consulta permanece pequena não importa o tamanho do repositório (é limitada pelo orçamento de tokens), então a proporção cresce com o código-fonte. Observe que o índice graph.json em si é grande porque codifica todos os símbolos e arestas; você nunca o carrega no contexto, você o consulta e obtém apenas a fatia acima.

Reprodutível. Os tokens são contagens exatas de cl100k_base via cargo run -p synaptic-server --example tokcount. A linha de base são os arquivos de código-fonte únicos referenciados pelo resultado (arquivos inteiros, o caso conservador de grep-e-depois-ler; não conta os arquivos sem saída que você abriria sem o grafo). Execute synaptic extract . em qualquer repositório e compare por conta própria. Esta é uma medição de compressão de contexto, não uma alegação de economia de agente de ponta a ponta; a metodologia pareada SWE-bench/BEIR está em BENCHMARKS.md.

Desempenho de ferramentas avançadas

As ferramentas de análise respondem em milissegundos porque operam sobre o grafo em memória, não sobre o código-fonte. Micro-benchmarks Criterion (máquina de desenvolvimento; execute cargo bench -p synaptic-synql -p synaptic-refactor):

Operação	Carga de trabalho	Tempo
Consulta de propriedade SYNQL (search)	WHERE/loc/fan_out sobre um grafo de 2.000 nós	~0,47 ms
Junção de padrão de relacionamento SYNQL (search)	junção de um salto sobre um grafo de 2.000 nós	~0,97 ms
Plano de renomeação de refatoração segura (refactor rename)	símbolo quente, ~120 locais de chamada em 40 arquivos, incl. a varredura textual	~4,9 ms

A auditoria do pipeline de grafo 0.6.3 adicionou cobertura Criterion dedicada para construção, comparação incremental e federação (cargo bench -p synaptic-graph -p synaptic-incremental -p synaptic-workspace). Nos fixtures de auditoria, federação de 16 x 500 nós em uma passada medida 136,1 -> 6,07 ms, uma comparação de topologia de 10k nós 54,92 -> 9,77 ms e uma aresta duplicada de 1.000 locais 240,74 -> 0,56 ms. Estes são micro-benchmarks dependentes de máquina; os fixtures confirmados e curvas de crescimento são a evidência reprodutível.

O diff de viagem no tempo é limitado por build em vez de consulta: o delta do grafo em si é quase instantâneo, e o custo é construir cada revisão em um worktree git descartável. Grafos construídos são armazenados em cache por SHA de commit sob synaptic-out/history/, então um diff repetido dos mesmos commits retorna imediatamente e apenas o lado da árvore de trabalho é reconstruído.

Precisão

O estudo de tokens acima é um teste de fumaça em um repositório. As relações que o Synaptic extrai são validadas separadamente, contra um corpus rotulado manualmente de mini-repositórios cujas arestas de chamada reais, vínculos de teste, raios de explosão (incluindo nós distratores que não devem ser sinalizados), e acoplamentos entre linguagens (incluindo similares que não devem se conectar) são escritos à mão em um ground_truth.toml. Uma verificação prévia falha na execução se qualquer símbolo rotulado não for resolvido, então um nó descartado se torna uma falha ruidosa em vez de um denominador silenciosamente menor. Cada número abaixo é uma comparação exata de conjuntos contra esses rótulos, reproduzível com synaptic eval corpus:

Fixture	Família	Chamada P/R/F1	Rec. teste-afetado	Rec. explosão / excl. / tamanho	Cross P/R/F1
systems-rust	systems-rust	100/50/66	—	100% / 100% / 1.0	—
scripting-python	scripting-python	100/100/100	100%	100% / 100% / 2.0	—
web-ts	web-ts	100/100/100	—	100% / 100% / 1.0	—
oo-java	oo-java	100/100/100	—	100% / 100% / 1.0	—
systems-go	systems-go	100/100/100	—	100% / 100% / 1.0	—
deep-python (multi-salto)	scripting-python	100/100/100	100%	100% / 100% / 3.0	—
cross-lang-ts-rust	cross-lang	—	—	—	100/100/100
cross-lang-grpc	cross-lang	—	—	—	100/100/100
cross-lang-queue	cross-lang	100/100/100	—	—	100/100/100
cross-lang-pyo3	cross-lang	100/100/100	—	—	100/100/100
cross-lang-ws	cross-lang	100/100/100	—	—	100/100/100

Em 11 fixtures / 6 famílias de linguagens / 42 símbolos rotulados (todos resolvidos): arestas de chamada agrupadas precisão 100% / recall 94% / F1 97% sobre 18 arestas rotuladas; raio de explosão recall 100% com 0 distratores vazados; teste-afetado recall 100% sobre os vínculos rotulados, com o único teste rotulado como não relacionado corretamente não selecionado; entre linguagens precisão 100% / recall 100% / F1 100% sobre 6 acoplamentos rotulados, com 6 acoplamentos distratores (rotas similares, um stub gRPC de serviço errado, um helper PyO3 não registrado, ...) corretamente não conectados. Lendo os números honestamente:

• Nenhuma aresta de chamada falsa foi observada neste corpus de 18 arestas (precisão 100%); isso é um resultado no corpus, não uma garantia em escala.
• Recall é 100% para Python/TypeScript/Java/Go, que resolvem chamadas entre arquivos. Os 50% em Rust são reais e esperados: a resolução de chamadas em Rust é intra-arquivo, então uma chamada entre arquivos qualificada por módulo é uma falha verdadeira. A alcançabilidade entre arquivos ainda é preservada através de arestas imports, que é o motivo pelo qual o recall do raio de explosão permanece em 100%.
• O raio de explosão é pontuado por ruído, não apenas por falhas: cada semente rotula nós distratores que devem ficar de fora, e nenhum vazou (exclusão 100%); o tamanho médio do conjunto de impacto relatado é igual ao tamanho real do conjunto afetado, então a caminhada não é excessivamente ampla.
• A seleção de teste-afetado é multi-salto: a fixture deep-python altera uma folha a três saltos de chamada abaixo de seu teste e ainda a seleciona, enquanto um teste deliberadamente não relacionado é excluído (então o recall não é comprado com precisão).
• A precisão entre linguagens é conquistada em cinco tipos de fronteira: um fetch("/session") TypeScript conecta-se ao handler axum Rust que o serve (e um cliente /api/users montado alcança sua rota composta por prefixo); um cliente gRPC Python alcança seu servidor tonic; um produtor Kafka alcança seu consumidor; um import Python alcança sua função Rust exportada via PyO3; um comando WebSocket JS alcança seu handler C# — enquanto cada distrator similar (um caminho /sessions, um stub de serviço errado, um tópico errado, um helper PyO3 não registrado, uma mensagem não tratada) é corretamente deixado desconectado.

O corpus é intencionalmente pequeno e verificado manualmente; ele valida a correção da extração em formas representativas, não cobertura em escala de internet. A seção escala mede repositórios reais. Veja BENCHMARKS.md para metodologia e o formato da verdade fundamental.

Calibração de previsão

A camada de previsão de mudanças anexa uma confiança a cada co-mudança prevista. synaptic eval calibrate mede se essa confiança é significativa: ele percorre o histórico recente e, para cada commit, usa cada arquivo alterado como semente, pergunta ao preditor (treinado apenas em commits anteriores) quais arquivos devem co-mudar, então pontua a confiança de cada previsão contra o que realmente mudou. Ele relata uma tabela de confiabilidade (taxa de acerto prevista vs. observada por intervalo de confiança), uma pontuação de Brier, a pontuação de habilidade de Brier contra uma linha de base de sempre-adivinhar-a-taxa-base (para que o número de Brier seja interpretável), e erro de calibração esperado.

Isso é uma propriedade por repositório: a confiança reflete os hábitos de commit de cada repositório, então execute-o no seu. No histórico deste próprio repositório (sintético, com muitos squashes), a pontuação de habilidade é negativa — a previsão de co-mudança ali é pior do que adivinhar a taxa base, porque commits com squash tocam muitos arquivos de uma vez e inflam a co-mudança aparente. Isso é a métrica funcionando: ela se recusa a enfeitar um preditor que está mal calibrado neste histórico. Metodologia em BENCHMARKS.md.

Escala

Taxa de extração em repositórios OSS reais abrangendo níveis de tamanho e famílias de linguagens, cada um clonado em um SHA fixado (synaptic eval scale; rede + git, opt-in). Cada tempo é a mediana de 5 repetições. A execução de 2026-08-12 cobriu 10 repositórios, 9 famílias de linguagens, 783.928 LOC suportados, 71.437 nós e 111.851 arestas sem pulos. A taxa de transferência quente variou de 44k a 339k LOC/s; a aceleração mediana de frio para quente variou de 1,4x a 2,8x. O maior checkout medido aqui, Humanizer (476.967 LOC suportados), levou 7,07s frio e 2,69s quente.

Esses são resultados de árvore de trabalho de desenvolvimento específicos da máquina, não alegações universais ou de release limpo. "Frio" limpa o cache AST do Synaptic, mas o checkout e o cache de arquivos do SO estavam quentes; o tempo incremental re-extrai um arquivo de origem nomeado inalterado e não é latência de patch. Método completo, resultados por repositório, limitações, SHAs exatos e amostras brutas estão em BENCHMARKS.md.

Qualidade de extração em escala

Escala mede quão rápida a extração roda; um grafo que ancorasse cada declaração na linha errada postaria tempos idênticos. synaptic eval quality mede se o grafo está correto, em 60 repositórios fixados cobrindo todas as 39 linguagens fornecidas (80.061 arquivos, 938.001 nós), usando propriedades que não precisam de rótulos manuais: exatidão de ancoragem, saúde de parse e recuperação, determinismo, equivalência incremental e uma comparação independente com universal-ctags.

A execução de 2026-08-15: exatidão de ancoragem agrupada 735.198 / 735.493 (99,96%), com 60/60 repositórios determinísticos e incrementalmente equivalentes e sem pulos. 30 de 39 linguagens são exatas em toda declaração verificada.

O corpus é completo em linguagens por construção — um teste falha quando um extrator fornecido não tem repositório exercitando-o — e cada repositório carrega limites fixados, então uma regressão sai com código de saída não-zero nomeando o repositório e a métrica. O oráculo é publicado como uma diferença simétrica, nunca uma pontuação de recall: ctags é uma segunda opinião independente, não verdade fundamental. Método, resultados por linguagem e os defeitos que este benchmark encontrou estão em BENCHMARKS.md.

Instalação

O Synaptic compila com uma toolchain Rust estável (fixada em 1.97.1 via rust-toolchain.toml).

# From a clone, installs the `synaptic` binary onto your PATH:
cargo install --path bin/synaptic

# Optional native workspace/MCP setup app (uses `synaptic` from the same directory or PATH):
cargo install --path bin/synaptic-ui

# ...or build it in-tree:
cargo build --release -p synaptic -p synaptic-ui

Binários CLI pré-compilados e UI opcionais para Linux/macOS/Windows estão anexados a cada GitHub Release marcado (veja o workflow release). Integrações opcionais estão atrás de flags de feature (desligadas por padrão): pg (introspecção Postgres), push (exportação ao vivo Neo4j/FalkorDB), e office / gws / media (ingestão de planilha / Google-Workspace / áudio-vídeo), por exemplo cargo install --path bin/synaptic --features pg,push. Veja Instalação, UI Desktop, e Configuração.

Uma vez instalado, atualize no lugar com synaptic self-update (verifica uma soma de verificação SHA-256 e solicita confirmação antes de substituir o binário). Opte por um aviso em segundo plano "atualização disponível" com synaptic self-update --enable — desligado por padrão, roda no máximo uma vez por dia e nunca bloqueia comandos normais. cargo install / builds de fonte podem se auto-atualizar também, mas a troca instala o binário pré-compilado com features padrão.

Início rápido

# 1. Build the graph for the current directory -> synaptic-out/
synaptic extract .

# 2. Ask the graph a question (returns a relevant subgraph)
synaptic query "authentication flow"

# 3. What would changing a symbol break? (reverse impact)
synaptic affected parse_config

# 4. Serve the graph to an AI assistant over MCP
synaptic serve

extract honra .synapticignore / .gitignore e pula arquivos sensíveis (.env, chaves). Um corpus somente código roda totalmente offline; a passagem semântica opcional de LLM sobre docs e papers (extract --semantic) precisa de uma chave de API (por exemplo OPENAI_API_KEY). Veja Início rápido.

Artefatos de saída (synaptic-out/)

Artefato	O que é
graph.json	Grafo completo (JSON node-link), consulte sem reler arquivos
GRAPH_REPORT.md	Nós deus, conexões surpreendentes, perguntas sugeridas, ciclos de importação
graph.html	Explorador 2D interativo (busca + cor de comunidade)
graph-3d.html	Grafo de força 3D interativo (busca, alternância de relações, cores de federação)
graph.svg	Layout estático (Barnes-Hut, empacotado por componente, em forma de ativo)
chart.html	Mapa de arquitetura sob demanda com drill-down de comunidade para símbolo a partir de synaptic chart
graph.graphml / graph.cypher / graph.dot	Importação para Gephi / Neo4j / Graphviz
callflow.html / tree.html	Fluxo de chamadas Mermaid + árvore de arquivos D3
obsidian/, wiki/	Cofre Obsidian / wiki Markdown (com --obsidian / --wiki)

Comandos

Comando	O que faz
extract [path]	Constrói o grafo e grava synaptic-out/. Flags: --directed, --obsidian, --wiki, --semantic
export <format>	Reemite um formato a partir de um graph.json existente (sem reconstrução) ou envia ao vivo para Neo4j/FalkorDB
chart	Cria um mapa de arquitetura interativo offline com detalhamento de subsistemas com base no código-fonte. Flags: --graph, --out, --repo, --max-communities
query <text>	Retorna um subgrafo classificado por relevância (cada nó pontuado). Flags: --max-nodes, --repo, --dfs, --since <ref> (impulsiona código alterado no branch), --seed-changed, --json
path <from> <to>	Caminho mais curto entre dois nós
explain <node>	Mostra um nó e seus vizinhos
affected <node>	Nós que dependem (transitivamente) de um nó; adiciona uma ressalva quando um símbolo com "0 dependentes" é alcançável apenas via despacho dinâmico. Flags: --depth, --relation
hazards	Lista os locais de reflexão/despacho dinâmico que o grafo registra, para que uma resposta de "0 dependentes" não seja confundida com "seguro". Flags: --repo, --kind, --limit
search [synql]	Busca estrutural via SYNQL ou um --pattern nomeado. Flags: --explain, --save/--saved, --json
diff <rev1> [rev2]	Diff de grafo com viagem no tempo entre duas revisões git. Flags: --since, --report, --html, --scope
refactor <action>	Planeja um rename/move/extract seguro para um agente e então verify o grafo (nunca edita o código-fonte)
predict [paths...]	Prevê uma mudança antes de aplicá-la: raio de impacto, testes em risco, risco, APIs removidas, ciclos. Flags: --base, --edit "<kind>:<symbol>", --gate
speculate [paths...]	Executa uma mudança de verdade em um worktree descartável: testes em risco + build/verificação de tipos, reportando sucesso/falha. Flags: --patch, --test-cmd, --check-cmd
audit readiness	Auditoria estática de portabilidade/prontidão: classifica retornos de sentinela de frameworks, placeholders/stubs, ruído de recursos gerados e metadados do projeto. Flags: --profile, --severity, --repo, --json
sql <action>	audit SQL para desempenho + segurança sobre o grafo ciente de SQL, ou advise --query "<sql>" em uma consulta candidata antes de escrevê-la. Flags: --severity, --explain --db-url (EXPLAIN ao vivo, requer --features live-explain)
eval replay [from]	Reproduz o histórico para pontuar a qualidade das previsões contra a verdade básica do git (passível de CI). Flag: --min-test-recall
eval quality	Mede a correção da extração no corpus do mundo real fixado, com limites por repositório (rede + git, opt-in). Flags: --language, --repo, --pin, --update-baselines
update [paths...]	Reconstrói incrementalmente após mudanças em arquivos (--full para reconstrução completa)
watch	Reconstrói automaticamente conforme os arquivos mudam (repositório único; use workspace build --watch para um workspace)
serve	Executa o servidor MCP (stdio, ou --http <addr> --api-key <key>)
prs [number]	Dashboard/detalhe de PR ciente do grafo. Flags: --triage, --conflicts, --base, --repo
workspace <action>	Federação multi-repositório / monorepo (init/add/discover/build/federate/coordinate/sync/status/list). build --watch mantém um grafo federado ao vivo em todos os repositórios membros
global <action>	O armazenamento global de grafos entre repositórios (~/.synaptic)
memory <action>	Ingerir, registrar, buscar, compactar, trocar e avaliar memória durável de repositório com base no código-fonte
api <action>	Inventariar dependências de API, descobrir contratos, medir cobertura, escanear mudanças, avaliar impacto e reparar/verificar/publicar com segurança um rascunho de PR
merge-graphs <graphs...>	Compõe vários arquivos graph.json em um único grafo com namespaces
ingest <source>	Ingerir uma fonte externa (cargo / mcp / scip / pg / url; office / gws / media atrás de feature flags)
hook <action>	Gerencia git hooks + o merge driver graph.json
install / uninstall [platform]	Instala a habilidade Synaptic para um assistente host
cache <action>	Mantém o cache de extração em disco
self-update	Atualiza o binário a partir do release mais recente do GitHub (opt-in). Flags: --enable/--disable (aviso em segundo plano), --check, --yes

A referência completa com todas as flags está em Commands. Execute synaptic <command> --help para a lista de flags no terminal.

Use a partir de um assistente de IA (MCP)

synaptic serve                                                        # stdio MCP server
synaptic serve --http 127.0.0.1:8765 --api-key "$SYNAPTIC_API_KEY"   # HTTP server
synaptic serve --allow-memory-write                                   # opt-in outcome recording
synaptic serve --memory-principal reviewer \
  --memory-repository-claim owner/repo                                # scope-filtered memory
synaptic serve --graph promoted/graph.json --immutable-graph \
  --expected-graph-sha256 "$GRAPH_SHA256"                             # authenticate exact loaded bytes
synaptic serve --http 127.0.0.1:0 --ready-file /run/synaptic/ready.json # race-free child startup

O servidor expõe 30 ferramentas principais, cinco ferramentas de vulnerabilidade e cinco ferramentas somente leitura de memória de repositório: navegação no grafo (query_graph, get_node, get_source, get_neighbors, get_community, god_nodes, graph_stats, shortest_path), análise de impacto (affected, find_callers, find_callees, find_references, dynamic_hazards, predict_impact, affected_tests, predict_edit), federação (list_repos, repo_stats), revisão de mudanças/PR (working_changes_impact, list_prs, get_pr_impact, triage_prs), o trio avançado (structural_search, time_travel_diff, somente planejamento plan_rename), auditoria de portabilidade/prontidão (readiness_audit) e auditoria de SQL (audit_sql, advise_sql). O trabalho de vulnerabilidade adiciona vuln_check_dependency, vuln_findings, vuln_explain, vuln_scan e vuln_brief; uma varredura grava apenas com record: true e envia coordenadas de dependência para OSV apenas com online: true. Em grafos federados, os agentes selecionam uma tag de list_repos; varreduras, descobertas, explicações, registros e briefs de reparo são então isolados para aquele membro, incluindo checkouts externos e repositórios em cache do Git. Membros somente artefato são explicitamente reportados como não escaneáveis. A recuperação de memória adiciona search_memory, explain_history, find_similar_change, known_pitfalls e explain_decision; record_change_outcome é anunciado apenas com --allow-memory-write. Também serve prompts MCP, completions de argumentos, templates de recursos e assinaturas, e uma pequena superfície REST (/api/stats, /api/query, ...) para clientes não MCP. A saída das ferramentas é ajustada para permanecer enxuta em tokens (padrões concisos, listas limitadas); adicione serve --concise (ou defina SYNAPTIC_CONCISE) para reduzir ainda mais os tamanhos padrão. Para implantações com pin de digest ou somente leitura, serve --immutable-graph --expected-graph-sha256 <HEX> autentica o buffer de bytes exato que analisa e desativa hot-reload em disco, atualização de código-fonte e monitoramento do sistema de arquivos. --http 127.0.0.1:0 --ready-file <PATH> vincula antes de publicar atomicamente o endereço atribuído pelo kernel, evitando corridas de reserva de porta em supervisores de processo. synaptic install conecta o grafo a um assistente host (um hook PreToolUse para Claude; um servidor MCP nativo para Codex, com synaptic install codex --global para o aplicativo de desktop Codex). Veja MCP Server e Assistant Integration.

Linguagens

30+ linguagens via tree-sitter, cada uma construída e testada isoladamente no CI: Python, JavaScript/TypeScript (+ JSX/TSX, Vue/Svelte/Astro), Go, Rust, Java, C#, Kotlin, Swift, C, C++, Objective-C, Ruby, PHP, Scala, Groovy, Lua, Dart, Elixir, Julia, Zig, Bash, PowerShell, Verilog, Fortran, CodeQL QL e extratores de regex/delegação para Classic ASP, Salesforce Apex, Pascal/Delphi e Razor/Blazor. Além de formatos de dados e projeto: SQL, JSON, YAML, HCL/Terraform, arquivos de projeto .NET (.csproj/.sln/.slnx) e estrutura Markdown. Arestas cientes de framework para PHP/Laravel e Dart/Flutter. Detalhamento completo em Languages.

Documentação

O fluxo de trabalho de manutenção de API nativo de grafo, neutro de fornecedor e automantido está documentado em API maintenance.

A documentação completa vive no wiki do projeto:

• Começando: Home - Installation - Quickstart
• Conceitos: Architecture - Languages
• Usando: Commands - Extraction - Querying - Analysis and Reports - Output Formats - Visualizations
• Integrações: MCP Server - Assistant Integration - Ingestion - Semantic Analysis
• Escalando: Workspaces and Federation - Incremental Updates - PR Dashboard
• Referência: Configuration - Development

Desenvolvimento

cargo test --workspace --all-features              # all tests
cargo fmt --all --check                            # formatting (enforced in CI)
cargo clippy --workspace --all-targets --all-features -- -D warnings

O código é composto por 27 crates de biblioteca (crates/*) mais o binário synaptic (bin/). O CI constrói cada gramática de linguagem isoladamente, para que um bump de gramática que silenciosamente remove nós/arestas falhe por conta própria. Veja Development e Architecture.

Histórico de Estrelas

Comunidade

Perguntas, ideias ou quer mostrar o que você construiu? Junte-se a nós no Discord.

Licença

GNU Affero General Public License, versão 3 ou posterior (AGPL-3.0-or-later), veja LICENSE e NOTICE. Se você modificar o Synaptic e permitir que usuários interajam com ele por uma rede, a licença exige que você ofereça a esses usuários o código-fonte correspondente. Lançamentos históricos permanecem disponíveis sob as licenças sob as quais foram recebidos. O site privado da Plataforma Synaptic mantido separadamente e o plano de controle B2B são proprietários e não são cobertos pela licença deste repositório.