mirror of
https://github.com/MBombeck/HealthLog.git
synced 2026-11-08 12:32:43 +00:00
Marc-André Bombeck
7bc8e572b1
The yaml@2 emitter could not stringify .meta()-tagged sub-schemas inside z.array(...) under sortMapEntries: true — alphabetic sorting moved alias references ahead of their anchor definitions, tripping verifyAliasOrder with "Unresolved alias: a1" during stringify. The fix drops sortMapEntries from both generate-openapi and check-openapi so anchors stay emitted before their aliases; output stability is preserved by upstream determinism (Zod property declaration order + single-object path table). The committed openapi.yaml is regenerated in declaration order — large diff, functionally identical. With the emitter stable, the v1.4.48 H-APNs-1 admin diagnostic endpoint now appears in docs/api/openapi.yaml alongside its component schemas: AdminDiagnosticDevice (APNs token masked to prefix + suffix), AdminDiagnosticChannel (enabled + configPresent), and AdminDiagnosticPushAttempt (reserved for the v1.4.48+ PushAttempt table).
45 lines
1.9 KiB
TypeScript
45 lines
1.9 KiB
TypeScript
#!/usr/bin/env tsx
|
|
/**
|
|
* Emit `docs/api/openapi.yaml` from the registered Zod schemas + route
|
|
* table in `src/lib/openapi/registry.ts`.
|
|
*
|
|
* v1.4.23 baseline: only the iOS-touched routes are registered (see
|
|
* `src/lib/openapi/routes.ts`). The CI step that wraps this script runs
|
|
* with `continue-on-error: true` until the registry catches up with the
|
|
* rest of the hand-maintained `docs/api/openapi.yaml` — once coverage is
|
|
* complete, the gate flips to hard-fail in v1.4.24+.
|
|
*
|
|
* The output is stable across re-runs because the upstream order is
|
|
* itself deterministic: Zod preserves schema property declaration
|
|
* order and the path table is a single object literal in
|
|
* `src/lib/openapi/routes.ts`. `yaml@2`'s `sortMapEntries` option is
|
|
* intentionally NOT set — when enabled, the emitter reorders keys
|
|
* alphabetically and can place an `*alias` reference before its
|
|
* `&anchor` definition, which triggers `verifyAliasOrder` and throws
|
|
* `Unresolved alias` during `stringify`. This started biting once
|
|
* `.meta()`-tagged sub-schemas were nested inside `z.array(...)` for
|
|
* the v1.4.48 admin diagnostic envelope: the array's element-schema
|
|
* anchor lives under `recentPushAttempts` (sorted to the bottom of
|
|
* the data object) while the alias from `notificationChannels`
|
|
* (sorted above it) refers to the same `$ref`. Leaving the source
|
|
* order intact keeps anchors emitted before their aliases.
|
|
*/
|
|
import { writeFileSync } from "node:fs";
|
|
import { resolve } from "node:path";
|
|
import { stringify } from "yaml";
|
|
import { buildOpenApiDocument } from "../src/lib/openapi/registry";
|
|
|
|
const SPEC_PATH = resolve(__dirname, "..", "docs", "api", "openapi.yaml");
|
|
|
|
function main(): void {
|
|
const document = buildOpenApiDocument();
|
|
const yaml = stringify(document, {
|
|
sortMapEntries: false,
|
|
lineWidth: 120,
|
|
});
|
|
writeFileSync(SPEC_PATH, yaml, "utf8");
|
|
console.log(`Wrote ${SPEC_PATH} (${yaml.length} bytes)`);
|
|
}
|
|
|
|
main();
|