build2-community/build2-review

O que build2-review faz?

Resolver ROOT

Seja HERE o diretório que contém este SKILL.md (caminho absoluto a partir do contexto do sistema).

ROOT é a árvore de habilidades build2. Use o primeiro candidato cujo guides/packaging-guide-review.md exista:

1. HERE/../build2 (layout de irmão: este diretório adjacente a uma habilidade build2, incluindo uma cópia em um diretório de habilidades do usuário)
2. HERE/../.. (layout aninhado: este diretório sob o subdiretório skills/ da habilidade build2)

Se nenhum existir, pare.

Todos os caminhos read_file posteriores são ${ROOT}/....

Esta é uma verificação de sanidade somente leitura e local. Ela existe para detectar problemas de empacotamento antes de você publicar, executando a mesma lista de verificação que um revisor do cppget.org usaria no repositório. Ela nunca deve criar, comentar ou mesclar uma issue ou pull request do GitHub, nunca enviar um branch, nunca enviar e-mail e nunca modificar o repositório em análise (sem commits, sem tags, sem edições de arquivos, sem bdep release, sem bdep publish, sem git push). Se uma etapa abaixo faria tal alteração, pule-a e transforme-a em um achado relatado. O repositório em análise deve sair desta verificação exatamente como entrou. Esboçar um plano para os achados relatados, sem executá-lo, não conta como alteração; veja "Modo de plano" abaixo para quando isso se aplica.

A lista de verificação e os critérios em ${ROOT}/guides/packaging-guide-review.md são a fonte da verdade. Copie os itens da lista de verificação. Não parafraseie os critérios exigidos. Não invente critérios de revisão.

As revisões cobrem apenas suporte de compilação e empacotamento. Ignore qualidade do código-fonte original, documentação original e estilo de C/C++ original.

Regras rígidas

1. Sem alterações externamente visíveis: nunca crie, comente ou mescle uma issue ou pull request do GitHub, nunca envie um branch, nunca envie e-mail. Isso é incondicional, mesmo que o usuário peça explicitamente uma dessas ações durante a execução: recuse e aponte para o fluxo de trabalho de revisão manual separado (veja "Parar e perguntar" abaixo) em vez de fazê-lo aqui.
2. Sem alterações no repositório em análise: sem commits, tags ou edições de arquivos, sem git push, sem bdep release, sem bdep publish. Apenas inspeção (git log, git show, git diff, leitura de arquivos). Se você precisar compilar ou testar algo para verificar um item, faça-o fora da árvore em um diretório temporário, nunca dentro da árvore de trabalho do repositório revisado.
3. Se for fornecido um caminho local, use-o no local, somente leitura. Não faça checkout de uma ref diferente, não faça stash ou reset.
4. Se for fornecido um repositório remoto ou URL, clone-o somente leitura em um diretório temporário sob /tmp/claude/. Nunca use remotes com capacidade de push ou git push. Trate o clone como descartável.
5. Nunca marque um item da lista de verificação sem verificá-lo pessoalmente nesta execução.
6. Bloqueante vs não bloqueante segue os critérios do guia. Em caso de dúvida, diga isso em vez de silenciosamente rebaixar um erro conceitual de buildfile.
7. A saída é um relatório na conversa (opcionalmente também escrito em um arquivo temporário sob /tmp/claude/). Nunca publique em nenhum lugar externo.

Leituras obrigatórias (antes de relatar achados)

Leia estes arquivos na íntegra com read_file antes de relatar qualquer achado. Não leia por cima.

1. ${ROOT}/guides/packaging-guide-review.md
2. ${ROOT}/guides/packaging-guide-antipatterns.md
3. ${ROOT}/HOWTO/package-naming.md
4. ${ROOT}/guides/packaging-guide-testing.md, apenas Etapa 9 ("Teste o Pacote"). A Etapa 10 ("Publicar") mescla review em main e está fora do escopo aqui, ignore-a.

Carregue sob demanda a partir do mapa no final. A Lista de Verificação de Revisão Inicial dentro de packaging-guide-review.md é a lista de verificação que você percorre. Esse arquivo é a única cópia.

Argumentos

$ARGUMENTS é o texto após /build2-review (ou após /build2 review). Analise na ordem. A primeira regra correspondente vence.

