feat(openapi): auto-generate spec from Drizzle schema with CI drift check (#203)

The hand-written public/openapi.json (last touched 2026-04-23) had drifted
badly from reality — e.g. Utility documented 14 fields while the DB table
and API returned all 43. Multiple endpoint families shipped since then
(substations, transmission-lines, power-plants/substations,
pricing-nodes/versions, programs/versions, territories/lookup, changelog)
weren't in the spec at all.

Before vs after field counts (public schema objects):
  Utility              14 → 37
  PowerPlant            9 → 31
  EvStation            11 → 26
  Program               7 → 31
  PricingNode           5 → 17
  BalancingAuthority    4 → 17
  Iso                   5 → 14
  Rto                   4 → 14
  Region                4 → 14
  Substation            — → 22
  TransmissionLine      — → 18
  Territory             5 →  9

Approach:
- scripts/generate-openapi.ts walks every Drizzle table via getTableColumns
  and maps PG column types → OpenAPI 3.1 schemas. Internal fields
  (submittedBy, reviewedAt, reviewedBy, lockedStatus, searchVector,
  notionPageId, geography/geometry) are stripped by default. jsonb columns
  with known shape get per-field overrides.
- scripts/openapi/endpoints.ts is the canonical per-endpoint registry.
  Query params mirror the actual Zod schemas / URL parsing in
  app/api/v1/**. Auth-required/internal endpoints (mod/*, developer/*,
  contributions, discussions, follows, notifications, me, editable-fields,
  webhooks, revalidate, health, tiles) are intentionally excluded.
- scripts/openapi/base.ts preserves the previous info/servers/tags and
  shared components (ErrorResponse, PaginatedMeta, SearchResults) plus
  adds ChangelogResponse, EntityVersion, GeoJsonFeature.

New endpoints now documented:
  /substations, /substations/{slug}, /substations/{slug}/transmission-lines
  /power-plants/{slug}/substations
  /pricing-nodes/{slug}/versions, /programs/{slug}/versions
  /territories/lookup
  /changelog

npm scripts:
  npm run openapi          # regenerate public/openapi.json
  npm run openapi:check    # exit 1 on drift, used by CI

CI: new 'openapi' job runs openapi:check on every PR; drift fails the build.

Fixes ALL-728

Co-authored-by: texture-coding-agent <[email protected]>

Author: texture-fleet-agent[bot]

.github/workflows/ci.yml

@@ -28,6 +28,17 @@ jobs:
       - run: npm install
       - run: npm test
 
+  openapi:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+      - run: npm install
+      - run: npm run openapi:check
+
   build:
     runs-on: ubuntu-latest
     needs: [lint, test]

package.json

@@ -19,6 +19,8 @@
     "sync:pricing-nodes": "tsx scripts/sync-pricing-nodes.ts",
     "sync:substations": "tsx scripts/sync-substations.ts",
     "generate:changelog": "npx tsx scripts/generate-changelog.ts",
+    "openapi": "tsx scripts/generate-openapi.ts",
+    "openapi:check": "tsx scripts/generate-openapi.ts --check",
     "sync:all": "npx tsx scripts/sync-all.ts",
     "seed": "tsx scripts/seed-database.ts",
     "test:api": "tsx scripts/test-api-endpoints.ts"