PR Lens: visualize o impacto do pull request antes do diff

ANÁLISE EDITORIAL

Um pull request pode ter centenas de linhas alteradas e ainda esconder a pergunta mais importante: qual parte do sistema mudou, o que ficou ao redor e por onde os dados passam agora? A PR Lens ensina um agente de código a representar essa mudança como um documento estruturado, validar o contrato e renderizar diagramas de arquitetura e fluxo de dados. O ganho é compreensão visual antes do mergulho no diff, não aprovação automática do código.

O que esta Skill faz

A Skill organiza um fluxo em cinco partes. Primeiro, o agente lê o diff usando a base de merge correta. Depois escreve .pr-lens/graph.json, com faixas, componentes, conexões, sequências, estados da mudança e referências a arquivos. Em seguida, valida o JSON com o CLI do PR Lens, corrige todas as falhas contratuais e só então renderiza SVGs.

Quando a tarefa envolve um pull request, a orientação também explica como anexar um ou mais diagramas à descrição ou a um comentário usando GitHub CLI. Para uma explicação fora do GitHub, a Skill oferece a opção de publicar o grafo em um canvas hospedado. Cada etapa tem efeitos diferentes e deve receber autorização própria.

Para quem serve

PR Lens serve a equipes que recebem mudanças grandes, revisam código produzido com auxílio de agentes ou precisam apresentar o impacto arquitetural de um refactor. É especialmente útil quando o diff atravessa serviços, filas, bancos, interfaces e integrações, pois o documento pode mostrar componentes alterados e vizinhos inalterados no mesmo contexto.

Ela não substitui a leitura do código, a execução de testes nem uma revisão de segurança. O próprio projeto afirma que não existe uma lente de achados. O diagrama explica a forma da mudança, mas não prova correção, desempenho, ausência de vulnerabilidades ou compatibilidade.

Origem e curadoria

A origem auditada é a pasta skills/pr-lens no repositório oficial. A curadoria fixou o commit 0993b4dec8ae73f5e000370e6a758cdd8aa2bfd0, de 11/09/2026, e confirmou a licença MIT da pasta.

Foram lidos o SKILL.md, as duas referências em Markdown, o exemplo JSON e o arquivo de licença. A pasta individual não contém scripts ou executáveis. GitLab e Hugging Face foram pesquisados para localizar outra origem canônica, mas a fonte mantida pela Coldtea AI permanece o GitHub acima.

Compatibilidade e pré-requisitos

O SKILL.md é texto compatível com agentes que aceitam instruções por Skill ou regra de projeto. O uso funcional pressupõe um repositório Git, acesso aos arquivos autorizados e uma base de comparação conhecida. Para validar e renderizar, o projeto declara Node.js 20.11 ou posterior e usa o pacote @coldtea/pr-lens-cli.

Se o resultado for anexado a um pull request, também são necessários GitHub CLI compatível com --attach, autenticação válida e acesso de escrita ao repositório. A documentação oficial do GitHub sobre anexos esclarece que o arquivo é enviado e a referência local é substituída por uma URL hospedada.

Instalação com revisão

O README oficial fixado sugere npx skills add coldteadotai/pr-lens. Esse comando consulta a rede, baixa conteúdo e grava arquivos no ambiente do agente. Para uma adoção controlada, faça primeiro o download ou clone em uma pasta de teste, confira o commit e compare os seis arquivos do pacote documental antes de copiá-los para o projeto.

git clone https://github.com/coldteadotai/pr-lens.git
cd pr-lens
git checkout 0993b4dec8ae73f5e000370e6a758cdd8aa2bfd0

# revise skills/pr-lens antes de instalar

O ZIP do Bastidores não instala Node.js, o CLI ou dependências. Ele serve para auditoria e importação manual da Skill. A página mantém separados o download local e o repositório oficial para que o leitor possa conferir a procedência sem confundir documentação com instalador.

