Skip to content

Commit ff78363

Browse files
authored
ci: fail the lint job when openapi.json drifts from its JSDoc (#3040)
## Summary **Adds a CI gate so `packages/api/openapi.json` can't silently drift from the JSDoc it is generated from.** - **Problem:** the committed spec was enforced only by the husky lint-staged hook, which `--no-verify`, a hook-less clone, a bad merge resolution, or a direct hand-edit all bypass — nothing in CI noticed. - **Fix:** `scripts/ci/check-openapi-sync.sh` regenerates the spec and fails on a diff, wired into the `lint` job and `make ci-lint`; the lint-staged key now also covers `src/utils/swagger.ts`, whose `swaggerOptions` (title, `servers`, `tags`) is a spec input the hook never watched. - **Why it runs outside nx:** the api's own `ci:lint` regenerates the spec but never asserts on it — `nx affected` skips the api on PRs that don't touch it, and because `ci:lint.outputs` lists the file, a cache hit *restores* the spec rather than regenerating it. - **`.prettierignore` is part of the fix, not cleanup:** prettier reformats the spec by ~1400 lines (it collapses short arrays; the generator's `JSON.stringify` does not) and the root lint-staged JSON group matches it, so without the ignore no commit could satisfy both formatters and the gate would be permanently red. Verified by perturbing the JSDoc (gate fails, `git add` clears it), by hand-editing the spec (fails, where `nx run @hyperdx/api:ci:lint` is a cache hit that passes), and by a real `lint-staged` run on a `swagger.ts` edit. `make ci-lint` is green. ### How to test on Vercel preview N/A — non-UI change. ### References - Linear Issue: none - Related PRs: none Note for reviewers: this invalidates every nx cache entry once (`.prettierignore` and root `package.json` are both in `sharedGlobals`), so this PR's `lint` job runs cold. Recent runs are 3:25–4:21 against `timeout-minutes: 8`; if it trips the timeout it needs bumping here, since a re-run is restore-only and will still be cold.
1 parent 53336f7 commit ff78363

6 files changed

Lines changed: 55 additions & 1 deletion

File tree

‎.github/workflows/main.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,10 @@ jobs:
5959
run: node --test scripts/ci/__tests__/ratchet.test.mjs
6060
- name: Escape-hatch ratchet
6161
run: node scripts/ci/ratchet.mjs
62+
# Also unconditional: the api's own `ci:lint` regenerates the spec but
63+
# never asserts on it, and nx can skip or cache-replay that task.
64+
- name: Check openapi.json is in sync with its sources
65+
run: scripts/ci/check-openapi-sync.sh
6266
# Runs even when lint fails, so a red main still refreshes the cache that
6367
# PR runs restore from.
6468
- name: Save nx computation cache

‎.prettierignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,3 +2,7 @@
22
dist
33
coverage
44
.volumes
5+
6+
# docgen serialises with JSON.stringify; prettier would reformat ~1400 lines and
7+
# the two would fight, leaving check-openapi-sync.sh permanently red.
8+
packages/api/openapi.json

‎Makefile‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -114,6 +114,11 @@ ci-build:
114114
ci-lint:
115115
npx nx run-many -t ci:lint
116116
node scripts/ci/ratchet.mjs
117+
scripts/ci/check-openapi-sync.sh
118+
119+
.PHONY: ci-openapi
120+
ci-openapi:
121+
scripts/ci/check-openapi-sync.sh
117122

118123
.PHONY: dev-int-down
119124
dev-int-down:

‎agent_docs/architecture.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,10 @@ Key (`validateUserAccessKey` middleware), rate-limited to 100 req/min.
6868
When adding or modifying external API endpoints, run `yarn docgen` to regenerate
6969
the OpenAPI spec and `yarn lint:openapi` to validate it.
7070

71+
`scripts/ci/check-openapi-sync.sh` (run by `make ci-lint` and by CI) fails if the
72+
committed spec is stale. `swaggerOptions` in `src/utils/swagger.ts` is also an
73+
input, and the spec is in `.prettierignore` because docgen owns its formatting.
74+
7175
### MCP Server (`src/mcp/`)
7276

7377
[Model Context Protocol](https://modelcontextprotocol.io/) server that lets AI

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@
5555
"release": "npx changeset publish --no-git-tag && npx changeset tag"
5656
},
5757
"lint-staged": {
58-
"packages/api/src/routers/external-api/**/*.ts": [
58+
"packages/api/src/{routers/external-api/**/*.ts,utils/swagger.ts}": [
5959
"prettier --write --ignore-unknown",
6060
"eslint --flag v10_config_lookup_from_file --fix --quiet",
6161
"sh -c 'cd packages/api && yarn run lint:openapi && git add openapi.json'"

‎scripts/ci/check-openapi-sync.sh‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
#!/usr/bin/env bash
2+
# Fails if the committed packages/api/openapi.json differs from what its sources
3+
# generate. Runs outside nx on purpose: `ci:lint` lists openapi.json in its
4+
# `outputs`, so a cache hit restores the spec rather than regenerating it, and
5+
# `nx affected` skips the api on PRs that don't touch it.
6+
set -euo pipefail
7+
8+
cd "$(dirname "$0")/../.."
9+
10+
SPEC=packages/api/openapi.json
11+
12+
# `swaggerOptions.apis` is a cwd-relative glob; from the repo root it matches
13+
# nothing and emits an empty spec.
14+
yarn workspace @hyperdx/api docgen
15+
16+
# Against the index, not HEAD, so staging the regenerated spec counts as fixed.
17+
if git --no-pager diff --quiet -- "$SPEC"; then
18+
echo "$SPEC is in sync with its sources"
19+
exit 0
20+
fi
21+
22+
diff_output=$(git --no-pager diff -- "$SPEC")
23+
diff_lines=$(printf '%s\n' "$diff_output" | wc -l | tr -d ' ')
24+
head -n 80 <<< "$diff_output"
25+
if [ "$diff_lines" -gt 80 ]; then
26+
echo
27+
echo " ... diff truncated, $diff_lines lines total"
28+
fi
29+
echo
30+
echo "::error::$SPEC is out of date with its sources"
31+
echo "$SPEC does not match what the JSDoc in"
32+
echo "packages/api/src/routers/external-api/ and \`swaggerOptions\` in"
33+
echo "packages/api/src/utils/swagger.ts generate. It has just been regenerated"
34+
echo "in your working tree, so all that is left is to stage it:"
35+
echo
36+
echo " git add $SPEC"
37+
exit 1

0 commit comments

Comments
 (0)