Ensure that output JSON is deterministic

Author: m-houston

packages/excel-parser/README.md

@@ -59,6 +59,8 @@ The JSON output contains the following top-level keys:
 - `allocations` - Record of SupplierAllocation objects keyed by ID
 - `supplierPacks` - Record of SupplierPack objects keyed by ID
 
+Object keys are written in sorted order to keep generated JSON deterministic across runs.
+
 #### Parse Excel to a file-store directory
 
 When `--output-dir` is used, the parser writes one JSON file per record using the directory names expected by the file-store package:

packages/excel-parser/src/__tests__/config-store-output.test.ts

@@ -203,6 +203,21 @@ describe("writeParseResultToConfigStore", () => {
       await expect(readFile(packFile, "utf8")).resolves.toContain(
         '  "billingId": "BILL-001"',
       );
+      await expect(readFile(packFile, "utf8")).resolves.toBe(`{
+  "billingId": "BILL-001",
+  "createdAt": "2026-01-01T00:00:00.000Z",
+  "description": "Basic pack specification for local testing",
+  "id": "pack-spec-1",
+  "name": "Standard Letter Pack",
+  "postage": {
+    "deliveryDays": 2,
+    "id": "postage-standard",
+    "size": "STANDARD"
+  },
+  "status": "DRAFT",
+  "updatedAt": "2026-01-01T00:00:00.000Z",
+  "version": 1
+}\n`);
     } finally {
       await rm(outputDir, { recursive: true, force: true });
     }

packages/excel-parser/src/__tests__/json-output.test.ts

@@ -0,0 +1,97 @@
+import { stringifyJsonWithSortedKeys } from "../json-output";
+
+describe("stringifyJsonWithSortedKeys", () => {
+  it("sorts object keys recursively while preserving array order", () => {
+    const output = stringifyJsonWithSortedKeys(
+      {
+        z: {
+          d: 4,
+          a: 1,
+        },
+        a: [
+          {
+            z: 2,
+            a: 1,
+          },
+          "keep-order",
+          {
+            b: 2,
+            a: 1,
+          },
+        ],
+        m: true,
+      },
+      2,
+    );
+
+    expect(output).toBe(`{
+  "a": [
+    {
+      "a": 1,
+      "z": 2
+    },
+    "keep-order",
+    {
+      "a": 1,
+      "b": 2
+    }
+  ],
+  "m": true,
+  "z": {
+    "a": 1,
+    "d": 4
+  }
+}`);
+  });
+
+  it("produces the same output for equivalent objects with different insertion order", () => {
+    const left = {
+      variants: {
+        beta: {
+          status: "DRAFT",
+          id: "beta",
+        },
+        alpha: {
+          status: "DRAFT",
+          id: "alpha",
+        },
+      },
+      packs: {
+        packB: {
+          version: 1,
+          id: "pack-b",
+        },
+        packA: {
+          version: 1,
+          id: "pack-a",
+        },
+      },
+    };
+    const right = {
+      packs: {
+        packA: {
+          id: "pack-a",
+          version: 1,
+        },
+        packB: {
+          id: "pack-b",
+          version: 1,
+        },
+      },
+      variants: {
+        alpha: {
+          id: "alpha",
+          status: "DRAFT",
+        },
+        beta: {
+          id: "beta",
+          status: "DRAFT",
+        },
+      },
+    };
+
+    expect(stringifyJsonWithSortedKeys(left)).toBe(
+      stringifyJsonWithSortedKeys(right),
+    );
+  });
+});

packages/excel-parser/src/cli-parse.ts

@@ -4,6 +4,7 @@ import path from "node:path";
 import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
 import { writeParseResultToConfigStore } from "./config-store-output";
+import { stringifyJsonWithSortedKeys } from "./json-output";
 import { parseExcelFile } from "./parse-excel";
 
 interface Arguments {
@@ -88,9 +89,10 @@ async function main() {
     const result = parseExcelFile(resolvedInput);
 
     // Format the output
-    const jsonOutput = pretty
-      ? JSON.stringify(result, null, 2)
-      : JSON.stringify(result);
+    const jsonOutput = stringifyJsonWithSortedKeys(
+      result,
+      pretty ? 2 : undefined,
+    );
 
     if (outputDir) {
       const resolvedOutputDir = path.isAbsolute(outputDir)

packages/excel-parser/src/config-store-output.ts

@@ -1,6 +1,7 @@
 import { mkdir, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
 
+import { stringifyJsonWithSortedKeys } from "./json-output";
 import type { ParseResult } from "./parse-excel";
 
 type ConfigStoreEntityDirectory =
@@ -140,7 +141,7 @@ export async function writeParseResultToConfigStore(
         entity,
         `${encodeRecordIdForFileName(id)}.json`,
       );
-      const serialized = `${JSON.stringify(data, null, jsonSpacing)}\n`;
+      const serialized = `${stringifyJsonWithSortedKeys(data, jsonSpacing)}\n`;
 
       // eslint-disable-next-line security/detect-non-literal-fs-filename
       await writeFile(outputFile, serialized, "utf8");

packages/excel-parser/src/json-output.ts

@@ -0,0 +1,22 @@
+function sortJsonValue(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map((item) => sortJsonValue(item));
+  }
+
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value)
+        .toSorted(([left], [right]) => left.localeCompare(right))
+        .map(([key, nestedValue]) => [key, sortJsonValue(nestedValue)]),
+    );
+  }
+
+  return value;
+}
+
+export function stringifyJsonWithSortedKeys(
+  value: unknown,
+  spacing?: number,
+): string {
+  return JSON.stringify(sortJsonValue(value), null, spacing);
+}