Skip to content

Commit db39b8a

Browse files
jimmynjimmyn
committed
chore: setup comprehensive linting workflow with lint-staged
- Add lint-staged for automatic fixing of staged files on commit - Move PHPStan to pre-push hook for faster commits (~0.9s) - Add master/main branch protection in pre-push hook - Add lint:fix convenience script to auto-fix all issues - Add lint:css-fix for consistency with lint:js-fix - Configure PHPCS to ignore warnings (only fail on errors) - Create .eslintignore and .stylelintignore to exclude public/ - Update phpcs.xml with file paths for src/ and includes/ - Update DEVELOPER.md with comprehensive linting documentation - Update CLAUDE.md with optimized workflow guide Fixed 1200+ linting errors: - PHP: 811 PHPCS errors auto-fixed with phpcbf - PHP: 4 wpautop escaping errors in gateway files - JavaScript: 14+ console statements removed/replaced - CSS: 456 style errors fixed (indentation, units, empty blocks) Developer workflow improvements: - Pre-commit: Auto-fixes staged files (~0.9s) - Commit-msg: Validates conventional commits - Pre-push: Runs PHPStan + blocks master pushes (~1s) - yarn lint:fix: One command to fix all issues
1 parent 4f3628c commit db39b8a

40 files changed

+1067
-671
lines changed

‎.eslintignore‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Build outputs
2+
public/
3+
build/
4+
dist/
5+
6+
# Dependencies
7+
node_modules/
8+
vendor/
9+
10+
# Cache
11+
.phpcs.cache

‎.husky/pre-commit‎

Lines changed: 2 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,4 @@
11
#!/usr/bin/env sh
22

3-
# Get list of staged PHP files
4-
STAGED_PHP_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep '\.php$' || true)
5-
6-
if [ -n "$STAGED_PHP_FILES" ]; then
7-
echo "Running PHPStan on staged PHP files..."
8-
9-
# Run PHPStan only on staged files with memory limit
10-
vendor/bin/phpstan analyse $STAGED_PHP_FILES --error-format=table --memory-limit=1G
11-
12-
if [ $? -ne 0 ]; then
13-
echo "❌ PHPStan found errors. Please fix them before committing."
14-
exit 1
15-
fi
16-
17-
echo "✅ PHPStan passed!"
18-
fi
3+
# Run lint-staged to lint and fix files
4+
yarn lint-staged

‎.husky/pre-push‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
#!/usr/bin/env sh
2+
3+
# Protect master/main branch from direct pushes
4+
current_branch=$(git symbolic-ref --short HEAD)
5+
if [ "$current_branch" = "master" ] || [ "$current_branch" = "main" ]; then
6+
echo "❌ Direct pushes to master/main are not allowed!"
7+
echo "Please create a feature branch and submit a pull request."
8+
echo ""
9+
echo "To create a feature branch:"
10+
echo " git checkout -b feature/your-feature-name"
11+
exit 1
12+
fi
13+
14+
# Run static analysis before push
15+
echo "Running PHPStan static analysis..."
16+
yarn lint:php:phpstan

‎.lintstagedrc.json‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"*.php": [
3+
"composer phpcbf --"
4+
],
5+
"*.{js,jsx}": [
6+
"wp-scripts lint-js --fix"
7+
],
8+
"*.{css,scss}": [
9+
"wp-scripts lint-style --fix"
10+
]
11+
}

‎.stylelintignore‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# Build outputs
2+
public/
3+
build/
4+
dist/
5+
6+
# Dependencies
7+
node_modules/
8+
vendor/

‎CLAUDE.md‎

Lines changed: 87 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -304,39 +304,85 @@ WooCommerce Blocks checkout requires testing in WordPress with WooCommerce Block
304304

305305
### Overview
306306

307-
The project uses static analysis and code style tools to catch bugs before runtime and maintain consistent code style:
307+
The project uses automated linting and static analysis tools with git hooks for an optimized developer workflow:
308308

309-
- **PHPStan** - Static analysis to catch type errors, undefined methods, and bugs
310-
- **PHPCS** - WordPress Coding Standards enforcement
311-
- **PHPCBF** - Automatic code style fixer
312-
- **Pre-commit hooks** - Automated checks before committing code
309+
- **JavaScript/CSS**: ESLint + Stylelint (via `@wordpress/scripts`)
310+
- **PHP Code Style**: PHPCS (WordPress Coding Standards) + PHPCBF (auto-fixer)
311+
- **PHP Static Analysis**: PHPStan Level 4 (type checking, bug detection)
312+
- **Git Hooks**: Husky + lint-staged for automatic fixing on commit
313+
- **Commit Messages**: Commitlint (conventional commits validation)
313314

