formatting-enforcement

Files (5)

• SKILL.md
• lint.yml · references/
• package-json.snippets.json · references/
• pre-commit · references/
• runbook.md · references/

SKILL.md (first lines)

# Formatting Enforcement — Existing Project Retrofit

Existing projects typically have two problems this skill fixes:

1. **Silent-green lint CI** — the workflow runs formatters in fix mode (`pint`, `biome --write`, `prettier --write`), which always exit 0, so unformatted code merges forever and drift accumulates. Reformatting it later collides with open PRs.
2. **Conflicting formatters** — Prettier (with organize-imports/tailwind plugins) and Biome disagree on CSS quote style, import ordering, and JSON key sorting, so a pipeline that runs both can never satisfy a gate that checks both.

## Procedure

### Phase 0 — Measure the drift (check-only commands)

```bash
# PHP: Pint dry-run — exits 1 when files need reformatting
composer test:lint            # pint --parallel --test

# Frontend: check-only, no writes
npm run format:check          # prettier --check resources/  (if prettier is kept)
npm run lint:check            # biome ci .  (if biome is kept)
```

A non-zero exit on a clean checkout of master = drift exists. Record which files are flagged — that is the one-time cleanup list.

### Phase 1 — Clean the drift on a chore branch (never on a feature branch)

1. `git checkout -b chore/apply-quality-pipeline` from fresh `master`
2. Run the repo's pipeline in **gate-consistent order** (whichever formatter runs last owns the files on disk):
   - Biome + Prettier project: `npm run lint` (biome --write) **then** `npm run format` (prettier --write) — Prettier last, so it owns the final on-disk state (CSS quote style, import order, Tailwind class order)
   - Biome-only project: `npm run lint` (biome --write)
   - PHP: `composer lint` (pint)
3. **Resolve formatter conflicts before committing** (see Conflict Matrix below)
4. Commit the delta as a single commit: `chore: apply quality pipeline formatting to clear accumulated drift`
5. PR to `master`, get it merged. Master is now self-consistent.
6. In each open feature branch: `git merge master` — never rebase a branch that has been pushed to GitHub (rebase rewrites history and breaks collaborators with the branch checked out). The formatting is now underneath, so the feature branch's own churn dissolves and its diff shrinks to the feature.

### Phase 2 — Install the gate (CI) and hooks

1. Replace fix-mode CI commands with check-only ones in `.github/workflows/lint.yml` (see `references/lint.yml` for the npm variant). Set `permissions: contents: read`; delete any dead auto-commit step.
2. Add husky + lint-staged (merge `references/package-json.snippets.json`; copy `references/pre-commit` into `.husky/pre-commit`; `npm install` or `bun install` to wire hooks).
3. Verify the gate is green on the cleaned tree:

```bash
composer test:lint && npm run format:check && npm run lint:check   # all exit 0
git config core.hooksPath   # -> .husky/_  (hooks wired)
```

## Conflict Matrix (Prettier + Biome coexistence)

When an existing project keeps Prettier AND Biome, align them or the gate is unsatisfiable. Apply **all** of:

| Conflict | Fix | Where |
|---|---|---|
| CSS quotes (prettier single vs biome double) | `css.formatter.quoteStyle = "single"` | biome.json |
| Import ordering (prettier's organize-imports vs biome's organizeImports sort differently) | `assist.enabled = false` (prettier owns imports) | biome.json |
| JSON key sorting (biome sorts keys, prettier preserves order) | exclude composer.json from biome formatter (`!composer.json` in `formatter.includes`) | biome.json |

These apply to every project that keeps Prettier (the company standard keeps Prettier for Tailwind class ordering and import organization, so the retrofit uses these in every case). A project that drops Prettier entirely (Biome-only) needs none of them — Biome owns everything, and the gate checks only `pint --test` + `biome ci`.

## Verification

- [ ] All check commands exit 0 on the cleaned tree
- [ ] `git diff --stat origin/master` shows only the expected drift files
- [ ] A deliberately misformatted staged file is reformatted by the pre-commit hook
- [ ] Open feature branches re-based onto the cleaned master show no formatting churn

## References

- [Runbook](references/runbook.md) — Expanded step-by-step with commands and rationale
- [CI workflow (npm variant)](references/lint.yml) — Check-only gate for npm projects
- [Pre-commit hook](references/pre-commit) — Bare `lint-staged` (portable across npm and Bun)
- [package.json snippets](references/package-json.snippets.json) — Scripts, lint-staged config, devDependencies

## Five Touchpoints (where formatting enforcement lives)

| # | Touchpoint | What | How |
|---|---|---|---|
| 1 | **CI lint workflow** | Gate on every push/PR | `lint.yml` runs check-only commands (`pint --test`, `biome ci`); fails on drift |
| 2 | **CI tests workflow** | Capture drift on failure | `tests.yml` runs the fixers in a subshell to capture which files drift + Biome version as an artifact |
| 3 | **Pre-commit hook** | Catch drift before commit | `lint-staged` runs pint/biome/prettier on staged files only |
| 4 | **`composer check`** | Local gate (non-mutating mirror of `fix`) | Runs check-mode tools; exits 1 on any drift, leaves tree unchanged |
| 5 | **`composer fix`** | Local repair (mutating) | Runs fix-mode tools; rewrites files, then verifies the rewritten tree |

## Fixer → Checker Mapping

Every fixer has a corresponding check-mode command. The gate must run the check, not the fixer — otherwise the gate never fails.

| Fixer | Check equivalent | What it checks |
|---|---|---|
| `pint` (Laravel Pint) | `pint --test` (or `composer test:lint`) | PHP formatting (PSR-12, project rules) |
| `biome check --write` | `biome ci` (or `bun run lint:check`) | JS/TS linting + formatting |
| `prettier --write` | `prettier --check` (or `bun run format:check`) | CSS quotes, import order, Tailwind class order |
| `tsc` | `tsc --noEmit` | TypeScript type errors |
| `vitest run` | `vitest run` | Unit/integration tests |
| `pest` | `pest` (with `--order-by=rand` in CI) | PHP tests |

**Important:** `composer check` must run in build-then-check order — `bun run build` (or equivalent) must execute before `tsc --noEmit`, because `tsc` reads generated route definitions and other build artifacts. Running `tsc` first validates against stale definitions.

## Notes

- Hooks are per-worktree: each clone/worktree needs one `npm install`/`bun install` for `core.hooksPath` to be set. CI is the enforcement backstop for anyone who skips installs.
- Do NOT run the pipeline on a feature branch and commit the results there — that is exactly what caused the churn-in-PR problem. Drift cleanup belongs on its own chore branch off master.
- **Build before check:** Always run `bun run build` before `composer check` (or the CI equivalent). `tsc --noEmit` reads generated definitions from the build output; checking first validates against stale definitions and produces false positives or misses real errors.
- **Drift-cleanup prerequisite:** Formatting drift must be cleaned on a chore branch off master BEFORE installing the gate. The gate cannot pass on a tree with existing drift — that is the whole point. Clean first, gate second.
- **Acceptance test:** After installing the gate, inject deliberate drift (e.g., remove a trailing semicolon from a PHP file) and verify `composer check` exits 1 and `composer fix` repairs it. This confirms the gate is live, not decorative.

From ceilidhboy/skills, MIT.

More from ceilidhboy/skills