⚡ Project management that doesn't become the project. Boards, Gantt charts, and GitHub integration. Self-host it or use Kaneo Cloud.
TypeScript honoissue-managementissue-trackerjira-alternativekanbanlinear-alternativemcpproject-managementreactself-hostedtypescript
ci: fail when the API reference drifts from the routes
Andrej Acevski7f294b05eea7
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 9fd2fbb7c..c3c9f7668 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -62,6 +62,31 @@ jobs:- name: Check locale files against en-USrun: pnpm i18n:check+ openapi:+ runs-on: ubuntu-24.04+ steps:+ - name: Checkout repository+ uses: actions/[email protected]+ with:+ persist-credentials: false++ - name: Setup pnpm+ uses: pnpm/action-setup@v6+ with:+ version: 10.32.1++ - name: Setup Node.js+ uses: actions/setup-node@v7+ with:+ node-version: 24.19.0+ cache: pnpm++ - name: Install dependencies+ run: pnpm install --frozen-lockfile++ - name: Check the API reference against the routes+ run: pnpm openapi:check+typecheck:runs-on: ubuntu-24.04steps:diff --git a/AGENTS.md b/AGENTS.mdindex 415bcd4f3..a0ccf325b 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -61,6 +61,7 @@ Not every change touches every surface. Make the decision deliberately rather th- Use the client from `@kaneo/libs`; do not create a parallel untyped request layer.- Define database schema in `apps/api/src/database/schema.ts` and relations in `apps/api/src/database/relations.ts`.- Generate migrations with `pnpm --filter @kaneo/api db:generate`, inspect the SQL, and include it with the schema change.+- `apps/docs/openapi.json` is a committed artifact that the docs site serves. Regenerate it with `pnpm openapi:check:fix` whenever a route, request schema, or response schema changes; CI fails when it drifts.- Prefer inferred TypeScript types and `type` over `interface` unless extension or declaration merging is required.- Comments should explain constraints or surprising decisions, not narrate code.diff --git a/apps/api/scripts/export-openapi.ts b/apps/api/scripts/export-openapi.tsindex 82b5c3e67..71bfe929e 100644--- a/apps/api/scripts/export-openapi.ts+++ b/apps/api/scripts/export-openapi.ts@@ -10,5 +10,8 @@ if (!response.ok) {}const spec = await response.json();-const outputPath = resolve(import.meta.dirname, "../../docs/openapi.json");+// Defaults to the file the docs site reads; the drift check passes a temp path.+const outputPath = process.argv[2]+ ? resolve(process.argv[2])+ : resolve(import.meta.dirname, "../../docs/openapi.json");await writeFile(outputPath, `${JSON.stringify(spec, null, 2)}\n`);diff --git a/package.json b/package.jsonindex 9b612efc6..a75dc9bf2 100644--- a/package.json+++ b/package.json@@ -7,6 +7,8 @@"dev": "turbo dev","i18n:check": "node ./scripts/i18n/check.mjs","i18n:check:fix": "node ./scripts/i18n/check.mjs --fix",+ "openapi:check": "node ./scripts/openapi/check.mjs",+ "openapi:check:fix": "node ./scripts/openapi/check.mjs --fix","i18n:report": "node ./scripts/i18n/report.mjs","i18n:report:fix": "node ./scripts/i18n/report.mjs --fix","i18n:schema": "node ./scripts/i18n/schema.mjs && biome format --write i18n/schema.json",diff --git a/scripts/openapi/check.mjs b/scripts/openapi/check.mjsnew file mode 100644index 000000000..e27d63834--- /dev/null+++ b/scripts/openapi/check.mjs@@ -0,0 +1,50 @@+#!/usr/bin/env node+// apps/docs/openapi.json is a committed artifact that Mintlify serves as the API+// reference, so it only stays truthful if something regenerates it. This fails+// when the committed document no longer matches what the routes produce.+import { execFileSync } from "node:child_process";+import { copyFileSync, mkdtempSync, readFileSync, rmSync } from "node:fs";+import { tmpdir } from "node:os";+import { join, resolve } from "node:path";++const COMMITTED = resolve("apps/docs/openapi.json");+const FIX = process.argv.includes("--fix");++const workdir = mkdtempSync(join(tmpdir(), "kaneo-openapi-"));+const generated = join(workdir, "openapi.json");++try {+ execFileSync(+ "pnpm",+ [+ "--filter",+ "@kaneo/api",+ "exec",+ "tsx",+ "scripts/export-openapi.ts",+ generated,+ ],+ { stdio: ["ignore", "ignore", "inherit"] },+ );++ if (readFileSync(COMMITTED, "utf8") === readFileSync(generated, "utf8")) {+ console.log("apps/docs/openapi.json is up to date");+ process.exit(0);+ }++ if (FIX) {+ copyFileSync(generated, COMMITTED);+ console.log("apps/docs/openapi.json regenerated");+ process.exit(0);+ }++ console.error(+ "apps/docs/openapi.json is out of date with the API routes.\n" ++ "The docs site serves this file, so it has to be regenerated and committed\n" ++ "whenever a route, request schema, or response schema changes.\n\n" ++ " pnpm openapi:check:fix\n",+ );+ process.exit(1);+} finally {+ rmSync(workdir, { recursive: true, force: true });+}