Husky & Commitlint

O projeto nx-suite-front-novo utiliza Husky integrado ao Commitlint para garantir que todos os commits sigam o padrão de convenções definido pelo time de frontend da Smart NX (SNX).
Essa validação automática mantém o histórico limpo, rastreável e semântico, facilitando o versionamento e a integração contínua (CI/CD).

---

Objetivo

• Impedir commits fora do padrão (git commit -m) que possam comprometer o histórico.
• Garantir que mensagens sigam o formato Conventional Commits, com escopos válidos (NXS ou SUI).
• Automatizar validações antes de commits e pushes.
• Detectar alterações em dependências (package.json, yarn.lock, pnpm-lock.yaml) e rodar install automaticamente.

---

Funcionamento

A integração é composta por três partes principais:

1. Hooks do Husky — scripts executados automaticamente em ações do Git (como commit e push).
2. Commitlint — valida as mensagens dos commits conforme as regras da equipe.
3. Scripts auxiliares — validam commits locais e monitoram alterações em dependências.

---

Estrutura e Arquivos Envolvidos

Caminho / Arquivo	Função
.husky/commit-msg	Valida o formato da mensagem de commit utilizando o Commitlint.
.husky/pre-push	Executa o script validate-commits.ts para checar commits antes do push.
.husky/post-merge	Detecta alterações em dependências e executa yarn install automaticamente.
scripts/validate-commits.ts	Executa o Commitlint em cada commit local não enviado para o repositório remoto.
scripts/commitlint-rules/scope-format.ts	Define as regras para validação dos escopos (ex: NXS-123, SUI-456).
commitlint.config.ts	Arquivo principal de configuração do Commitlint (tipos aceitos, escopos, padrões).

---

Padrões de Commits

Todos os commits devem seguir o padrão Conventional Commits, com o seguinte formato:

<type>(<scope>): <descrição>

Exemplo:

feat(NXS-123): adiciona integração com módulo de relatórios

---

Tipos de Commits Aceitos

Tipo	Descrição	Exemplo
feat	Nova funcionalidade	feat(NXS-123): adiciona integração com módulo de relatórios
fix	Correção de bug	fix(SUI-98): corrige erro de carregamento
refactor	Alteração de código sem mudança funcional	refactor(NXS-456): simplifica lógica de renderização
chore	Atualizações diversas, dependências ou configs	chore: atualiza dependências do projeto
docs	Atualização de documentação	docs: adiciona guia de setup de ambiente
test	Adição ou atualização de testes	test(NXS-789): adiciona testes para o hook useAuth
style	Alterações visuais ou de formatação	style: ajusta espaçamento e indentação
perf	Melhorias de performance	perf(NXS-321): otimiza re-renderização de componentes
ci	Alterações no pipeline ou integração contínua	ci: ajusta workflow de build e deploy
build	Alterações no processo de build	build: adiciona configuração de compressão gzip
revert	Reversão de commit anterior	revert: volta commit abc123 por regressão
story	Atualização de componentes do Storybook	story(NXS-888): adiciona variação do componente Button

---

Exemplos de Commits Rejeitados

Caso	Motivo da Rejeição	Exemplo
❌ Escopo inválido	Não segue formato NXS-xxxx ou SUI-xxxx	feat(nx): novo componente
❌ Tipo inexistente	Tipo fora da lista permitida	update(NXS-123): altera fluxo de login
❌ Ausência de tipo/escopo	Falta tipo e escopo no commit	corrige bug de layout
❌ Escopos múltiplos incorretos	Separados incorretamente	fix(NXS123,SUI456): ajusta labels
❌ Assunto vazio	Não há descrição do commit	feat(NXS-222):

---

Regras de Validação

As principais regras estão definidas em:

• commitlint.config.ts — Define os tipos válidos (feat, fix, docs, etc.), tamanho máximo do cabeçalho e formatação do texto.
• scope-format.ts — Regra customizada que valida o formato do escopo (ex: NXS-123, SUI-456), permitindo múltiplos separados por vírgula.
• validate-commits.ts — Executa a validação de commits locais antes do push e bloqueia o envio se houver erros.

💡 Mensagens fora do padrão bloqueiam automaticamente o commit ou o push, garantindo rastreabilidade entre código e tickets JIRA.

---

Boas Práticas

• Prefira commits pequenos e objetivos.
• Sempre relacione a mudança a um ticket JIRA (ex: NXS-123).
• Evite commits genéricos como “fixes” ou “ajustes”.
• Use git commit --amend ou git rebase -i para corrigir mensagens inválidas.
• Não utilize --no-verify sem aprovação do time técnico.

---

Histórico de Versões

Data	Versão	Autor / Revisor	Alterações
29/10/2025	v1.0.0	@Matheus Telles	Criação inicial e estrutura base do documento