/understand-diff

Analisa as mudanças atuais no código em relação ao grafo de conhecimento no diretório de dados do projeto (.ua/knowledge-graph.json, ou o legado .understand-anything/knowledge-graph.json quando esse diretório está presente).

Referência da Estrutura do Grafo

O JSON do grafo de conhecimento tem esta estrutura:

• project — {nome, descrição, linguagens, frameworks, analisadoEm, hashCommitGit}
• nodes[] — cada um tem {id, tipo, nome, caminhoArquivo?, resumo, tags[], complexidade, notasLinguagem?}
  • Tipos de nó de código: arquivo, função, classe, módulo, conceito
  • Tipos de nó que não são de código: config, documento, serviço, tabela, endpoint, pipeline, schema, recurso
  • Tipos de nó de domínio/conhecimento: domínio, fluxo, etapa, artigo, entidade, tópico, alegação, fonte
  • IDs usam o tipo de nó como prefixo, por exemplo, file:path, function:path:name, config:path, article:path
• edges[] — cada um tem {origem, destino, tipo, direção, peso}
  • Tipos de chave: imports, contém, chama, depende_de, configura, documenta, implanta, aciona, contém_fluxo, etapa_fluxo, relacionado, cita
• layers[] — cada um tem {id, nome, descrição, idsNodos[]}
• tour[] — cada um tem {ordem, título, descrição, idsNodos[]}

Como Ler Eficientemente

1. Use Grep para pesquisar dentro do JSON por entradas relevantes ANTES de ler o arquivo completo
2. Leia apenas as seções que você precisa — não despeje o grafo inteiro no contexto
3. Nomes de nós e resumos são os campos mais úteis para entender
4. Arestas mostram como os componentes se conectam — siga imports e chamadas para cadeias de dependência

Instruções

1. Resolva o diretório de dados $UA_DIR. Execute UA_DIR=$([ -d .understand-anything ] && echo .understand-anything || echo .ua) — este é o legado .understand-anything/ quando ele já existe, caso contrário, o novo .ua/. Verifique se $UA_DIR/knowledge-graph.json existe. Se não, diga ao usuário para executar /understand primeiro.

2. Obtenha a lista de arquivos alterados (NÃO leia o grafo ainda):

   • Se estiver em um branch com alterações não commitadas: git diff --name-only
   • Se estiver em um branch de funcionalidade: git diff main...HEAD --name-only (ou o branch base)
   • Se o usuário especificar um número de PR: obtenha o diff desse PR

3. Leia os metadados do projeto e verifique a atualidade do grafo — use Grep ou Read com um limite de linhas para extrair a seção "project", incluindo gitCommitHash como GRAPH_COMMIT_RAW, então:

   • Resolva-o como um commit antes de usá-lo em qualquer diff do Git. A partir da raiz do projeto, compare o commit resolvido com git rev-parse HEAD e inspecione as alterações commitadas e na árvore de trabalho do escopo do projeto:

     GRAPH_COMMIT=$(git rev-parse --verify --end-of-options "${GRAPH_COMMIT_RAW}^{commit}" 2>/dev/null)
     git rev-parse HEAD
     git diff --name-only "$GRAPH_COMMIT" HEAD -- .
     git diff --cached --name-only -- .
     git diff --name-only -- .
     git ls-files --others --exclude-standard -- .
     

   • O pathspec -- . é obrigatório: commits que tocam apenas um projeto monorepo irmão não devem tornar este grafo obsoleto. Uma incompatibilidade de hash por si só não é obsoleta quando o diff do projeto está vazio.
   • Ignore o diretório de dados selecionado (.ua/ ou o legado .understand-anything/) em cada saída de comando porque ele contém artefatos gerados do grafo, não desvios de código do projeto.
   • Se o diff commitado ou qualquer comando da árvore de trabalho relatar arquivos do projeto, avise antes da análise de impacto que o grafo pode omitir essas alterações. Sugira: Execute /understand para atualizar o grafo.
   • Execute o diff do commit apenas quando GRAPH_COMMIT_RAW for resolvido com sucesso. Se o commit do grafo ou os metadados do Git estiverem faltando, inválidos ou indisponíveis, forneça um breve aviso de melhor esforço e continue em vez de bloquear.

4. Encontre nós para arquivos alterados — para cada caminho de arquivo alterado, use Grep para pesquisar no grafo de conhecimento por:

   • Nós com valores "filePath" correspondentes (por exemplo, grep "changed/file/path")
   • Isso encontra nós em nível de arquivo (incluindo tipos que não são de código) E nós de função/classe definidos nesses arquivos
   • Anote os valores id de todos os nós correspondentes

5. Encontre arestas conectadas (1 salto) — para cada ID de nó correspondente, use Grep para procurar esse ID nas arestas para encontrar:

   • O que importa ou depende dos nós alterados (chamadores upstream)
   • O que os nós alterados importam ou chamam (dependências downstream)
   • Estes são os "componentes afetados" — coisas que podem quebrar ou precisar de atualização

6. Identifique camadas afetadas — Use Grep para os IDs de nós correspondentes na seção "layers" para determinar quais camadas arquiteturais são tocadas.

7. Forneça análise estruturada:

…