Computação de revisão (coortes, eixos e diffs determinísticos)

O separador Revisão de uma PR mostra o progresso em direto do pipeline de revisão enquanto este trabalha e, em seguida, o artefacto que publicou, com as ações disponíveis sobre ele. Um só separador com dois estados, porque são a mesma coisa em dois momentos. Não é um separador predefinido: uma PR não tem revisão até alguém pedir uma, por isso é o Ask AI que a abre.

Por detrás desse separador, o cc_server constrói coortes de ficheiros, executa os eixos determinísticos e disponibiliza-os através das operações RPC review_studio.* (cohorts, blastRadius, cohortImpact, ciSignals, dependencyDiffs, setContractDecision, approveVisual, compute e as respetivas gémeas watch*). Uma disposição persistida que ainda mencione pr.reviewStudio abre este mesmo separador Revisão.

No separador Revisão:

O agente de consolidação publica um artefacto de conversa comum com publish_artifact, pelo que o separador o apresenta através do mesmo visualizador de artefactos que uma bolha de chat abre — não existe nenhuma cópia do sistema de artefactos com a forma de uma revisão.
As constatações ficam numa barra lateral ao lado, e o veredicto surge numa barra estreita por cima do artefacto, em vez de num cabeçalho de painel.
Aparece uma faixa de desatualização quando a cabeça da PR avançou para além da revisão.

Consulte Usar revisão com IA para conhecer o fluxo e Rever e fazer merge de uma PR para agir sobre ela.

Coortes

As coortes agrupam os ficheiros alterados da PR em grupos derivados do conteúdo, reunindo os ficheiros que pertencem uns aos outros pelo significado, ordenados por impacto para que o grupo mais arriscado se leia primeiro. São recalculadas a cada alteração do SHA de cabeça e substituídas integralmente; cada coorte tem uma chave estável de um push para o outro, pelo que um resumo e o progresso da revisão sobrevivem a um rebase.

Se o repo não tiver um índice de código, as coortes recuam para um agrupamento por caminhos. Para indexar um repo, use Definições → Espaço de trabalho → Repositórios — cada linha de repo tem uma ação Indexar código que executa o pipeline index_code e comunica o progresso no local.

O grafo de código só analisa linguagens com uma gramática incluída (Dart, JS/TS, PHP, Python, Rust, Zig, C/C++, Go, Java, Ruby, C#, Swift, Kotlin, R, Assembly, MATLAB, Ada). Um repo em qualquer outra linguagem nunca poderá produzir coortes semânticas, por mais vezes que o indexe.

Um agente pode registar um resumo em markdown para uma coorte com set_cohort_summary e anexar-lhe um diagrama de percurso estruturado com add_review_diagram — um objeto tipado de sequência, de relação entre entidades ou de máquina de estados, nunca texto mermaid. Cada aresta é cruzada com o grafo de código real, e uma aresta que o grafo não consegue corroborar é marcada como não verificada em vez de ser desenhada como um facto.

O eixo do contrato de API

O eixo do contrato compara apenas ficheiros de especificação explícitos. Reconhece os seis nomes predefinidos — openapi.yaml, openapi.yml, openapi.json, swagger.yaml, swagger.yml, swagger.json — mais qualquer ficheiro alterado cujo nome contenha openapi ou swagger e termine em .yaml, .yml ou .json. Um contrato inferido a partir do código de um handler está fora do âmbito, e os esquemas GraphQL não são comparados.

Cada alteração é classificada — adições, remoções e modificações de endpoints, parâmetros, esquemas e respostas — e tem uma gravidade: breaking (endpoint ou parâmetro removido, tipo restringido, novo parâmetro obrigatório), non-breaking (aditiva) ou informativa. Uma alteração rejeitada faz falhar o portão do contrato, tal como uma alteração breaking deixada por decidir; uma alteração breaking mas aprovada avisa; e, na ausência de alterações breaking, o portão é ultrapassado. Um diff marcado como derivado (indicativo) nunca funciona como portão.

Aprovar ou rejeitar uma alteração faz-se com review_studio.setContractDecision.

O eixo visual

Se a PR alterar componentes de interface num repo Flutter com uma aplicação Widgetbook, a passagem de computação renderiza os componentes alterados antes e depois através de uma passagem golden flutter test headless, nos worktrees de base e de cabeça da PR, e compara depois os píxeis.

Os instantâneos marcados como changed ou removed mantêm o portão visual até serem aprovados; os instantâneos unchanged, added e approved desbloqueiam-no. A indisponibilidade tem um de quatro motivos: não haver SDK Flutter no anfitrião, não haver aplicação Widgetbook no repo, não haver casos de uso testáveis em golden, ou um erro do harness golden.

Aprovar uma alteração pretendida faz-se com review_studio.approveVisual.

Os eixos e o veredicto

Eixo	Determinado por
Correção	Agentes revisores (tokens)
Segurança	Agentes revisores (tokens)
Lacuna de testes	Agentes revisores (tokens)
Visual	Determinístico (harness golden)
Contrato de API	Determinístico (diff de especificação)

Os três eixos de tokens são registados quando um agente líder chama finalize_review; os dois eixos determinísticos são registados pela passagem de computação.

Cada eixo comunica um de:

Estado	Significado
Pass	Foi executado, não encontrou nada bloqueante
Warn	Foi executado, com preocupações não bloqueantes
Fail	Foi executado e encontrou um problema bloqueante
Partial	Foi executado mas não conseguiu concluir; os resultados estão incompletos
Unavailable	Não conseguiu ser executado de todo

Só pass e warn desbloqueiam um eixo com portão. Partial e unavailable são deliberadamente distintos de fail, e nenhum deles desbloqueia um portão.

Os eixos agregam-se em Ship, Hold ou Block, e só podem tornar o veredicto mais severo — nunca é atenuado. Um eixo com portão que falha força Block; um que esteja partial ou unavailable força, no mínimo, Hold. Assim, um eixo bloqueante que não conseguiu ser executado retém o veredicto: a ausência de provas nunca abre um portão.

O veredicto no separador Revisão é o que o finalize_review publicou.