feat: Enforce OpenAPI artifact drift checks for every route (Closes #…

[Killerjunior]

Summary

Closes #938

This PR implements comprehensive and deterministic OpenAPI artifact drift checks across every route in predictify-backend. It expands the OpenAPI registry definitions to achieve 100% route parity with Express route handlers, updates scripts/check-openapi.ts to perform multi-stage verification (structure, route coverage, artifact drift with line ending normalization, and route contract invariants), updates openapi.yaml, and introduces exhaustive automated tests in tests/openapi.drift.test.ts.

---

Key Changes

1. OpenAPI Route Registry Parity (src/openapi/registry.ts):

   • Registered all route endpoints mounted across the application with complete request/response schemas, path/query parameters, and error responses.
   • Enforced security requirements (bearerAuth) for protected endpoints and documented standard auth failure codes (401/403).
   • Added 400 validation error envelopes for paginated endpoints (cursor/limit).
   • Aligned prediction listing schemas (data, nextCursor) and documented OpenAPI components.

2. Automated Drift & Invariant Checks (scripts/check-openapi.ts):

   • validateStructure: Validates OpenAPI 3.1.0 document integrity, info metadata, and paths object.
   • validateRouteCoverage: Enforces bidirectional 1:1 route parity between EXPECTED_ROUTES and the generated specification, catching missing or undocumented routes.
   • validateArtifactDrift: Verifies byte-for-byte reproducibility of openapi.yaml with CRLF/LF line-ending normalization.
   • validateRouteInvariants: Enforces contract rules across all operations:
     • Non-empty and unique operationId across the entire specification.
     • Defined tags and summary/description.
     • Defined 2xx / 304 success responses.
     • Protected routes with bearerAuth document 401 or 403 error responses.
     • Path parameter parity between URL template {param} and declared in: "path" parameters.
     • Paginated endpoints document 400 validation errors.

3. Metrics & Route Fixes (src/metrics/registry.ts, src/routes/predictions.ts):

   • Exported prediction metrics (predictionsListTotal, predictionExplainTotal, predictionsRequestDuration).
   • Unauthenticated educational endpoint GET /api/predictions/:id/explain moved before requireAuth guard with UUID route parameter validation and ETag caching.

4. Automated Drift Test Suite (tests/openapi.drift.test.ts):

   • Added unit tests covering structure validation, route coverage, artifact drift detection, and contract invariant checks (missing/duplicate operationId, missing tags, missing auth errors, missing path params, and paginated validation).

---

Acceptance Criteria Mapping

Acceptance Criteria	Implementation / Evidence
Deterministic behavior for inputs & routes	Bidirectional mapping between EXPECTED_ROUTES and OpenAPI registry ensures no missing or extra routes.
Auth, validation, & invariants enforced	Invariant check validates bearerAuth -> 401/403, path parameters parity, and paginated 400 responses across all operations.
Artifact reproducibility & CI checks	npm run openapi:generate and npm run openapi:check run deterministically in CI with zero drift.
Focused test coverage	tests/openapi.drift.test.ts and tests/openapi*.test.ts cover success, rejection, missing route, and stale artifact scenarios.
Backward compatibility	Preserves all existing route paths and request/response contracts.

---

Validation Commands

# 1. Generate OpenAPI spec
npm run openapi:generate

# 2. Run OpenAPI drift and contract invariant checks
npm run openapi:check

# 3. Run OpenAPI unit & drift tests
npx jest tests/openapi.drift.test.ts tests/openapi.test.ts tests/openapi*.test.ts

[drips-wave]

@Killerjunior Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits