ci: regenerate from the committed spec so the drift check is hermetic

Author: ph33nx

.github/workflows/ci.yml

@@ -15,11 +15,16 @@ jobs:
       - uses: oven-sh/setup-bun@v2
       - run: bun install --frozen-lockfile
 
-      - name: Verify OpenAPI spec is in sync with live API
+      # Hermetic: regenerates from the committed spec, so this verifies that the committed
+      # generated types still reproduce from it, with no network dependency. Refreshing the
+      # spec itself is the release workflow's job.
+      - name: Verify generated types match the committed OpenAPI spec
+        env:
+          ROXYAPI_SPEC_FILE: specs/openapi.json
         run: |
           bun run generate
           git diff --exit-code -- specs/openapi.json packages/ui/src/types/ \
-            || { echo "::error::OpenAPI spec or generated types are stale. Run 'bun run generate' locally and commit."; exit 1; }
+            || { echo "::error::Generated types are stale. Run 'bun run generate' locally and commit."; exit 1; }
 
       - run: bun run check
       - name: No stray backticks inside css`` templates

lefthook.yml

@@ -51,11 +51,15 @@ pre-commit:
 pre-push:
   parallel: false
   commands:
+    # Hermetic: regenerates from the committed spec, so this verifies the committed types still
+    # reproduce from it, with no network dependency. Refreshing the spec is the release job.
     spec-drift:
+      env:
+        ROXYAPI_SPEC_FILE: specs/openapi.json
       run: |
         bun run generate
         git diff --exit-code -- specs/openapi.json packages/ui/src/types/ \
-          || { echo "specs/openapi.json or generated types drifted from live spec. Run 'bun run generate' and commit."; exit 1; }
+          || { echo "Generated types drifted from the committed spec. Run 'bun run generate' and commit."; exit 1; }
       priority: 1
     typecheck:
       run: bun run typecheck

scripts/generate.ts

@@ -11,23 +11,38 @@ const SPEC_URL =
 	process.env.ROXY_OPENAPI_URL ?? 'https://roxyapi.com/api/v2/openapi.json';
 const SPEC_PATH = 'specs/openapi.json';
 
-console.log(`Fetching OpenAPI spec from ${SPEC_URL}`);
+/**
+ * Path to read the spec from instead of fetching it.
+ *
+ * @remarks
+ * Keeps generation offline and byte-reproducible, which is what the codegen drift check in CI
+ * relies on. Distinct from `ROXY_OPENAPI_URL`, which only points the fetch at a different server.
+ */
+const SPEC_FILE = process.env.ROXYAPI_SPEC_FILE;
 
 let spec: unknown;
-try {
-	const res = await fetch(SPEC_URL, {
-		headers: { 'Cache-Control': 'no-cache' },
-	});
-	if (!res.ok) throw new Error(`HTTP ${res.status} ${res.statusText}`);
-	spec = await res.json();
-} catch (err) {
-	if (existsSync(SPEC_PATH)) {
-		console.warn(
-			`! Live spec fetch failed (${err instanceof Error ? err.message : String(err)}). Using cached ${SPEC_PATH}.`,
-		);
-		spec = JSON.parse(await Bun.file(SPEC_PATH).text());
-	} else {
-		throw err;
+if (SPEC_FILE) {
+	console.log(
+		`Reading OpenAPI spec from ${SPEC_FILE} (offline, ROXYAPI_SPEC_FILE)`,
+	);
+	spec = JSON.parse(await Bun.file(SPEC_FILE).text());
+} else {
+	console.log(`Fetching OpenAPI spec from ${SPEC_URL}`);
+	try {
+		const res = await fetch(SPEC_URL, {
+			headers: { 'Cache-Control': 'no-cache' },
+		});
+		if (!res.ok) throw new Error(`HTTP ${res.status} ${res.statusText}`);
+		spec = await res.json();
+	} catch (err) {
+		if (existsSync(SPEC_PATH)) {
+			console.warn(
+				`! Live spec fetch failed (${err instanceof Error ? err.message : String(err)}). Using cached ${SPEC_PATH}.`,
+			);
+			spec = JSON.parse(await Bun.file(SPEC_PATH).text());
+		} else {
+			throw err;
+		}
 	}
 }