314-
### Running Linters
315+
### Automated Workflow (Git Hooks)
315316

316-
```bash
317-
# Run all linters (PHP + JS + CSS)
318-
yarn lint
317+
**Pre-commit Hook** (~0.9s - fast!):
318+
- Runs `lint-staged` to auto-fix only staged files
319+
- PHP: `phpcbf` (auto-fixes WordPress coding standards)
320+
- JavaScript: `eslint --fix` (auto-fixes linting errors)
321+
- CSS: `stylelint --fix` (auto-fixes style errors)
322+
- **Result**: All fixable issues are automatically corrected before commit
319323

320-
# PHP Static Analysis (PHPStan)
321-
yarn lint:php:phpstan
322-
composer phpstan
324+
**Commit-msg Hook** (instant):
325+
- Validates commit message follows conventional commits format
326+
- Types: `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`, etc.
327+
- **Result**: Invalid commit messages are rejected
323328

324-
# PHP Code Style (PHPCS)
325-
yarn lint:php:phpcs
326-
composer phpcs
329+
**Pre-push Hook** (~1s):
330+
- **Branch Protection**: Blocks direct pushes to `master`/`main`
331+
- **PHPStan**: Runs static analysis (moved from pre-commit for speed)
332+
- **Result**: Type errors are caught before pushing to remote
327333

328-
# Auto-fix PHP code style issues
329-
yarn lint:php:fix
330-
composer phpcbf
331-
332-
# JavaScript linting
333-
yarn lint:js
334-
yarn lint:js-fix
334+
### Running Linters Manually
335335

336-
# CSS linting
337-
yarn lint:css
336+
```bash
337+
# Auto-fix all issues at once (recommended workflow)
338+
yarn lint:fix
339+
340+
# Individual auto-fixers
341+
yarn lint:js-fix # Fix JavaScript
342+
yarn lint:css-fix # Fix CSS
343+
yarn lint:php:fix # Fix PHP code style (phpcbf)
344+
345+
# Linters only (no auto-fix)
346+
yarn lint # Check all (JS + CSS + PHP + PHPStan)
347+
yarn lint:js # Check JavaScript
348+
yarn lint:css # Check CSS
349+
yarn lint:php # Check PHP (PHPCS + PHPStan)
350+
yarn lint:php:phpcs # Check PHP code style only
351+
yarn lint:php:phpstan # Check PHP static analysis only
338352
```
339353

354+
### Developer Workflow
355+
356+
**Recommended workflow for best experience:**
357+
358+
1. **Make your changes** in the codebase
359+
2. **Before staging**: Run `yarn lint:fix` to auto-fix all issues
360+
3. **Stage your files**: `git add <files>`
361+
4. **Commit**: `git commit -m "feat: your message"`
362+
- Pre-commit hook auto-fixes staged files (~0.9s)
363+
- Commit-msg hook validates message format
364+
5. **Push**: `git push`
365+
- Pre-push hook runs PHPStan (~1s)
366+
- Branch protection prevents pushing to master
367+
368+
**If pre-push fails (PHPStan errors)**:
369+
- Fix the type errors reported by PHPStan
370+
- Commit the fixes
371+
- Push again
372+
373+
### Configuration Files
374+
375+
- **`.lintstagedrc.json`** - Auto-fix configuration for staged files
376+
- **`.husky/pre-commit`** - Runs lint-staged on commit
377+
- **`.husky/commit-msg`** - Validates commit messages
378+
- **`.husky/pre-push`** - Runs PHPStan + branch protection
379+
- **`.eslintrc.js`** - JavaScript linting rules
380+
- **`.eslintignore`** - Excludes `public/` from JS linting
381+
- **`.stylelintignore`** - Excludes `public/` from CSS linting
382+
- **`phpcs.xml`** - PHP code style rules (WordPress standards)
383+
- **`phpstan.neon`** - PHP static analysis configuration (Level 4)
384+
- **`commitlint.config.js`** - Commit message validation
385+
340386
### PHPStan Configuration
341387

342388
**Configuration**: `phpstan.neon`
@@ -357,11 +403,13 @@ composer phpstan -- src/Gateways/PaymentMethods/WCGatewayMoneiCC.php
357403

358404
### PHPCS WordPress Coding Standards
359405

360-
**Configuration**: `.phpcs.xml.dist`
406+
**Configuration**: `phpcs.xml`
361407
- WordPress-Core ruleset
362408
- PSR-4 autoloading compatibility
363409
- Tabs for indentation (WordPress standard)
364410
- File naming follows WordPress conventions
411+
- Files checked: `src/` and `includes/`
412+
- Ignores warnings (only errors fail the build)
365413

366414
**Auto-fixing issues**:
367415
```bash
@@ -372,16 +420,23 @@ composer phpcbf
372420
composer phpcbf -- src/Gateways/PaymentMethods/WCGatewayMoneiCC.php
373421
```
374422

375-
### Pre-commit Hooks
423+
### Git Hooks Best Practices
376424

377-
**File**: `.husky/pre-commit`
425+
**CRITICAL**: NEVER use `--no-verify` to bypass git hooks!
426+
- Git hooks auto-fix issues and catch errors before they reach the repository
427+
- If a hook fails, fix the actual errors instead of bypassing the check
428+
- Using `--no-verify` can introduce bugs and break the build
429+
- Pre-commit is fast (~0.9s) and only checks/fixes staged files
378430

379-
Automatically runs PHPStan on staged PHP files before each commit. This prevents committing code with type errors.
431+
**Branch Protection**:
432+
- Direct pushes to `master`/`main` are automatically blocked
433+
- Always work in feature branches: `git checkout -b feat/my-feature`
434+
- Create pull requests for code review before merging to master
380435

381-
**CRITICAL**: NEVER use `--no-verify` to bypass pre-commit hooks!
382-
- Pre-commit hooks are there to catch errors before they reach the repository
383-
- If the hook fails, fix the actual errors instead of bypassing the check
384-
- Using `--no-verify` can introduce bugs and break the build
436+
**Performance**:
437+
- Pre-commit hook is optimized for speed (~0.9s)
438+
- PHPStan runs only on pre-push (~1s) to keep commits fast
439+
- lint-staged only processes staged files, not the entire codebase
385440

386441
### Common PHPStan Errors & Fixes
387442

‎DEVELOPER.md‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -158,14 +158,138 @@ yarn release 6.4.0 # Specific version
158158
└── readme.txt # WordPress.org plugin readme
159159
```
160160

