feat(api): Ruff import order (PLAN §3.7), Turbo lint:fix, editor integration (#14)

* feat(api): Ruff import order (PLAN §3.7), Turbo lint:fix, editor integration

- Add Ruff 0.15.9 with I rules and known-first-party app; exclude generated OpenAPI
- Wire lint to pnpm run build then ruff check; add lint:fix for api
- Root turbo lint:fix (cache: false); web placeholder; root pnpm lint:fix script
- Document import order in apps/api README; mark PLAN §3.7 complete
- Recommend Ruff extension; Python codeActionsOnSave for fixAll/organizeImports

Made-with: Cursor

* chore(vscode): format settings.json (indent, trailing newline)

Made-with: Cursor

* fix(api): install dev extras in postinstall so Ruff is available for lint

- postinstall: pip install -e ".[dev]" (matches Copilot review)
- README: document that pnpm install pulls Ruff/pytest; clarify Import order prereqs

Made-with: Cursor

Author: mcalthrop

.vscode/extensions.json

@@ -1,5 +1,6 @@
 {
   "recommendations": [
+    "charliermarsh.ruff",
     "ms-python.python",
     "ms-python.vscode-pylance",
     "redhat.vscode-yaml",

.vscode/settings.json

@@ -1,8 +1,11 @@
 {
-    "python.defaultInterpreterPath": "${workspaceFolder}/apps/api/.venv/bin/python",
-    "python.terminal.activateEnvironment": true,
-    "cSpell.words": [
-        "dataclass",
-        "dataclasses"
-    ]
-}
+  "python.defaultInterpreterPath": "${workspaceFolder}/apps/api/.venv/bin/python",
+  "python.terminal.activateEnvironment": true,
+  "[python]": {
+    "editor.codeActionsOnSave": {
+      "source.fixAll.ruff": "explicit",
+      "source.organizeImports.ruff": "explicit"
+    }
+  },
+  "cSpell.words": ["dataclass", "dataclasses"]
+}

PLAN.md

@@ -21,7 +21,7 @@ Tasks and subtasks for building the bread-recipes app (SolidJS + Python REST + O
 - [x] **3.4** Implement REST handlers to match the OpenAPI spec (response shapes and status codes); keep behaviour aligned with the spec.
 - [x] **3.5** Generate Pydantic models from **`packages/openapi/openapi.yaml`** (e.g. **datamodel-code-generator**), commit generated output, and add CI that fails when the spec changes without regenerating (drift check).
 - [x] **3.6** Tests with 100% coverage and a coverage gate in CI for the API package; add `README.md` for install, run, and test commands.
-- [ ] **3.7** Select and configure a Python import-ordering tool (PEP 8–aligned; e.g. **Ruff**’s isort rules or **isort**), apply it across **`apps/api`**, and document how to run it (CI enforcement can align with §3.6 / §6.1).
+- [x] **3.7** Select and configure a Python import-ordering tool (PEP 8–aligned; e.g. **Ruff**’s isort rules or **isort**), apply it across **`apps/api`**, and document how to run it (CI enforcement can align with §3.6 / §6.1).
 
 ## 4. SolidJS front end
 

apps/api/README.md

@@ -15,18 +15,12 @@ FastAPI ASGI service: **`GET /health`**, **`GET /recipes`**, and **`GET /recipes
 
 ## Setup
 
-From the **repository root**, **`pnpm install`** runs this package’s **`postinstall`**: create **`apps/api/.venv`** if it is missing, then **`pip install -e .`** inside it so **`datamodel-code-generator`** and the rest of the core dependencies are available to **`pnpm openapi:generate`**.
+From the **repository root**, **`pnpm install`** runs this package’s **`postinstall`**: create **`apps/api/.venv`** if it is missing, then **`pip install -e ".[dev]"`** so runtime dependencies (**`datamodel-code-generator`**, **FastAPI**, …) and **dev** tools (**`pytest`**, **`ruff`**, …) are available for **`pnpm openapi:generate`**, **`pnpm lint`**, **`pnpm test`**, and **`pnpm lint:fix`**.
 
-For tests and optional dev tools, from **`apps/api`** with the venv activated:
-
-```bash
-source .venv/bin/activate
-pip install -e ".[dev]"
-```
-
-Alternatively, create the venv and install everything in one go manually:
+If you create the venv yourself (without **`pnpm install`**), install the editable package with dev extras:
 
 ```bash
+cd apps/api
 python3 -m venv .venv
 source .venv/bin/activate
 pip install -e ".[dev]"
@@ -48,6 +42,22 @@ This runs **`pytest`** with **line coverage** for the **`app`** package, **fails
 
 Configuration lives in **`pyproject.toml`** (**`[tool.pytest.ini_options]`**, **`[tool.coverage.*]`**).
 
+## Import order (Ruff / isort)
+
+Imports are checked with **[Ruff](https://docs.astral.sh/ruff/)** using the **`I`** rules (PEP 8–style ordering compatible with **isort**). Configuration lives under **`[tool.ruff]`** in **`pyproject.toml`** (`known-first-party = ["app"]`; generated OpenAPI models under **`app/openapi/generated/`** are excluded). **Ruff** is a **dev** dependency; after **[Setup](#setup)** ( **`pnpm install`** or **`pip install -e ".[dev]"`** ), **`apps/api/.venv/bin/ruff`** is available.
+
+Check (matches CI):
+
+```bash
+pnpm lint
+```
+
+Auto-fix import order:
+
+```bash
+pnpm lint:fix
+```
+
 ## Run (development)
 
 ```bash

apps/api/app/main.py

@@ -6,10 +6,10 @@
 from starlette.requests import Request
 from starlette.responses import JSONResponse
 
-from app.routers.recipes.data_paths import resolve_recipes_json_path
 from app.openapi.paths import resolve_openapi_spec_path
 from app.openapi.spec import load_openapi_info
 from app.routers import health_router, recipes_router
+from app.routers.recipes.data_paths import resolve_recipes_json_path
 from app.routers.recipes.exceptions import RecipeNotFoundError
 from app.routers.recipes.repository import StaticRecipeRepository
 from app.routers.recipes.state import RecipeAppState

apps/api/app/openapi/codegen.py

@@ -9,6 +9,7 @@
     PythonVersion,
     generate,
 )
+
 from app.openapi.paths import resolve_openapi_spec_path
 
 _PKG = Path(__file__).resolve().parent

apps/api/package.json

@@ -7,8 +7,9 @@
     "dev": ".venv/bin/python -m uvicorn app.main:app --reload --host 127.0.0.1 --port 8000",
     "openapi:generate": ".venv/bin/python -m app.openapi.codegen",
     "openapi:validate": "bash scripts/validate_openapi_generated.sh",
-    "lint": ".venv/bin/python -m compileall -q app",
+    "lint": "pnpm build && .venv/bin/ruff check app",
+    "lint:fix": ".venv/bin/ruff check app --fix",
     "test": ".venv/bin/python -m pytest -v",
-    "postinstall": "bash -e -c 'test -d .venv || python3 -m venv .venv; .venv/bin/python -m pip install -e .'"
+    "postinstall": "bash -e -c 'test -d .venv || python3 -m venv .venv; .venv/bin/python -m pip install -e \".[dev]\"'"
   }
 }

apps/api/pyproject.toml

@@ -20,6 +20,7 @@ dev = [
   "httpx==0.28.1",
   "pytest==8.3.5",
   "pytest-cov==6.0.0",
+  "ruff==0.15.9",
 ]
 
 [tool.hatch.build.targets.wheel]
@@ -44,3 +45,14 @@ exclude_lines = [
   "if TYPE_CHECKING:",
   "^ *\\.\\.\\.$",
 ]
+
+[tool.ruff]
+target-version = "py312"
+src = ["app"]
+exclude = ["app/openapi/generated"]
+
+[tool.ruff.lint]
+select = ["I"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["app"]

apps/web/package.json

@@ -6,6 +6,7 @@
     "build": "node -e \"console.log('web: build placeholder')\"",
     "dev": "node -e \"console.log('web: dev placeholder')\"",
     "lint": "node -e \"console.log('web: lint placeholder')\"",
+    "lint:fix": "node -e \"console.log('web: lint:fix placeholder')\"",
     "openapi:generate": "node -e \"console.log('web: openapi:generate placeholder')\"",
     "openapi:validate": "node -e \"console.log('web: openapi:validate placeholder')\"",
     "test": "node -e \"console.log('web: test placeholder')\""

package.json

@@ -11,6 +11,7 @@
     "build": "turbo run build",
     "dev": "turbo run dev",
     "lint": "turbo run lint",
+    "lint:fix": "turbo run lint:fix",
     "openapi:generate": "turbo run openapi:generate",
     "openapi:validate": "turbo run openapi:validate",
     "test": "turbo run test"