@cosmicdrift/kumiko-dev-server 0.1.0

package/src/codegen/__tests__/strict-mode-diagnostics.test.ts

@@ -0,0 +1,467 @@
+// Regression-Guard für die EIGENTLICHE Behauptung der Codegen-Pipeline:
+// `ctx.appendEvent` wird via Lokal-Wrapper STRICT typgeprüft.
+//
+// Ohne diesen Test verifizieren die anderen 12 Codegen-Tests nur, dass
+// die richtigen Strings ins File geschrieben werden. Wenn jemand später
+// das `export *`-Shadowing kaputt macht, den `KumikoEventTypeMap`-
+// Re-Export aus `engine/index.ts` entfernt, oder TS-Verhalten in einer
+// neuen Version subtil bricht — die anderen Tests bleiben grün und der
+// strict-mode stirbt schweigend. Genau das wäre der Fall den dieser
+// Test fängt.
+//
+// Ablauf pro Test-Case:
+//   1. tmp-App mit feature.ts + events.ts + bin/main.ts erzeugen.
+//   2. `runCodegen` auf die tmp-App fahren — schreibt
+//      `.kumiko/types.generated.d.ts` + `define.ts`.
+//   3. Eine synthetische Test-Datei mit den gewünschten Aufrufen schreiben.
+//   4. ts.createProgram über die App + paths-alias zur framework-source.
+//   5. Diagnostics auswerten — auf konkrete TS-Codes prüfen.
+//
+// `paths` zeigt direkt auf die framework-source (`packages/framework/src`),
+// damit der TS-Type-Checker die Augmentation als Teil DESSELBEN Compiles
+// sieht (Use-Site-Substitution funktioniert nur so — siehe
+// project_x1_typemap_findings memory).
+
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import * as ts from "typescript";
+import { afterAll, describe, expect, test } from "vitest";
+import { runCodegen } from "../run-codegen";
+
+const REPO_ROOT = join(__dirname, "../../../../..");
+const FRAMEWORK_SRC = join(REPO_ROOT, "packages/framework/src");
+
+// Test-Apps werden IM Repo-Tree angelegt (gitignored), damit Node's
+// natürliches `node_modules`-Hochsuchen 'zod' & Co finden kann. tmpdir
+// liegt außerhalb des Repo-Trees → keine node_modules-Sicht.
+const TEST_FIXTURE_DIR = join(__dirname, ".tmp-fixtures");
+const createdDirs: string[] = [];
+
+function makeAppDir(): string {
+  mkdirSync(TEST_FIXTURE_DIR, { recursive: true });
+  const dir = mkdtempSync(join(TEST_FIXTURE_DIR, "app-"));
+  createdDirs.push(dir);
+  return dir;
+}
+
+afterAll(() => {
+  for (const d of createdDirs) {
+    try {
+      rmSync(d, { recursive: true, force: true });
+    } catch {
+      // best-effort cleanup
+    }
+  }
+  try {
+    rmSync(TEST_FIXTURE_DIR, { recursive: true, force: true });
+  } catch {
+    // ditto
+  }
+});
+
+function write(dir: string, relPath: string, content: string): string {
+  const full = join(dir, relPath);
+  mkdirSync(dirname(full), { recursive: true });
+  writeFileSync(full, content, "utf-8");
+  return full;
+}
+
+/**
+ * Baut ein TS-Program über die App + framework-source, gibt die
+ * semantischen Diagnostics zurück. Lib-files werden vom installierten
+ * typescript-Package geholt; sonst meckert TS über fehlende DOM-types.
+ */
+function compileApp(appRoot: string): readonly ts.Diagnostic[] {
+  // Wir lassen ts node_modules vom REPO_ROOT auflösen (tmp-Dir hat kein
+  // eigenes node_modules). `baseUrl` zeigt auf repo, `paths` mappt
+  // framework + tmp-app explizit; rest fällt auf node_modules-Lookup
+  // im repo-Tree zurück.
+  const compilerOptions: ts.CompilerOptions = {
+    target: ts.ScriptTarget.ESNext,
+    module: ts.ModuleKind.ESNext,
+    moduleResolution: ts.ModuleResolutionKind.Bundler,
+    strict: true,
+    skipLibCheck: true,
+    esModuleInterop: true,
+    noEmit: true,
+    baseUrl: REPO_ROOT,
+    paths: {
+      "@cosmicdrift/kumiko-framework/*": [join(FRAMEWORK_SRC, "*/index.ts")],
+    },
+    types: [],
+  };
+
+  // Sammle alle .ts-Files unter src/ + .kumiko/, plus die framework-
+  // source-tree die wir via paths erreichen wollen.
+  const program = ts.createProgram({
+    rootNames: collectFiles(appRoot),
+    options: compilerOptions,
+  });
+  return ts.getPreEmitDiagnostics(program);
+}
+
+function collectFiles(dir: string): string[] {
+  const out: string[] = [];
+  const fs = require("node:fs");
+  const walk = (d: string) => {
+    let entries: string[];
+    try {
+      entries = fs.readdirSync(d);
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (e.startsWith(".") && e !== ".kumiko") continue;
+      if (e === "node_modules") continue;
+      const full = join(d, e);
+      const stat = fs.statSync(full);
+      if (stat.isDirectory()) walk(full);
+      else if (stat.isFile() && (e.endsWith(".ts") || e.endsWith(".tsx")) && !e.endsWith(".d.ts"))
+        out.push(full);
+    }
+  };
+  walk(join(dir, "src"));
+  walk(join(dir, ".kumiko"));
+  return out;
+}
+
+// Default-shape feature: setup callback registers `placed` and returns
+// nothing. Used by tests that exercise the standard `ctx.appendEvent({
+// type: "orders:event:placed", ... })` literal-string path.
+function setupApp(): string {
+  const appRoot = makeAppDir();
+  writeOrderPlacedSchema(appRoot);
+  write(
+    appRoot,
+    "src/feature/feature.ts",
+    `import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { orderPlacedSchema } from "./events";
+
+export const ordersFeature = defineFeature("orders", (r) => {
+  r.defineEvent("placed", orderPlacedSchema);
+});
+`,
+  );
+  return appRoot;
+}
+
+// Exports-shape feature: setup callback returns `{ placed }` so handler
+// modules can do `ordersFeature.exports.placed.name` and pick up the
+// literal type. Used by the eventDef.name pattern test.
+function setupAppWithExports(): string {
+  const appRoot = makeAppDir();
+  writeOrderPlacedSchema(appRoot);
+  write(
+    appRoot,
+    "src/feature/feature.ts",
+    `import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { orderPlacedSchema } from "./events";
+
+export const ordersFeature = defineFeature("orders", (r) => ({
+  placed: r.defineEvent("placed", orderPlacedSchema),
+}));
+`,
+  );
+  return appRoot;
+}
+
+function writeOrderPlacedSchema(appRoot: string): void {
+  write(
+    appRoot,
+    "src/feature/events.ts",
+    `import { z } from "zod";
+export const orderPlacedSchema = z.object({
+  orderId: z.string(),
+  customerId: z.string(),
+  amount: z.number(),
+});
+`,
+  );
+}
+
+// Each test compiles a tmp-app via ts.createProgram, which traverses
+// the framework-source via paths-alias (~700 files). Lokal ~1.7s pro
+// test; CI auf cdgs-runner (Hetzner CAX21 ARM64) braucht teilweise
+// >60s — vermutlich kleinere Cores + weniger RAM-cache als M-Series-
+// Mac. 120s gibt genug Puffer für den langsamsten Run-Path
+// (eventDef.name pattern lädt full augmented map) ohne echte Hänger
+// zu maskieren.
+const STRICT_MODE_TIMEOUT_MS = 120_000;
+
+describe("strict-mode diagnostics — the actual contract of the codegen", () => {
+  test("good ctx.appendEvent compiles cleanly", { timeout: STRICT_MODE_TIMEOUT_MS }, () => {
+    const appRoot = setupApp();
+    runCodegen({ appRoot });
+
+    write(
+      appRoot,
+      "src/feature/handler.ts",
+      `import { defineWriteHandler } from "../../.kumiko/define";
+import { z } from "zod";
+
+export const placeOrder = defineWriteHandler({
+  name: "orders.placeOrder",
+  schema: z.object({}),
+  access: { roles: ["Admin"] },
+  handler: async (_event, ctx) => {
+    await ctx.appendEvent({
+      aggregateId: "x",
+      aggregateType: "order",
+      type: "orders:event:placed",
+      payload: { orderId: "o1", customerId: "c1", amount: 99 },
+    });
+    return { isSuccess: true as const, data: { id: "o1" } };
+  },
+});
+`,
+    );
+
+    const diagnostics = compileApp(appRoot);
+    const handlerErrors = diagnostics.filter((d) =>
+      d.file?.fileName.endsWith("/feature/handler.ts"),
+    );
+    expect(handlerErrors).toHaveLength(0);
+  });
+
+  test("unknown event-type triggers TS2322 with augmented map in error message", {
+    timeout: STRICT_MODE_TIMEOUT_MS,
+  }, () => {
+    const appRoot = setupApp();
+    runCodegen({ appRoot });
+
+    write(
+      appRoot,
+      "src/feature/handler.ts",
+      `import { defineWriteHandler } from "../../.kumiko/define";
+import { z } from "zod";
+
+export const placeOrder = defineWriteHandler({
+  name: "orders.placeOrder",
+  schema: z.object({}),
+  access: { roles: ["Admin"] },
+  handler: async (_event, ctx) => {
+    await ctx.appendEvent({
+      aggregateId: "x",
+      aggregateType: "order",
+      type: "totally:made:up",
+      payload: { whatever: 1 },
+    });
+    return { isSuccess: true as const, data: { id: "x" } };
+  },
+});
+`,
+    );
+
+    const diagnostics = compileApp(appRoot);
+    const handlerErrors = diagnostics.filter((d) =>
+      d.file?.fileName.endsWith("/feature/handler.ts"),
+    );
+    // We expect at least one TS2322 ("not assignable") for the bogus
+    // type-string. The exact column may move with TS versions; the code
+    // + the type-name are the stable contract.
+    const ts2322 = handlerErrors.filter((d) => d.code === 2322);
+    expect(ts2322.length).toBeGreaterThan(0);
+    const flattened = ts2322
+      .map((d) => ts.flattenDiagnosticMessageText(d.messageText, "\n"))
+      .join("\n");
+    expect(flattened).toMatch(/keyof KumikoEventTypeMap|"orders:event:placed"/);
+  });
+
+  test("payload-shape mismatch triggers a property-error", {
+    timeout: STRICT_MODE_TIMEOUT_MS,
+  }, () => {
+    const appRoot = setupApp();
+    runCodegen({ appRoot });
+
+    write(
+      appRoot,
+      "src/feature/handler.ts",
+      `import { defineWriteHandler } from "../../.kumiko/define";
+import { z } from "zod";
+
+export const placeOrder = defineWriteHandler({
+  name: "orders.placeOrder",
+  schema: z.object({}),
+  access: { roles: ["Admin"] },
+  handler: async (_event, ctx) => {
+    await ctx.appendEvent({
+      aggregateId: "x",
+      aggregateType: "order",
+      type: "orders:event:placed",
+      payload: { orderId: "o1", customerId: "c1", amount: 99, bogus: "extra" },
+    });
+    return { isSuccess: true as const, data: { id: "o1" } };
+  },
+});
+`,
+    );
+
+    const diagnostics = compileApp(appRoot);
+    const handlerErrors = diagnostics.filter((d) =>
+      d.file?.fileName.endsWith("/feature/handler.ts"),
+    );
+    // TS2353 = "Object literal may only specify known properties, and
+    // 'bogus' does not exist in type". This is the property-level
+    // strict-check we promised.
+    const propErrors = handlerErrors.filter((d) => d.code === 2353);
+    expect(propErrors.length).toBeGreaterThan(0);
+    const flattened = propErrors
+      .map((d) => ts.flattenDiagnosticMessageText(d.messageText, "\n"))
+      .join("\n");
+    expect(flattened).toMatch(/'bogus'/);
+  });
+
+  test("direct framework-import + augmentation-included compiles strict too", {
+    timeout: STRICT_MODE_TIMEOUT_MS,
+  }, () => {
+    // Sanity-Check: in einem isolated app-tsc (tmp-fixture mit paths-
+    // mapping zur framework-source UND .kumiko/types.generated.d.ts im
+    // include-Glob) greift strict-mode auch beim direct framework-import.
+    // Generic-function-inference nimmt die augmentation am use-site wahr.
+    //
+    // Konsequenz: der Wrapper ist NICHT der einzige Weg zu strict —
+    // aber er ist DER ROBUSTE Weg. Er importiert `types.generated`
+    // explicit als side-effect, sodass die Augmentation auch in
+    // partial-builds / IDE-Sprachserver-stati garantiert visible ist.
+    // Direkter Import setzt voraus, dass das tsconfig-Setup stimmt.
+    //
+    // Die alte "K=never"-Beobachtung aus den 13 Probes war im
+    // bundled-features-Compile, wo das `.kumiko/`-Output nicht im
+    // include-Glob lag — die Augmentation aus inline `declare module`
+    // hatte einen anderen Resolution-Pfad. Der Wrapper bleibt der
+    // empfohlene Pfad für Apps, weil er diese Setup-Sensibilität wegabstrahiert.
+    const appRoot = setupApp();
+    runCodegen({ appRoot });
+
+    write(
+      appRoot,
+      "src/feature/handler-direct.ts",
+      `import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+
+export const placeOrder = defineWriteHandler({
+  name: "orders.placeOrder",
+  schema: z.object({}),
+  access: { roles: ["Admin"] },
+  handler: async (_event, ctx) => {
+    await ctx.appendEvent({
+      aggregateId: "x",
+      aggregateType: "order",
+      type: "orders:event:placed",
+      payload: { orderId: "o1", customerId: "c1", amount: 99 },
+    });
+    return { isSuccess: true as const, data: { id: "o1" } };
+  },
+});
+`,
+    );
+
+    const diagnostics = compileApp(appRoot);
+    const handlerErrors = diagnostics.filter((d) =>
+      d.file?.fileName.endsWith("/feature/handler-direct.ts"),
+    );
+    // Good call should compile — augmentation is visible via include of
+    // `.kumiko/types.generated.d.ts`.
+    expect(handlerErrors).toHaveLength(0);
+  });
+
+  test("eventDef.name pattern: literal-typed name resolves to correct payload-shape", {
+    timeout: STRICT_MODE_TIMEOUT_MS,
+  }, () => {
+    // Marten pattern: `const placed = r.defineEvent(...)`, then
+    // `type: placed.name` in appendEvent. This requires `EventDef.name`
+    // to be LITERAL-typed (`"orders:event:placed"`, NOT `string`) —
+    // otherwise the lookup collapses to `string` and the strict check
+    // silently disappears.
+    //
+    // This test catches regressions in `EventDef<TPayload, TName>` and
+    // the `<const TInner>` inference in `defineFeature`/`defineEvent`
+    // — both have to cooperate so that `placed.name` resolves as a
+    // literal into the `KumikoEventTypeMap` key.
+    //
+    // Setup: `setupAppWithExports` returns `{ placed }` from the
+    // defineFeature callback so handler modules can read it as
+    // `ordersFeature.exports.placed.name`.
+    const appRoot = setupAppWithExports();
+    runCodegen({ appRoot });
+
+    write(
+      appRoot,
+      "src/feature/handler-byname.ts",
+      `import { defineWriteHandler } from "../../.kumiko/define";
+import { z } from "zod";
+import { ordersFeature } from "./feature";
+
+const { placed } = ordersFeature.exports;
+
+export const placeOrder = defineWriteHandler({
+  name: "orders.placeOrder",
+  schema: z.object({}),
+  access: { roles: ["Admin"] },
+  handler: async (_event, ctx) => {
+    await ctx.appendEvent({
+      aggregateId: "x",
+      aggregateType: "order",
+      type: placed.name,
+      payload: { orderId: "o1", customerId: "c1", amount: 99 },
+    });
+    return { isSuccess: true as const, data: { id: "o1" } };
+  },
+});
+`,
+    );
+
+    const goodDiagnostics = compileApp(appRoot);
+    const goodErrors = goodDiagnostics.filter((d) =>
+      d.file?.fileName.endsWith("/feature/handler-byname.ts"),
+    );
+    if (goodErrors.length > 0) {
+      const msgs = goodErrors
+        .map((d) => `  TS${d.code}: ${ts.flattenDiagnosticMessageText(d.messageText, "\n")}`)
+        .join("\n");
+      throw new Error(`expected handler-byname.ts to compile cleanly, got:\n${msgs}`);
+    }
+
+    // Negative-Case: bad payload (extra property) → TS2353. Der
+    // entscheidende Punkt — wenn `placed.name` zu `string` kollabiert
+    // wäre, würde TS hier eine `Record<string, unknown>` annehmen und
+    // die extra property NICHT melden. TS2353 hier beweist die
+    // literal-typed Auflösung über `.name`.
+    write(
+      appRoot,
+      "src/feature/handler-byname.ts",
+      `import { defineWriteHandler } from "../../.kumiko/define";
+import { z } from "zod";
+import { ordersFeature } from "./feature";
+
+const { placed } = ordersFeature.exports;
+
+export const placeOrder = defineWriteHandler({
+  name: "orders.placeOrder",
+  schema: z.object({}),
+  access: { roles: ["Admin"] },
+  handler: async (_event, ctx) => {
+    await ctx.appendEvent({
+      aggregateId: "x",
+      aggregateType: "order",
+      type: placed.name,
+      payload: { orderId: "o1", customerId: "c1", amount: 99, bogus: "extra" },
+    });
+    return { isSuccess: true as const, data: { id: "o1" } };
+  },
+});
+`,
+    );
+
+    const badDiagnostics = compileApp(appRoot);
+    const badErrors = badDiagnostics.filter((d) =>
+      d.file?.fileName.endsWith("/feature/handler-byname.ts"),
+    );
+    const propErrors = badErrors.filter((d) => d.code === 2353);
+    expect(propErrors.length).toBeGreaterThan(0);
+    const flattened = propErrors
+      .map((d) => ts.flattenDiagnosticMessageText(d.messageText, "\n"))
+      .join("\n");
+    expect(flattened).toMatch(/'bogus'/);
+  });
+});