161+
## Code Quality & Linting
162+
163+
### Overview
164+
165+
The project uses automated linting and code quality tools to maintain consistent code style and catch bugs early:
166+
167+
- **JavaScript/CSS**: ESLint + Stylelint (via `@wordpress/scripts`)
168+
- **PHP**: PHPCS (WordPress Coding Standards) + PHPStan (static analysis)
169+
- **Git Hooks**: Husky + lint-staged for automatic fixing
170+
- **Commit Messages**: Commitlint (conventional commits)
171+
172+
### Git Hooks
173+
174+
**Pre-commit Hook** (fast ~0.9s):
175+
- Auto-fixes staged files with `lint-staged`
176+
- PHP: `phpcbf` (WordPress coding standards auto-fix)
177+
- JavaScript: `eslint --fix`
178+
- CSS: `stylelint --fix`
179+
180+
**Commit-msg Hook**:
181+
- Validates commit message format (conventional commits)
182+
183+
**Pre-push Hook** (~1s):
184+
- **Branch Protection**: Blocks direct pushes to `master`/`main` branches
185+
- **PHPStan**: Static analysis (type checking, bug detection)
186+
187+
### Linting Commands
188+
189+
```bash
190+
# Auto-fix all issues at once (recommended)
191+
yarn lint:fix
192+
193+
# Individual fixers
194+
yarn lint:js-fix # Fix JavaScript issues
195+
yarn lint:css-fix # Fix CSS issues
196+
yarn lint:php:fix # Fix PHP code style issues (phpcbf)
197+
198+
# Linters only (no auto-fix)
199+
yarn lint # Check all (JS + CSS + PHP)
200+
yarn lint:js # Check JavaScript
201+
yarn lint:css # Check CSS
202+
yarn lint:php # Check PHP (PHPCS + PHPStan)
203+
yarn lint:php:phpcs # Check PHP code style only
204+
yarn lint:php:phpstan # Check PHP static analysis only
205+
```
206+
207+
### Workflow Best Practices
208+
209+
1. **Before committing**: Run `yarn lint:fix` to auto-fix all issues
210+
2. **During commit**: Hooks auto-fix staged files and validate commit message
211+
3. **Before push**: PHPStan runs automatically (takes ~1s)
212+
4. **If push fails**: Fix PHPStan errors and push again
213+
214+
### Configuration Files
215+
216+
- `.lintstagedrc.json` - Auto-fix configuration for staged files
217+
- `.eslintrc.js` - JavaScript linting rules
218+
- `.eslintignore` - Exclude `public/` build outputs from JS linting
219+
- `.stylelintignore` - Exclude `public/` build outputs from CSS linting
220+
- `phpcs.xml` - PHP code style rules (WordPress standards)
221+
- `phpstan.neon` - PHP static analysis configuration (Level 4)
222+
- `commitlint.config.js` - Commit message validation rules
223+
224+
### PHPStan (Static Analysis)
225+
226+
PHPStan analyzes PHP code for type errors and bugs without running it:
227+
228+
```bash
229+
# Run PHPStan manually
230+
composer phpstan
231+
232+
# Or via yarn
233+
yarn lint:php:phpstan
234+
```
235+
236+
**Common PHPStan errors:**
237+
- Missing type hints in docblocks
238+
- Calling undefined methods
239+
- Type mismatches in function parameters
240+
- Unreachable code
241+
242+
**Configuration**: `phpstan.neon` (Level 4)
243+
- WordPress/WooCommerce function stubs included
244+
- Bootstrap file for plugin constants
245+
246+
### PHPCS (Code Style)
247+
248+
PHPCS checks PHP code against WordPress Coding Standards:
249+
250+
```bash
251+
# Check code style
252+
composer phpcs
253+
yarn lint:php:phpcs
254+
255+
# Auto-fix code style issues
256+
composer phpcbf
257+
yarn lint:php:fix
258+
```
259+
260+
**Configuration**: `phpcs.xml`
261+
- WordPress-Core ruleset
262+
- Tabs for indentation
263+
- PSR-4 autoloading compatible
264+
265+
### Branch Protection
266+
267+
Direct pushes to `master`/`main` branches are blocked by the pre-push hook:
268+
269+
```bash
270+
# ❌ This will fail:
271+
git checkout master
272+
git push origin master
273+
274+
# ✅ Instead, use feature branches:
275+
git checkout -b feat/my-feature
276+
git push origin feat/my-feature
277+
# Then create a Pull Request on GitHub
278+
```
279+
161280
## Scripts
162281

