@canonical/pragma-cli 0.34.0 → 0.36.0

package/src/testing/perf/codegen.test.ts

@@ -0,0 +1,126 @@
+/**
+ * Unit pins for the committed-codegen CHECK seam (`scripts/codegen.ts`) —
+ * the mechanism behind two loop MAJORs: a gate's build must COMPARE the
+ * committed generated module and fail on staleness instead of silently
+ * repairing it before the PROTECTED drift guard (create.test.ts's
+ * projection-fidelity cell) reads it. The generator cell drives the EXPORTED
+ * generator with an injected `out` in a tmpdir — no spawn, no build, no repo
+ * write. The wiring cells pin the two halves the
+ * seam is made of and the fact that they MEET: the flag's VALUE (the
+ * exported GATE_BUILD_ENV) and its READER (the exported
+ * checkModeFromEnv). They do NOT pin the two CALL SITES — the gate
+ * spawn's `...GATE_BUILD_ENV` spread (perf/globalSetup.ts) and
+ * build.ts's `checkModeFromEnv(process.env)` read — which stay pinned by
+ * CONSTRUCTION: scripts/build.ts is executed by no test at all, and
+ * dropping the spread leaves every cell here green. A refactor that
+ * severs either call site still reverts gate builds to write mode
+ * silently; only a VALUE or READER change reddens.
+ */
+
+import {
+  copyFileSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  checkModeFromEnv,
+  generateCreateSurface,
+} from "../../../scripts/codegen.js";
+import { GATE_BUILD_ENV } from "./globalSetup.js";
+
+const SURFACE_COMMITTED = fileURLToPath(
+  new URL(
+    "../../capabilities/create/createSurface.generated.ts",
+    import.meta.url,
+  ),
+);
+describe("the committed-codegen CHECK seam (scripts/codegen.ts)", () => {
+  let surfaceOut: string;
+  let dir: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "codegen-check-"));
+    surfaceOut = join(dir, "createSurface.generated.ts");
+    copyFileSync(SURFACE_COMMITTED, surfaceOut);
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+    vi.restoreAllMocks();
+  });
+
+  it("check mode over the committed bytes: green, nothing written, ZERO notices — the healthy-tree gate", () => {
+    // Seeded with the bytes git holds, check mode must compute NO change (this
+    // is also the healthy gate build's determinism: a fresh render equals the
+    // committed bytes), must never write — and must log NOTHING. The
+    // zero-notices half is what separates "byte-identical" from "tolerated".
+    const before = readFileSync(surfaceOut, "utf-8");
+    const log = vi.spyOn(console, "log").mockImplementation(() => {});
+    const surface = generateCreateSurface({ check: true, out: surfaceOut });
+    expect(surface.changed).toBe(false);
+    expect(surface.surfaced).toBeGreaterThan(0);
+    expect(log).not.toHaveBeenCalled();
+    expect(readFileSync(surfaceOut, "utf-8")).toBe(before);
+  });
+
+  it("check mode over STALE bytes: throws naming the module — and never repairs it", () => {
+    // The other arm of the seam — the one the gate exists for. Seed bytes
+    // that differ from a fresh render; check mode must FAIL loudly (naming
+    // the committed module and the repair) and must leave the seeded bytes
+    // untouched: a check that silently rewrote them would green the stale
+    // tree before the PROTECTED drift guard reads it.
+    const stale = "// stale committed projection\n";
+    writeFileSync(surfaceOut, stale);
+    expect(() =>
+      generateCreateSurface({ check: true, out: surfaceOut }),
+    ).toThrowError(/createSurface\.generated\.ts is STALE[\s\S]*bun run build/);
+    expect(readFileSync(surfaceOut, "utf-8")).toBe(stale);
+  });
+
+  it("write mode over STALE bytes repairs them to the committed render", () => {
+    // The developer path `bun run build` takes: the same seeded staleness,
+    // check off — the module is rewritten to exactly the bytes a fresh
+    // render produces (the committed generation this suite copied in).
+    const committed = readFileSync(SURFACE_COMMITTED, "utf-8");
+    writeFileSync(surfaceOut, "// stale committed projection\n");
+    const result = generateCreateSurface({ check: false, out: surfaceOut });
+    expect(result.changed).toBe(true);
+    expect(readFileSync(surfaceOut, "utf-8")).toBe(committed);
+  });
+});
+
+describe("the CHECK seam's wiring (GATE_BUILD_ENV → checkModeFromEnv)", () => {
+  it("checkModeFromEnv: exactly the documented flag value flips a build into the gate's check", () => {
+    // The READ side of the seam, pinned: build.ts consumes this one-liner
+    // over its process.env, so a build enters check mode exactly when the
+    // flag is the string "1" — an ordinary developer env (no flag) and a
+    // flag EXPLICITLY set to any other value both stay in write mode,
+    // where `bun run build` repairs the committed artifacts. The
+    // third case is what makes "exactly" true: a predicate that merely
+    // tested for the key's presence, or accepted "0" as well, would pass
+    // the first two.
+    expect(checkModeFromEnv({ PRAGMA_BUILD_SKIP_DOCS: "1" })).toBe(true);
+    expect(checkModeFromEnv({})).toBe(false);
+    expect(checkModeFromEnv({ PRAGMA_BUILD_SKIP_DOCS: "0" })).toBe(false);
+  });
+
+  it("GATE_BUILD_ENV carries the check-mode flag — the gate spawn's env enters check mode", () => {
+    // The SET side of the seam, pinned against the read side: the exported
+    // constant IS the object the gate spawn spreads into its child env
+    // (perf/globalSetup.ts), and feeding it to checkModeFromEnv proves the
+    // VALUE and the READER meet — changing the flag's value, or renaming
+    // the key on either side, reddens here. What this cell does NOT see is
+    // the spawn's `...GATE_BUILD_ENV` spread itself: dropping that leaves
+    // every cell in this file green while gate builds silently revert to
+    // write mode (repairing the stale committed tree every drift guard
+    // exists to catch), so the call site stays pinned by construction.
+    expect(GATE_BUILD_ENV.PRAGMA_BUILD_SKIP_DOCS).toBe("1");
+    expect(checkModeFromEnv(GATE_BUILD_ENV)).toBe(true);
+  });
+});

