lint-format-pipeline
verified396e5734-f43d-4373-9f46-0207b35d0adc
Set up a zero-warning lint + format pipeline (ruff/black/prettier/eslint) with auto-fix and CI enforcement. Use to make style a non-issue in any repo.
Metadata
Skill file
# Lint & Format Pipeline
Use when setting up or fixing linting and formatting in a repo — the goal is zero warnings, auto-fix on save, and CI enforcement so style drift is impossible.
## Install & Configure
### Python (ruff + black)
```bash
pip install ruff black
# pyproject.toml
# [tool.ruff] — lint config
# [tool.ruff.lint] — rule selection
```
```toml
# pyproject.toml
[tool.ruff]
line-length = 100
target-version = "py311"
[tool.ruff.lint]
select = ["E", "F", "I", "N", "W", "UP", "B", "C4"]
ignore = ["E501"] # handled by the formatter
[tool.black]
line-length = 100
target-version = ["py311"]
```
### JavaScript/TypeScript (prettier + eslint)
```bash
npm install --save-dev prettier eslint
# .prettierrc
{ "semi": true, "singleQuote": true, "printWidth": 100, "trailingComma": "all" }
```
## The Auto-Fix Pass (do this ONCE first)
```bash
# Python — auto-fix everything fixable
ruff check . --fix
black .
# JavaScript — auto-fix
npx prettier --write .
npx eslint . --fix
```
## The Zero-Warning Bar
| Decision | Rule |
|---|---|
| A rule you agree with | Fix the code |
| A rule you disagree with | Disable it **deliberately** in config with a comment |
| A rule that's genuinely noisy | Narrow it with `per-file-ignores`, don't blanket-ignore |
| A pre-existing violation | Fix now, or add to a tracked backlog (never "later") |
```toml
# Deliberate, documented disable — NOT a lazy blanket ignore
[tool.ruff.lint.per-file-ignores]
"tests/*" = ["S101"] # assert statements are idiomatic in pytest
"migrations/*" = ["E501"] # auto-generated Django migrations
```
## Enforcing in CI
```yaml
# .github/workflows/lint.yml
name: Lint
on: [push, pull_request]
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.11"
- run: pip install ruff black
- name: Format check
run: black --check .
- name: Lint check
run: ruff check .
```
## Configuring VS Code (format on save)
```jsonc
// .vscode/settings.json
{
"[python]": {
"editor.defaultFormatter": "ms-python.black-formatter",
"editor.formatOnSave": true,
"editor.codeActionsOnSave": {
"source.fixAll.ruff": "explicit"
}
}
}
```
## Guardrails
- **Never** introduce a linter and turn it on for the whole repo without an auto-fix pass first — you'll get hundreds of pre-existing errors.
- **Never** use blanket `# noqa` or `// eslint-disable` — always cite the specific rule and reason.
- **Never** let CI pass with warnings while local runs show them — CI and local must use the same config.
- **Always** commit the config file (`.prettierrc`, `pyproject.toml`, `eslint.config.js`) so the whole team shares it.
## Pitfalls
- **Introducing a linter with hundreds of pre-existing errors and no autofix pass**: The team sees 400 errors and disables the linter. Run `--fix` first, then enable enforcement.
- **Formatting churn in unrelated files**: A formatting PR that touches 200 files is unreviewable. Format the whole repo in ONE dedicated commit, then enforce going forward.
- **Rule disagreement handled lazily**: Instead of disabling a disagreeable rule, someone leaves it on and adds `# noqa` everywhere. Decide the rule once, in config.
- **CI/local config drift**: CI uses a different ruff version than local. Pin versions in `requirements-dev.txt` or `pre-commit`.
- **`--fix` on code you don't understand**: Auto-fixers can introduce subtle behavior changes (especially import sorting and string normalization). Review the diff.
## Verify / Checklist
- [ ] `ruff check .` returns zero warnings (or only deliberate, documented disables)
- [ ] `black --check .` reports "would reformat" nothing
- [ ] Auto-fix pass ran once and was committed as a standalone change
- [ ] Config files are committed and shared (not local-only)
- [ ] CI has a lint job that runs `--check` (not `--fix`) and fails on violations
- [ ] Format-on-save works in the IDE (tested on one file)
- [ ] Pre-commit hook runs the same checks as CI (no drift)Attached files
No attached files.