@zmdb/compiler 1.0.0-beta.1

package/src/unplugin/index.ts

@@ -0,0 +1,182 @@
+// The bundler hook. One compiler session per build, one transform per module.
+//
+// `enforce: 'pre'` is load-bearing rather than decorative. The transform rewrites by
+// text offset against the positions the TypeScript compiler parsed, so it has to see
+// the module before anything else edits it. Running late means `sourceFile.text !== code`
+// and the whole file degrades to the tag-only path — silently faster to build and
+// silently slower to run, which is the worst way for this to fail.
+//
+// The session is opened on the first module and held for the build (REQ-TF-11). Loading
+// the project is the expensive half; a checker call is a cheap round-trip. A session per
+// file would make the AOT path cost more than the runtime walker it replaces.
+
+import { resolveNaming, type NamingStrategyConfig } from '@zmdb/schema/naming';
+
+import type { EmitOptions } from '../emit/index.js';
+import { ReflectSession } from '../reflect/session.js';
+import { transformCode, transformFile, type TransformDiagnostic } from '../transform/index.js';
+
+/** Inline `validate(tags.X(…), …)` with no compiler. Type arguments need `transformFile`. */
+export function transformTypeChecks(code: string): string {
+  return transformCode(code);
+}
+
+export interface UnpluginLike {
+  readonly name: string;
+  /**
+   * Rollup/Vite ordering. `'pre'` because the offsets this plugin rewrites at are only
+   * valid for the text the compiler parsed.
+   */
+  readonly enforce?: 'pre' | 'post';
+  transform(code: string, id: string): { code: string } | null;
+  /**
+   * Watch mode: re-check the changed file without reloading the project.
+   *
+   * The `change` argument is Rollup's, and it matters rather than being decorative: a
+   * `changed` notification for a file the program has never seen does nothing at all, so a
+   * newly added module has to be reported as `create` or it stays invisible.
+   */
+  watchChange?(id: string, change?: WatchChange): void;
+  buildEnd?(): void;
+}
+
+/** Rollup's second argument to `watchChange`. */
+export interface WatchChange {
+  readonly event: 'create' | 'update' | 'delete';
+}
+
+export interface ZmdbAotOptions {
+  /**
+   * Absolute path to the `tsconfig.json` that defines the program. Without one — and
+   * without `session` — the plugin cannot ask what a type is, so it inlines only the
+   * `validate(tags.X(…), …)` form and leaves every `f<T>(…)` call alone.
+   */
+  readonly project?: string;
+  readonly cwd?: string;
+  /** An already-open session. The caller keeps ownership, including closing it. */
+  readonly session?: ReflectSession;
+  readonly emit?: EmitOptions;
+  /** A named or custom build-time strategy, resolved once for this plugin instance. */
+  readonly naming?: NamingStrategyConfig;
+  /**
+   * Called for each refused call site. The default throws, because a type the emitter
+   * could not model means the call falls back to a runtime walker that has no
+   * descriptor to walk — a build that "succeeded" and a program that throws on first
+   * use (plan D4).
+   */
+  readonly onDiagnostic?: (diagnostic: TransformDiagnostic) => void;
+}
+
+const SOURCE = /\.(?:ts|tsx|mts|cts|js|jsx|mjs)$/;
+
+export function zmdbAot(options: ZmdbAotOptions = {}): UnpluginLike {
+  let session: ReflectSession | undefined = options.session;
+  const reflect = { naming: resolveNaming(options.naming) } as const;
+  /** Whether this plugin opened the session, and therefore has to close it. */
+  let owned = false;
+  /** Files already refreshed after a text mismatch, so the retry happens at most once. */
+  const retried = new Set<string>();
+
+  const ensureSession = (): ReflectSession | undefined => {
+    if (session) return session;
+    if (options.project === undefined) return undefined;
+    session = ReflectSession.open({ project: options.project, ...(options.cwd ? { cwd: options.cwd } : {}) });
+    owned = true;
+    return session;
+  };
+
+  return {
+    name: 'zmdb-aot',
+    enforce: 'pre',
+
+    transform(code: string, id: string): { code: string } | null {
+      // Never dependencies and never declaration files: a package ships already-built
+      // JavaScript, and rewriting it would be rewriting someone else's compiled output.
+      if (id.includes('node_modules')) return null;
+      if (id.endsWith('.d.ts') || !SOURCE.test(id)) return null;
+
+      const open = ensureSession();
+      if (!open) {
+        const out = transformCode(code);
+        return out === code ? null : { code: out };
+      }
+
+      // Workspace package exports point at source files, so a bundler can hand us a
+      // dependency whose path does not contain `node_modules`. The compiler still marks
+      // that file as an external library. Treat it exactly like an installed dependency:
+      // framework code ships its own build and must not be recompiled as consumer code.
+      const sourceFile = open.sourceFile(id);
+      if (sourceFile !== undefined && open.program.isSourceFileFromExternalLibrary(sourceFile)) return null;
+
+      let result = transformFile(id, code, {
+        session: open,
+        reflect,
+        ...(options.emit ? { emit: options.emit } : {}),
+      });
+
+      // A stale program is the likely cause of a text mismatch, and it is cheap to rule
+      // out: re-check this one file and try again. Once per file — if the text still
+      // disagrees, something else edited the module and no refresh will fix that.
+      if (isStale(result.diagnostics) && !retried.has(id)) {
+        retried.add(id);
+        // A module the program has never seen has to be announced as created; telling it a
+        // file it does not know about "changed" is a no-op.
+        if (open.sourceFile(id)) open.refresh([id]);
+        else open.created([id]);
+        result = transformFile(id, code, {
+          session: open,
+          reflect,
+          ...(options.emit ? { emit: options.emit } : {}),
+        });
+      }
+
+      const refusals = result.diagnostics.filter(diagnostic => diagnostic.position !== undefined);
+      if (refusals.length > 0) {
+        if (options.onDiagnostic) for (const refusal of refusals) options.onDiagnostic(refusal);
+        else throw new Error(formatRefusals(refusals));
+      }
+
+      return result.changed ? { code: result.code } : null;
+    },
+
+    watchChange(id: string, change?: WatchChange): void {
+      retried.delete(id);
+      if (!session) return;
+      if (change?.event === 'create') session.created([id]);
+      else if (change?.event === 'delete') session.deleted([id]);
+      else session.refresh([id]);
+    },
+
+    buildEnd(): void {
+      if (owned) session?.close();
+      session = undefined;
+      owned = false;
+      retried.clear();
+    },
+  };
+}
+
+/**
+ * Whether the complaint was about the program's view of the file rather than the code.
+ *
+ * Both cases are recoverable and both are ordinary: the bundler is handing over a module
+ * the compiler has not read yet (a new file) or has read at an older revision (an edit).
+ * A refusal about a call site is not in here, because no amount of re-reading fixes it.
+ */
+function isStale(diagnostics: readonly TransformDiagnostic[]): boolean {
+  return diagnostics.some(
+    diagnostic =>
+      diagnostic.position === undefined &&
+      (diagnostic.reason.includes('not the text the compiler parsed') ||
+        diagnostic.reason.includes('not part of the TypeScript project')),
+  );
+}
+
+function formatRefusals(refusals: readonly TransformDiagnostic[]): string {
+  const lines = refusals.map(refusal => {
+    const where = refusal.path === '' ? '' : ` at \`${refusal.path}\``;
+    const printed = refusal.source === undefined ? '' : ` (${refusal.source})`;
+    return `  ${refusal.fileName}:${refusal.position ?? 0} — \`${refusal.callee ?? '?'}<T>\`${where}: ${refusal.reason}${printed}`;
+  });
+  return `@zmdb/compiler cannot compile ${refusals.length} call site(s):\n${lines.join('\n')}`;
+}