Configure o escopo antes do primeiro pedido

Defina a raiz do repositório, a branch de trabalho, a referência base e os diretórios que o agente pode ler. Se houver código privado, estabeleça desde o início que o grafo, nomes de componentes e caminhos não podem sair da máquina. Também escolha se a tarefa termina no SVG local ou inclui uma alteração remota no pull request.

Comece com autorização apenas para leitura e escrita em uma pasta descartável. A própria Skill informa que o CLI pode criar .pr-lens/ e adicionar essa pasta ao .gitignore na primeira gravação. Se o repositório não pode ser alterado, use um diretório de saída explícito ou execute em uma cópia de trabalho.

Primeiro uso seguro

Um pedido inicial pode ser: “Leia somente o diff entre a base de merge e a branch atual. Proponha o conteúdo de graph.json em um diretório descartável, sem instalar pacotes, sem mudar .gitignore, sem usar rede e sem publicar nada. Mostre as suposições e marque como não verificável o que não estiver no código”.

Depois de revisar o JSON, autorize separadamente a validação com uma versão fixada do CLI. O SKILL.md usa @latest, que muda com o tempo. No commit auditado, @coldtea/pr-lens-cli aparece como 0.5.1 e @coldtea/pr-lens-agent-skill como 0.2.0. Fixar a versão torna o teste repetível e reduz o risco de executar código diferente do revisado.

Como o documento representa a mudança

O contrato usa faixas para separar fronteiras como interface, serviço, processamento e sistema externo. Cada nó representa um componente e cada conexão registra uma relação. Os estados added, modified, removed e unchanged permitem distinguir mudança de contexto. A documentação oficial do documento de grafo descreve os campos e limites.

Os componentes inalterados não são enfeite. Eles ajudam a mostrar o raio de impacto. Uma fila modificada pode continuar ligada a uma API e a um worker sem que esses dois arquivos tenham mudado. Excluir esses vizinhos produz uma imagem menor, porém também remove a relação que o revisor precisava compreender.

Arquitetura, fluxo de dados e walkthrough

A lente de arquitetura mostra componentes e conexões. A lente de fluxo de dados ordena mensagens entre participantes quando existe uma sequência real. A página “What is PR Lens?” diferencia as duas e alerta que App e Action mantêm comentários próprios. Ativar ambos no mesmo repositório pode produzir duas publicações sobre a mesma mudança.

O walkthrough é uma visita guiada opcional com passos curtos. Cada passo aponta para uma parte do diagrama e explica o que mudou. Ele não deve repetir nomes de arquivos nem inventar uma narrativa. A recomendação editorial é manter de três a sete passos quando o grafo não for trivial e omitir a visita quando houver apenas uma pequena visão.

Validação e renderização local

O validador rejeita campos inventados, identificadores duplicados, referências quebradas e versões de schema não suportadas. Algumas regras dependem do parser, como intervalos de linha invertidos e passos que apontam para mensagens fora do fluxo selecionado. Por isso, um JSON aceito por um editor genérico ainda pode falhar no contrato do PR Lens.

npx @coldtea/pr-lens-cli@0.5.1 validate .pr-lens/graph.json
npx @coldtea/pr-lens-cli@0.5.1 render .pr-lens/graph.json --theme light

Esses comandos podem baixar e executar o pacote pela primeira vez. Revise origem, versão e lockfile do ambiente antes da autorização. validate e render não precisam de chave de modelo, mas escrevem resultados locais. Leia o manifesto gerado para descobrir os nomes reais dos SVGs em vez de adivinhar hashes.

Quando uma chave de modelo é necessária

Se o agente que já conhece o diff escrever o documento, nenhuma chave adicional é exigida. A alternativa analyze pede a um provedor que transforme o diff em grafo. Nesse caminho, o CLI lê a chave do ambiente, e o comando analyze envia o diff ao provedor escolhido, como Gemini, OpenAI ou um endpoint compatível.

