Skip to content

armgit / kaneo

Public Imported from GitHub
0

⚡ Project management that doesn't become the project. Boards, Gantt charts, and GitHub integration. Self-host it or use Kaneo Cloud.

ci: fail when the API reference drifts from the routes

Andrej Acevski7f294b05eea7
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 9fd2fbb7c..c3c9f7668 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -62,6 +62,31 @@ jobs:
- name: Check locale files against en-US
run: 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.04
steps:
diff --git a/AGENTS.md b/AGENTS.md
index 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.ts
index 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.json
index 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.mjs
new file mode 100644
index 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 });
+}