diskd-ai/codespaces

Codespaces -- Descoberta de Arquitetura com Mapa de Crenças

Consulte .belief_map.sexp para descobrir módulos, fronteiras e dependências antes de ler arquivos fonte. Nunca leia código cegamente -- consulte o grafo primeiro.

Scripts

Este skill inclui scripts Python. Execute-os a partir do diretório base do skill:

• scripts/belief_search.py -- consulta o grafo do mapa de crenças
• scripts/build_belief_map.py -- gera o mapa de crenças a partir do código fonte
• scripts/build_infra_topology.py -- extrai fatos de topologia de Kustomize, Helm e Terraform
• scripts/git_descendants.py -- encontra todos os commits descendentes de HEAD (ou de uma referência específica)

Nunca use cópias locais destes scripts -- elas podem estar desatualizadas e produzir JSON em vez de sexp.

Pré-requisito

Localize o mapa de crenças. Se ausente, construa-o:

ls .belief_map.sexp belief_map.sexp 2>/dev/null
# Construir: pip3 install tree-sitter tree-sitter-typescript tree-sitter-python
python3 scripts/build_belief_map.py          # incremental ~5s
python3 scripts/build_belief_map.py --full   # reconstrução completa ~30s

Fluxo de Trabalho Obrigatório: Consulte Antes do Código

Para trabalhos de código não triviais, execute uma consulta ao mapa de crenças antes de rg, find, sed, cat, nl, abrir diretórios ou ler arquivos fonte. O skill só ajuda quando usado como primeiro passo de escopo, não como confirmação após o código já ter sido inspecionado.

Primeira passagem rápida quando a tarefa tem uma palavra-chave clara:

python3 scripts/belief_search.py quick "palavra-chave"

quick busca o primeiro módulo correspondente e executa imediatamente analyze. Use-o para obter arquivos de fronteira, dependências, dependências reversas, camadas e violações em um único passo. Se quick retornar o módulo errado ou nenhuma correspondência, use o fluxo explícito search -> analyze abaixo.

Passo 1 -- Encontre o ID do módulo:

python3 scripts/belief_search.py search "palavra-chave"
python3 scripts/belief_search.py entity EntityName

Use search ou entity para localizar o ID do módulo. IDs de módulo são caminhos relativos completos como pki-service/src/modules/ca/ca.service, não códigos curtos como ps34. O mapa de crenças pode conter IDs internos de mapa de caminho curtos, mas eles são resolvidos automaticamente -- sempre passe strings legíveis de caminho. NÃO adivinhe ou invente IDs de módulo -- sempre confirme com search primeiro.

Passo 2 -- Analise o módulo (faça isso IMEDIATAMENTE, não opcionalmente):

python3 scripts/belief_search.py analyze <id-do-modulo>

analyze é o comando PRINCIPAL. Ele retorna o contexto completo: arquivos de fronteira, dependências, dependências reversas, camada de arquitetura e violações. Sempre execute-o antes de ler qualquer fonte.

Passo 3 -- Leia apenas os arquivos de fronteira listados na saída de analyze.

Passo 4 -- NÃO leia diretórios inteiros. Se a fronteira mostrar 2-3 arquivos relevantes, leia apenas esses arquivos. Ignore todo o resto no diretório.

Referência de Comandos

Comando	Propósito	Exemplo
search "<padrão>"	Busca regex no grafo (encontra IDs de módulo)	search "operative.*service"
analyze <id>	Análise completa do módulo (comando PRINCIPAL)	analyze drive/modules/drive/drive_schema
quick <palavra-chave>	Busca + analisa a primeira correspondência (atalho)	quick operatives
boundary <id>	Arquivos a ler para uma mudança	boundary operatives.service
boundary <id> --files-only	Apenas caminhos de arquivos (compacto)	boundary operatives.service --files-only
entity <Nome>	Encontra definições + referências	entity DrivePath
deps <id> [profundidade]	Árvore de dependências de saída	deps operatives.service 3
rdeps <id> [profundidade]	Raio de explosão (quem depende disto)	rdeps drive_schema 2
flow <id> <fn>	Rastreia fluxo de chamadas/dados	flow drive_api fetchFiles
module <id>	Módulo único com arestas	module operatives.controller
`boundaries [id	all]`	Verifica violações de arquitetura
`invariants [id	all]`	Verifica violações de convenção de nomenclatura
layers	Mostra todos os módulos por camada	layers
find_function <nome>	Encontra definições de função/método	find_function createOrder
find_type <nome>	Encontra definições de tipo/classe/ifc/enum	find_type DriveDbCommitResponse
find_callchain <src> <tgt> [profundidade]	Rastreia caminho de chamada entre funções	find_callchain createOrder processPayment
find_callers <fn> [profundidade]	Quem chama esta função	find_callers handleRequest 3
find_calls <fn> [profundidade]	O que esta função chama	find_calls createOrder 2
grep_functions <padrão>	Busca corpos de funções no código fonte	grep_functions "validate.*input"
diff_functions [ref]	Funções alteradas no git diff	diff_functions HEAD~3
query '<sexp>'	Consulta Scheme componível	query '(count (boundary "X"))'
repl	REPL Scheme interativo	repl

