milharis-core

Biblioteca que contém as funções e modelos centrais do projeto Milharis.

Este pacote é publicado no npm e segue a convenção de Semantic Versioning para versionamento.

📦 Instalação

Este projeto deve usar npm para instalação e publicação.

Versão do Node.js: Este projeto foi criado com Node.js versão v20.19.0 (gerenciado via nvm).

npm install

🚀 Comandos de Deploy

IMPORTANTE: Use sempre npm para os comandos de deploy, não yarn:

# ✅ Correto
npm run deploy:fix "Correção de bug"
npm run deploy:feat "Nova funcionalidade"  
npm run deploy:break "Breaking change"

# ❌ Incorreto
yarn deploy:fix "Correção de bug"

🚀 Scripts Disponíveis

Os scripts definidos no package.json são usados para construir, testar e publicar novas versões da biblioteca.

1. npm run build

Compila o projeto usando o tsup.

npm run build

Gera a versão compilada (JavaScript) a partir do código TypeScript.

Saída final fica na pasta definida no tsup.config.ts ou package.json.

2. npm test

Executa todos os testes unitários usando Jest.

npm test

Garante que todas as funcionalidades estão funcionando antes de publicar.

Ideal rodar antes de qualquer commit importante.

3. npm run deploy:break

Publica uma nova versão major (X.0.0).

npm run deploy:break "Refatoração completa da API"

📌 Quando usar:

Alterações incompatíveis com versões anteriores (breaking changes).

APIs removidas ou alteradas de forma que quebrem implementações existentes.

Passos executados automaticamente:

• Roda os testes (jest).
• Compila o projeto (tsup).
• Commita suas mudanças com a mensagem fornecida.
• Faz push para o repositório.
• Incrementa a versão major (npm version major).
• Publica no npm (npm publish).

4. npm run deploy:feat

Publica uma nova versão minor (X.Y.0).

npm run deploy:feat "Adiciona nova funcionalidade X"

📌 Quando usar:

Novas funcionalidades compatíveis com versões anteriores.

Alterações que não quebram código existente.

Passos executados automaticamente:

• Roda os testes (jest).
• Compila o projeto (tsup).
• Commita suas mudanças com a mensagem fornecida.
• Faz push para o repositório.
• Incrementa a versão minor (npm version minor).
• Publica no npm (npm publish).

5. npm run deploy:fix

Publica uma nova versão patch (X.Y.Z).

npm run deploy:fix "Correção de bug na validação"

📌 Quando usar:

• Correções de bugs.
• Ajustes pequenos que não adicionam novas funcionalidades.

Passos executados automaticamente:

• Roda os testes (jest).
• Compila o projeto (tsup).
• Commita suas mudanças com a mensagem fornecida.
• Faz push para o repositório.
• Incrementa a versão patch (npm version patch).
• Publica no npm (npm publish).

📖 Convenção de Versionamento (SemVer)

O projeto segue Semantic Versioning no formato:

MAJOR.MINOR.PATCH

• MAJOR: Alterações incompatíveis (breaking changes).
• MINOR: Novas funcionalidades compatíveis.
• PATCH: Correções e melhorias internas.

🛠 Fluxo de Publicação

Deploy Automatizado

O projeto possui scripts de deploy que automatizam todo o processo:

# Para correções (patch)
npm run deploy:fix "Correção de bug na validação"

# Para novas funcionalidades (minor)  
npm run deploy:feat "Adiciona nova funcionalidade X"

# Para mudanças que quebram compatibilidade (major)
npm run deploy:break "Refatoração completa da API"

⚠️ IMPORTANTE: A mensagem de commit é obrigatória! Sem ela, o deploy falhará.

O que acontece automaticamente:

1. Executa testes - Se algum teste falhar, o processo para
2. Faz build - Compila o TypeScript para JavaScript
3. Commit automático - Pega todas as mudanças e commita com sua mensagem
4. Push automático - Envia para o repositório (incluindo tags de versão)
5. Incrementa versão - Atualiza package.json automaticamente
6. Publica no npm - Faz o publish automaticamente

Fluxo Manual (se necessário):

# 1. Testar
npm test

# 2. Build
npm run build

# 3. Commit manual
git add .
git commit -m "Sua mensagem"
git push

# 4. Incrementar versão
npm version patch  # ou minor/major

# 5. Publicar
npm publish

⚠️ Importante:

• Certifique-se de estar na branch principal (main)
• Todos os testes devem passar antes do deploy
• A mensagem de commit é obrigatória - sem ela o deploy falhará
• A mensagem de commit será usada para descrever as mudanças