test(scripts): add direct unit tests for write-ui-openapi's preserveExistingObjectOrder (#7788)

preserveExistingObjectOrder() re-orders the freshly generated OpenAPI spec's keys
to match the committed file so ui:openapi:check (a hard test:ci gate) produces a
stable diff, but it had no direct test — a regression in its recursive logic would
either spuriously fail ui:openapi:check on unrelated PRs or mask a genuinely stale
spec.

Export the function (and guard the script's side-effecting main behind the
standard `import.meta.url === argv[1]` check, so importing it for a unit test does
not build/read/write the spec or call process.exit — mirrors write-cloudflare-schema.ts).
Add test/unit/write-ui-openapi-script.test.ts covering a nested-object reorder,
new-only and current-only keys, an array-valued key walked positionally (incl. a
shorter current array), undefined/null/primitive leaves, and a wrong-shape current
value. Script behavior when run via tsx is unchanged (ui:openapi:check still passes).

Closes #7770

Author: xfodev

scripts/write-ui-openapi.ts

@@ -4,39 +4,15 @@ import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { buildOpenApiSpec } from "../src/openapi/spec";
 
-const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
-const target = resolve(root, "apps/loopover-ui/public/openapi.json");
-const checkOnly = process.argv.includes("--check");
-
-const spec = buildOpenApiSpec();
-spec.servers = [{ url: "https://api.loopover.ai", description: "Production" }];
-
-const current = await readFile(target, "utf8").catch(() => "");
-const currentSpec = parseCurrentSpec(current);
-const orderedSpec = currentSpec ? preserveExistingObjectOrder(spec, currentSpec) : spec;
-const next = `${JSON.stringify(orderedSpec, null, 2)}\n`;
-
-if (checkOnly) {
-  if (current !== next) {
-    console.error("apps/loopover-ui/public/openapi.json is stale; run npm run ui:openapi.");
-    process.exit(1);
-  }
-  console.log("checked apps/loopover-ui/public/openapi.json");
-} else {
-  await writeFile(target, next);
-  console.log("wrote apps/loopover-ui/public/openapi.json");
-}
-
-function parseCurrentSpec(currentText: string): Record<string, unknown> | null {
-  try {
-    return JSON.parse(currentText) as Record<string, unknown>;
-  } catch {
-    return null;
-  }
-}
-
-function preserveExistingObjectOrder<T>(next: T, current: unknown): T {
-  if (Array.isArray(next)) return next.map((item, index) => preserveExistingObjectOrder(item, Array.isArray(current) ? current[index] : undefined)) as T;
+/** Recursively re-order the keys of `next` to match `current`'s existing key order (keys only in `next` are
+ *  appended in their own order), so `ui:openapi:check` produces a stable, minimal diff. Arrays are walked
+ *  positionally; non-plain-object values (primitives, `undefined`, `null`, arrays' leaves) pass through
+ *  unchanged. Exported for direct unit testing (#7770). */
+export function preserveExistingObjectOrder<T>(next: T, current: unknown): T {
+  if (Array.isArray(next))
+    return next.map((item, index) =>
+      preserveExistingObjectOrder(item, Array.isArray(current) ? current[index] : undefined),
+    ) as T;
   if (!isPlainObject(next)) return next;
 
   const currentObject = isPlainObject(current) ? current : {};
@@ -53,3 +29,40 @@ function preserveExistingObjectOrder<T>(next: T, current: unknown): T {
 function isPlainObject(value: unknown): value is Record<string, unknown> {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
+
+function parseCurrentSpec(currentText: string): Record<string, unknown> | null {
+  try {
+    return JSON.parse(currentText) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
+
+async function main(): Promise<void> {
+  const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+  const target = resolve(root, "apps/loopover-ui/public/openapi.json");
+  const checkOnly = process.argv.includes("--check");
+
+  const spec = buildOpenApiSpec();
+  spec.servers = [{ url: "https://api.loopover.ai", description: "Production" }];
+
+  const current = await readFile(target, "utf8").catch(() => "");
+  const currentSpec = parseCurrentSpec(current);
+  const orderedSpec = currentSpec ? preserveExistingObjectOrder(spec, currentSpec) : spec;
+  const next = `${JSON.stringify(orderedSpec, null, 2)}\n`;
+
+  if (checkOnly) {
+    if (current !== next) {
+      console.error("apps/loopover-ui/public/openapi.json is stale; run npm run ui:openapi.");
+      process.exit(1);
+    }
+    console.log("checked apps/loopover-ui/public/openapi.json");
+  } else {
+    await writeFile(target, next);
+    console.log("wrote apps/loopover-ui/public/openapi.json");
+  }
+}
+
+if (process.argv[1] && import.meta.url === new URL(process.argv[1], "file://").href) {
+  await main();
+}

test/unit/write-ui-openapi-script.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it } from "vitest";
+
+import { preserveExistingObjectOrder } from "../../scripts/write-ui-openapi";
+
+// #7770: direct unit tests for the OpenAPI key-ordering helper, which only had indirect coverage before.
+describe("preserveExistingObjectOrder (#7770)", () => {
+  it("reorders a nested object's keys to match the current file's order", () => {
+    const next = { b: 1, a: { y: 2, x: 3 }, c: 4 };
+    const current = { a: { x: 0, y: 0 }, b: 0 };
+    const result = preserveExistingObjectOrder(next, current);
+    // Top level: current's a, b first; c (new-only) appended.
+    expect(Object.keys(result)).toEqual(["a", "b", "c"]);
+    // Nested object is reordered to current's x, y with next's values.
+    expect(Object.keys(result.a)).toEqual(["x", "y"]);
+    expect(result).toEqual({ a: { x: 3, y: 2 }, b: 1, c: 4 });
+  });
+
+  it("appends keys present in next but not current, in next's own order", () => {
+    const result = preserveExistingObjectOrder({ first: 1, second: 2, third: 3 }, { second: 0 });
+    expect(Object.keys(result)).toEqual(["second", "first", "third"]);
+  });
+
+  it("drops keys present in current but not in next (only next's keys survive)", () => {
+    const result = preserveExistingObjectOrder({ a: 1 }, { a: 0, removed: 0 });
+    expect(result).toEqual({ a: 1 });
+    expect("removed" in result).toBe(false);
+  });
+
+  it("walks array-valued keys positionally, aligning each item with the current array", () => {
+    const next = {
+      list: [
+        { b: 1, a: 2 },
+        { d: 3, c: 4 },
+      ],
+    };
+    // Shorter current array: index 1 has no counterpart, so it stays in next's own order.
+    const current = { list: [{ a: 0, b: 0 }] };
+    const result = preserveExistingObjectOrder(next, current);
+    expect(Object.keys(result.list[0]!)).toEqual(["a", "b"]);
+    expect(result.list[1]).toEqual({ d: 3, c: 4 });
+    expect(result.list).toHaveLength(2);
+  });
+
+  it("passes primitive, null, and undefined leaf values through unchanged", () => {
+    expect(preserveExistingObjectOrder(5, { a: 1 })).toBe(5);
+    expect(preserveExistingObjectOrder("s", undefined)).toBe("s");
+    expect(preserveExistingObjectOrder(null, { a: 1 })).toBe(null);
+    // An undefined-valued key is retained as a key (with undefined value), ordered by current.
+    const result = preserveExistingObjectOrder({ b: undefined, a: 1 }, { a: 0, b: 0 });
+    expect(Object.keys(result)).toEqual(["a", "b"]);
+    expect(result.b).toBeUndefined();
+  });
+
+  it("treats a current value of the wrong shape as empty, keeping next's own order", () => {
+    // next is an object but current is an array -> currentObject falls back to {}, so next's order wins.
+    const objVsArr = preserveExistingObjectOrder({ z: 1, a: 2 }, [1, 2, 3]);
+    expect(Object.keys(objVsArr)).toEqual(["z", "a"]);
+    // next is an array but current is an object -> each current[index] is undefined.
+    const arrVsObj = preserveExistingObjectOrder([{ b: 1, a: 2 }], { not: "an-array" });
+    expect(Object.keys(arrVsObj[0]!)).toEqual(["b", "a"]);
+  });
+});