Versionamento

O TyForge segue o Semantic Versioning (SemVer) para todas as publicações no npm.

Semver

O formato de versão segue o padrão MAJOR.MINOR.PATCH:

• Major (X.0.0) — breaking changes na API pública. Remoção de exports, mudanças de assinatura de métodos públicos, alteração de comportamento que quebra consumidores existentes.
• Minor (0.X.0) — adições retrocompatíveis. Novas features, mudanças arquiteturais internas, novas regras de lint, novos TypeFields, novos módulos complementares.
• Patch (0.0.X) — correções retrocompatíveis. Bug fixes, melhorias internas de performance, correções de documentação.

Exemplos

Mudança	Tipo
Novo TypeField FPhone	Minor
Correção de validação em FEmail	Patch
Remoção de export público	Major
Nova regra de lint no-magic-number	Minor
Fix em mensagem de exceção	Patch
Novo módulo @tyforge/graphql	Minor
Alteração de assinatura de SchemaBuilder.compile()	Major

Pinagem de dependências

O TyForge segue o modelo lib-padrão: o package.json publicado usa ranges (^) e o package-lock.json commitado é a fonte de reprodutibilidade de build.

• dependencies (runtime) e peerDependencies — usam caret (^). Como o TyForge é publicado no npm, ranges permitem que consumidores deduplicam a árvore de dependências e recebam patches transitivos (ex: correções de segurança em uuid). Pinar exato numa lib publicada trava a árvore de deps do consumidor e gera conflitos de peer dependency.
• devDependencies de build (tsdown, tsx, typescript, @types/node) — mantidas em versão exata: não afetam consumidores e o lockfile garante builds reprodutíveis.
• Dependências internas (tyforge, @tyforge/*) — sempre ^, inclusive quando aparecem em devDependencies, para não reintroduzir a cascata de re-bump dos pacotes complementares a cada versão do core.

{
  "dependencies": {
    "uuid": "^13.0.2"
  },
  "peerDependencies": {
    "tyforge": "^0.2.22"
  },
  "devDependencies": {
    "typescript": "6.0.2"
  }
}

Modo estrito (opt-in)

Projetos que exigem pinagem exata universal podem ativar via tyforge.config.json:

{
  "pinning": { "strict": true }
}

Com pinning.strict: true, o CheckVersions volta a rejeitar qualquer ^/~/* e o CheckPublishReady exige versão exata idêntica nas dependências internas. O default é false (modelo lib-padrão).

Justificativa

• Compatibilidade do consumidor — ranges ^ em deps de runtime e peer evitam travar a árvore de dependências de quem instala o TyForge e permitem absorver patches de segurança transitivos
• Reprodutibilidade — garantida pelo package-lock.json commitado, não pela pinagem manual no package.json
• Segurança — npm audit bloqueia commits com vulnerabilidades conhecidas; o modo estrito continua disponível para quem precisa de pinagem exata

Pre-commit

O hook de pre-commit inclui verificações automáticas de versionamento:

• CheckVersions — quando pinning.strict: true, verifica que todas as dependências estão pinadas (sem ^/~/*) e rejeita versões não pinadas. No default (strict: false), ranges são permitidos.
• CheckPublishReady — roda apenas na branch de release (configurável via publish.releaseBranch no tyforge.config.json, default main): valida versão inédita no npm, incremento SemVer válido, e que as dependências internas (@tyforge/*) satisfazem a versão local do core.
• npm audit — executa auditoria de segurança e bloqueia commits quando vulnerabilidades conhecidas são detectadas.

Essas verificações rodam automaticamente a cada commit via Husky.

Pacotes complementares

O TyForge é organizado em pacotes independentes:

Pacote	Descrição
tyforge	Core — schemas, TypeFields, domain models, result
@tyforge/http	Cliente HTTP type-safe
@tyforge/graphql	Cliente GraphQL type-safe
@tyforge/websocket	Cliente WebSocket type-safe
@tyforge/guard	Linter de padrões (análise estática)

Versionamento independente

Cada pacote tem seu próprio package.json e segue versionamento independente. O pacote core (tyforge) pode estar na versão 0.2.5 enquanto @tyforge/http está na 0.1.3.

peerDependencies com range

Pacotes complementares declaram o core como peerDependency com range:

{
  "peerDependencies": {
    "tyforge": "^0.2.0"
  }
}

Isso permite que o consumidor use qualquer versão compatível do core.

Regras

1. Incrementar versão antes do CHANGELOG — a versão no package.json deve ser atualizada antes de criar a entrada no CHANGELOG.
2. Nunca publicar versão existente — cada publicação no npm deve ter uma versão única. Tentar publicar uma versão que já existe resulta em erro.
3. Nunca pular versões — incrementar sequencialmente (0.2.3 para 0.2.4, nunca para 0.2.6).
4. Tag git — cada release deve ter uma tag git correspondente (ex: v0.2.4).
5. CHANGELOG obrigatório — toda versão publicada deve ter uma entrada no CHANGELOG descrevendo as mudanças.