fix: move PHPStan to pre-commit to catch errors immediately

jimmyn · jimmyn · commit c370b92e6978 · 2025-10-03T13:04:49.000+02:00
PHPStan should run at commit time, not push time, to ensure every commit
in git history is type-safe and prevent committing broken code.

Changes:
- Move PHPStan from pre-push to pre-commit (lint-staged)
- Update pre-push hook to only check branch protection
- Update DEVELOPER.md and CLAUDE.md documentation

Why this is better:
- Type errors caught immediately when committing
- No broken commits in git history
- No need to fix and re-commit after failed push
- Clearer workflow: fix → stage → commit → push
diff --git a/.husky/pre-push b/.husky/pre-push
@@ -11,6 +11,4 @@ if [ "$current_branch" = "master" ] || [ "$current_branch" = "main" ]; then
     exit 1
 fi
 
-# Run static analysis before push
-echo "Running PHPStan static analysis..."
-yarn lint:php:phpstan
+echo "✅ Branch check passed"
diff --git a/.lintstagedrc.json b/.lintstagedrc.json
@@ -1,6 +1,7 @@
 {
   "*.php": [
-    "composer phpcbf --"
+    "composer phpcbf --",
+    "composer phpstan --"
   ],
   "*.{js,jsx}": [
     "wp-scripts lint-js --fix"
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -314,22 +314,21 @@ The project uses automated linting and static analysis tools with git hooks for
 
 ### Automated Workflow (Git Hooks)
 
-**Pre-commit Hook** (~0.9s - fast!):
-- Runs `lint-staged` to auto-fix only staged files
-- PHP: `phpcbf` (auto-fixes WordPress coding standards)
+**Pre-commit Hook**:
+- Runs `lint-staged` to auto-fix and validate staged files
+- PHP: `phpcbf` (auto-fixes code style) + `phpstan` (static analysis)
 - JavaScript: `eslint --fix` (auto-fixes linting errors)
 - CSS: `stylelint --fix` (auto-fixes style errors)
-- **Result**: All fixable issues are automatically corrected before commit
+- **Result**: All fixable issues corrected, type errors caught immediately
 
 **Commit-msg Hook** (instant):
 - Validates commit message follows conventional commits format
 - Types: `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`, etc.
 - **Result**: Invalid commit messages are rejected
 
-**Pre-push Hook** (~1s):
+**Pre-push Hook** (instant):
 - **Branch Protection**: Blocks direct pushes to `master`/`main`
-- **PHPStan**: Runs static analysis (moved from pre-commit for speed)
-- **Result**: Type errors are caught before pushing to remote
+- **Result**: Enforces feature branch workflow
 
 ### Running Linters Manually
 
@@ -359,16 +358,21 @@ yarn lint:php:phpstan # Check PHP static analysis only
 2. **Before staging**: Run `yarn lint:fix` to auto-fix all issues
 3. **Stage your files**: `git add <files>`
 4. **Commit**: `git commit -m "feat: your message"`
-   - Pre-commit hook auto-fixes staged files (~0.9s)
+   - Pre-commit hook auto-fixes staged files
+   - Pre-commit hook runs PHPStan to catch type errors
    - Commit-msg hook validates message format
 5. **Push**: `git push`
-   - Pre-push hook runs PHPStan (~1s)
-   - Branch protection prevents pushing to master
+   - Pre-push hook checks branch protection
 
-**If pre-push fails (PHPStan errors)**:
+**If commit fails (PHPStan errors)**:
 - Fix the type errors reported by PHPStan
-- Commit the fixes
-- Push again
+- Stage the fixes: `git add <files>`
+- Commit again
+
+**Why this is better**:
+- Type errors are caught at commit time, not push time
+- Every commit in git history is guaranteed to be type-safe
+- No need to fix and re-commit after a failed push
 
 ### Configuration Files
 
@@ -434,9 +438,9 @@ composer phpcbf -- src/Gateways/PaymentMethods/WCGatewayMoneiCC.php
 - Create pull requests for code review before merging to master
 
 **Performance**:
-- Pre-commit hook is optimized for speed (~0.9s)
-- PHPStan runs only on pre-push (~1s) to keep commits fast
 - lint-staged only processes staged files, not the entire codebase
+- PHPStan analyzes only staged PHP files and their dependencies
+- Pre-push hook is instant (only branch check)
 
 ### Common PHPStan Errors & Fixes
 
diff --git a/DEVELOPER.md b/DEVELOPER.md
@@ -171,18 +171,18 @@ The project uses automated linting and code quality tools to maintain consistent
 
 ### Git Hooks
 
-**Pre-commit Hook** (fast ~0.9s):
+**Pre-commit Hook**:
 - Auto-fixes staged files with `lint-staged`
-- PHP: `phpcbf` (WordPress coding standards auto-fix)
+- PHP: `phpcbf` (auto-fix code style) + `phpstan` (static analysis)
 - JavaScript: `eslint --fix`
 - CSS: `stylelint --fix`
+- **Prevents committing broken code** by running PHPStan
 
 **Commit-msg Hook**:
 - Validates commit message format (conventional commits)
 
-**Pre-push Hook** (~1s):
+**Pre-push Hook**:
 - **Branch Protection**: Blocks direct pushes to `master`/`main` branches
-- **PHPStan**: Static analysis (type checking, bug detection)
 
 ### Linting Commands
 
@@ -207,9 +207,9 @@ yarn lint:php:phpstan # Check PHP static analysis only
 ### Workflow Best Practices
 
 1. **Before committing**: Run `yarn lint:fix` to auto-fix all issues
-2. **During commit**: Hooks auto-fix staged files and validate commit message
-3. **Before push**: PHPStan runs automatically (takes ~1s)
-4. **If push fails**: Fix PHPStan errors and push again
+2. **During commit**: Hooks auto-fix staged files, run PHPStan, and validate commit message
+3. **If commit fails**: Fix PHPStan errors and commit again
+4. **Before push**: Branch protection check ensures you're not pushing to master
 
 ### Configuration Files
 

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,7 @@`
`1`	`1`	`{`
`2`	`2`	`"*.php": [`
`3`		`- "composer phpcbf --"`
	`3`	`+ "composer phpcbf --",`
	`4`	`+ "composer phpstan --"`
`4`	`5`	`],`
`5`	`6`	`"*.{js,jsx}": [`
`6`	`7`	`"wp-scripts lint-js --fix"`