rastack 0.0.50 → 0.0.51

package/src/plugin/index.ts

@@ -0,0 +1,243 @@
+/**
+ * `rastack/plugin` — the schema compiles itself inside your dev server.
+ *
+ * Class and interface entities are pure types, so the manifest has to be
+ * derived by the TypeScript checker — but not by a command you run. Add the
+ * plugin to the bundler you already use and the whole `rastack compile`
+ * pass disappears into the dev loop:
+ *
+ * ```ts
+ * // vite.config.ts
+ * import { rastackPlugin } from "rastack/plugin";
+ * export default defineConfig({
+ *   plugins: [rastackPlugin({ resourcesDir: "src/entities" })],
+ * });
+ * ```
+ *
+ * ```tsx
+ * // app — the manifest is a live import, recompiled on every save
+ * import manifest from "virtual:rastack-manifest";
+ * <RAStackProvider mode="local" manifest={manifest}>…</RAStackProvider>
+ * ```
+ *
+ * What it does on your behalf, on every relevant file save:
+ * - recompiles the entity graph (classes, interfaces, `resource()` calls);
+ * - serves the manifest as the `virtual:rastack-manifest` module and
+ *   hot-invalidates it;
+ * - rewrites `.rastack/rastack-env.d.ts` (string-key row types) and
+ *   `schema.rastack.json`/`openapi.json`, so the committed artifacts and the
+ *   registry never go stale;
+ * - on a broken in-progress edit, reports the error and keeps serving the
+ *   last good manifest.
+ *
+ * The plugin object is Vite/Rollup-compatible (Vite-specific hooks are
+ * ignored by plain Rollup). For dev servers with other plugin systems
+ * (Next/webpack, Metro/Expo), `startRastackWatcher` does the same
+ * recompile-on-save against the filesystem — call it once from your config —
+ * and `rastack dev` remains the zero-config path.
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import {
+  createSchemaState,
+  isEntitySource,
+  registerModuleCode,
+  RESOLVED_MANIFEST_ID,
+  VIRTUAL_MANIFEST_ID,
+  VIRTUAL_REGISTER_ID,
+  type RastackPluginOptions,
+  type SchemaState,
+} from "./core";
+
+export {
+  createSchemaState,
+  GLOBAL_MANIFEST_KEY,
+  isEntitySource,
+  manifestModuleCode,
+  registerModuleCode,
+  resolveOptions,
+  RESOLVED_MANIFEST_ID,
+  runCompile,
+  VIRTUAL_MANIFEST_ID,
+  VIRTUAL_REGISTER_ID,
+  virtualModuleDts,
+} from "./core";
+export type {
+  RastackPluginOptions,
+  ResolvedPluginOptions,
+  SchemaState,
+} from "./core";
+
+/** One HTML tag descriptor in Vite's `transformIndexHtml` shape. */
+export interface HtmlTagDescriptor {
+  tag: string;
+  attrs?: Record<string, string>;
+  children?: string;
+  injectTo?: "head" | "head-prepend" | "body" | "body-prepend";
+}
+
+/** The minimal bundler-plugin surface we emit (Vite superset of Rollup). */
+export interface RastackBundlerPlugin {
+  name: string;
+  buildStart(): void;
+  resolveId(id: string): string | undefined;
+  load(id: string): string | undefined;
+  watchChange(id: string): void;
+  /**
+   * Vite-only: auto-register the schema. Injects a module script that sets
+   * `globalThis.__RASTACK_MANIFEST__` before the app boots, so the provider
+   * and hooks need no `manifest` wiring at all. Object form with
+   * `order: "pre"` — the tag must be injected *before* Vite scans the HTML
+   * entry, or the build ships the virtual import verbatim.
+   */
+  transformIndexHtml: {
+    order: "pre";
+    handler(html: string, ctx?: { server?: unknown }): HtmlTagDescriptor[];
+  };
+  /** Vite-only: recompile + hot-invalidate the virtual manifest module. */
+  handleHotUpdate(ctx: {
+    file: string;
+    server: {
+      moduleGraph: {
+        getModuleById(id: string): unknown;
+        invalidateModule(mod: any): void;
+      };
+    };
+    modules: unknown[];
+  }): unknown[] | void;
+  /** The live schema state — exposed for tests and advanced callers. */
+  api: SchemaState;
+}
+
+/**
+ * The bundler plugin. Works as-is in Vite and Rollup; the returned object is
+ * plain data + closures, so any bundler with resolve/load/watch hooks can
+ * adapt it.
+ */
+export function rastackPlugin(
+  options: RastackPluginOptions = {},
+): RastackBundlerPlugin {
+  const state = createSchemaState(options);
+
+  return {
+    name: "rastack",
+
+    buildStart() {
+      // Compile eagerly so authoring errors surface at server start, and the
+      // artifacts (env.d.ts, schema.rastack.json) exist before first load.
+      state.manifest();
+    },
+
+    resolveId(id: string) {
+      if (id === VIRTUAL_MANIFEST_ID) return RESOLVED_MANIFEST_ID;
+      if (id === VIRTUAL_REGISTER_ID) return VIRTUAL_REGISTER_ID;
+      return undefined;
+    },
+
+    load(id: string) {
+      if (id === RESOLVED_MANIFEST_ID) return state.code();
+      if (id === VIRTUAL_REGISTER_ID) return registerModuleCode();
+      return undefined;
+    },
+
+    watchChange(id: string) {
+      if (isEntitySource(id, state.options)) state.invalidate();
+    },
+
+    handleHotUpdate(ctx) {
+      if (!isEntitySource(ctx.file, state.options)) return;
+      state.invalidate();
+      const mod = ctx.server.moduleGraph.getModuleById(RESOLVED_MANIFEST_ID);
+      if (mod) {
+        ctx.server.moduleGraph.invalidateModule(mod);
+        return [...ctx.modules, mod];
+      }
+    },
+
+    transformIndexHtml: {
+      order: "pre",
+      handler(_html: string, ctx?: { server?: unknown }) {
+        // Dev serves resolved ids at /@id/<id>; build gets an inline module
+        // script that (because this runs `pre`, before Vite scans the HTML
+        // entry) is bundled, its import resolving back through
+        // resolveId/load above.
+        const attrs: Record<string, string> = { type: "module" };
+        const tag: HtmlTagDescriptor = ctx?.server
+          ? {
+              tag: "script",
+              attrs: { ...attrs, src: `/@id/${VIRTUAL_REGISTER_ID}` },
+            }
+          : {
+              tag: "script",
+              attrs,
+              children: `import ${JSON.stringify(VIRTUAL_REGISTER_ID)};`,
+            };
+        return [{ ...tag, injectTo: "head-prepend" }];
+      },
+    },
+
+    api: state,
+  };
+}
+
+/** Alias so `import { rastack } from "rastack/plugin"` reads naturally. */
+export const rastack = rastackPlugin;
+
+export interface RastackWatcher {
+  /** Stop watching. */
+  close(): void;
+  /** The live schema state (same object the recompiles flow through). */
+  state: SchemaState;
+}
+
+/**
+ * The plugin for everything that isn't Rollup-shaped: watch the resources
+ * directory and rewrite the artifacts (`schema.rastack.json`,
+ * `openapi.json`, `rastack-env.d.ts`) on every save. Call once from any
+ * Node-side config (next.config.js, metro.config.js, a dev script):
+ *
+ * ```js
+ * // next.config.js
+ * const { startRastackWatcher } = require("rastack/plugin");
+ * if (process.env.NODE_ENV === "development") startRastackWatcher();
+ * ```
+ *
+ * The app then imports `.rastack/schema.rastack.json` directly (a plain JSON
+ * import every bundler hot-reloads) instead of the virtual module.
+ */
+export function startRastackWatcher(
+  options: RastackPluginOptions = {},
+): RastackWatcher {
+  const state = createSchemaState(options);
+  state.manifest(); // initial compile (writes the artifacts)
+
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const watcher = fs.watch(
+    state.options.resourcesDir,
+    { recursive: true },
+    (_event, filename) => {
+      // fs.watch reports paths relative to the watched directory.
+      const file = filename
+        ? path.join(state.options.resourcesDir, String(filename))
+        : undefined;
+      if (!file || !isEntitySource(file, state.options)) {
+        return;
+      }
+      state.invalidate();
+      // Debounce bursts (editors write twice, git checkouts touch many files).
+      if (timer) clearTimeout(timer);
+      timer = setTimeout(() => {
+        state.manifest();
+      }, 100);
+    },
+  );
+
+  return {
+    close: () => {
+      if (timer) clearTimeout(timer);
+      watcher.close();
+    },
+    state,
+  };
+}