package/src/testing/perf/globalSetup.test.ts

@@ -0,0 +1,286 @@
+/**
+ * Unit pins for the gate's per-root build-or-destroy wrapper — the loop's
+ * one confirmed false-green producer (round 12), previously guarded by
+ * nothing: a dropped rmSync (restoring the false green) or a restored
+ * destroy-on-spawn-error (deleting a good dist the builder never touched)
+ * stayed invisible to every suite until a real CI build failed. Drives the
+ * EXPORTED wrapper in a tmpdir with an injected runner — no real builds,
+ * no subprocesses. TWIN: cli/summon's globalSetup.test.ts pins the sibling
+ * copy the same way.
+ */
+
+import { spawn } from "node:child_process";
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  utimesSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { buildDistOrDestroy, TEMPLATE_COPIER } from "./globalSetup.js";
+
+describe("buildDistOrDestroy — the per-root build-or-destroy wrapper", () => {
+  let root: string;
+  let artifact: string;
+  // The wrapper judges freshness only UNDER the lock; always-stale makes
+  // every cell take the build path.
+  const stale = (): boolean => false;
+
+  beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), "gate-wrapper-"));
+    mkdirSync(join(root, "dist", "esm"), { recursive: true });
+    artifact = join(root, "dist", "esm", "index.js");
+  });
+
+  afterEach(() => {
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it("a build that RAN and failed destroys the artifact it emitted — the round-12 rule", () => {
+    expect(() =>
+      buildDistOrDestroy(root, artifact, stale, () => {
+        // tsc's failure shape: EMIT the served entry, then exit nonzero
+        // (nothing sets noEmitOnError).
+        writeFileSync(artifact, "// compiled from erroring sources\n");
+        return { status: 2, signal: null, stdout: "out", stderr: "err" };
+      }),
+    ).toThrowError(`perf globalSetup: failed to build ${root}'s dist:\nouterr`);
+    // The destroy: a fresh-looking dist compiled from erroring sources
+    // must read STALE to the contender's re-stat and every later run.
+    expect(existsSync(artifact)).toBe(false);
+    expect(existsSync(join(root, ".dist-build.lock"))).toBe(false);
+  });
+
+  it("a builder that never STARTED preserves the previous good artifact and names the spawn error", () => {
+    writeFileSync(artifact, "// previous good generation\n");
+    expect(() =>
+      buildDistOrDestroy(root, artifact, stale, () => ({
+        // spawnSync's spawn-failure shape with NO child (ENOENT/EACCES):
+        // status unset, signal null (no child was ever killed), both
+        // streams null, the reason ONLY in `error`. NOT the only
+        // `error`-carrying shape — spawnSync's own kills of a RUNNING
+        // child set `error` too, WITH a signal (the cell below).
+        status: undefined,
+        signal: null,
+        stdout: null,
+        stderr: null,
+        error: new Error("spawn bun ENOENT"),
+      })),
+    ).toThrowError(
+      `perf globalSetup: failed to RUN the build for ${root}: spawn bun ENOENT`,
+    );
+    // No child ever ran, so nothing was emitted: the dist on disk is
+    // still the previous good generation — pre-fix this was destroyed
+    // and the message interpolated the null streams as `nullnull`.
+    expect(readFileSync(artifact, "utf-8")).toBe(
+      "// previous good generation\n",
+    );
+    expect(existsSync(join(root, ".dist-build.lock"))).toBe(false);
+  });
+
+  it("a build KILLED mid-run destroys what it emitted — `error` alone is not `never started`", () => {
+    expect(() =>
+      buildDistOrDestroy(root, artifact, stale, () => {
+        // spawnSync's OWN kill of a running child (ENOBUFS at a
+        // maxBuffer cap, or a timeout): the child RAN, emitted the
+        // entry, and was then SIGTERMed — `status` null, `signal` set,
+        // `error` set, a stream captured. Pre-fix the error-first
+        // branch read this as "never started" and PRESERVED the
+        // poisoned dist, which the next run's stats blessed FRESH: the
+        // round-12 false green, reintroduced.
+        writeFileSync(artifact, "// compiled from erroring sources\n");
+        return {
+          status: null,
+          signal: "SIGTERM",
+          stdout: "1 MiB of diagnostics…",
+          stderr: "",
+          error: new Error("spawnSync bun ENOBUFS"),
+        };
+      }),
+    ).toThrowError(
+      `perf globalSetup: failed to build ${root}'s dist: ` +
+        "(killed mid-run: spawnSync bun ENOBUFS)\n1 MiB of diagnostics…",
+    );
+    // The destroy: the poisoned emit must read STALE to every later run.
+    expect(existsSync(artifact)).toBe(false);
+    expect(existsSync(join(root, ".dist-build.lock"))).toBe(false);
+  });
+
+  it("success leaves the artifact as built — no destroy, no lock residue", () => {
+    buildDistOrDestroy(root, artifact, stale, () => {
+      writeFileSync(artifact, "// good generation\n");
+      return { status: 0, signal: null, stdout: "", stderr: "" };
+    });
+    expect(readFileSync(artifact, "utf-8")).toBe("// good generation\n");
+    expect(existsSync(join(root, ".dist-build.lock"))).toBe(false);
+  });
+
+  it("a FRESH root's lock cycle never invokes the runner and never moves the artifact's parent-dir mtime chain", () => {
+    writeFileSync(artifact, "// previous good generation\n");
+    // Pin the watched dirs to a past instant: any directory mutation inside
+    // them — e.g. a lockfile created and unlinked beside the artifact, the
+    // round-14 regression that marked `dist/pragma` stale on EVERY run —
+    // moves them to NOW and fails the equality below. The lock must live at
+    // the ROOT, whose own mtime no freshness rule reads.
+    const watched = [join(root, "dist"), join(root, "dist", "esm")];
+    const past = new Date(Date.now() - 60_000);
+    for (const dir of watched) {
+      utimesSync(dir, past, past);
+    }
+    const before = watched.map((dir) => statSync(dir).mtimeMs);
+    let invoked = false;
+    buildDistOrDestroy(
+      root,
+      artifact,
+      () => true,
+      () => {
+        invoked = true;
+        return { status: 0, signal: null, stdout: "", stderr: "" };
+      },
+    );
+    expect(invoked).toBe(false);
+    expect(watched.map((dir) => statSync(dir).mtimeMs)).toEqual(before);
+    expect(existsSync(join(root, ".dist-build.lock"))).toBe(false);
+  });
+});
+
+describe("buildUnderLock contention — a waiter blocks, then re-acquires and re-stats under the lock", () => {
+  let root: string;
+  let artifact: string;
+  let lockPath: string;
+
+  beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), "gate-contention-"));
+    mkdirSync(join(root, "dist", "esm"), { recursive: true });
+    artifact = join(root, "dist", "esm", "index.js");
+    lockPath = join(root, ".dist-build.lock");
+  });
+
+  afterEach(() => {
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+  it("a contender waits out a held lock and blesses the holder's emit without building — never statting lock-free", async () => {
+    // The EEXIST wait path, driven for real across processes: the parent
+    // plays the HOLDER (lockfile on disk, build in flight), a bun child
+    // plays the CONTENDER — buildDistOrDestroy with an isFresh that stats
+    // the artifact and a runner that would drop a marker file. The child
+    // must neither build while the lock is held (no concurrent double
+    // build) nor build after release (the holder's emit re-stats FRESH) —
+    // the marker never appears. The isFresh is also an OWNERSHIP sentinel:
+    // it drops `violation` whenever it runs while the lockfile is absent or
+    // carries another pid. Freshness observed without holding the lock is
+    // exactly the waiter fast path this pins against — after `existsSync`
+    // saw no lock, a new holder could acquire and begin an in-place rebuild
+    // whose mid-flight mtimes the lock-free stat blessed — so the sentinel
+    // fires deterministically on release under that shape, where the torn
+    // artifact itself only appears when the third process wins a race.
+    const marker = join(root, "contender-built");
+    const ready = join(root, "contender-ready");
+    const violation = join(root, "contender-statted-lock-free");
+    const driver = join(root, "driver.ts");
+    const setupModule = fileURLToPath(
+      new URL("./globalSetup.ts", import.meta.url),
+    );
+    writeFileSync(
+      driver,
+      [
+        `import { existsSync, readFileSync, writeFileSync } from "node:fs";`,
+        `import { buildDistOrDestroy } from ${JSON.stringify(setupModule)};`,
+        `const [root, artifact, marker, ready, lockPath, violation] = process.argv.slice(2) as [string, string, string, string, string, string];`,
+        `writeFileSync(ready, "");`,
+        `const isFresh = () => {`,
+        `  let owned = false;`,
+        `  try {`,
+        `    owned = readFileSync(lockPath, "utf-8") === \`\${process.pid}\\n\`;`,
+        `  } catch {}`,
+        `  if (!owned) writeFileSync(violation, "");`,
+        `  return existsSync(artifact);`,
+        `};`,
+        `buildDistOrDestroy(root, artifact, isFresh, () => {`,
+        `  writeFileSync(marker, "// built by the contender\\n");`,
+        `  return { status: 0, signal: null, stdout: "", stderr: "" };`,
+        `});`,
+      ].join("\n"),
+    );
+
+    // The holder's lock is on disk BEFORE the contender starts.
+    writeFileSync(lockPath, "424242\n");
+    const child = spawn(
+      "bun",
+      [driver, root, artifact, marker, ready, lockPath, violation],
+      {
+        stdio: ["ignore", "pipe", "pipe"],
+      },
+    );
+    let stderr = "";
+    child.stderr.on("data", (chunk: Buffer) => {
+      stderr += chunk.toString();
+    });
+    const exited = new Promise<number | null>((resolve) => {
+      child.on("close", (code) => resolve(code));
+    });
+    let exitCode: number | null | undefined;
+    void exited.then((code) => {
+      exitCode = code;
+    });
+
+    try {
+      // Wait for the contender to reach the lock loop (bailing out early —
+      // with its stderr — if it dies instead)…
+      const deadline = Date.now() + 15_000;
+      while (
+        !existsSync(ready) &&
+        exitCode === undefined &&
+        Date.now() < deadline
+      ) {
+        await sleep(20);
+      }
+      expect(existsSync(ready), `contender exited ${exitCode}: ${stderr}`).toBe(
+        true,
+      );
+
+      // …then hold the lock across several poll intervals (LOCK_POLL_MS is
+      // 200): the contender must still be waiting — alive, no marker, no
+      // concurrent build.
+      await sleep(700);
+      expect(exitCode).toBeUndefined();
+      expect(existsSync(marker)).toBe(false);
+
+      // The holder finishes: emit lands, lock clears. The contender must
+      // loop back, take the lock for ITSELF, and only then re-stat — the
+      // sentinel proves every isFresh ran under its own lock — blessing
+      // the emit and returning WITHOUT running its own build.
+      writeFileSync(artifact, "// the holder's emit\n");
+      rmSync(lockPath);
+      expect(await exited).toBe(0);
+      expect(existsSync(marker)).toBe(false);
+      expect(existsSync(violation)).toBe(false);
+      expect(readFileSync(artifact, "utf-8")).toBe("// the holder's emit\n");
+      expect(stderr).toBe("");
+    } finally {
+      child.kill("SIGKILL");
+    }
+  }, 30_000);
+});
+
+describe("TEMPLATE_COPIER — the watched repo-root constant", () => {
+  it("resolves to a real file — a dangling constant would stat 0 and silently un-watch the copier", () => {
+    // The gate's isFresh uses `newestMtime(TEMPLATE_COPIER) < built`, and
+    // newestMtime returns 0 for a missing path — always true against an
+    // existing artifact, i.e. the clause becomes a NO-OP with no red cell.
+    // The module also throws at load when the path is missing; this pin
+    // fails the suite loudly at the moment a relocation (PRA-138) orphans
+    // the constant instead of quietly returning to the round-15 F8 hole.
+    expect(existsSync(TEMPLATE_COPIER)).toBe(true);
+  });
+});