/understand

Analisa a base de código atual e produz um arquivo knowledge-graph.json no diretório de dados do projeto (.ua/, ou o legado .understand-anything/ quando ele já existe). Este arquivo alimenta o painel interativo para explorar a arquitetura do projeto.

Opções

• $ARGUMENTS pode conter:
  • --full — Força uma reconstrução completa, ignorando qualquer grafo existente
  • --auto-update — Habilita atualizações automáticas do grafo no commit (escreve autoUpdate: true para $UA_DIR/config.json)
  • --no-auto-update — Desabilita atualizações automáticas do grafo (escreve autoUpdate: false para $UA_DIR/config.json)
  • --review — Executa o revisor de grafo LLM completo em vez da validação determinística inline
  • --language <lang> — Gera todo o conteúdo textual (resumos, descrições, tags, títulos, languageNotes, languageLesson) no idioma especificado. Aceita códigos ISO 639-1 (zh, ja, ko, en, es, fr, de, etc.) ou nomes amigáveis (chinese, japanese, korean, english, spanish, etc.). Variantes de localidade suportadas: zh-TW, zh-HK, etc. O padrão é en (Inglês). Armazena a preferência em $UA_DIR/config.json para consistência em atualizações incrementais.
  • --exclude <patterns> — Padrões glob de vírgula para arquivos/diretórios adicionais a serem excluídos da análise (por exemplo, --exclude "tests/*,docs/*"). Esses padrões têm a maior prioridade sobre os padrões internos e as regras .understandignore. Suporta sintaxe gitignore, incluindo negação !.
  • Um caminho de diretório (por exemplo, /path/to/repo ou ../other-project) — Analisa o diretório fornecido em vez do diretório de trabalho atual

Relatório de Progresso

Ao longo da execução, relate o progresso ao usuário em cada transição de fase e durante o processamento em lote. Isso mantém os usuários informados sobre bases de código grandes onde a análise pode levar muito tempo.

• Transições de fase: No início de cada fase, imprima uma linha de status:

  [Phase N/7] <phase name>...

  Exemplo: [Phase 2/7] Analyzing files (12 batches)...

• Progresso em lote: Durante a Fase 2, relate cada lote com seu índice e total:

  Analyzing batch X/N (files: foo.ts, bar.ts, ...) (liste até 3 nomes de arquivo, depois ... se houver mais)

• Conclusão da fase: Quando uma fase terminar, confirme brevemente:

  Phase N complete. <one-line summary of result>

  Exemplo: Phase 1 complete. Found 247 files across 3 languages.

Fase 0 — Pré-voo

Determine se deve executar uma análise completa ou uma atualização incremental.

1. Resolver PROJECT_ROOT:

   • Analise $ARGUMENTS em busca de um token que não seja uma flag (qualquer argumento que não comece com --). Se encontrado, trate-o como o caminho do diretório de destino.

     • Se o caminho for relativo, resolva-o em relação ao diretório de trabalho atual.
     • Verifique se o caminho resolvido existe e é um diretório (execute test -d <path>). Se não existir ou não for um diretório, relate um erro ao usuário e PARE.
     • Defina PROJECT_ROOT para o caminho absoluto resolvido.

   • Se nenhum argumento de caminho de diretório for encontrado, defina PROJECT_ROOT para o diretório de trabalho atual.

   • Redirecionamento de worktree. Se PROJECT_ROOT estiver dentro de um worktree git (não o checkout principal), redirecione a saída para a raiz do repositório principal. Worktrees gerenciados pelo Claude Code são efêmeros — o diretório de dados (.ua/, ou o legado .understand-anything/) escrito lá é destruído quando a sessão termina, levando o grafo de conhecimento com ele (issue #133). Detecte um worktree comparando git rev-parse --git-dir com git rev-parse --git-common-dir; em um checkout normal ou submódulo, eles se resolvem para o mesmo caminho, em um worktree eles diferem e o pai de --git-common-dir é a raiz do repositório principal.

     COMMON_DIR=$(git -C "$PROJECT_ROOT" rev-parse --git-common-dir 2>/dev/null)
     GIT_DIR=$(git -C "$PROJECT_ROOT" rev-parse --git-dir 2>/dev/null)
     if [ -n "$COMMON_DIR" ] && [ -n "$GIT_DIR" ]; then
       COMMON_ABS=$(cd "$PROJECT_ROOT" && cd "$COMMON_DIR" 2>/dev/null && pwd -P)
       GIT_ABS=$(cd "$PROJECT_ROOT" && cd "$GIT_DIR" 2>/dev/null && pwd -P)
       if [ -n "$COMMON_ABS" ] && [ "$COMMON_ABS" != "$GIT_ABS" ]; then
         MAIN_ROOT=$(dirname "$COMMON_ABS")
         if [ -d "$MAIN_ROOT" ] && [ "${UNDERSTAND_NO_WORKTREE_REDIRECT:-0}" != "1" ]; then
           echo "[understand] Detected git worktree at $PROJECT_ROOT"
           echo "[understand] Redirecting output to main repo root: $MAIN_ROOT"
           echo "[understand] (Set UNDERSTAND_NO_WORKTREE_REDIRECT=1 to keep PROJECT_ROOT as the worktree.)"
     

…