doughnut: Skill for Claude Code

Linting and Formatting in Donut Project

When to Use This Rule

Use this rule when:

• Fixing linting or formatting errors
• Running code quality checks
• Validating OpenAPI specifications
• Formatting code before committing
• Troubleshooting linting failures
• Working with Biome, Redocly, or backend linting

Overview

This project uses multiple linting tools to ensure code quality:

• Biome: Frontend, CLI, packages/donut-test-fixtures, Cypress, and other root-level TypeScript/JavaScript code
• Redocly CLI: OpenAPI specification validation
• Backend linting: Java code quality checks (via Gradle)

Linting Philosophy

IMPORTANT: Linting is primarily for CI/CD validation. During development, format changed components explicitly before staging; the pre-commit hook only validates staged components and never formats or stages files.

Running Linting

Run commands from the repo root through Nix.

Lint All Code

CURSOR_DEV=true nix develop -c pnpm lint:all

This runs:

• Backend Java linting (pnpm backend:lint)
• Frontend TypeScript/Vue linting (pnpm frontend:lint)
• CLI TypeScript linting (pnpm cli:lint)
• Shared API test fixtures (packages/donut-test-fixtures) via Biome (pnpm test-fixtures:lint)
• Cypress E2E test linting (pnpm cy:lint)
• OpenAPI specification linting (pnpm openapi:lint)

Individual Linting Commands

• pnpm backend:lint - Java code linting
• pnpm frontend:lint - Frontend TypeScript/Vue linting
• pnpm cli:lint - CLI TypeScript linting
• pnpm test-fixtures:lint - Biome on packages/donut-test-fixtures only
• pnpm cy:lint - Cypress E2E test linting
• pnpm openapi:lint - OpenAPI spec validation

Format vs Lint

• Use ./scripts/run.sh pnpm format:changed before staging — it selects affected components from staged, unstaged, and nonignored untracked paths, then applies their formatter commands. During slice wrap-up, the coordinator runs it once after refactor/API generation and before the PLAN update; it does not pre-filter paths or spawn a formatting agent. Repeat only after an intervening repair invalidates that preparation. The format-changed skill remains available for explicit on-demand use.
• Use CURSOR_DEV=true nix develop -c pnpm format:all only when intentionally formatting the entire repository.
• The pre-commit hook runs pnpm lint:changed against affected staged components. It is check-only: it does not format files or mutate the Git index. Implementers and refactorers do not run format:changed or standalone lint:changed; the coordinator owns formatting and the hook owns the independent lint check. When a selected component needs workspace tools, the hook first validates one installation through setup_pnpm_deps (scripts/dev_setup.sh) with a frozen lockfile and the checks reuse it; a manifest change missing from pnpm-lock.yaml fails with ERR_PNPM_OUTDATED_LOCKFILE (run pnpm install and stage the lockfile). The frontend check reads the committed (index) content from a temporary copy, so unrelated unstaged or untracked work does not affect it. The copy reuses the checkout's node_modules, so workspace packages linked there (such as donut-test-fixtures) are still read from the working tree; its vue-tsc run makes a frontend commit take roughly 8 s, other components about 1–2 s. Other components still check the working tree. To measure the hook, run bash scripts/profiling/profile-commit-hook.sh baseline <evidence-dir> outside Nix: it times the fixed 40-change corpus in a disposable worktree at the committed HEAD.
• Use CURSOR_DEV=true nix develop -c pnpm lint:all for CI/CD validation only — it checks without fixing (plus a few script unit tests that format does not run).