350 lines
8.6 KiB
Markdown
350 lines
8.6 KiB
Markdown
---
|
|
# agentskills.io specification v1.0
|
|
name: "qa-lefthook-all"
|
|
version: "1.0.0"
|
|
description: "Run all lefthook pre-commit-phase hooks for comprehensive code quality validation"
|
|
author: "Charon Project"
|
|
license: "MIT"
|
|
tags:
|
|
- "qa"
|
|
- "quality"
|
|
- "pre-commit"
|
|
- "linting"
|
|
- "validation"
|
|
compatibility:
|
|
os:
|
|
- "linux"
|
|
- "darwin"
|
|
shells:
|
|
- "bash"
|
|
requirements:
|
|
- name: "python3"
|
|
version: ">=3.8"
|
|
optional: false
|
|
- name: "lefthook"
|
|
version: ">=0.14"
|
|
optional: false
|
|
environment_variables:
|
|
- name: "SKIP"
|
|
description: "Comma-separated list of hook IDs to skip"
|
|
default: ""
|
|
required: false
|
|
parameters:
|
|
- name: "files"
|
|
type: "string"
|
|
description: "Specific files to check (default: all staged files)"
|
|
default: "--all-files"
|
|
required: false
|
|
outputs:
|
|
- name: "validation_report"
|
|
type: "stdout"
|
|
description: "Results of all pre-commit hook executions"
|
|
- name: "exit_code"
|
|
type: "number"
|
|
description: "0 if all hooks pass, non-zero if any fail"
|
|
metadata:
|
|
category: "qa"
|
|
subcategory: "quality"
|
|
execution_time: "medium"
|
|
risk_level: "low"
|
|
ci_cd_safe: true
|
|
requires_network: false
|
|
idempotent: true
|
|
---
|
|
|
|
# QA Pre-commit All
|
|
|
|
## Overview
|
|
|
|
Executes all configured lefthook pre-commit-phase hooks to validate code quality, formatting, security, and best practices across the entire codebase. This skill runs checks for Python, Go, JavaScript/TypeScript, Markdown, YAML, and more.
|
|
|
|
This skill is designed for CI/CD pipelines and local quality validation before committing code.
|
|
|
|
## Prerequisites
|
|
|
|
- Python 3.8 or higher installed and in PATH
|
|
- Python virtual environment activated (`.venv`)
|
|
- Pre-commit installed in virtual environment: `pip install pre-commit`
|
|
- Pre-commit hooks installed: `pre-commit install`
|
|
- All language-specific tools installed (Go, Node.js, etc.)
|
|
|
|
## Usage
|
|
|
|
### Basic Usage
|
|
|
|
Run all pre-commit-phase hooks on all files:
|
|
|
|
```bash
|
|
cd /path/to/charon
|
|
lefthook run pre-commit
|
|
```
|
|
|
|
### Staged Files Only
|
|
|
|
Run lefthook on staged files only (faster):
|
|
|
|
```bash
|
|
lefthook run pre-commit --staged
|
|
```
|
|
|
|
### Specific Hook
|
|
|
|
Run only a specific hook by ID:
|
|
|
|
```bash
|
|
lefthook run pre-commit --hooks=trailing-whitespace
|
|
```
|
|
|
|
### Skip Specific Hooks
|
|
|
|
Skip certain hooks during execution:
|
|
|
|
```bash
|
|
SKIP=prettier,eslint .github/skills/scripts/skill-runner.sh qa-precommit-all
|
|
```
|
|
|
|
## Parameters
|
|
|
|
| Parameter | Type | Required | Default | Description |
|
|
|-----------|------|----------|---------|-------------|
|
|
| files | string | No | --all-files | File selection mode (--all-files or staged) |
|
|
|
|
## Environment Variables
|
|
|
|
| Variable | Required | Default | Description |
|
|
|----------|----------|---------|-------------|
|
|
| SKIP | No | "" | Comma-separated hook IDs to skip |
|
|
| PRE_COMMIT_HOME | No | ~/.cache/pre-commit | Pre-commit cache directory |
|
|
|
|
## Outputs
|
|
|
|
- **Success Exit Code**: 0 (all hooks passed)
|
|
- **Error Exit Codes**: Non-zero (one or more hooks failed)
|
|
- **Output**: Detailed results from each hook
|
|
|
|
## Pre-commit Hooks Included
|
|
|
|
The following hooks are configured in `.pre-commit-config.yaml`:
|
|
|
|
### General Hooks
|
|
- **trailing-whitespace**: Remove trailing whitespace
|
|
- **end-of-file-fixer**: Ensure files end with newline
|
|
- **check-yaml**: Validate YAML syntax
|
|
- **check-json**: Validate JSON syntax
|
|
- **check-merge-conflict**: Detect merge conflict markers
|
|
- **check-added-large-files**: Prevent committing large files
|
|
|
|
### Python Hooks
|
|
- **black**: Code formatting
|
|
- **isort**: Import sorting
|
|
- **flake8**: Linting
|
|
- **mypy**: Type checking
|
|
|
|
### Go Hooks
|
|
- **gofmt**: Code formatting
|
|
- **go-vet**: Static analysis
|
|
- **golangci-lint**: Comprehensive linting
|
|
|
|
### JavaScript/TypeScript Hooks
|
|
- **prettier**: Code formatting
|
|
- **eslint**: Linting and code quality
|
|
|
|
### Markdown Hooks
|
|
- **markdownlint**: Markdown linting and formatting
|
|
|
|
### Security Hooks
|
|
- **detect-private-key**: Prevent committing private keys
|
|
- **detect-aws-credentials**: Prevent committing AWS credentials
|
|
|
|
## Examples
|
|
|
|
### Example 1: Full Quality Check
|
|
|
|
```bash
|
|
# Run all hooks on all files
|
|
source .venv/bin/activate
|
|
.github/skills/scripts/skill-runner.sh qa-precommit-all
|
|
```
|
|
|
|
Output:
|
|
```
|
|
Trim Trailing Whitespace.....................................Passed
|
|
Fix End of Files.............................................Passed
|
|
Check Yaml...................................................Passed
|
|
Check JSON...................................................Passed
|
|
Check for merge conflicts....................................Passed
|
|
Check for added large files..................................Passed
|
|
black........................................................Passed
|
|
isort........................................................Passed
|
|
prettier.....................................................Passed
|
|
eslint.......................................................Passed
|
|
markdownlint.................................................Passed
|
|
```
|
|
|
|
### Example 2: Quick Staged Files Check
|
|
|
|
```bash
|
|
# Run only on staged files (faster for pre-commit)
|
|
.github/skills/scripts/skill-runner.sh qa-precommit-all staged
|
|
```
|
|
|
|
### Example 3: Skip Slow Hooks
|
|
|
|
```bash
|
|
# Skip time-consuming hooks for quick validation
|
|
SKIP=golangci-lint,mypy .github/skills/scripts/skill-runner.sh qa-precommit-all
|
|
```
|
|
|
|
### Example 4: CI/CD Pipeline Integration
|
|
|
|
```yaml
|
|
# GitHub Actions example
|
|
- name: Set up Python
|
|
uses: actions/setup-python@v4
|
|
with:
|
|
python-version: '3.11'
|
|
|
|
- name: Install pre-commit
|
|
run: pip install pre-commit
|
|
|
|
- name: Run QA Pre-commit Checks
|
|
run: .github/skills/scripts/skill-runner.sh qa-precommit-all
|
|
```
|
|
|
|
### Example 5: Auto-fix Mode
|
|
|
|
```bash
|
|
# Some hooks can auto-fix issues
|
|
# Run twice: first to fix, second to validate
|
|
.github/skills/scripts/skill-runner.sh qa-precommit-all || \
|
|
.github/skills/scripts/skill-runner.sh qa-precommit-all
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
### Common Issues
|
|
|
|
**Virtual environment not activated**:
|
|
```bash
|
|
Error: pre-commit not found
|
|
Solution: source .venv/bin/activate
|
|
```
|
|
|
|
**Pre-commit not installed**:
|
|
```bash
|
|
Error: pre-commit command not available
|
|
Solution: pip install pre-commit
|
|
```
|
|
|
|
**Hooks not installed**:
|
|
```bash
|
|
Error: Run 'pre-commit install'
|
|
Solution: pre-commit install
|
|
```
|
|
|
|
**Hook execution failed**:
|
|
```bash
|
|
Hook X failed
|
|
Solution: Review error output and fix reported issues
|
|
```
|
|
|
|
**Language tool missing**:
|
|
```bash
|
|
Error: golangci-lint not found
|
|
Solution: Install required language tools
|
|
```
|
|
|
|
## Exit Codes
|
|
|
|
- **0**: All hooks passed
|
|
- **1**: One or more hooks failed
|
|
- **Other**: Hook execution error
|
|
|
|
## Hook Fixing Strategies
|
|
|
|
### Auto-fixable Issues
|
|
These hooks automatically fix issues:
|
|
- `trailing-whitespace`
|
|
- `end-of-file-fixer`
|
|
- `black`
|
|
- `isort`
|
|
- `prettier`
|
|
- `gofmt`
|
|
|
|
**Workflow**: Run pre-commit, review changes, commit fixed files
|
|
|
|
### Manual Fixes Required
|
|
These hooks only report issues:
|
|
- `check-yaml`
|
|
- `check-json`
|
|
- `flake8`
|
|
- `eslint`
|
|
- `markdownlint`
|
|
- `go-vet`
|
|
- `golangci-lint`
|
|
|
|
**Workflow**: Review errors, manually fix code, re-run pre-commit
|
|
|
|
## Related Skills
|
|
|
|
- [test-backend-coverage](./test-backend-coverage.SKILL.md) - Backend test coverage
|
|
- [test-frontend-coverage](./test-frontend-coverage.SKILL.md) - Frontend test coverage
|
|
- [security-scan-trivy](./security-scan-trivy.SKILL.md) - Security scanning
|
|
|
|
## Notes
|
|
|
|
- Pre-commit hooks cache their environments for faster execution
|
|
- First run may be slow while environments are set up
|
|
- Subsequent runs are much faster (seconds vs minutes)
|
|
- Hooks run in parallel where possible
|
|
- Failed hooks stop execution (fail-fast behavior)
|
|
- Use `SKIP` to bypass specific hooks temporarily
|
|
- Recommended to run before every commit
|
|
- Can be integrated into Git pre-commit hook for automatic checks
|
|
- Cache location: `~/.cache/pre-commit` (configurable)
|
|
|
|
## Performance Tips
|
|
|
|
- **Initial Setup**: First run takes longer (installing hook environments)
|
|
- **Incremental**: Run on staged files only for faster feedback
|
|
- **Parallel**: Pre-commit runs compatible hooks in parallel
|
|
- **Cache**: Hook environments are cached and reused
|
|
- **Skip**: Use `SKIP` to bypass slow hooks during development
|
|
|
|
## Integration with Git
|
|
|
|
To automatically run on every commit:
|
|
|
|
```bash
|
|
# Install Git pre-commit hook
|
|
pre-commit install
|
|
|
|
# Now pre-commit runs automatically on git commit
|
|
git commit -m "Your commit message"
|
|
```
|
|
|
|
To bypass pre-commit hook temporarily:
|
|
|
|
```bash
|
|
git commit --no-verify -m "Emergency commit"
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Pre-commit configuration is in `.pre-commit-config.yaml`. To update hooks:
|
|
|
|
```bash
|
|
# Update to latest versions
|
|
pre-commit autoupdate
|
|
|
|
# Clean cache and re-install
|
|
pre-commit clean
|
|
pre-commit install --install-hooks
|
|
```
|
|
|
|
---
|
|
|
|
**Last Updated**: 2025-12-20
|
|
**Maintained by**: Charon Project
|
|
**Source**: `pre-commit run --all-files`
|