e48adbcb00
- Migrated from Python pre-commit to NodeJS-native solution - Reorganized documentation structure - Set up Husky + lint-staged for efficient pre-commit hooks - Fixed Dockerfile healthcheck issue - Added comprehensive documentation index
118 lines
3.7 KiB
Markdown
118 lines
3.7 KiB
Markdown
# NodeJS-Native Pre-commit Setup Migration
|
|
|
|
## Overview
|
|
|
|
Successfully migrated from Python's `pre-commit` framework to a 100% NodeJS-native solution using Husky and lint-staged.
|
|
|
|
## What Was Removed
|
|
|
|
- `.pre-commit-config.yaml` - Python pre-commit configuration
|
|
- `.secrets.baseline` - Python detect-secrets baseline
|
|
- Python `pre-commit` dependency requirement
|
|
- Python `detect-secrets` dependency requirement
|
|
|
|
## What Was Added
|
|
|
|
### Core Tools
|
|
|
|
- **Husky v9** - Modern Git hooks manager
|
|
- **lint-staged** - Run tools on staged files only (performance optimization)
|
|
|
|
### NodeJS Alternatives for Previous Python Tools
|
|
|
|
| Python Tool | NodeJS Alternative | Purpose |
|
|
| ------------------ | --------------------------- | -------------------------------------- |
|
|
| `pre-commit-hooks` | Built into Husky hook | File checks, trailing whitespace, etc. |
|
|
| `mirrors-prettier` | `prettier` (direct) | Code formatting |
|
|
| `eslint` (local) | `eslint` (direct) | JavaScript/TypeScript linting |
|
|
| `tsc` (local) | `typescript` (direct) | Type checking |
|
|
| `hadolint` | `dockerfilelint` | Dockerfile linting |
|
|
| `shellcheck-py` | Custom shell checks in hook | Shell script validation |
|
|
| `markdownlint-cli` | `markdownlint-cli2` | Markdown linting |
|
|
| `detect-secrets` | `@secretlint/node` | Secret detection |
|
|
|
|
## New Package.json Scripts
|
|
|
|
```json
|
|
{
|
|
"lint:markdown": "markdownlint-cli2 \"**/*.md\"",
|
|
"lint:markdown:fix": "markdownlint-cli2 --fix \"**/*.md\"",
|
|
"lint:docker": "dockerfilelint docker/Dockerfile",
|
|
"check:secrets": "secretlint \"**/*\"",
|
|
"check:editorconfig": "eclint check .",
|
|
"fix:editorconfig": "eclint fix ."
|
|
}
|
|
```
|
|
|
|
## Enhanced lint-staged Configuration
|
|
|
|
```json
|
|
{
|
|
"lint-staged": {
|
|
"*.{js,jsx,ts,tsx}": ["eslint --fix", "prettier --write"],
|
|
"*.{json,yaml,yml,md,css,scss,html}": ["prettier --write"],
|
|
"*.md": ["markdownlint-cli2 --fix"],
|
|
"docker/Dockerfile": ["dockerfilelint"],
|
|
"*": ["eclint fix"]
|
|
}
|
|
}
|
|
```
|
|
|
|
## Husky Hooks
|
|
|
|
### `.husky/pre-commit`
|
|
|
|
- Runs lint-staged for efficient file-specific checks
|
|
- TypeScript type checking
|
|
- Large file detection (>500KB)
|
|
- Merge conflict marker detection
|
|
- Basic private key detection
|
|
|
|
### `.husky/commit-msg`
|
|
|
|
- Basic commit message validation
|
|
|
|
## Key Benefits
|
|
|
|
1. **No Python Dependencies** - Pure NodeJS ecosystem
|
|
2. **Better Performance** - lint-staged only processes changed files
|
|
3. **Simpler Setup** - No Python virtual environment needed
|
|
4. **Consistent Toolchain** - Everything uses npm/bun
|
|
5. **Modern Tooling** - Latest versions of all tools
|
|
6. **Easier CI/CD** - Same tools in development and CI
|
|
|
|
## Usage
|
|
|
|
### Setup
|
|
|
|
```bash
|
|
|
|
./scripts/setup-pre-commit.sh
|
|
```
|
|
|
|
### Manual Commands
|
|
|
|
```bash
|
|
bun run format # Format all files
|
|
bun run lint:fix # Fix linting issues
|
|
bun run lint:markdown:fix # Fix markdown issues
|
|
|
|
bun run check:secrets # Check for secrets
|
|
bun run type-check # TypeScript validation
|
|
```
|
|
|
|
### What Happens on Commit
|
|
|
|
1. **lint-staged** processes only changed files:
|
|
- ESLint auto-fix + Prettier for JS/TS files
|
|
- Prettier for JSON/YAML/MD/CSS files
|
|
- Markdownlint for Markdown files
|
|
- Dockerfilelint for Dockerfile
|
|
- EditorConfig fixes for all files
|
|
2. **TypeScript** type checking on entire project
|
|
3. **Security checks** for large files, merge conflicts, private keys
|
|
|
|
## Migration Complete ✅
|
|
|
|
The project now uses a modern, efficient, NodeJS-native pre-commit setup that provides the same (and better) functionality as the previous Python-based solution.
|