Primeiro token	Tipo
vazio / omitido	detectar automaticamente após resolver o destino
initial	lista de verificação completa de submissão inicial
version	nova versão upstream, baseada em diff
revision	nova revisão de empacotamento, baseada em diff com verificações extras
qualquer outra coisa	tratar como <repo-ou-caminho-local> e detectar tipo automaticamente

Tokens restantes: <repo-ou-caminho-local> (URL do GitHub, owner/repo ou um caminho de clone local) e <versão> opcional. Se o destino estiver faltando, pergunte.

Relate o tipo e a versão escolhidos ao usuário antes de começar.

Obter o repositório

Se o usuário forneceu um caminho local, use-o como está, somente leitura.

Caso contrário, clone somente leitura em um diretório temporário (nunca faça push para este clone, nunca o adicione como destino de push para qualquer outra coisa):

git clone --recurse-submodules --shallow-submodules <url> /tmp/claude/<nome>

Classificar

Determine <VERSAO> a partir do campo version: do manifest (a tag lançada mais recente se houver vários pacotes). Determine o tipo:

Evidência	Tipo
Nenhuma tag lançada ainda, ou a ref revisada ainda é o primeiro commit bdep new	initial
Uma tag vX.Y.Z já existe e esta versão é X.Y.Z+R	revision
Uma versão anterior foi marcada e esta é uma nova X.Y.Z	version

Verifique o primeiro commit do repositório (somente leitura):

git log -p "$(git rev-list --all | tail -1)"

Esse commit deve conter apenas arquivos gerados por bdep new, e sua mensagem deve ser a linha de comando exata. Registre qualquer desvio como um achado. Não ignore.

Tipo: initial

Percorra cada item da seção Lista de Verificação de Revisão Inicial de packaging-guide-review.md no repositório. Marque um item apenas após verificá-lo pessoalmente (árvore, manifest, buildfiles, layout de instalação, testes, tags). Use o HOWTO/guia vinculado para cada item em vez da memória.

Classifique cada achado exatamente como o guia faz:

Classe	Quando
Bloqueante	alta gravidade ou impacto, muitos usuários, erro conceitual (opções de compilação erradas em buildfiles), ou não pode ser corrigido depois sem quebrar compatibilidade
Não bloqueante	deve ser corrigido em uma revisão ou na próxima versão, não falha na verificação
Nota	apenas observação

Carregue sob demanda ao verificar:

• nomes: ${ROOT}/HOWTO/package-naming.md
• licença: ${ROOT}/guides/packaging-license.md
• resumo / README do -tests acompanhante: ${ROOT}/HOWTO/tests-extra-dependencies.md
• cabeçalhos privados: ${ROOT}/HOWTO/third-party-private-headers.md
• opções de compilação: ${ROOT}/HOWTO/buildfile-compile-options.md
• o que não fazer: ${ROOT}/guides/packaging-guide-antipatterns.md
• comentários ou notas estilo diário em buildfiles, manifest ou READMEs (narrativa de processo, uma abordagem anterior que não funcionou, um contratempo ao longo do caminho): ${ROOT}/guides/packaging-guide-antipatterns.md, "Não deixe comentários ou notas estilo diário"

Ao verificar "Usa submódulo git e links simbólicos para upstream": também execute find . -type l -exec test -d {} \; -print em cada diretório de pacote e confirme que cada resultado tem uma entrada symlink=dir correspondente no <pkg>/.gitattributes do próprio pacote (veja ${ROOT}/guides/packaging-guide-summary.md Etapa 5). O git não grava o tipo de link simbólico, portanto, um link simbólico de diretório sem esta entrada quebra silenciosamente um checkout no Windows. Trate uma entrada ausente como bloqueante.

Testar instalação e distribuição

A inspeção estática da lista de verificação não é suficiente. Também compile o pacote fora da árvore para detectar o que só aparece em tempo de compilação (cabeçalhos ausentes ou privados alcançando a árvore de instalação, arquivos faltando no grafo do buildfile, regras clean quebradas). Faça isso em um diretório temporário sob /tmp/claude/, nunca dentro do repositório revisado. Siga "Etapa 9: Teste o Pacote" em ${ROOT}/guides/packaging-guide-testing.md:

