fix: v3.5.1 — gerador lê as specs atuais, enum negativo (#39), deprecations (#36) e gate de php -l

[andrenfe]

Descrição

Correções do gerador e da base que destravam a atualização das specs às APIs atuais. O resync das specs vem num PR seguinte; este PR não altera openapi/.

Diagnóstico de origem: um ensaio de resync com as specs atuais do nfe/docs parou em três pontos. O gerador não lia 3 specs de NF-e, um enum gerado de CT-e dava erro fatal (#39) e um teste dependia do DNS da máquina.

Corrigido

• Fatal error na v3.5.0: enum gerado com case duplicado (ConsultaCteV2/DFe_NetCore_Domain_Enums_EntityStatus) #39: enum de CT-e com case duplicado. ConsultaCteV2\DFe_NetCore_Domain_Enums_EntityStatus declarava Value_1 duas vezes (para 1 e -1) e dava erro fatal ao carregar, em php -l e com --classmap-authoritative. Valores negativos agora viram Value_MinusN, seguindo o padrão Value_<n>. O gerador passa a falhar, citando spec, schema e valores, quando dois valores geram o mesmo nome de case ou o mesmo valor de backing.
• DTOs gerados de ConsultaNfeDistribuicaoV1 emitem Deprecated em PHP 8.2 (parâmetro opcional antes de obrigatório) #36: deprecations em 3 DTOs de ConsultaNfeDistribuicaoV1. Os DTOs declaravam parâmetro opcional antes de obrigatório. O gerador não emite mais esse default, que já era inalcançável. A ordem dos parâmetros e o tipo ?string não mudam.
• Specs atuais da fonte com string entre aspas e continuação na coluna 0. nf-produto-v2, nf-produto-v3 e product-invoice-rtc-v1 passaram a ter esse formato. PyYAML e js-yaml aceitam, mas o symfony/yaml recusava, e o composer generate não rodava.
  • Decisão: reindentar essas linhas no carregamento, só quando o parser recusa o arquivo como está. O valor lido não muda: nas 3 specs, o documento é idêntico ao do PyYAML. O resumo do composer generate informa quantas linhas foram reindentadas.
  • Descartado: trocar o parser, porque o libyaml usa tipos do YAML 1.1 e exige extensão PECL no CI.
  • Descartado: normalizar no sync, porque as specs vendoradas divergiriam da fonte.
• Teste de FailurePhase independente de DNS. O teste supunha que .invalid nunca resolve e falhava em rede com DNS curinga. Agora força conexão recusada numa porta livre de 127.0.0.1.

Adicionado

• Gate composer lint (scripts/lint.sh): php -l com E_ALL em todo src/, falhando em erro ou deprecation. Roda como job próprio no CI (PHP 8.2) e no verify da release. Pega o que o lint do gerador (token_get_all) deixava passar.

Removido

• Arquivo VERSION da raiz. Era resto da linha v2, dizia 3.4.1 e nada no repositório o lia. A versão vem só de Nfe\Version::CURRENT.

Versão

• Version::CURRENT sobe para 3.5.1 e o CHANGELOG ganha a seção [3.5.1] — 2026-10-17.
• A tag v3.5.1 fica para depois do merge.

Tipo de mudança

• fix
• feat
• docs
• chore/ci

Arquivos gerados alterados: 4

Todos explicados: 1 pela #39 (o enum) e 3 pela #36 (os 4 parâmetros que geravam deprecation).

Validação (Docker)

• Pest em PHP 8.2, 8.3 e 8.4: 298 passaram, 9 pulados.
• composer stan: sem erros.
• composer cs: 0 arquivos a corrigir.
• composer generate:check: em sincronia.
• composer lint: 933 arquivos limpos. Antes das correções, falhava com 1 erro fatal (Fatal error na v3.5.0: enum gerado com case duplicado (ConsultaCteV2/DFe_NetCore_Domain_Enums_EntityStatus) #39) e 4 deprecations (DTOs gerados de ConsultaNfeDistribuicaoV1 emitem Deprecated em PHP 8.2 (parâmetro opcional antes de obrigatório) #36).
• Ensaio do composer generate com as 3 specs atuais da fonte: 925 arquivos, php -l limpo.

Compatibilidade

Sem quebra:

• O case renomeado pertencia a um enum que nunca carregou.
• A remoção do default não muda comportamento, verificado em 8.2, 8.3 e 8.4.
• O gerador fica em scripts/, fora do pacote distribuído.

Fora deste PR

• Resync das specs com o nfe/docs.
• Issue no nfe/docs sobre as continuações em coluna 0. A tabela markdown dos eventos de autoridade vira uma linha só, porque dentro de aspas a quebra simples vira espaço; o certo é usar bloco |.
• Teste que volte a cobrir a falha de DNS (errno 6).

Closes #39
Closes #36