Cursor rule

1---
2description: Linting, formatting, code quality, Biome (2.4.x), Redocly, OpenAPI validation, code style, fix formatting errors, biome.json config, Vue SFC project-domain rule limitation, multi-file analysis (MFA)
3alwaysApply: false
4---
5# Linting and Formatting in Doughnut Project
6 
7## When to Use This Rule
8 
9**Use this rule when:**
10- Fixing linting or formatting errors
11- Running code quality checks
12- Validating OpenAPI specifications
13- Formatting code before committing
14- Troubleshooting linting failures
15- Working with Biome, Redocly, or backend linting
16 
17## Overview
18 
19This project uses multiple linting tools to ensure code quality:
20- **Biome**: Frontend, CLI, MCP server, `packages/doughnut-test-fixtures`, Cypress, and other root-level TypeScript/JavaScript code
21- **Redocly CLI**: OpenAPI specification validation
22- **Backend linting**: Java code quality checks (via Gradle)
23 
24## Linting Philosophy
25 
26**IMPORTANT**: Linting is primarily for CI/CD validation. Developers should use `format:all` instead of `lint:all` during development, as formatting also fixes most linting issues automatically.
27 
28## Running Linting
29 
30Run commands from the repo root through Nix.
31 
32### Lint All Code
33 
34```bash
35CURSOR_DEV=true nix develop -c pnpm lint:all
36```
37 
38This runs:
39- Backend Java linting (`pnpm backend:lint`)
40- Frontend TypeScript/Vue linting (`pnpm frontend:lint`)
41- CLI TypeScript linting (`pnpm cli:lint`)
42- Shared API test fixtures (`packages/doughnut-test-fixtures`) via Biome (`pnpm test-fixtures:lint`)
43- Cypress E2E test linting (`pnpm cy:lint`)
44- OpenAPI specification linting (`pnpm openapi:lint`)
45 
46### Individual Linting Commands
47 
48- `pnpm backend:lint` - Java code linting
49- `pnpm frontend:lint` - Frontend TypeScript/Vue linting
50- `pnpm cli:lint` - CLI TypeScript linting
51- `pnpm test-fixtures:lint` - Biome on `packages/doughnut-test-fixtures` only
52- `pnpm cy:lint` - Cypress E2E test linting
53- `pnpm openapi:lint` - OpenAPI spec validation
54 
55## Format vs Lint
56 
57- **Use `CURSOR_DEV=true nix develop -c pnpm format:all`** during development - it fixes formatting and catches most issues
58- **Use `CURSOR_DEV=true nix develop -c pnpm lint:all`** for CI/CD validation - it checks without fixing
59 
60## OpenAPI Linting
61 
62The OpenAPI specification (`open_api_docs.yaml`) is validated using Redocly CLI. This file is **auto-generated** from backend controllers.
63 
64### When OpenAPI Linting Fails
65 
661. **DO NOT** edit `open_api_docs.yaml` directly - it is auto-generated
672. **Fix the issue** in the backend Java controller that generates the problematic endpoint
683. **Regenerate** the OpenAPI spec and frontend client (do not hand-edit generated files):
69```bash
70   CURSOR_DEV=true nix develop -c pnpm generateTypeScript
71```
72   This runs OpenAPI generation from Spring controllers (`pnpm backend:generateOpenAPIDocs`) and TypeScript client generation from the spec (`pnpm openAPIToTypeScript`).
734. **Verify** by running `pnpm openapi:lint` again
74 
75### Common OpenAPI Issues
76 
77- **Duplicate operationIds**: Ensure each controller method has a unique `@Operation(operationId = "...")` annotation or unique method name
78- **Missing path parameters**: Add `@PathVariable` annotation to method parameters that match path variables
79- **Identical paths**: Standardize path parameter names across controllers (e.g., use `{notebook}` consistently, not `{notebookId}` in some places)
80 
81After API changes, also run frontend unit tests and fix call sites — see the `generate-api-client` skill.
82 
83## Linting Tools Configuration
84 
85- **Biome**: Configured in `biome.json` (root) and `frontend/biome.json`
86- **Redocly**: Configured in `redocly.yaml`
87- **Backend**: Configured in `backend/build.gradle` (Spotless for formatting, custom linting rules)
88 
89## Biome Configuration (2.4.x)
90 
91This project uses `@biomejs/biome@2.4.x` across the workspace (`package.json`, `frontend/package.json`, `packages/doughnut-test-fixtures/package.json`). Keep those versions pinned and in sync — `syncpack fix` runs on `postinstall` to help.
92 
93### Monorepo config layout
94 
95- **`biome.json`** (workspace root) — governs `e2e_test/`, `cli/`, `mcp-server/`, `scripts/`, `infra/`, `packages/doughnut-test-fixtures/`, etc. Implicit `root: true`.
96- **`frontend/biome.json`** — sets `"root": false`; governs `frontend/` only. Uses Vue-specific rules (`noVueReservedProps`, `noVueDuplicateKeys`, `noVueSetupPropsReactivityLoss`, etc.).
97 
98When running `pnpm biome check` from the workspace root, Biome walks up from each file to find the nearest config. The frontend subtree uses the frontend config; everything else uses the root config.
99 
100### Keep the `$schema` URL in sync with the CLI version
101 
102Both configs must pin `$schema` to the exact CLI version. A mismatch emits a `deserialize` warning on every run:
103 
104```
105i The configuration schema version does not match the CLI version 2.4.x
106```
107 
108When upgrading `@biomejs/biome`, run `pnpx @biomejs/biome migrate --write` from both the repo root and `frontend/` to bump the schema URLs (and auto-apply any rule renames / config restructuring).
109 
110### Ignore quirk: `biome migrate` suggesting `root: false` in the root config
111 
112Running `biome migrate` from inside `frontend/` sometimes suggests adding `"root": false` to **the workspace root** `biome.json`. **Do not apply it.** The workspace root must remain the root. This is a known artifact of the migrator walking up from a nested package.
113 
114### Path scoping: use `files.includes`, not separate `linter.includes`
115 
116- `files.includes` is the canonical include/exclude list; it scopes **both** formatter and linter.
117- `linter.includes` and `formatter.includes` exist but further narrow each tool's scope and are easy to get wrong (and desynced from `files.includes`). Prefer `files.includes` plus scoped overrides when a specific tool needs different treatment.
118- To express "format but don't lint this file", use an override with `linter: { enabled: false }` scoped via `includes`, e.g. for `vitest.config.ts` and `src/assets/daisyui.css` in `frontend/biome.json`. **Do not** rely on a hidden-in-`linter.includes` exclusion — that pattern is opaque.
119 
120### CRITICAL: Project-domain (MFA) rules and Vue SFCs
121 
122Biome 2.x introduces "project" / multi-file-analysis (MFA) rules that build a cross-file import graph. As of Biome 2.4.x, **the MFA resolver does not understand Vue SFC `<script setup>` implicit default exports**. Every `import X from "./X.vue"` in the frontend is flagged as unresolved once MFA activates.
123 
124Project-domain rules include (non-exhaustive):
125- `correctness/noUnresolvedImports`
126- `suspicious/noDeprecatedImports`
127- `suspicious/noImportCycles`
128- `correctness/noFloatingPromises`
129- `correctness/noMisusedPromises`
130- `correctness/noPrivateImports`
131 
132**Rule**: Do NOT enable any of these in the workspace root `biome.json`. Enabling them anywhere the project graph reaches Vue SFCs (which includes the root config, since it delegates to `frontend/biome.json` via MFA) produces 400+ false-positive `noUnresolvedImports` errors even in pure `.ts` files that import from `.vue`.
133 
134- `frontend/biome.json` currently has `noUnresolvedImports: "error"`. It is silently a no-op today because MFA is not activated (no project-domain rule is triggering it). If you add one of the rules above at the root, `frontend:lint` will break even though `frontend/biome.json` hasn't changed.
135- Safe alternative for TS-only subtrees: put project-domain rules in a TS-only override, or in a scoped nested config (e.g. `cli/biome.json`) — but test carefully, since MFA scope is workspace-wide.
136- Revisit this restriction once Biome releases proper Vue SFC module resolution. See Biome issues on `<script setup>` default-export detection.
137 
138### `noUnusedExpressions` and Chai/Cypress assertions
139 
140`suspicious/noUnusedExpressions` is enabled at the root but **turned off for `e2e_test/**`**. Chai's property-chain assertions (e.g. `expect(x).to.not.be.null`, `expect(x).to.be.true`) look like unused expressions to Biome but are real assertions that throw. The override lives in the existing `e2e_test` block inside root `biome.json`.
141 
142### Suppression comment format
143 
144Biome 2.x expects:
145 
146```ts
147// biome-ignore lint/<GROUP>/<RULE>: reason
148```
149 
150The 1.9.x form `// biome-ignore lint(<GROUP>/<RULE>): reason` no longer parses. `biome migrate --write` handles existing comments; new suppressions must use the slash form.
151 
152Bulk variants new in 2.x:
153- `// biome-ignore-all lint/suspicious/noConsole: allowed in this file`
154- `// biome-ignore-start lint/complexity/noForEach: legacy block`
155- `// biome-ignore-end lint/complexity/noForEach:`
156 
157### Empty overrides / includes: delete them
158 
159`{ "includes": [], "linter": { "rules": {} } }` and overrides whose `rules` object is empty do nothing and only obscure intent. Clean them up during any biome-config edit.
160 
161### Running `pnpm lint:all` non-interactively
162 
163The `lint:all` script's first step is `pnpm --frozen-lockfile --silent recursive install`. Outside an interactive TTY, pnpm refuses to purge stale `node_modules` and aborts with:
164 
165```
166ERR_PNPM_ABORTED_REMOVE_MODULES_DIR_NO_TTY
167```
168 
169Export `CI=true` (or set `"confirmModulesPurge": false` in `.npmrc`) before running `pnpm lint:all` in agents / scripts / non-TTY shells. CI already sets `CI=true`.
170 
171## Integration with CI/CD
172 
173The `pnpm lint:all` command is used in CI/CD pipelines to ensure code quality. All linting errors must be resolved before merging code.
174