1. Caso instalado: b install config.install.root=/tmp/claude/<nome>-install, depois compile e execute tests/ fora da fonte usando essa cópia instalada. Confirme que nada inesperado foi instalado (sem cabeçalhos ausentes, sem cabeçalhos privados instalados por engano).
2. Distribuição de código-fonte: b dist config.dist.root=/tmp/claude/<nome>-dist config.dist.uncommitted=true, então no arquivo extraído execute configure, update, test e clean. Um bdep test verde sozinho não é suficiente, é assim que o cppget.org realmente compila o pacote.

Remova ambos os diretórios temporários depois. Registre qualquer falha como um achado (um pacote que falha em instalar ou distribuir corretamente é normalmente bloqueante).

Relatar

Apresente os resultados ao usuário usando o mesmo layout de seção do comentário de resultado do guia, mas não o publique em nenhum lugar:

Problemas bloqueantes:

...

Problemas não bloqueantes:

...

Notas:

...

Omita seções vazias. Se você escreveu uma cópia temporária, mencione seu caminho.

Tipo: version

Diferencie a versão base (previamente revisada) da versão alvo. Prefira um git diff <tag-antiga>..<tag-nova> local se ambas as tags estiverem disponíveis no clone, caso contrário, a visualização de comparação do GitHub:

https://github.com/<dono>/<projeto>/compare/vANTIGA...vNOVA

Observe a compatibilidade em nível de compilação: renomear destinos exportados ou variáveis de configuração é uma quebra mesmo quando a API do upstream está estável.

Relate um dos:

1. Sem alterações substanciais de empacotamento, sem problemas: diga claramente, sem lista de verificação necessária.
2. Sem alterações substanciais de empacotamento, há problemas: liste-os diretamente (sem lista de verificação).
3. Alterações substanciais de empacotamento: execute o procedimento inicial completo acima, lista de verificação mais o teste de instalação e distribuição.

Tipo: revision

Mesmo que version, mais sinalize como achado se qualquer um destes não for verdadeiro:

• As alterações são limitadas a correções de bugs em buildfiles, manifest e arquivos de empacotamento semelhantes.
• As correções de código-fonte upstream são limitadas a bugs críticos backportados do upstream.
• Estritamente compatível com versões anteriores com a versão que substitui.
• Sem grandes mudanças estruturais (layout de fonte, nomes de destino exportados, nomes de variáveis de configuração).

Modo de plano

Esta habilidade permanece somente leitura de qualquer forma, nunca executa as correções por si mesma. O que muda é apenas se um plano para as alterações e melhorias necessárias é redigido junto com o relatório.

• Se a sessão atual estiver em modo de plano (espera-se que o assistente proponha um plano de implementação para aprovação antes de fazer alterações, em vez de agir imediatamente): após relatar, também redija um plano que aborde os achados bloqueantes e não bloqueantes, depois apresente-o através de qualquer mecanismo de aprovação de plano que o ambiente forneça. Escopo o plano para achados bloqueantes e não bloqueantes, pule notas a menos que o usuário peça. Agrupe correções relacionadas e destaque quaisquer que toquem no layout gerado por bdep new, manifest ou arquivos buildfile que precisam de cuidado ou ordenação particular.
• Caso contrário, siga o fluxo de relatório estabelecido acima e pare por aí. Não redija, proponha ou insinue um plano de implementação; as correções são para o usuário ou um fluxo de trabalho separado executar.

Parar e perguntar

Pare em vez de adivinhar quando qualquer uma destas condições for verdadeira:

• Você não consegue determinar a versão ou o tipo.
• Você não consegue acessar o repositório (clone falha, caminho local inválido).
• O primeiro commit não é um commit bdep new e o usuário não decidiu como registrar isso no relatório.
• Bloqueante vs não bloqueante não está claro para um achado que quebraria a compatibilidade.
• O usuário pediu para realmente abrir a issue/PR de revisão do GitHub, mesclar algo ou enviar o e-mail [email protected]. Esse é um fluxo de trabalho separado, fora do escopo, que esta habilidade não executa.
• O usuário pediu para criar o pacote em vez de verificá-lo (mude para build2-package).

Mapa sob demanda

Necessidade	Arquivo
Lista de verificação e critérios	${ROOT}/guides/packaging-guide-review.md
O que não fazer	${ROOT}/guides/packaging-guide-antipatterns.md
Nomes	${ROOT}/HOWTO/package-naming.md
Licença	${ROOT}/guides/packaging-license.md
Pacotes acompanhantes	${ROOT}/HOWTO/tests-extra-dependencies.md
Criando o pacote	../build2-package/SKILL.md