package/src/codegen/__tests__/watch.test.ts

@@ -0,0 +1,186 @@
+// watchAndRegenerate — file-watcher-Tests. Verifiziert: initial-Pass
+// läuft synchron, file-changes triggern einen erneuten Pass mit Debounce,
+// close() ist idempotent.
+//
+// Fixtures liegen wie bei strict-mode-diagnostics.test.ts unter
+// `__tests__/.tmp-fixtures/` (gitignored), damit Node's natürliches
+// `node_modules`-Hochsuchen 'zod' findet — auch wenn watch-Tests
+// 'zod' nicht direct nutzen, runCodegen scant feature-files die
+// `import { z } from "zod"` haben.
+
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { afterAll, describe, expect, test } from "vitest";
+import type { CodegenResult } from "../run-codegen";
+import { watchAndRegenerate } from "../watch";
+
+const TEST_FIXTURE_DIR = join(__dirname, ".tmp-fixtures");
+const createdDirs: string[] = [];
+
+function makeAppDir(): string {
+  mkdirSync(TEST_FIXTURE_DIR, { recursive: true });
+  const dir = mkdtempSync(join(TEST_FIXTURE_DIR, "watch-"));
+  createdDirs.push(dir);
+  return dir;
+}
+
+function writeFile(dir: string, relPath: string, content: string): string {
+  const full = join(dir, relPath);
+  mkdirSync(dirname(full), { recursive: true });
+  writeFileSync(full, content, "utf-8");
+  return full;
+}
+
+afterAll(() => {
+  for (const d of createdDirs) {
+    try {
+      rmSync(d, { recursive: true, force: true });
+    } catch {
+      /* best-effort */
+    }
+  }
+});
+
+/**
+ * Polls a predicate at `interval` ms until it returns true, or rejects
+ * after `timeout`. Replaces fixed `setTimeout(...)` waits — those
+ * implicitly assume "this many ms is enough", which is brittle on
+ * loaded CI runners. The polling form converges as fast as the system
+ * allows AND fails loudly with a useful message if the event never lands.
+ */
+async function waitFor(
+  predicate: () => boolean,
+  opts: { timeout?: number; interval?: number; label?: string } = {},
+): Promise<void> {
+  const timeout = opts.timeout ?? 2000;
+  const interval = opts.interval ?? 25;
+  const deadline = Date.now() + timeout;
+  while (!predicate()) {
+    if (Date.now() > deadline) {
+      throw new Error(`waitFor: ${opts.label ?? "predicate"} not satisfied within ${timeout}ms`);
+    }
+    await new Promise((r) => setTimeout(r, interval));
+  }
+}
+
+const FEATURE_TEMPLATE = (featureName: string, eventName: string) => `
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+
+export default defineFeature("${featureName}", (r) => {
+  r.defineEvent("${eventName}", z.object({ id: z.string() }));
+});
+`;
+
+describe("watchAndRegenerate", () => {
+  test("initial run produces output synchronously", () => {
+    const appRoot = makeAppDir();
+    writeFile(appRoot, "src/feature.ts", FEATURE_TEMPLATE("billing", "first-event"));
+
+    const results: CodegenResult[] = [];
+    const handle = watchAndRegenerate({
+      appRoot,
+      onResult: (r) => results.push(r),
+    });
+
+    expect(results).toHaveLength(1);
+    expect(results[0]?.eventCount).toBe(1);
+    handle.close();
+  });
+
+  test("file change triggers a re-run after debounce", async () => {
+    const appRoot = makeAppDir();
+    writeFile(appRoot, "src/feature.ts", FEATURE_TEMPLATE("orders", "first"));
+
+    const results: CodegenResult[] = [];
+    const handle = watchAndRegenerate({
+      appRoot,
+      debounceMs: 30,
+      onResult: (r) => results.push(r),
+    });
+
+    expect(results).toHaveLength(1);
+    expect(results[0]?.eventCount).toBe(1);
+
+    // Add a second event-definition by rewriting the feature.
+    writeFile(
+      appRoot,
+      "src/feature.ts",
+      `
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+
+export default defineFeature("orders", (r) => {
+  r.defineEvent("first", z.object({ id: z.string() }));
+  r.defineEvent("second", z.object({ tag: z.string() }));
+});
+`,
+    );
+
+    // Poll until the watcher's debounced re-run has landed. fs.watch
+    // events on macOS arrive in 1-5ms; CI runners can stretch that —
+    // polling adapts to the actual schedule instead of guessing a fixed
+    // sleep.
+    await waitFor(() => results.length >= 2, {
+      timeout: 2000,
+      label: "second codegen result",
+    });
+
+    expect(results.at(-1)?.eventCount).toBe(2);
+    handle.close();
+  });
+
+  test("close() is idempotent", () => {
+    const appRoot = makeAppDir();
+    writeFile(appRoot, "src/feature.ts", FEATURE_TEMPLATE("nope", "evt"));
+    const handle = watchAndRegenerate({ appRoot, onResult: () => {} });
+    handle.close();
+    handle.close(); // must not throw
+    expect(true).toBe(true);
+  });
+
+  test("non-ts file changes do not trigger codegen", async () => {
+    // Negative-assertion shape: prove that .css/.md changes do NOT add
+    // a codegen result. Naïve "sleep N ms then assert length stayed"
+    // is racy on macOS, where fs.watch can deliver stale events from
+    // pre-watcher writes after the watcher is attached. We sidestep
+    // that by anchoring on a POSITIVE control: a known-triggering .ts
+    // change at the end. waitFor proves the watcher is alive — so the
+    // pre-trigger count is trustworthy.
+    const appRoot = makeAppDir();
+    writeFile(appRoot, "src/feature.ts", FEATURE_TEMPLATE("ignore-css", "evt"));
+
+    const results: CodegenResult[] = [];
+    const handle = watchAndRegenerate({
+      appRoot,
+      debounceMs: 30,
+      onResult: (r) => results.push(r),
+    });
+    expect(results).toHaveLength(1);
+
+    // Drain any stale events from the pre-watcher feature.ts write —
+    // some platforms deliver these to a watcher attached after the
+    // write. Long enough to outlast debounce + scheduler jitter.
+    await new Promise((r) => setTimeout(r, 200));
+    const baseline = results.length;
+
+    // Non-ts writes — the regression we want to catch.
+    writeFile(appRoot, "src/styles.css", `body { color: red; }`);
+    writeFile(appRoot, "src/README.md", `# hi`);
+    await new Promise((r) => setTimeout(r, 200));
+    const afterNonTs = results.length;
+
+    // Positive control: a .ts change MUST trigger. waitFor exits as
+    // soon as the new result lands, confirming the watcher is alive.
+    writeFile(appRoot, "src/feature.ts", FEATURE_TEMPLATE("ignore-css", "after"));
+    await waitFor(() => results.length > afterNonTs, {
+      timeout: 2000,
+      label: "ts-change result after non-ts noise",
+    });
+
+    // The non-ts writes should not have advanced the count past the
+    // baseline. If they did, the watcher's filter is broken.
+    expect(afterNonTs).toBe(baseline);
+    handle.close();
+  });
+});

package/src/codegen/index.ts

@@ -0,0 +1,17 @@
+export {
+  renderDefineFile,
+  renderInlineSchemasFile,
+  renderTypesAugmentation,
+} from "./render";
+export { type CodegenOptions, type CodegenResult, runCodegen } from "./run-codegen";
+export {
+  qualifiedNameToConstName,
+  rewriteImportPath,
+  type ScannedEvent,
+  type ScanOptions,
+  type ScanResult,
+  type ScanWarning,
+  type SchemaSource,
+  scanEvents,
+} from "./scan-events";
+export { type WatchHandle, type WatchOptions, watchAndRegenerate } from "./watch";