46 lines
2.5 KiB
Markdown
46 lines
2.5 KiB
Markdown
# Research: Pre-Commit Gate
|
|
|
|
## R1: Hook Management Tool
|
|
|
|
**Decision**: Use [Lefthook](https://github.com/evilmartians/lefthook) (npm package) as the Git hooks manager.
|
|
|
|
**Rationale**:
|
|
- User explicitly requested Lefthook.
|
|
- Lightweight, standalone Go binary distributed via npm -- no runtime dependencies.
|
|
- Simple YAML configuration (`lefthook.yml`).
|
|
- Auto-installs hooks via npm `postinstall` lifecycle script -- satisfies FR-005 (no manual setup).
|
|
- Well-maintained, widely adopted (used by n8n, Shopify, and others).
|
|
- Respects `--no-verify` by default (standard Git behavior) -- satisfies FR-006.
|
|
|
|
**Alternatives considered**:
|
|
- Husky: Popular but heavier configuration, requires `.husky/` directory with shell scripts.
|
|
- `core.hooksPath`: Native Git, but requires manual setup or custom scripts for auto-install.
|
|
- Simple `prepare` script copying a shell script: Works but no parallel jobs, no structured config.
|
|
|
|
## R2: Auto-Install Mechanism
|
|
|
|
**Decision**: Use a `prepare` script in root `package.json` that runs `lefthook install`.
|
|
|
|
**Rationale**:
|
|
- The `prepare` lifecycle hook runs automatically after `pnpm install`.
|
|
- This ensures every developer gets hooks installed without extra steps after cloning.
|
|
- Lefthook's npm package includes a `postinstall` script that can auto-install, but an explicit `prepare` script is more transparent and reliable across package managers.
|
|
- In CI environments, `CI=true` prevents the `prepare` script from running (standard npm/pnpm behavior), avoiding unnecessary hook installation in CI.
|
|
|
|
**Alternatives considered**:
|
|
- Relying solely on lefthook's built-in `postinstall`: Less transparent; behavior varies with `CI` env var.
|
|
- Manual `lefthook install` step in README: Violates FR-005.
|
|
|
|
## R3: Hook Command Strategy
|
|
|
|
**Decision**: The pre-commit hook runs `pnpm check` as a single command.
|
|
|
|
**Rationale**:
|
|
- `pnpm check` already orchestrates format, lint, typecheck, and test in sequence.
|
|
- Running it as one command keeps the hook configuration minimal and consistent with the existing merge-gate workflow.
|
|
- Output from `pnpm check` already identifies which specific check failed (FR-004, SC-004).
|
|
|
|
**Alternatives considered**:
|
|
- Running each check as a separate Lefthook job with `parallel: true`: Could be faster but adds configuration complexity and the existing `pnpm check` script already handles sequencing. MVP baseline does not include parallel hook jobs.
|
|
- Using `{staged_files}` for file-scoped checks: MVP baseline does not include staged-only checking per spec assumptions.
|