Referência Rápida: Consultas com rg

Quando precisar de buscas rápidas e direcionadas sem invocar o script Python, consulte o mapa de crenças diretamente com rg. O construtor incluído escreve .belief_map.sexp; se um repositório ainda usar o legado belief_map.sexp, substitua esse nome de arquivo nos comandos abaixo:

# Todos os fatos sobre um módulo
rg 'drive/modules/drive_db/api ' .belief_map.sexp

# Quem importa um módulo
rg 'imports .* drive/modules/commons/result' .belief_map.sexp

# O que um módulo importa
rg 'imports drive/modules/drive_db/api' .belief_map.sexp

# Todas as referências a uma entidade
rg 'DriveDbCommitResponse' .belief_map.sexp

# Todas as classes em um repositório
rg '^\(cls drive/' .belief_map.sexp

# Arestas de fluxo de dados
rg 'data-flow' .belief_map.sexp

Essas linhas únicas são úteis para verificações rápidas. Para saída estruturada e análise completa, use os comandos do script Python.

Notação de Saída

Toda a saída são fatos em S-expression, um por linha. Veja references/sexp-notation.md para o formato completo.

Padrões principais:

(boundary <mod> :lang py :file <caminho> :purpose "<desc>")
(boundary-dep <mod> <dep> :lang ts :file <caminho> :relation imports)
(boundary-rdep <mod> <rdep> :lang tsx :file <caminho> :relation imports)
(boundary-summary <mod> :total 10 :deps 7 :rdeps 2)
(entity-def cls <mod> <Nome> <linha> :lang py :file <caminho>)
(violation <src> <tgt> :src-layer domain :tgt-layer api :via imports :lang ts "<motivo>")
(result <módulo-ou-caminho>)
(result-count 42)

Valores de :lang: py = Python (snake_case), ts = TypeScript (camelCase), tsx = TSX (PascalCase).

Linguagem de Consulta Scheme

Componha consultas para análises complexas. Veja references/scheme-queries.md para a referência completa.

Essenciais:

(boundary "id")                ; alvo + dependências + dependências reversas (fronteira da mudança)
(entity "Nome")                ; módulos que definem a entidade
(deps "id" profundidade)       ; dependências de saída
(rdeps "id" profundidade)      ; dependências reversas
(find-function "nome")         ; módulos com definições de função correspondentes
(find-type "nome")             ; módulos com definições de tipo correspondentes
(find-callers "fn" profundidade)      ; módulos que chamam uma função
(find-calls "fn" profundidade)        ; módulos chamados por uma função
(intersect A B)                ; interseção de conjuntos
(filter SET "padrão")          ; filtro regex
(files SET)                    ; resolve para caminhos de arquivo
(count SET)                    ; conta membros
(violations)                   ; módulos com violações de fronteira
(layer "id")                   ; camada de arquitetura de um módulo

Padrão de Plano de Análise

Antes de modificar código, componha um plano a partir de consultas:

; 1. Escopo
(boundary "operatives.service")
(count (boundary "operatives.service"))

; 2. Restrições de arquitetura
(violations "operatives.service")
(layer "operatives.service")

; 3. Fronteiras entre linguagens
(filter (refs-to "DrivePath") "app-service")

; 4. Restringir a arquivos acionáveis
(filter (boundary "operatives.service") "dto")
(intersect (deps "controller" 2) (deps "service" 2))

