@hasna/hooks 0.9.5 → 0.9.6

package/scripts/verify-generated-artifacts.ts

@@ -0,0 +1,237 @@
+#!/usr/bin/env bun
+/**
+ * Verify that the committed generated registry client is byte-identical to what
+ * the current source produces — and that it is a real client, not an empty file
+ * that trivially matches itself.
+ *
+ * `src/sdk/generated.ts` is committed because `package.json`'s build bundles it
+ * into the published `./sdk` export, so a drifted file ships. The repo rule is
+ * explicit (".github/workflows/ci.yml", `verify-generated` job): a member that
+ * commits generated bundles adds its own step to that job, sharing the job's
+ * bun-version pin — "a committed bundle no job regenerates is drift by
+ * construction". This is that step for hooks.
+ *
+ * THE RULES THIS HOLDS TO (mirrors apps/telephony and apps/knowledge):
+ *
+ *   1. ONE ENTRY POINT. The regeneration happens inside this script via
+ *      `package.json`'s `generate:sdk`, so it cannot be run without the
+ *      regeneration and read as a sync check, and the two can never disagree.
+ *
+ *   2. THE REGENERATION MUST BE BYTE-STABLE, NOT ONLY MATCH THE INDEX. The
+ *      generator runs TWICE; the two outputs must be byte-identical before the
+ *      index comparison means anything. A nondeterministic generator would make
+ *      the byte gate pass on one run and fail on the next with no commit in
+ *      between — the vacuous-check class wearing a green gate.
+ *
+ *   3. THE CHECK PROVES THE ARTIFACT IS REAL BEFORE TRUSTING A CLEAN RESULT. A
+ *      generator that emitted nothing would be byte-stable and match its own
+ *      empty index forever. The artifact must carry the client class and one
+ *      method per operation in the SERVED document — the exact binding
+ *      `hasna.contract.json`'s `serviceSurfaces[3].generatedFrom` claims.
+ *
+ *   4. THE PRECONDITION IS CHECKED. `git diff` after a regeneration only means
+ *      something if the file matched the index BEFORE it; a file that was
+ *      already modified proves nothing afterwards.
+ */
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, join, resolve } from "node:path";
+import { generateSdkFromOpenApi } from "@hasna/contracts/sdk";
+import { buildOpenApiDocument } from "../src/openapi.ts";
+
+const appRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+/** The one committed-and-shipped file `generate:sdk` rewrites. */
+export const GENERATED_FILE = "src/sdk/generated.ts";
+
+/** The class the manifest's `./sdk` surface advertises as generated. */
+export const GENERATED_CLASS = "HooksRegistryApiClient";
+
+function fail(message: string): never {
+  console.error(`verify-generated-artifacts: ${message}`);
+  process.exit(1);
+}
+
+function git(args: string[]): { status: number; stdout: string; stderr: string } {
+  const run = spawnSync("git", args, { cwd: appRoot, encoding: "utf8" });
+  // A spawn that never started reports status null. Treat that as failure: this
+  // whole script is a control, and a control that cannot run must not pass.
+  return { status: run.status ?? 1, stdout: run.stdout ?? "", stderr: run.stderr ?? "" };
+}
+
+function sha256Of(relativePath: string): string {
+  return createHash("sha256").update(readFileSync(join(appRoot, relativePath))).digest("hex");
+}
+
+/* ------------------------------------------------------------------ *
+ * Rule 3: prove the committed artifact is a real generated client for *
+ * the served document — before any clean result is believed.          *
+ * ------------------------------------------------------------------ */
+
+/**
+ * The operations the SERVED document declares. Derived from
+ * `buildOpenApiDocument`, the same builder src/serve.ts answers
+ * `GET /openapi.json` with, so this is the binding the contract claims.
+ */
+export function servedOperations(): string[] {
+  const spec = buildOpenApiDocument("0.0.0") as {
+    paths?: Record<string, Record<string, unknown>>;
+  };
+  const methods = ["get", "put", "post", "delete", "patch", "options", "head"];
+  const found: string[] = [];
+  for (const [path, item] of Object.entries(spec.paths ?? {})) {
+    for (const method of methods) {
+      if (item[method]) found.push(`${method.toUpperCase()} ${path}`);
+    }
+  }
+  return found.sort();
+}
+
+/** Problems with the committed artifact, or [] when it looks generated. */
+export function artifactProblems(text: string): string[] {
+  const problems: string[] = [];
+  if (!text.includes("// @generated")) {
+    problems.push(`${GENERATED_FILE} carries no "@generated" header — it is not generator output`);
+  }
+  if (!text.includes(`export class ${GENERATED_CLASS}`)) {
+    problems.push(`${GENERATED_FILE} does not declare "export class ${GENERATED_CLASS}"`);
+  }
+  return problems;
+}
+
+/**
+ * The operations the committed artifact exposes, as `METHOD path` pairs. Read
+ * from the generated `this.request("METHOD", \`path\`)` call sites so this is
+ * about what was actually emitted, not about what the spec says. Emitted path
+ * templates interpolate path params (`\${encodeURIComponent(String(name))}`);
+ * they are normalized back to the OpenAPI `{name}` form so the comparison is
+ * against the served document's spelling.
+ */
+export function artifactOperations(text: string): string[] {
+  const found: string[] = [];
+  const re = /this\.request\(\s*"([A-Z]+)",\s*`([^`]+)`/g;
+  for (const match of text.matchAll(re)) {
+    found.push(`${match[1]} ${normalizePathTemplate(match[2]!)}`);
+  }
+  return found.sort();
+}
+
+/** `\${encodeURIComponent(String(name))}` -> `{name}`. */
+export function normalizePathTemplate(path: string): string {
+  return path.replace(
+    /\$\{encodeURIComponent\(String\(([A-Za-z_$][A-Za-z0-9_$]*)\)\)\}/g,
+    "{$1}",
+  );
+}
+
+/**
+ * A served-operation extractor that can no longer find call sites reports "all
+ * covered" forever. These fixtures prove the extraction still fires, and still
+ * normalizes, before a clean result is believed. The fixture is the exact
+ * emitted shape for the parameterized artifact route.
+ */
+export const EXTRACTION_FIXTURE =
+  'return this.request("GET", `/api/v1/hooks/${encodeURIComponent(String(name))}/${encodeURIComponent(String(version))}`, {';
+export const EXTRACTION_FIXTURE_EXPECTED = "GET /api/v1/hooks/{name}/{version}";
+// Must NOT match: a bare path with no request call site is not an operation.
+export const EXTRACTION_COUNTER_FIXTURE = 'const p = "/api/v1/hooks/{name}/{version}";';
+
+/** Problems with the extraction pattern itself; [] means it is worth believing. */
+export function patternSelfCheck(): string[] {
+  const problems: string[] = [];
+  const extracted = artifactOperations(EXTRACTION_FIXTURE);
+  if (extracted.length !== 1 || extracted[0] !== EXTRACTION_FIXTURE_EXPECTED) {
+    problems.push(
+      `the operation extractor no longer reads its own fixture (got ${JSON.stringify(extracted)} for ${EXTRACTION_FIXTURE_EXPECTED}) — the coverage check below cannot detect anything`,
+    );
+  }
+  if (artifactOperations(EXTRACTION_COUNTER_FIXTURE).length !== 0) {
+    problems.push("the operation extractor matches its counter-fixture — it is too loose to be meaningful");
+  }
+  return problems;
+}
+
+/**
+ * The served operations minus the ones the artifact emitted. Empty means the
+ * committed client covers the served document exactly.
+ */
+export function missingOperations(text: string): string[] {
+  const emitted = new Set(artifactOperations(text));
+  return servedOperations().filter((op) => !emitted.has(op));
+}
+
+function main(): void {
+  const committed = readFileSync(join(appRoot, GENERATED_FILE), "utf8");
+
+  // Rule 3 first: a clean regeneration of a broken artifact must not be read
+  // as a pass, and a dead extractor must not be read as full coverage.
+  const patternProblems = patternSelfCheck();
+  const problems = [...patternProblems, ...artifactProblems(committed)];
+  const missing = missingOperations(committed);
+  if (missing.length > 0) {
+    problems.push(
+      `${GENERATED_FILE} is missing ${missing.length} operation(s) the served /openapi.json declares: ${missing.join(", ")}`,
+    );
+  }
+  if (problems.length > 0) {
+    for (const problem of problems) console.error(`verify-generated-artifacts: ${problem}`);
+    process.exit(1);
+  }
+
+  // Rule 4: the precondition for the diff gate below.
+  const dirtyBefore = git(["status", "--porcelain", "--", GENERATED_FILE]);
+  if (dirtyBefore.status !== 0) fail(`git status failed: ${dirtyBefore.stderr.trim()}`);
+  if (dirtyBefore.stdout.trim() !== "") {
+    fail(
+      `${GENERATED_FILE} is already modified before the regeneration, so this check cannot tell drift from your edits:\n` +
+        `${dirtyBefore.stdout.trimEnd()}\nCommit or restore it, then re-run.`,
+    );
+  }
+
+  // Rule 1: regenerate through the package script, never a repeated command.
+  const generate = (pass: number): void => {
+    const run = spawnSync("bun", ["run", "generate:sdk"], { cwd: appRoot, stdio: "inherit" });
+    if ((run.status ?? 1) !== 0) {
+      fail(`\`bun run generate:sdk\` (pass ${pass}) exited ${run.status ?? "without a status"}`);
+    }
+  };
+
+  // Rule 2: two regenerations of the same source must be byte-identical.
+  generate(1);
+  const first = sha256Of(GENERATED_FILE);
+  generate(2);
+  const second = sha256Of(GENERATED_FILE);
+  if (first !== second) {
+    fail(
+      `regeneration is NOT byte-stable: two consecutive \`bun run generate:sdk\` runs of the same source produced different bytes for ${GENERATED_FILE}.\n` +
+        `This bun is ${process.versions?.bun ?? "unknown"}. A nondeterministic generator makes the byte gate vacuous — fix the generator (or the bun version) rather than committing either output.`,
+    );
+  }
+
+  // The gate: the regeneration must equal what is committed.
+  const drift = git(["diff", "--exit-code", "--", GENERATED_FILE]);
+  if (drift.status !== 0) {
+    console.error(
+      `verify-generated-artifacts: the committed registry client is not what the current source generates.\n` +
+        `Run \`bun run generate:sdk\` and commit the result. ${GENERATED_FILE} is bundled into the published\n` +
+        `\`./sdk\` export, so an uncommitted regeneration ships a client that disagrees with src/openapi.ts.`,
+    );
+    process.exit(drift.status ?? 1);
+  }
+
+  // Post-condition: the artifact survived the regeneration with its binding intact.
+  const finalText = readFileSync(join(appRoot, GENERATED_FILE), "utf8");
+  const finalProblems = [...artifactProblems(finalText), ...missingOperations(finalText).map((op) => `missing ${op}`)];
+  if (finalProblems.length > 0) {
+    fail(`regeneration rewrote ${GENERATED_FILE} but it is not usable: ${finalProblems.join("; ")}`);
+  }
+
+  console.log(
+    `verify-generated-artifacts: two consecutive regenerations of ${GENERATED_FILE} are byte-identical to each other and to the committed output; all ${servedOperations().length} operations in the served /openapi.json are covered.`,
+  );
+}
+
+// Run only when invoked directly, so the exports above are importable from tests.
+if (process.argv[1] && resolve(process.argv[1]) === resolve(fileURLToPath(import.meta.url))) main();