163282
- `yarn build` - Build production assets
164283
- `yarn start` - Development build with watch mode
165284
- `yarn release` - Create new release (automated versioning)
285+
- `yarn lint` - Lint all files (JS + CSS + PHP)
286+
- `yarn lint:fix` - Auto-fix all linting issues
166287
- `yarn lint:js` - Lint JavaScript
167288
- `yarn lint:js-fix` - Fix JavaScript linting issues
168289
- `yarn lint:css` - Lint CSS
290+
- `yarn lint:css-fix` - Fix CSS linting issues
291+
- `yarn lint:php` - Lint PHP (PHPCS + PHPStan)
292+
- `yarn lint:php:fix` - Fix PHP code style issues
169293

170294
## Tech Stack
171295

‎assets/css/monei-admin.css‎

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -3,21 +3,23 @@
33
.monei-settings-header-logo,
44
.monei-settings-header-welcome,
55
.monei-settings-header-buttons {
6-
text-align: left;
7-
margin-bottom: 20px;
6+
text-align: left;
7+
margin-bottom: 20px;
88
}
99

1010
.monei-settings-header-logo img {
11-
max-width: 200px;
12-
height: auto;
11+
max-width: 200px;
12+
height: auto;
1313
}
1414

1515
.monei-settings-header-welcome p {
16-
font-size: 16px;
16+
font-size: 16px;
1717
}
18+
1819
.wc-settings-sub-nav a[href*="tab=monei_settings"] {
19-
display: none !important;
20+
display: none !important;
2021
}
22+
2123
.nav-tab-wrapper a.nav-tab[href*="tab=monei_settings"] {
22-
display: none !important;
24+
display: none !important;
2325
}

0 commit comments

Comments
 (0)