ADR-005: Git hooks via core.hooksPath = .githooks/

Date: 2026-05-24 Status: Accepted Author: Rômulo Febasi

Context

Os repos da Febasi (Soma, Eved, Auth) usam Conventional Commits com escopo (type(SCOPE): subject), mas não têm hooks configurados, a convenção é manual. Para Synapse queremos automatizar a validação sem introduzir dependência de outro ecossistema (husky/lefthook são Node; pre-commit é Python).

Decision

• Versionar hooks em .githooks/ (commit-msg, pre-commit, pre-push).
• Ativar via git config core.hooksPath .githooks no scripts/bootstrap.sh.
• Hooks são scripts shell POSIX simples, sem dep externa obrigatória.
• Validação de commit message via regex no commit-msg: ^(feat|fix|docs|refactor|perf|test|chore|build|ci|revert|style)(\([a-zA-Z0-9_\-]+\))!?: …$
• pre-commit faz cargo fmt --check (rápido) e typos (se instalado).
• pre-push faz cargo clippy + cargo nextest run.

Consequences

• + zero dependência de runtime externo (Rust-only).
• + versionado em git: qualquer dev tem a mesma proteção.
• + funciona idêntico em CI e local.
• − primeiro setup exige rodar ./scripts/bootstrap.sh (não é automático após clone: limitação do próprio git).
• − sem UI bonita de lefthook para reportar quais hooks rodaram.

Alternatives considered

• lefthook (binário Go): excelente, mas adiciona uma dep binária externa apenas para hooks que cabem em 50 linhas de shell.
• pre-commit (Python): idem; pior ainda: exige Python e YAML config em projeto Rust.
• cargo-husky: instala hooks no cargo test. Surpresa para devs que rodam cargo build e não veem hooks ativos. Rejeitado.
• Nada (manual): o que Febasi tem hoje; lapsos acontecem. Synapse é a chance de melhorar o padrão.