A documentação do CLI separa análise, validação, renderização, composição de comentário e canvas. Antes de usar analyze em repositório privado, verifique contrato, retenção, região e política do provedor. Nunca cole a chave no prompt, no comando, no grafo ou no pull request.

Canvas hospedado e privacidade

canvas push envia o documento de grafo ao serviço prlens.dev. A política de privacidade do PR Lens informa que o canvas armazena títulos, componentes, caminhos, intervalos de linhas, conexões, fluxos, texto do walkthrough e proveniência. O link de visualização abre sem login para quem o possuir.

O token de escrita fica no fragmento do link de edição e em um registro local ignorado pelo Git. Ele permite atualizar o canvas. Não publique esse link, não o coloque no artigo ou no pull request e não trate o identificador não listado como controle equivalente a autenticação corporativa. Os termos do serviço também deixam claro que o diagrama é apoio de leitura e pode estar errado.

GitHub App, Action e Skill não são iguais

A GitHub App do PR Lens é um serviço hospedado que recebe eventos do GitHub, analisa mudanças e atualiza um comentário. A Action roda no CI do próprio repositório com uma chave fornecida pela equipe. A Skill usa o agente já ativo para escrever o grafo e permite renderização local.

Escolha uma rota por repositório e revise permissões. A App tem acesso às fontes selecionadas na instalação. A Action pede permissões para conteúdo e pull requests. A Skill pode permanecer local até alguém autorizar o anexo. Uma página sobre a Skill não equivale a recomendar a instalação da App em todos os repositórios.

Anexar ao pull request sem surpresa

Para anexar um SVG, a Skill orienta escrever uma imagem Markdown no corpo e passar o mesmo caminho para gh pr create --attach, gh pr edit --attach ou gh pr comment --attach. O GitHub CLI envia o arquivo, troca o caminho local por uma URL e preserva o texto alternativo da imagem.

Isso é uma mudança remota visível. Antes de executar, mostre o texto final, o pull request alvo e os arquivos que serão enviados. Confirme se os diagramas expõem nomes internos, caminhos, arquitetura ou fornecedores. A documentação do GitHub sobre arquivos anexados lista os formatos aceitos e ajuda a separar visual local de publicação.

Corrigir o mapa sem editar saída gerada

Se o diagrama insiste em chamar um componente pelo nome errado ou inclui testes irrelevantes, a Skill recomenda gravar correções em .github/pr-lens.yml. Esse arquivo pode renomear, excluir, mover para outra faixa e agrupar nós. A referência oficial de configuração mostra o formato atual.

Não edite o SVG nem o JSON gerado como solução permanente, pois a próxima execução pode recriar tudo. Mesmo a configuração deve passar por revisão. Um padrão amplo de exclusão pode apagar contexto importante e uma renomeação incorreta pode ensinar o mesmo erro em todas as próximas visualizações.

Resultado esperado

Uma boa execução termina com um graph.json válido, SVGs legíveis, um manifesto de saída e uma lista explícita de suposições. O diagrama deve mostrar o componente principal, os vizinhos necessários, a relação central e apenas os fluxos que realmente aparecem no código. Cada referência a arquivo precisa apontar para um caminho e intervalo verificável.

Se a tarefa inclui o GitHub, o resultado esperado também traz o texto alternativo, o pull request alvo e a confirmação da URL depois do envio. A revisão humana deve comparar o desenho com o diff. Um grafo bonito que troca direção de chamada, omite um consumidor ou atribui comportamento não observado é um resultado inválido.

Permissões e riscos

A leitura do diff pode expor código e nomes internos ao agente. A escrita do documento cria arquivos. npx consulta a rede e executa dependências. analyze envia dados ao provedor. canvas push publica metadados técnicos em serviço externo. gh envia mídia e altera o pull request. A App e a Action acrescentam permissões no GitHub ou no CI.