package/src/unplugin/inline-bench.ts

@@ -0,0 +1,92 @@
+// The timing helper the AOT plugin benchmarks share.
+//
+// Both #82 (the build produces a working inlined validator) and #83 (the acceptance gate)
+// time the emitted check against the runtime walker. Each used to carry its own copy of the
+// loop, so a change to how "ops/sec" is measured would have had to be made twice for the
+// two numbers to stay comparable.
+//
+// Building the validator no longer lives here. It used to, back when the transform was a
+// text parser that needed nothing but a string; now it needs a compiler, and the project
+// harness in `emit/__testing__/project.ts` is what owns that.
+//
+// A note on why the loops below look the way they do, since it is the whole reason these
+// numbers mean anything. The measured function must be called for its *result*, and that
+// result has to reach something observable. An earlier version timed `() => void check(input)`
+// and discarded the boolean: for the inlined AOT check — a pure function of a hoisted constant
+// — V8 eventually proves the call has no effect and deletes the loop body. That does not read
+// as an error, it reads as 1.4 *billion* ops/sec, about 90x the honest figure, and it only
+// appears once the function is fully optimized. So the fixed 200k-iteration single shot was
+// getting a roughly truthful number by not running long enough to be optimized properly, and
+// any attempt to measure it more carefully made it worse.
+//
+// Hence: `fn` returns a value, every return value is folded into a counter, and the counter is
+// read afterwards. The input is also rotated, so the checked object is not a constant the
+// optimizer can fold the property loads out of.
+
+import { threadCpuUsage } from 'node:process';
+
+declare const performance: { now(): number };
+
+function measuredOpsPerSecond(
+  fn: (index: number) => unknown,
+  n: number,
+  now: () => number,
+  ticksPerSecond: number,
+): number {
+  let sink = 0;
+  for (let i = 0; i < 10_000; i++) if (fn(i)) sink++;
+  const start = now();
+  for (let i = 0; i < n; i++) if (fn(i)) sink++;
+  const elapsed = now() - start;
+  // Reading `sink` is what keeps the calls that produced it alive. Without a use, the whole
+  // loop is dead code and a sufficiently good optimizer is entitled to say so.
+  if (sink < 0) throw new Error('unreachable, and here to make the measured work observable');
+  return Math.round((n / elapsed) * ticksPerSecond);
+}
+
+/**
+ * Ops/sec for `fn` over `n` iterations, after a 10k-iteration warm-up.
+ *
+ * `fn` receives a rotating index and must return something derived from the work it did. Both
+ * halves matter — see the file header.
+ */
+export function opsPerSecond(fn: (index: number) => unknown, n: number): number {
+  return measuredOpsPerSecond(fn, n, () => performance.now(), 1000);
+}
+
+/**
+ * Ops per current-thread CPU second for an absolute performance floor.
+ *
+ * Unlike wall time, this clock does not advance while another test worker has descheduled the
+ * current one. The measured work remains synchronous JavaScript on this thread, so CPU time
+ * preserves the cost distinction while removing suite contention from the result.
+ */
+export function threadCpuOpsPerSecond(fn: (index: number) => unknown, n: number): number {
+  return measuredOpsPerSecond(
+    fn,
+    n,
+    () => {
+      const usage = threadCpuUsage();
+      return usage.user + usage.system;
+    },
+    1_000_000,
+  );
+}
+
+/**
+ * The best of `trials` runs of `opsPerSecond(fn, n)`.
+ *
+ * For a *ratio* between two functions, one measurement each is not enough. A single timed loop
+ * here is tens of milliseconds long, and when vitest is running the whole suite across every
+ * core, one descheduling of that length is the difference between a 6x reading and a 4.6x one
+ * — which is exactly how the acceptance gate came to fail under load and pass in isolation.
+ *
+ * Best-of rather than a mean, because contention is one-sided: it can only ever make a
+ * function look slower than it is, never faster. The fastest of several runs is the closest
+ * available estimate of what the code itself does, which is what the gate is a claim about.
+ */
+export function peakOpsPerSecond(fn: (index: number) => unknown, n: number, trials: number): number {
+  let best = 0;
+  for (let trial = 0; trial < trials; trial++) best = Math.max(best, opsPerSecond(fn, n));
+  return best;
+}