malpercio.dev
WIP! A BB-style forum, on the ATmosphere!
We're still working... we'll be back soon when we have something to show off!
node
typescript
hono
htmx
atproto
docs: add oxlint and lefthook pre-commit automation design
+186
+186
docs/plans/2026-02-10-oxlint-lefthook-setup-design.md
+186
docs/plans/2026-02-10-oxlint-lefthook-setup-design.md
···
1
+
# Oxlint and Lefthook Pre-Commit Automation
2
+
3
+
**Date:** 2026-02-10
4
+
**Status:** Approved for Implementation
5
+
6
+
## Goal
7
+
8
+
Add automated linting and testing to pre-commit hooks. Catch style issues, type errors, and test failures before they reach the repository.
9
+
10
+
## Architecture
11
+
12
+
### Tools Selected
13
+
14
+
**Oxlint** — Rust-based linter, runs in milliseconds. Uses recommended preset to catch common issues without overwhelming developers.
15
+
16
+
**Lefthook** — Git hook manager written in Go. Executes checks in parallel, maximizing speed in monorepo environments.
17
+
18
+
### Configuration Location
19
+
20
+
Single configuration at monorepo root:
21
+
- `.oxlintrc.json` — Lint rules inherited by all packages
22
+
- `.lefthook.yml` — Hook definitions and execution strategy
23
+
- Root `package.json` — Tool dependencies and prepare script
24
+
25
+
Per-package additions:
26
+
- `lint:fix` script in each `apps/*/package.json` and `packages/*/package.json`
27
+
28
+
## Pre-Commit Hook Strategy
29
+
30
+
### Execution Flow
31
+
32
+
On `git commit`, lefthook runs three checks in parallel:
33
+
34
+
1. **Lint staged files** — `oxlint` on staged TypeScript/JavaScript files (< 1s)
35
+
2. **Type check affected packages** — `tsc --noEmit` on packages with changes
36
+
3. **Test affected packages** — `vitest` on packages with changes
37
+
38
+
All checks must pass. Any failure blocks the commit.
39
+
40
+
### Affected Package Detection
41
+
42
+
Use turbo's filter syntax to test only packages with staged changes:
43
+
44
+
```bash
45
+
pnpm turbo test --filter=...[HEAD] --force
46
+
pnpm turbo lint --filter=...[HEAD]
47
+
```
48
+
49
+
This prevents running all tests when only one package changed.
50
+
51
+
### Parallel Execution
52
+
53
+
Lefthook runs all three checks simultaneously. First failure stops execution and displays errors. This design minimizes wait time while maintaining thoroughness.
54
+
55
+
## Configuration Files
56
+
57
+
### `.oxlintrc.json`
58
+
59
+
```json
60
+
{
61
+
"rules": {
62
+
"oxc/recommended": "error"
63
+
},
64
+
"env": {
65
+
"node": true,
66
+
"es2022": true
67
+
},
68
+
"ignorePatterns": ["dist", "node_modules", ".turbo"]
69
+
}
70
+
```
71
+
72
+
Rules set to `error` level — violations block commits immediately. No migration period needed (team consists of one developer and AI assistants).
73
+
74
+
### `.lefthook.yml`
75
+
76
+
```yaml
77
+
pre-commit:
78
+
parallel: true
79
+
commands:
80
+
lint:
81
+
glob: "*.{ts,tsx,js,jsx}"
82
+
run: npx oxlint {staged_files}
83
+
typecheck:
84
+
glob: "*.{ts,tsx}"
85
+
run: pnpm turbo lint --filter=...[HEAD]
86
+
test:
87
+
glob: "*.{ts,tsx,js,jsx}"
88
+
run: pnpm turbo test --filter=...[HEAD] --force
89
+
```
90
+
91
+
### Root `package.json` Updates
92
+
93
+
Add dependencies:
94
+
```json
95
+
{
96
+
"devDependencies": {
97
+
"oxlint": "latest",
98
+
"lefthook": "^1.9.0"
99
+
},
100
+
"scripts": {
101
+
"prepare": "lefthook install"
102
+
}
103
+
}
104
+
```
105
+
106
+
The `prepare` script auto-installs git hooks after `pnpm install`.
107
+
108
+
### Per-Package Scripts
109
+
110
+
Add to each `apps/*/package.json` and `packages/*/package.json`:
111
+
112
+
```json
113
+
{
114
+
"scripts": {
115
+
"lint:fix": "oxlint --fix src/"
116
+
}
117
+
}
118
+
```
119
+
120
+
Developers run this manually to auto-fix lint violations before committing.
121
+
122
+
## Developer Workflow
123
+
124
+
### Normal Commit Flow
125
+
126
+
1. Make changes
127
+
2. Stage files with `git add`
128
+
3. Run `git commit`
129
+
4. Lefthook executes lint, typecheck, and test in parallel
130
+
5. If all pass, commit succeeds
131
+
6. If any fail, commit blocks — errors display in terminal
132
+
133
+
### Fixing Lint Violations
134
+
135
+
Auto-fix safe issues:
136
+
```bash
137
+
pnpm turbo lint:fix
138
+
```
139
+
140
+
Or fix a specific package:
141
+
```bash
142
+
pnpm --filter @atbb/appview lint:fix
143
+
```
144
+
145
+
Then retry the commit.
146
+
147
+
### Fixing Type Errors
148
+
149
+
Review TypeScript errors in terminal output. Fix manually, then retry commit.
150
+
151
+
### Fixing Test Failures
152
+
153
+
Review failing tests in terminal output. Fix code or tests, then retry commit.
154
+
155
+
### Emergency Bypass
156
+
157
+
Use `git commit --no-verify` to skip hooks. Discouraged but available for urgent situations.
158
+
159
+
## Installation
160
+
161
+
After merging this change:
162
+
163
+
1. Developers pull latest `main`
164
+
2. Run `pnpm install` — the `prepare` script installs lefthook hooks automatically
165
+
3. Hooks activate immediately for next commit
166
+
167
+
No additional setup required.
168
+
169
+
## Documentation Updates
170
+
171
+
Add to `CLAUDE.md` under a new "Pre-Commit Checks" section:
172
+
173
+
- Explain what runs on every commit (lint, typecheck, test)
174
+
- Show how to auto-fix lint issues (`pnpm turbo lint:fix`)
175
+
- Document bypass mechanism (`git commit --no-verify`)
176
+
- Link to `.lefthook.yml` for full configuration
177
+
178
+
## Benefits
179
+
180
+
**Speed** — Oxlint runs in milliseconds. Lefthook parallelizes checks. Turbo filters to affected packages only.
181
+
182
+
**Safety** — Catches style violations, type errors, and test failures before they enter the repository.
183
+
184
+
**Consistency** — All commits meet the same quality bar automatically.
185
+
186
+
**Low friction** — Most issues auto-fix with `lint:fix`. Hook bypass available when needed.