Autorize cada camada separadamente. Use uma base de merge correta, fixe versões, restrinja diretórios, mantenha segredos fora dos arquivos, examine o grafo antes de compartilhar e prefira renderização local para código sensível. O aviso de privacidade do repositório diferencia operações locais das partes hospedadas.

Erros comuns e como corrigir

• Comparar com a ponta da branch base: calcule a base de merge para representar somente a mudança do pull request.
• Desenhar apenas arquivos alterados: inclua vizinhos inalterados quando eles explicarem o raio de impacto.
• Renderizar JSON inválido: corrija todos os erros do validador antes de gerar o SVG.
• Usar @latest em produção: fixe a versão revisada do CLI e registre a data.
• Publicar o link de edição: compartilhe somente o link de visualização e proteja o token de escrita.
• Anexar sem revisar: confira caminhos, nomes internos, direção das relações, texto alternativo e pull request alvo.
• Tratar o desenho como parecer: mantenha testes, revisão linha a linha e análise de segurança como etapas distintas.

Quando não usar

Não use PR Lens como detector de vulnerabilidade, ferramenta de cobertura, benchmark de desempenho, gerador de documentação permanente ou aprovação automática. Se a mudança é pequena e explicada por duas frases, um diagrama pode adicionar mais trabalho do que clareza.

Para revisar comentários e defeitos por linha, a Open Code Review atende a outra finalidade. PR Lens é a camada de compreensão arquitetural. Em código altamente confidencial, mantenha o processo local e não use analyze, canvas, App, Action ou anexo sem uma avaliação formal de dados.

Versão, licença e pacote auditado

A pasta skills/pr-lens não declara versão própria. Esta curadoria usa o commit 0993b4dec8ae73f5e000370e6a758cdd8aa2bfd0, sob MIT. No mesmo commit, o pacote da Skill aparece como 0.2.0 e o CLI como 0.5.1. A consulta do repositório registrou 1.065 estrelas e 42 forks em 11/09/2026.

O ZIP local tem 19.746 bytes e seis arquivos textuais: SKILL.md, LICENSE, ORIGEM.md, references/config.md, references/example.graph.json e references/graph-document.md. SHA-256: e49f18e963994b778815fc2a5eb1a56e7b121edba3c1cdc65b300cabb3addc8d.

O que a revisão editorial confirmou

O exemplo JSON é sintaticamente válido, a licença permite redistribuição e os cinco arquivos originais da pasta correspondem ao commit fixado. A curadoria não executou o CLI e não apresenta o exemplo como teste de comportamento. O pacote não contém Node.js, npm, npx, dependências, binários, scripts, código do projeto, grafos do leitor, SVGs, configurações privadas, tokens ou credenciais.

O principal cuidado está nos saltos entre etapas. Escrever um grafo local é diferente de enviar um diff ao provedor, publicar um canvas ou editar um pull request. A Skill documenta essas possibilidades no mesmo fluxo, portanto o operador precisa separar leitura, escrita, execução, envio de dados e mudança remota.

Checklist antes de executar

• Fixe repositório, commit da Skill, versão do CLI, branch base e branch atual.
• Defina arquivos autorizados e confirme se o código pode sair da máquina.
• Comece com leitura e saída descartável, sem alterar .gitignore.
• Revise o graph.json e valide todas as referências antes de renderizar.
• Compare os SVGs com o diff e escreva texto alternativo específico.
• Proteja chaves de modelo, token do canvas e credenciais do GitHub.
• Aprove separadamente npx, analyze, canvas, App, Action e comandos gh.

Fontes oficiais consultadas

• PR Lens no GitHub, visão geral, instalação, modos e requisitos.
• SKILL.md no commit auditado.
• Referência do documento de grafo.
• Referência de configuração.
• Exemplo oficial de grafo.
• PR Lens, tratamento de código, armazenamento e retenção.
• GitHub Docs, anexos pelo GitHub CLI.
• Pacote oficial do CLI no npm.