; 5. Após mudanças: verificar
(violations "operatives.service")

Exemplos de Gatilho

Use este skill antes de ler o código fonte para:

• Investigações de causa raiz que mencionam serviços, APIs, jobs, eventos, fluxos de UI ou comportamento com falha.
• Perguntas entre serviços ou módulos, incluindo "como X chama Y?" e "onde isso é armazenado?"
• Esclarecimento de Redmine quando a resposta depende do comportamento do código.
• Revisões de arquitetura, análise de impacto, mudanças em contratos públicos ou verificações de raio de explosão.
• Revisões de mudanças em staged não triviais quando a direção da dependência ou a propriedade do módulo importa.

Não force para tarefas apenas de commit, resumos de git-log, execuções manuais de demonstração/servidor, testes puramente em navegador ou análise de log de sessão.

Recuperação de Erros

Se um comando retornar (error no-match ...):

1. NÃO tente novamente com o mesmo ID ou adivinhe outro ID
2. Execute search com uma palavra-chave mais ampla para encontrar o ID do módulo correto
3. Use o campo :suggestions se presente -- ele lista IDs de módulo similares

# Errado: adivinhando IDs
python3 scripts/belief_search.py analyze ps34        # falha: ps34 é um ID de mapa de caminho curto
python3 scripts/belief_search.py analyze ca.service  # falha: caminho incompleto

# Certo: busque primeiro, depois use o caminho completo dos resultados
python3 scripts/belief_search.py search "ca.*service"
# Saída mostra: pki-service/src/modules/ca/ca.service
python3 scripts/belief_search.py analyze pki-service/src/modules/ca/ca.service

Antipadrões

• Adivinhar IDs de módulo. IDs de módulo são caminhos relativos completos (ex.: pki-service/src/modules/ca/ca.service). Códigos curtos como ps34 são IDs internos de mapa de caminho e não devem ser usados diretamente. Sempre faça search primeiro.
• Construir mas nunca consultar. Construir o mapa de crenças e nunca executar search, analyze ou boundary não agrega valor.
• Consultar após ler o código fonte. A primeira leitura do código fonte deve vir das linhas boundary-file na saída de analyze.
• Ler .belief_map.sexp como um arquivo inteiro. Use search, analyze ou rg para consultar fatos específicos.
• Pular o mapa de crenças para tarefas entre módulos. Sempre consulte o grafo para entender as fronteiras antes de ler arquivos fonte.
• Ler todos os arquivos de um diretório. Quando a fronteira mostrar 2-3 arquivos, leia apenas esses.
• Usar scripts locais do projeto. Sempre use os scripts incluídos neste skill. Cópias do projeto podem produzir JSON em vez de sexp.

Reconstruindo o Grafo

python3 scripts/build_belief_map.py          # incremental (~5s)
python3 scripts/build_belief_map.py --full   # reconstrução completa (~30s)
python3 scripts/build_belief_map.py ./drive  # único sub-repositório
python3 scripts/build_belief_map.py --lsp    # com hierarquia de chamadas LSP (~1-5min)

Reconstrua após mudanças estruturais (adicionar/remover arquivos, alterar imports, adicionar classes).

Topologia de Infraestrutura

Extraia topologia de serviços de arquivos Kustomize, Helm e Terraform. Este script requer PyYAML (pip3 install pyyaml).

python3 scripts/build_infra_topology.py                    # detecta automaticamente todas as IaC
python3 scripts/build_infra_topology.py --kustomize .      # apenas kustomize
python3 scripts/build_infra_topology.py --helm ./charts    # apenas charts helm
python3 scripts/build_infra_topology.py --terraform ./infra # apenas terraform
python3 scripts/build_infra_topology.py --append .belief_map.sexp  # mescla no grafo

Emite arestas infra-node, k8s-depends, k8s-service, helm-depends, tf-depends e infra-maps. Consulte com:

rg 'infra-node' .belief_map.sexp                  # todos os serviços
rg 'k8s-depends' .belief_map.sexp                 # dependências de serviço
rg 'infra-node.*:component database' .belief_map.sexp  # todos os bancos de dados
rg 'infra-maps.*app-service' .belief_map.sexp     # mapeamento infra -> código fonte