package/test/plugin.spec.ts

@@ -0,0 +1,315 @@
+/**
+ * The dev-server schema compiler (`rastack/plugin`) — the way around
+ * "classes need a compile step". The plugin runs the same
+ * `analyzeProject`/`compile` pass as the CLI *inside* the bundler: entities
+ * authored as plain classes/interfaces become the `virtual:rastack-manifest`
+ * module, recompiled on save, with `rastack-env.d.ts` kept fresh and the
+ * last good manifest served through broken in-progress edits.
+ */
+
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
+import { join } from "path";
+import {
+  GLOBAL_MANIFEST_KEY,
+  isEntitySource,
+  manifestModuleCode,
+  rastackPlugin,
+  registerModuleCode,
+  resolveOptions,
+  RESOLVED_MANIFEST_ID,
+  startRastackWatcher,
+  VIRTUAL_MANIFEST_ID,
+  VIRTUAL_REGISTER_ID,
+  virtualModuleDts,
+} from "../src/plugin";
+import { getGlobalManifest } from "../hooks/manifest";
+import { resolveEntityRef } from "../hooks/entity";
+
+const workRoot = join(__dirname, "plugin-fixtures");
+const resourcesDir = join(workRoot, "entities");
+const outDir = join(workRoot, ".rastack");
+
+// Plain classes + a hook-rooted interface — no resource() DSL anywhere.
+const GOOD_SOURCE = `
+export class Airport {
+  code!: string;
+  name!: string;
+}
+
+export class Terminal {
+  airport!: Airport;   // FK — inferred from the type
+  label!: string;
+}
+`;
+
+// An all-required FK cycle — a compile *error* (the mid-edit breakage case).
+const BROKEN_SOURCE = `
+export class Airport {
+  code!: string;
+  home!: Terminal;
+}
+
+export class Terminal {
+  airport!: Airport;
+  label!: string;
+}
+`;
+
+function writeEntities(source: string): void {
+  writeFileSync(join(resourcesDir, "airports.ts"), source);
+}
+
+beforeEach(() => {
+  rmSync(workRoot, { recursive: true, force: true });
+  mkdirSync(resourcesDir, { recursive: true });
+  writeEntities(GOOD_SOURCE);
+});
+
+afterAll(() => {
+  rmSync(workRoot, { recursive: true, force: true });
+});
+
+function makePlugin(overrides: Record<string, unknown> = {}) {
+  return rastackPlugin({
+    resourcesDir,
+    outDir,
+    onError: () => {},
+    ...overrides,
+  });
+}
+
+describe("rastackPlugin — the bundler hooks", () => {
+  it("serves class entities as the virtual manifest module", () => {
+    const plugin = makePlugin();
+    plugin.buildStart();
+
+    expect(plugin.resolveId(VIRTUAL_MANIFEST_ID)).toBe(RESOLVED_MANIFEST_ID);
+    expect(plugin.resolveId("some/other/module")).toBeUndefined();
+
+    const code = plugin.load(RESOLVED_MANIFEST_ID)!;
+    expect(code).toContain("export default manifest");
+    const manifest = plugin.api.manifest();
+    expect(code).toContain(JSON.stringify(manifest));
+
+    // The classes were compiled: fields read off the type system, the
+    // Airport-typed property inferred as a foreign key.
+    // The app name derives from the defining file (airports.ts → "airports").
+    const terminal = manifest.resources.find((r) => r.model === "terminal")!;
+    expect(terminal.relations).toEqual([
+      { field: "airport", target: "airports.airport", kind: "fk" },
+    ]);
+    expect(manifestModuleCode(manifest)).toBe(code);
+  });
+
+  it("writes the artifacts — schema, openapi, env.d.ts, virtual-module types", () => {
+    makePlugin().buildStart();
+    expect(existsSync(join(outDir, "schema.rastack.json"))).toBe(true);
+    expect(existsSync(join(outDir, "openapi.json"))).toBe(true);
+
+    const env = readFileSync(join(outDir, "rastack-env.d.ts"), "utf8");
+    expect(env).toContain('"airports.airport": import("../entities/airports").Airport;');
+
+    const dts = readFileSync(join(outDir, "rastack-plugin.d.ts"), "utf8");
+    expect(dts).toBe(virtualModuleDts());
+    expect(dts).toContain(`declare module "${VIRTUAL_MANIFEST_ID}"`);
+  });
+
+  it("recompiles when a watched entity changes", () => {
+    const plugin = makePlugin();
+    plugin.buildStart();
+    expect(
+      plugin.api.manifest().resources.map((r) => r.model),
+    ).toEqual(["airport", "terminal"]);
+
+    writeEntities(GOOD_SOURCE + "\nexport class Gate { number!: string }\n");
+    plugin.watchChange(join(resourcesDir, "airports.ts"));
+
+    expect(plugin.api.manifest().resources.map((r) => r.model)).toEqual([
+      "airport",
+      "gate",
+      "terminal",
+    ]);
+    expect(plugin.load(RESOLVED_MANIFEST_ID)).toContain('"gate"');
+  });
+
+  it("keeps serving the last good manifest through a broken edit", () => {
+    const errors: unknown[] = [];
+    const plugin = makePlugin({ onError: (e: unknown) => errors.push(e) });
+    plugin.buildStart();
+    const goodCode = plugin.load(RESOLVED_MANIFEST_ID);
+
+    writeEntities(BROKEN_SOURCE);
+    plugin.watchChange(join(resourcesDir, "airports.ts"));
+
+    // The compile failed (reported), but the app keeps its manifest.
+    expect(plugin.load(RESOLVED_MANIFEST_ID)).toBe(goodCode);
+    expect(errors).toHaveLength(1);
+    expect(String((errors[0] as Error).message)).toMatch(/circular/i);
+    expect(plugin.api.error()).toBe(errors[0]);
+
+    // Fixing the file recovers on the next change (load() recompiles).
+    writeEntities(GOOD_SOURCE);
+    plugin.watchChange(join(resourcesDir, "airports.ts"));
+    expect(plugin.load(RESOLVED_MANIFEST_ID)).toBe(goodCode);
+    expect(plugin.api.error()).toBeUndefined();
+  });
+
+  it("throws at startup when there is no good manifest to fall back to", () => {
+    writeEntities(BROKEN_SOURCE);
+    const plugin = makePlugin();
+    expect(() => plugin.buildStart()).toThrow(/circular/i);
+  });
+
+  it("hot-invalidates the virtual module in a Vite-shaped server", () => {
+    const plugin = makePlugin();
+    plugin.buildStart();
+
+    const virtualModule = { id: RESOLVED_MANIFEST_ID };
+    const invalidated: unknown[] = [];
+    const server = {
+      moduleGraph: {
+        getModuleById: (id: string) =>
+          id === RESOLVED_MANIFEST_ID ? virtualModule : undefined,
+        invalidateModule: (mod: unknown) => invalidated.push(mod),
+      },
+    };
+
+    const changed = { id: "changed" };
+    const result = plugin.handleHotUpdate({
+      file: join(resourcesDir, "airports.ts"),
+      server,
+      modules: [changed],
+    });
+    expect(invalidated).toEqual([virtualModule]);
+    expect(result).toEqual([changed, virtualModule]);
+
+    // Unrelated files don't touch the schema.
+    expect(
+      plugin.handleHotUpdate({
+        file: join(workRoot, "App.tsx"),
+        server,
+        modules: [changed],
+      }),
+    ).toBeUndefined();
+  });
+});
+
+describe("auto-registration — no manifest prop anywhere", () => {
+  afterEach(() => {
+    delete (globalThis as Record<string, unknown>)[GLOBAL_MANIFEST_KEY];
+  });
+
+  it("serves a register module that publishes the manifest globally", () => {
+    const plugin = makePlugin();
+    plugin.buildStart();
+
+    expect(plugin.resolveId(VIRTUAL_REGISTER_ID)).toBe(VIRTUAL_REGISTER_ID);
+    const code = plugin.load(VIRTUAL_REGISTER_ID)!;
+    expect(code).toBe(registerModuleCode());
+    expect(code).toContain(`import manifest from "${VIRTUAL_MANIFEST_ID}"`);
+    expect(code).toContain(`globalThis.${GLOBAL_MANIFEST_KEY} = manifest`);
+  });
+
+  it("injects the register script into index.html (dev src, build inline)", () => {
+    const plugin = makePlugin();
+    expect(plugin.transformIndexHtml.order).toBe("pre");
+
+    const dev = plugin.transformIndexHtml.handler("<html/>", { server: {} });
+    expect(dev).toEqual([
+      {
+        tag: "script",
+        attrs: { type: "module", src: `/@id/${VIRTUAL_REGISTER_ID}` },
+        injectTo: "head-prepend",
+      },
+    ]);
+
+    const build = plugin.transformIndexHtml.handler("<html/>", {});
+    expect(build).toEqual([
+      {
+        tag: "script",
+        attrs: { type: "module" },
+        children: `import "${VIRTUAL_REGISTER_ID}";`,
+        injectTo: "head-prepend",
+      },
+    ]);
+  });
+
+  it("the runtime falls back to the registered global manifest", () => {
+    class Airport {
+      code!: string;
+    }
+    // Nothing registered → the class cannot resolve without a manifest.
+    expect(getGlobalManifest()).toBeUndefined();
+    expect(() => resolveEntityRef(Airport, getGlobalManifest())).toThrow(
+      /manifest/,
+    );
+
+    // What the injected register module does at boot:
+    (globalThis as Record<string, unknown>)[GLOBAL_MANIFEST_KEY] = {
+      version: 1,
+      resources: [
+        { app: "airports", model: "airport", fields: [], relations: [] },
+      ],
+    };
+
+    const manifest = getGlobalManifest()!;
+    expect(manifest.resources).toHaveLength(1);
+    expect(getGlobalManifest()).toBe(manifest); // cached per assignment
+    // useRastackManifest (which useData/useForm read outside any provider)
+    // falls back to this global, so a bare useData(Airport) resolves with
+    // zero schema wiring in app code.
+    expect(resolveEntityRef(Airport, getGlobalManifest()).listUrl).toBe(
+      "/api/airports/v1/airport/",
+    );
+  });
+});
+
+describe("isEntitySource — what triggers a recompile", () => {
+  const options = resolveOptions({ resourcesDir, outDir }, workRoot);
+
+  it("accepts .ts/.tsx under the resources dir and nothing else", () => {
+    expect(isEntitySource(join(resourcesDir, "a.ts"), options)).toBe(true);
+    expect(isEntitySource(join(resourcesDir, "deep", "b.tsx"), options)).toBe(true);
+    expect(isEntitySource(join(resourcesDir, "a.d.ts"), options)).toBe(false);
+    expect(isEntitySource(join(resourcesDir, "notes.md"), options)).toBe(false);
+    expect(isEntitySource(join(workRoot, "elsewhere.ts"), options)).toBe(false);
+    // The emitted artifacts must never re-trigger the compiler.
+    expect(isEntitySource(join(outDir, "rastack-env.d.ts"), options)).toBe(false);
+  });
+});
+
+describe("startRastackWatcher — the non-Rollup dev servers", () => {
+  it("compiles at start and rewrites artifacts on save", async () => {
+    const watcher = startRastackWatcher({
+      resourcesDir,
+      outDir,
+      onError: () => {},
+    });
+    try {
+      expect(existsSync(join(outDir, "schema.rastack.json"))).toBe(true);
+      expect(
+        watcher.state.manifest().resources.map((r) => r.model),
+      ).toEqual(["airport", "terminal"]);
+
+      writeEntities(GOOD_SOURCE + "\nexport class Gate { number!: string }\n");
+      await waitFor(() =>
+        readFileSync(join(outDir, "schema.rastack.json"), "utf8").includes(
+          '"gate"',
+        ),
+      );
+    } finally {
+      watcher.close();
+    }
+  });
+});
+
+async function waitFor(check: () => boolean, timeoutMs = 5000): Promise<void> {
+  const start = Date.now();
+  for (;;) {
+    if (check()) return;
+    if (Date.now() - start > timeoutMs) {
+      throw new Error("waitFor: condition not met in time");
+    }
+    await new Promise((r) => setTimeout(r, 50));
+  }
+}