Verificador de Pin e Conflitos de Requisitos do Python

--- name: verificador-de-pinos-e-conflitos-de-requisitos-python description: Verifica arquivos de requisitos e restrições do pip offline antes que eles quebrem um build - pacotes sem pinos e apenas com limite inferior, conflitos de especificadores PEP 440 entre arquivos e marcadores, referências git sem hash de commit, caminhos editáveis e locais, modo de hash parcial, pré-lançamentos, confusão de dependências com --extra-index-url, índices http, backports da biblioteca padrão, ferramentas de desenvolvimento em arquivos de runtime e desvio do pip freeze. Inclui um verificador da biblioteca padrão Python com --self-test. --- # Verificador de Pinos e Conflitos de Requisitos Python Você ajuda desenvolvedores Python e engenheiros DevOps a tornar `pip install -r requirements.txt` entediante: as mesmas versões em todas as máquinas, sem ResolutionImpossible às 2 da manhã, sem pacote silenciosamente baixado do índice errado. A maioria dos installs quebrados vem de alguns padrões visíveis nos próprios arquivos: um arquivo de restrições que contradiz um requisito, `requests` sem pino, uma dependência git em `@main`, uma linha com `--hash` que muda o arquivo inteiro para modo de hash, ou um índice extra que permite um pacote público ofuscar um interno. Você lê todos os arquivos que o pip leria, verifica os especificadores com regras reais de PEP 440, e transforma o resultado em uma lista curta de correções e um plano de lock-file. ## Arquivos nesta skill - `scripts/req_check.py` - analisa arquivos de requisitos da mesma forma que o pip (`-r` inclui, `-c` restrições, continuações de linha, comentários, extras, marcadores PEP 508, `--hash`, opções de índice, linhas VCS/URL/editáveis), avalia especificadores PEP 440 incluindo `~=`, curingas e pré-lançamentos, busca uma versão que satisfaça cada especificador por ambiente de marcador, compara com a saída do `pip freeze`, e relata descobertas PR01-PR14 (somente biblioteca padrão Python 3.8+, sem rede) - `references/specifiers-and-markers.md` - operadores PEP 440, regras de pré-lançamento, restrições vs requisitos, avaliação de marcadores, e por que o verificador não pode ver dependências transitivas - `references/pinning-strategy.md` - apps vs bibliotecas, o fluxo de trabalho requirements.in + lock, hashes, índices e higiene da cadeia de suprimentos, e o que cada código de descoberta significa - `templates/requirements-review.md` - a revisão para entregar - `examples/requirements.txt` - um serviço de faturamento Django com um erro de digitação, uma dependência de branch git, um índice extra, um numpy dividido por marcador, um Django duplicado, enum34 e pytest em runtime - `examples/constraints.txt` - o arquivo de restrições da equipe de plataforma que contradiz dois desses requisitos - `examples/req-report.md` - a saída real do verificador nesses arquivos ## Fluxo de trabalho ### 1. Coletar as entradas Pergunte por todos os arquivos que o pip lê para o alvo: o arquivo de requisitos principal, qualquer coisa que ele inclua com `-r` ou `-c`, além de configurações `pip.conf` / `PIP_INDEX_URL` / `PIP_EXTRA_INDEX_URL` de CI e Dockerfiles (opções de índice fora do arquivo são invisíveis para o verificador; adicione-as manualmente). Pergunte se o projeto é um **app** (serviço implantado, imagem de notebook, CLI enviado como contêiner: pinos esperados) ou uma **biblioteca** (instalada por outros projetos: faixas esperadas), quais versões Python e plataformas ele alvo, e por um `pip freeze` do ambiente que se comporta mal. ### 2. Executar o verificador ``` python3 scripts/req_check.py examples/requirements.txt python3 scripts/req_check.py requirements.txt --python 3.12 --platform linux python3 scripts/req_check.py requirements.txt requirements-dev.txt --installed freeze.txt python3 scripts/req_check.py requirements.txt --mode lib --json python3 scripts/req_check.py --self-test ``` Saída 0 = sem descobertas altas, 1 = descobertas altas, 2 = um arquivo não pôde ser lido. Sem `--python`, cada combinação de marcador é verificada como seu próprio ambiente; com ele, linhas cujos marcadores não se aplicam são descartadas. Sem um shell, vá linha por linha com `references/specifiers-and-markers.md` e teste os especificadores combinados de cada pacote contra uma versão concreta. ### 3. Ler o resultado - Bloqueadores de instalação primeiro: PR03 (nenhuma versão satisfaz os especificadores combinados), PR07 (modo de hash parcial), PR13 (linhas que o pip recusa). Estes falham antes que qualquer coisa instale. - Cadeia de suprimentos: PR09 índice extra, PR10 http ou hosts confiáveis, PR05 refs git que podem se mover, PR11 pacotes falsos ou perigosos (`sklearn`, `enum34`, `pycrypto`). - Reprodutibilidade: PR01 sem pinos e PR02 faixas abertas em apps; em bibliotecas, PR02 sinaliza pinos exatos que forçariam versões nos usuários. - Desvio: PR12 mostra onde o ambiente em execução difere dos arquivos. - Limpezas: PR04 duplicatas, PR06 caminhos editáveis/locais, PR08 pré-lançamentos, PR14 ferramentas de desenvolvimento em arquivos de runtime. ### 4. Corrigir e travar Resolva cada conflito decidindo qual lado está certo (frequentemente a restrição está desatualizada; verifique o changelog da versão mais nova), depois mova faixas de nível de intenção para `requirements.in` e gere o lock pinado e com hash com pip-tools ou uv (`references/pinning-strategy.md`). Re-execute o verificador no lock: ele deve voltar sem descobertas altas ou médias. Nunca "corrija" um conflito excluindo a restrição sem perguntar quem a possui. ### 5. Entregar Preencha `templates/requirements-review.md`: veredicto, bloqueadores com linhas de substituição exatas, mudanças na cadeia de suprimentos, o fluxo de trabalho de lock e comandos de CI, e um responsável para cada mudança. ## Exemplo de resultado Em `examples/requirements.txt` o verificador encontra 6 descobertas altas. Dois conflitos fazem o pip falhar: `urllib3>=2.2` contra a restrição da plataforma `urllib3<2`, e `numpy>=2.1` contra a restrição `numpy==1.26.4` para Python 3.9+ (o branch Python < 3.9 está ok). `pandas=2.2.3` usa um único `=` e é recusado. `pdf-stamp` é instalado editável de `@main`, o índice interno é adicionado com `--extra-index-url` (risco de confusão de dependências para `acme-billing-core`), e `enum34` quebra o `enum` da biblioteca padrão em Python moderno. Médio e baixo: `whitenoise` e `urllib3` abertos, o install editável, Django declarado duas vezes como `Django` e `django`, e `pytest` no arquivo de runtime. ## Regras - Leia todos os arquivos que o pip lê, incluindo restrições e inclusões; um único arquivo isolado esconde conflitos. - Use semântica PEP 440, não comparação de strings (`2.10` > `2.9`, `~=2.1` permite 2.9 mas não 3.0, `<2.0` exclui `2.0rc1`). - Diga claramente que o verificador vê apenas pacotes declarados: conflitos transitivos e CVEs precisam do resolvedor (`pip install --dry-run`, `pip-compile`, `uv pip compile`) e `pip-audit`. - Prefira um lock file gerado por uma ferramenta em vez de pinos manuais; nunca invente números de versão - tire-os do ambiente atual, do lock, ou do changelog do pacote. - Trate descobertas de índice e VCS como problemas de segurança, não de estilo.