rastack 0.0.49 → 0.0.51

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));
+  }
+}

package/test/runtime-manifest.spec.ts

@@ -0,0 +1,309 @@
+/**
+ * The runtime manifest builder — `resource()` definitions are their own
+ * manifest, no `rastack compile` step required.
+ *
+ * The headline test is **parity**: the same definitions, authored once as
+ * source (compiled by the real compiler) and once as runtime values
+ * (assembled by `manifestFromResources`), must produce the identical
+ * manifest. That equivalence is what makes the compile step optional for the
+ * DSL path. Around it: the provider-input normalisation (`toManifest`),
+ * manifest-free entity resolution in the hooks, and the hand-written
+ * `EntityTypesOf` registry types.
+ */
+
+import { mkdirSync, rmSync, writeFileSync } from "fs";
+import { join } from "path";
+import { compile } from "../src/compile";
+import {
+  isResourceValue,
+  manifestFromResources,
+  resource,
+  resourceModel,
+  s,
+  toManifest,
+  type EntityKeyOf,
+  type EntityTypesOf,
+} from "../src/define";
+import { resolveEntityRef } from "../hooks/entity";
+import { initialValuesFromResource } from "../hooks/form/entity-form";
+import { writeSchema } from "../src/compile/openapi";
+import type { Manifest } from "../src/compile/model";
+
+// ---------------------------------------------------------------------------
+// The same definitions twice — as source for the compiler, and as runtime
+// values for manifestFromResources. Keep the two in sync: the parity test
+// exists to prove the two paths agree for identical input.
+// ---------------------------------------------------------------------------
+
+const FIXTURE_SOURCE = `
+import { resource, s } from "rastack/define";
+
+export const Airport = resource(
+  "airports",
+  "airport",
+  {
+    code: s.string({ maxLength: 3, unique: true }),
+    name: s.string({ maxLength: 120 }),
+    open: s.bool({ default: true }),
+    elevation: s.int({ null: true }),
+  },
+  {
+    search: ["code", "name"],
+    ordering: ["code"],
+    admin: { listDisplay: ["code", "name"] },
+    permission: "authenticatedOrReadOnly",
+  },
+);
+
+export const Terminal = resource("airports", "terminal", {
+  airport: s.ref(() => Airport),
+  label: s.string({ maxLength: 20 }),
+});
+
+export const Flight = resource(
+  "airports",
+  "flight",
+  {
+    number: s.string({ maxLength: 8 }),
+    status: s.string({ maxLength: 20 }),
+    owner_id: s.int(),
+  },
+  {
+    search: ["number"],
+    sync: { mode: "local", scope: "owner_id={user.id}", confirmed: ["update"] },
+    access: { ownerField: "owner_id", scope: "owner", adminGroups: ["staff"] },
+    transitions: {
+      field: "status",
+      states: ["scheduled", "boarding", "departed", "cancelled"],
+      initial: "scheduled",
+      on: {
+        board: { from: "scheduled", to: "boarding" },
+        depart: { from: "boarding", to: "departed" },
+        cancel: { from: ["scheduled", "boarding"], to: "cancelled" },
+      },
+    },
+  },
+);
+`;
+
+const Airport = resource(
+  "airports",
+  "airport",
+  {
+    code: s.string({ maxLength: 3, unique: true }),
+    name: s.string({ maxLength: 120 }),
+    open: s.bool({ default: true }),
+    elevation: s.int({ null: true }),
+  },
+  {
+    search: ["code", "name"],
+    ordering: ["code"],
+    admin: { listDisplay: ["code", "name"] },
+    permission: "authenticatedOrReadOnly",
+  },
+);
+
+const Terminal = resource("airports", "terminal", {
+  airport: s.ref(() => Airport),
+  label: s.string({ maxLength: 20 }),
+});
+
+const Flight = resource(
+  "airports",
+  "flight",
+  {
+    number: s.string({ maxLength: 8 }),
+    status: s.string({ maxLength: 20 }),
+    owner_id: s.int(),
+  },
+  {
+    search: ["number"],
+    sync: { mode: "local", scope: "owner_id={user.id}", confirmed: ["update"] },
+    access: { ownerField: "owner_id", scope: "owner", adminGroups: ["staff"] },
+    transitions: {
+      field: "status",
+      states: ["scheduled", "boarding", "departed", "cancelled"],
+      initial: "scheduled",
+      on: {
+        board: { from: "scheduled", to: "boarding" },
+        depart: { from: "boarding", to: "departed" },
+        cancel: { from: ["scheduled", "boarding"], to: "cancelled" },
+      },
+    },
+  },
+);
+
+/** The manifest as it would be serialised — what every consumer reads. */
+function asJson(manifest: Manifest): unknown {
+  return JSON.parse(JSON.stringify(manifest));
+}
+
+describe("manifestFromResources — parity with rastack compile", () => {
+  const workRoot = join(__dirname, "runtime-manifest-fixtures");
+  const resourcesDir = join(workRoot, "resources");
+  const outDir = join(workRoot, ".rastack");
+
+  beforeAll(() => {
+    mkdirSync(resourcesDir, { recursive: true });
+    writeFileSync(join(resourcesDir, "airline.ts"), FIXTURE_SOURCE);
+  });
+
+  afterAll(() => {
+    rmSync(workRoot, { recursive: true, force: true });
+  });
+
+  it("produces the exact manifest the compiler emits for the same definitions", () => {
+    const compiled = compile(workRoot, outDir).manifest;
+    const runtime = manifestFromResources(Airport, Terminal, Flight);
+    expect(asJson(runtime)).toEqual(asJson(compiled));
+
+    // Belt and braces: the interesting derived bits are actually present.
+    const flight = runtime.resources.find((r) => r.model === "flight")!;
+    expect(flight.transitions?.initial).toBe("scheduled");
+    const status = flight.fields.find((f) => f.name === "status")!;
+    expect(status.options).toEqual([
+      "scheduled",
+      "boarding",
+      "departed",
+      "cancelled",
+    ]);
+    expect(status.default).toBe("scheduled"); // machine initial → field default
+    const terminal = runtime.resources.find((r) => r.model === "terminal")!;
+    expect(terminal.relations).toEqual([
+      { field: "airport", target: "airports.airport", kind: "fk" },
+    ]);
+  });
+
+  it("orders resources like the compiler (app, then model)", () => {
+    const runtime = manifestFromResources(Flight, Terminal, Airport);
+    expect(runtime.resources.map((r) => r.model)).toEqual([
+      "airport",
+      "flight",
+      "terminal",
+    ]);
+  });
+
+  it("rejects an s.ref whose runtime target is missing", () => {
+    const broken = {
+      __rastack: "resource",
+      app: "airports",
+      model: "gate",
+      fields: { terminal: { __rastackRef: true } },
+      options: {},
+    } as any;
+    expect(() => resourceModel(broken)).toThrow(/target thunk/);
+  });
+});
+
+describe("toManifest — everything a provider may be handed", () => {
+  const expected = asJson(manifestFromResources(Airport, Terminal));
+
+  it("passes a compiled manifest through (object and JSON string)", () => {
+    const compiledShape = manifestFromResources(Airport, Terminal);
+    expect(toManifest(compiledShape)).toBe(compiledShape);
+    expect(asJson(toManifest(JSON.stringify(compiledShape))!)).toEqual(expected);
+  });
+
+  it("builds from an array of resource() values", () => {
+    expect(asJson(toManifest([Airport, Terminal])!)).toEqual(expected);
+  });
+
+  it("builds from a module namespace of resource() exports", () => {
+    const moduleNamespace = { Airport, Terminal, unrelated: 42, helper: () => 0 };
+    expect(asJson(toManifest(moduleNamespace)!)).toEqual(expected);
+  });
+
+  it("builds from a single resource() value and handles empties", () => {
+    const single = toManifest(Airport)!;
+    expect(single.resources.map((r) => r.model)).toEqual(["airport"]);
+    expect(toManifest(undefined)).toBeUndefined();
+    expect(toManifest(null)).toBeUndefined();
+  });
+
+  it("classifies resource() values", () => {
+    expect(isResourceValue(Airport)).toBe(true);
+    expect(isResourceValue({ app: "a", model: "b" })).toBe(false);
+    expect(isResourceValue("airports.airport")).toBe(false);
+  });
+});
+
+describe("hooks without a manifest — the definition is its own manifest", () => {
+  it("resolveEntityRef synthesises the resource from a resource() value", () => {
+    const resolved = resolveEntityRef(Flight); // no manifest anywhere
+    expect(resolved.listUrl).toBe("/api/airports/v1/flight/");
+    expect(resolved.resource).toBeDefined();
+    expect(resolved.resource!.relations).toEqual([]);
+    expect(resolved.transitions?.on.board).toEqual({
+      from: ["scheduled"],
+      to: "boarding",
+    });
+    // A supplied manifest still wins — the synthesised model is the fallback.
+    const manifest = manifestFromResources(Flight);
+    expect(resolveEntityRef(Flight, manifest).resource).toBe(
+      manifest.resources[0],
+    );
+  });
+
+  it("feeds the same write schema and form defaults the compiled path does", () => {
+    const resolved = resolveEntityRef(Flight);
+    const schema = writeSchema(resolved.resource!, false);
+    expect(schema.properties.status.enum).toEqual([
+      "scheduled",
+      "boarding",
+      "departed",
+      "cancelled",
+    ]);
+    expect(schema["x-rastack-transitions"]).toBe(resolved.resource!.transitions);
+    expect(initialValuesFromResource(resolved.resource!)).toEqual({
+      number: "",
+      status: "scheduled",
+      owner_id: "",
+    });
+  });
+
+  it("synthesises FK relations through the runtime target thunk", () => {
+    const resolved = resolveEntityRef(Terminal);
+    expect(resolved.resource!.relations).toEqual([
+      { field: "airport", target: "airports.airport", kind: "fk" },
+    ]);
+    const schema = writeSchema(resolved.resource!, false);
+    expect(schema.properties.airport["x-rastack-relation"]).toEqual({
+      app: "airports",
+      model: "airport",
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// EntityTypesOf — the hand-written registry, typed from the module itself
+// ---------------------------------------------------------------------------
+
+describe("EntityTypesOf — string-key row types with no codegen", () => {
+  it("derives keys and rows from a resources module", () => {
+    const moduleShape = { Airport, Terminal, Flight, notAResource: 42 };
+    type Registry = EntityTypesOf<typeof moduleShape>;
+
+    // The declaration-merging pattern the docs recommend must compile:
+    // an interface extending the mapped type.
+    interface Merged extends EntityTypesOf<typeof moduleShape> {}
+
+    const key: EntityKeyOf<typeof Airport> = "airports.airport";
+    const row: Registry["airports.airport"] = {
+      id: 1,
+      code: "LHR",
+      name: "Heathrow",
+      open: true,
+      elevation: null, // `null: true` → number | null
+    };
+    const merged: Merged["airports.terminal"] = {
+      id: 2,
+      airport: 1,
+      label: "T5",
+    };
+    // @ts-expect-error — `open` is a boolean
+    const wrong: Registry["airports.airport"] = { ...row, open: "yes" };
+    // @ts-expect-error — non-resource exports contribute no registry keys
+    const nope: Registry["notAResource"] = 42;
+    expect([key, row, merged, wrong, nope]).toBeDefined();
+  });
+});