fix(ci): retry cf-typegen's drift check once before reporting stale

wrangler types was observed to occasionally emit a differently-shaped
ProcessEnv union on a cold invocation (freshly restored node_modules, no
prior local wrangler state -- CI's steady state on every run) versus a
warm one, for the same wrangler.jsonc and the same wrangler version. This
is external-tool flakiness, not a defect in this script's own reformatting
logic, and it was intermittently failing CI on an otherwise-correct
committed file. One retry absorbs the transient case without masking a
real drift: a genuinely stale file mismatches on both the first attempt
and the immediately-following retry.

Author: JSONbored

scripts/gen-cf-typegen.mjs

@@ -37,20 +37,29 @@ export function formatCfTypegenOutput(source) {
   return stripped.replace(PICK_RE, `Pick<Cloudflare.Env,\n${lines}\n\t>>`);
 }
 
-export function genCfTypegen({ check = false } = {}) {
-  const target = check ? TEMP_PATH : OUTPUT_PATH;
+function generateOnce(target) {
   try {
     execFileSync("wrangler", ["types", target], { stdio: "inherit" });
-    const generated = formatCfTypegenOutput(readFileSync(target, "utf8"));
-    if (!check) {
-      writeFileSync(OUTPUT_PATH, generated);
-      return { changed: undefined };
-    }
-    const current = readFileSync(OUTPUT_PATH, "utf8");
-    return { changed: current !== generated };
+    return formatCfTypegenOutput(readFileSync(target, "utf8"));
   } finally {
-    if (check && existsSync(TEMP_PATH)) unlinkSync(TEMP_PATH);
+    if (target !== OUTPUT_PATH && existsSync(target)) unlinkSync(target);
+  }
+}
+
+export function genCfTypegen({ check = false } = {}) {
+  if (!check) {
+    writeFileSync(OUTPUT_PATH, generateOnce(OUTPUT_PATH));
+    return { changed: undefined };
   }
+  const current = readFileSync(OUTPUT_PATH, "utf8");
+  // `wrangler types` is observed to occasionally emit a differently-shaped ProcessEnv union on a "cold"
+  // invocation (freshly restored node_modules, no prior local wrangler state -- exactly CI's steady state on
+  // every run) versus a "warm" one, for the SAME wrangler.jsonc and the SAME wrangler version -- an external
+  // tool flakiness, not a defect in this repo's own reformatting logic (which is pure and independently
+  // regression-tested via a real `git merge-file`). One retry absorbs that without masking a REAL drift: a
+  // genuinely stale committed file mismatches on both the first AND the immediately-following attempt.
+  if (current === generateOnce(TEMP_PATH)) return { changed: false };
+  return { changed: current !== generateOnce(TEMP_PATH) };
 }
 
 function main(argv) {

test/unit/ci-cf-typegen.test.ts

@@ -1,9 +1,17 @@
-import { execFileSync } from "node:child_process";
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { describe, expect, it } from "vitest";
-import { formatCfTypegenOutput } from "../../scripts/gen-cf-typegen.mjs";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { formatCfTypegenOutput, genCfTypegen, OUTPUT_PATH } from "../../scripts/gen-cf-typegen.mjs";
+
+// Only the `wrangler` invocation is ever faked below (via mockImplementation in the retry tests); every other
+// call (the `git merge-file` regression tests further down) passes straight through to the real execFileSync,
+// so this mock changes nothing about those tests.
+vi.mock("node:child_process", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:child_process")>();
+  return { ...actual, execFileSync: vi.fn(actual.execFileSync) };
+});
+import { execFileSync } from "node:child_process";
 
 // #1667-followup: wrangler's own `wrangler types` output packs every declared env var into ONE long
 // single-line `Pick<Cloudflare.Env, "A" | "B" | ...>>` union. Two independent PRs that each add a DIFFERENT
@@ -105,3 +113,79 @@ describe("gen-cf-typegen: formatCfTypegenOutput", () => {
     }
   });
 });
+
+// `wrangler types` is observed to occasionally emit a differently-shaped ProcessEnv union on a "cold"
+// invocation vs a "warm" one for the SAME wrangler.jsonc and wrangler version -- external-tool flakiness, not
+// a defect in this repo's own reformatting logic. genCfTypegen's check path retries once before reporting
+// staleness, so a transient one-off mismatch self-heals instead of failing CI.
+describe("gen-cf-typegen: genCfTypegen retry behavior", () => {
+  const originalCwd = process.cwd();
+  let dir: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "cf-typegen-retry-"));
+    process.chdir(dir);
+  });
+
+  afterEach(() => {
+    process.chdir(originalCwd);
+    rmSync(dir, { recursive: true, force: true });
+    vi.mocked(execFileSync).mockClear();
+  });
+
+  function mockWrangler(outputs: string[]) {
+    let call = 0;
+    vi.mocked(execFileSync).mockImplementation(((cmd: string, args: string[]) => {
+      if (cmd !== "wrangler") throw new Error(`unexpected command: ${cmd}`);
+      const target = args[1]!;
+      const output = outputs[Math.min(call, outputs.length - 1)]!;
+      call += 1;
+      writeFileSync(target, output);
+      return Buffer.from("");
+    }) as typeof execFileSync);
+  }
+
+  it("REGRESSION: a mismatch on the first wrangler invocation self-heals when the retry matches (transient tool flakiness)", () => {
+    const committed = formatCfTypegenOutput(rawFixture(["ALPHA", "MID"]));
+    writeFileSync(OUTPUT_PATH, committed);
+    // First call emits an extra var (simulating a cold-vs-warm wrangler discrepancy); the retry matches.
+    mockWrangler([rawFixture(["ALPHA", "MID", "STRAY"]), rawFixture(["ALPHA", "MID"])]);
+
+    const { changed } = genCfTypegen({ check: true });
+
+    expect(changed).toBe(false);
+    expect(execFileSync).toHaveBeenCalledTimes(2);
+  });
+
+  it("still reports genuine drift when BOTH the first attempt and the retry mismatch the committed file", () => {
+    const committed = formatCfTypegenOutput(rawFixture(["ALPHA", "MID"]));
+    writeFileSync(OUTPUT_PATH, committed);
+    mockWrangler([rawFixture(["ALPHA", "MID", "REAL_NEW_VAR"])]);
+
+    const { changed } = genCfTypegen({ check: true });
+
+    expect(changed).toBe(true);
+    expect(execFileSync).toHaveBeenCalledTimes(2);
+  });
+
+  it("does not retry (single wrangler invocation) when the committed file is already up to date", () => {
+    const committed = formatCfTypegenOutput(rawFixture(["ALPHA", "MID"]));
+    writeFileSync(OUTPUT_PATH, committed);
+    mockWrangler([rawFixture(["ALPHA", "MID"])]);
+
+    const { changed } = genCfTypegen({ check: true });
+
+    expect(changed).toBe(false);
+    expect(execFileSync).toHaveBeenCalledTimes(1);
+  });
+
+  it("regenerate mode (check: false) writes the formatted output directly to worker-configuration.d.ts", () => {
+    mockWrangler([rawFixture(["ZEBRA", "ALPHA"])]);
+
+    const { changed } = genCfTypegen({ check: false });
+
+    expect(changed).toBeUndefined();
+    expect(readFileSync(OUTPUT_PATH, "utf8")).toBe(formatCfTypegenOutput(rawFixture(["ZEBRA", "ALPHA"])));
+    expect(execFileSync).toHaveBeenCalledTimes(1);
+  });
+});