rastack 0.0.58 → 0.0.59

package/test/entities.spec.ts

@@ -1,597 +0,0 @@
-import { mkdirSync, rmSync, writeFileSync } from "fs";
-import { join } from "path";
-import {
-  analyzeProject,
-  buildOpenApi,
-  compile,
-  detectCycles,
-  ResourceModel,
-} from "../src/compile";
-
-/**
- * Interface-driven inference: the app's entities are plain TypeScript
- * interfaces, discovered from the typed hook calls that consume them. The
- * fixtures are real `.ts`/`.tsx` files so the TypeChecker resolves the
- * interfaces exactly as it would in a consumer project.
- */
-const workRoot = join(__dirname, "entities-fixtures");
-const appDir = join(workRoot, "app");
-const classesDir = join(workRoot, "classes");
-const authDir = join(workRoot, "auth");
-const cycleDir = join(workRoot, "cycles");
-const hardCycleDir = join(workRoot, "hard-cycles");
-const mixedDir = join(workRoot, "mixed");
-const outDir = join(workRoot, "out");
-
-const AIRPORTS_TS = `
-/** @rastackSearch code,name */
-export interface Airport {
-  /**
-   * @maxLength 3
-   * @unique
-   */
-  code: string;
-  /** @maxLength 120 */
-  name: string;
-  terminals?: Terminal[]; // reverse side of Terminal.airport — no column
-}
-
-export interface Terminal {
-  airport: Airport; // FK — inferred from the property type
-  /** @maxLength 20 */
-  label: string;
-}
-
-/** Never consumed by a hook and never referenced — not a resource. */
-export interface Runway {
-  heading: number;
-}
-`;
-
-const FLIGHTS_TS = `
-import { Terminal } from "./airports";
-
-export interface Flight {
-  /** @maxLength 8 */
-  number: string;
-  /** @int */
-  seats: number;
-  onTime: boolean;
-  departure: Date;
-  notes?: string;
-  /** @default scheduled */
-  status: string;
-  terminal: Terminal | null; // nullable FK across files
-  tags: string[]; // unsupported — skipped with a warning
-}
-
-/** @rastackResource
- *  @rastackApp bookings
- *  @rastackModel booking
- */
-export interface IBookingRecord {
-  reference: string;
-}
-`;
-
-const PASSENGERS_TS = `
-import {
-  DbConfig,
-  Default,
-  Int,
-  MaxLength,
-  PrimaryKey,
-  Unique,
-  UUID,
-} from "rastack/db";
-import { Terminal } from "./airports";
-
-/** A reusable column config — "extend DbConfig once, use it everywhere". */
-interface SeatCode extends DbConfig<{ maxLength: 4; unique: true }> {}
-
-export interface Passenger {
-  id: UUID & PrimaryKey;
-  seat: string & SeatCode;
-  fullName: string & MaxLength<80>;
-  age: Int;
-  loyaltyPoints: number & Default<0>;
-  status: string & Default<"active">;
-  terminal?: Terminal;
-}
-
-declare function useEntityList<T>(name: string): T[];
-export const p = useEntityList<Passenger>("passengers");
-`;
-
-const SCREENS_TSX = `
-import { Flight } from "./flights";
-
-declare function useEntityList<T>(name: string): T[];
-
-export function FlightsScreen() {
-  // The hook call is what roots the entity graph.
-  return useEntityList<Flight>("flights");
-}
-`;
-
-const SOFT_CYCLE_TS = `
-export interface Employee {
-  name: string;
-  manager?: Employee; // optional self-FK — breakable cycle
-}
-
-declare function useEntity<T>(name: string): T;
-export const e = useEntity<Employee>("employee");
-`;
-
-const HARD_CYCLE_TS = `
-export interface Chicken {
-  egg: Egg;
-}
-export interface Egg {
-  chicken: Chicken;
-}
-
-declare function useEntity<T>(name: string): T;
-export const c = useEntity<Chicken>("chicken");
-`;
-
-const MIXED_TS = `
-import { resource, s } from "rastack/define";
-
-export const AirportResource = resource("mixed", "airport", {
-  code: s.string({ maxLength: 3, unique: true }),
-}, { admin: { listDisplay: ["code"] } });
-
-/** @rastackApp mixed */
-export interface Airport {
-  code: string;
-}
-
-declare function useEntity<T>(name: string): T;
-export const a = useEntity<Airport>("airport");
-`;
-
-const CLASSES_TS = `
-import { MaxLength, Unique } from "rastack/types";
-
-/** @rastackSearch code,name */
-export class Airport {
-  code!: string & Unique & MaxLength<3>;
-  /** @maxLength 120 */
-  name!: string;
-  region = "EU";        // initializer → type inferred, value is the default
-  active = true;
-  /** @int */
-  gates = 0;
-}
-
-export class Terminal {
-  airport!: Airport;    // FK — inferred from the property type
-  /** @maxLength 20 */
-  label!: string;
-  opened?: Date;
-  static kind = "terminal";        // not a column
-  private secret!: string;         // not a column
-}
-
-/** Not a plain data class — a method means it must opt in explicitly. */
-export class BoardingService {
-  queue: string[] = [];
-  board(): void {}
-}
-
-/** Heritage means app code, not a table. */
-export class SplashScreen extends BoardingService {}
-`;
-
-const AUTH_TS = `
-import {
-  AdminGroups,
-  Group,
-  IsAuthenticated,
-  IsAuthenticatedOrReadOnly,
-  Owner,
-  OwnerScoped,
-  SharedStorage,
-} from "rastack/auth";
-
-// Per-user rows: RLS on owner, physically partitioned per identity. The
-// implements clause is policy, not behaviour — still a plain data class.
-export class Itinerary
-  implements IsAuthenticated, AdminGroups<"staff">, OwnerScoped
-{
-  owner!: string & Owner;
-  notes!: string;
-}
-
-// A group-owned dataset — physically partitioned per group by default.
-export class Report
-  implements IsAuthenticatedOrReadOnly, AdminGroups<"staff" | "ops">
-{
-  team!: string & Group;
-  title!: string;
-}
-
-// Group RLS, but explicitly opted out of per-group storage.
-export class Note implements SharedStorage {
-  team!: string & Group;
-  body!: string;
-}
-
-// Interfaces attach the same markers with extends.
-export interface Memo extends IsAuthenticated, AdminGroups<"staff"> {
-  body: string;
-}
-
-/** JSDoc equivalents, tag-for-marker.
- * @rastackResource
- * @rastackPermission public
- * @rastackAdminGroups staff, ops
- */
-export interface Bulletin {
-  /** @owner */
-  author: string;
-  text: string;
-}
-
-declare function useEntityList<T>(name: string): T[];
-export const m = useEntityList<Memo>("memos");
-`;
-
-function findResource(
-  resources: ResourceModel[],
-  app: string,
-  model: string,
-): ResourceModel {
-  const found = resources.find((r) => r.app === app && r.model === model);
-  if (!found) throw new Error(`missing ${app}.${model}`);
-  return found;
-}
-
-beforeAll(() => {
-  mkdirSync(appDir, { recursive: true });
-  writeFileSync(join(appDir, "airports.ts"), AIRPORTS_TS);
-  writeFileSync(join(appDir, "flights.ts"), FLIGHTS_TS);
-  writeFileSync(join(appDir, "passengers.ts"), PASSENGERS_TS);
-  writeFileSync(join(appDir, "screens.tsx"), SCREENS_TSX);
-  mkdirSync(classesDir, { recursive: true });
-  writeFileSync(join(classesDir, "airports.ts"), CLASSES_TS);
-  mkdirSync(authDir, { recursive: true });
-  writeFileSync(join(authDir, "workspace.ts"), AUTH_TS);
-  mkdirSync(cycleDir, { recursive: true });
-  writeFileSync(join(cycleDir, "org.ts"), SOFT_CYCLE_TS);
-  mkdirSync(hardCycleDir, { recursive: true });
-  writeFileSync(join(hardCycleDir, "paradox.ts"), HARD_CYCLE_TS);
-  mkdirSync(mixedDir, { recursive: true });
-  writeFileSync(join(mixedDir, "airport.ts"), MIXED_TS);
-});
-
-afterAll(() => {
-  rmSync(workRoot, { recursive: true, force: true });
-});
-
-describe("interface entities — discovery from hooks", () => {
-  it("roots the graph at hook type arguments and closes over FK references", () => {
-    const { resources } = analyzeProject(appDir);
-    const keys = resources.map((r) => `${r.app}.${r.model}`);
-
-    // Flight is the hook root; Terminal and Airport are pulled in through the
-    // FK chain flight → terminal → airport.
-    expect(keys).toContain("flights.flight");
-    expect(keys).toContain("airports.terminal");
-    expect(keys).toContain("airports.airport");
-
-    // Declared but neither hooked nor referenced — not a resource.
-    expect(keys).not.toContain("airports.runway");
-  });
-
-  it("includes @rastackResource interfaces and honours @rastackApp/@rastackModel + I-prefix stripping", () => {
-    const { resources } = analyzeProject(appDir);
-    const booking = findResource(resources, "bookings", "booking");
-    expect(booking.fields).toEqual([{ name: "reference", type: "string" }]);
-  });
-
-  it("names entities from the interface and the defining file", () => {
-    const { resources } = analyzeProject(appDir);
-    // airports.ts → app "airports"; interface Airport → model "airport".
-    const airport = findResource(resources, "airports", "airport");
-    expect(airport.search).toEqual(["code", "name"]);
-  });
-});
-
-describe("interface entities — datatypes from the type system", () => {
-  it("maps property types to manifest scalars with JSDoc refinements", () => {
-    const { resources } = analyzeProject(appDir);
-    const flight = findResource(resources, "flights", "flight");
-    const field = (name: string) => flight.fields.find((f) => f.name === name);
-
-    expect(field("number")).toMatchObject({ type: "string", maxLength: 8 });
-    expect(field("seats")).toMatchObject({ type: "int" }); // number + @int
-    expect(field("onTime")).toMatchObject({ type: "bool" });
-    expect(field("departure")).toMatchObject({ type: "datetime" });
-    expect(field("notes")).toMatchObject({ type: "string", null: true });
-    expect(field("status")).toMatchObject({
-      type: "string",
-      default: "scheduled",
-    });
-  });
-
-  it("reads constraint tags (@maxLength/@unique) off interface properties", () => {
-    const { resources } = analyzeProject(appDir);
-    const airport = findResource(resources, "airports", "airport");
-    expect(airport.fields.find((f) => f.name === "code")).toMatchObject({
-      type: "string",
-      maxLength: 3,
-      unique: true,
-    });
-  });
-
-  it("reads column config from DbConfig brand types", () => {
-    const { resources } = analyzeProject(appDir);
-    const passenger = findResource(resources, "passengers", "passenger");
-    const field = (name: string) =>
-      passenger.fields.find((f) => f.name === name);
-
-    expect(field("id")).toMatchObject({ type: "uuid", primaryKey: true });
-    expect(field("fullName")).toMatchObject({ type: "string", maxLength: 80 });
-    expect(field("age")).toMatchObject({ type: "int" });
-    expect(field("loyaltyPoints")).toMatchObject({ type: "float", default: 0 });
-    expect(field("status")).toMatchObject({
-      type: "string",
-      default: "active",
-    });
-    expect(field("terminal")).toMatchObject({
-      type: "fk",
-      null: true,
-      relation: { app: "airports", model: "terminal" },
-    });
-  });
-
-  it("supports reusable configs that extend DbConfig", () => {
-    const { resources } = analyzeProject(appDir);
-    const passenger = findResource(resources, "passengers", "passenger");
-    expect(passenger.fields.find((f) => f.name === "seat")).toMatchObject({
-      type: "string",
-      maxLength: 4,
-      unique: true,
-    });
-
-    // The brand interface itself is configuration, not an entity.
-    expect(
-      resources.find((r) => r.model.toLowerCase().includes("seatcode")),
-    ).toBeUndefined();
-  });
-
-  it("skips unsupported property types with a warning", () => {
-    const { resources, diagnostics } = analyzeProject(appDir);
-    const flight = findResource(resources, "flights", "flight");
-    expect(flight.fields.find((f) => f.name === "tags")).toBeUndefined();
-    expect(
-      diagnostics.some(
-        (d) =>
-          d.severity === "warning" && d.message.includes("flights.flight.tags"),
-      ),
-    ).toBe(true);
-  });
-});
-
-describe("interface entities — FK inference", () => {
-  it("treats an interface-typed property as a foreign key", () => {
-    const { resources } = analyzeProject(appDir);
-    const terminal = findResource(resources, "airports", "terminal");
-
-    expect(terminal.fields.find((f) => f.name === "airport")).toMatchObject({
-      type: "fk",
-      relation: { app: "airports", model: "airport" },
-    });
-    expect(terminal.relations).toEqual([
-      { field: "airport", target: "airports.airport", kind: "fk" },
-    ]);
-  });
-
-  it("maps `Entity | null` to a nullable foreign key", () => {
-    const { resources } = analyzeProject(appDir);
-    const flight = findResource(resources, "flights", "flight");
-    expect(flight.fields.find((f) => f.name === "terminal")).toMatchObject({
-      type: "fk",
-      null: true,
-      relation: { app: "airports", model: "terminal" },
-    });
-  });
-
-  it("ignores `Entity[]` arrays — the reverse side of the FK", () => {
-    const { resources } = analyzeProject(appDir);
-    const airport = findResource(resources, "airports", "airport");
-    expect(airport.fields.find((f) => f.name === "terminals")).toBeUndefined();
-    expect(airport.relations).toEqual([]);
-  });
-});
-
-describe("class entities — plain data classes", () => {
-  it("roots a plain data class by declaration — no hook, tag, or DSL needed", () => {
-    const { resources } = analyzeProject(classesDir);
-    const keys = resources.map((r) => `${r.app}.${r.model}`);
-    expect(keys).toContain("airports.airport");
-    expect(keys).toContain("airports.terminal");
-  });
-
-  it("does not root classes with methods or heritage clauses", () => {
-    const { resources } = analyzeProject(classesDir);
-    const keys = resources.map((r) => `${r.app}.${r.model}`);
-    expect(keys).not.toContain("airports.boardingService");
-    expect(keys).not.toContain("airports.splashScreen");
-  });
-
-  it("reads DbConfig brands and JSDoc tags off class fields", () => {
-    const { resources } = analyzeProject(classesDir);
-    const airport = findResource(resources, "airports", "airport");
-    expect(airport.search).toEqual(["code", "name"]);
-    expect(airport.fields.find((f) => f.name === "code")).toMatchObject({
-      type: "string",
-      maxLength: 3,
-      unique: true,
-    });
-    expect(airport.fields.find((f) => f.name === "name")).toMatchObject({
-      type: "string",
-      maxLength: 120,
-    });
-  });
-
-  it("infers types and defaults from field initializers", () => {
-    const { resources } = analyzeProject(classesDir);
-    const airport = findResource(resources, "airports", "airport");
-    const field = (name: string) => airport.fields.find((f) => f.name === name);
-    expect(field("region")).toMatchObject({ type: "string", default: "EU" });
-    expect(field("active")).toMatchObject({ type: "bool", default: true });
-    expect(field("gates")).toMatchObject({ type: "int", default: 0 });
-  });
-
-  it("treats a class-typed field as a foreign key", () => {
-    const { resources } = analyzeProject(classesDir);
-    const terminal = findResource(resources, "airports", "terminal");
-    expect(terminal.fields.find((f) => f.name === "airport")).toMatchObject({
-      type: "fk",
-      relation: { app: "airports", model: "airport" },
-    });
-    expect(terminal.relations).toEqual([
-      { field: "airport", target: "airports.airport", kind: "fk" },
-    ]);
-    expect(terminal.fields.find((f) => f.name === "opened")).toMatchObject({
-      type: "datetime",
-      null: true,
-    });
-  });
-
-  it("ignores static and private class members", () => {
-    const { resources } = analyzeProject(classesDir);
-    const terminal = findResource(resources, "airports", "terminal");
-    expect(terminal.fields.find((f) => f.name === "kind")).toBeUndefined();
-    expect(terminal.fields.find((f) => f.name === "secret")).toBeUndefined();
-  });
-});
-
-describe("entity access policy — auth as types", () => {
-  it("reads permission / adminGroups / scope markers off a class's implements clause", () => {
-    const { resources } = analyzeProject(authDir);
-    const itinerary = findResource(resources, "workspace", "itinerary");
-    expect(itinerary.permission).toBe("authenticated");
-    expect(itinerary.access).toEqual({
-      ownerField: "owner",
-      scope: "owner",
-      adminGroups: ["staff"],
-    });
-  });
-
-  it("a Group field makes a group-owned dataset — partitioned per group by default", () => {
-    const { resources } = analyzeProject(authDir);
-    const report = findResource(resources, "workspace", "report");
-    expect(report.permission).toBe("authenticatedOrReadOnly");
-    expect(report.access).toEqual({
-      groupField: "team",
-      scope: "group",
-      adminGroups: ["ops", "staff"],
-    });
-    // The group column is an ordinary string field in the schema.
-    expect(report.fields.find((f) => f.name === "team")?.type).toBe("string");
-  });
-
-  it("SharedStorage opts a Group dataset out of physical partitioning", () => {
-    const { resources } = analyzeProject(authDir);
-    const note = findResource(resources, "workspace", "note");
-    expect(note.access).toEqual({ groupField: "team", scope: "shared" });
-  });
-
-  it("interfaces attach markers via extends; markers add no columns", () => {
-    const { resources } = analyzeProject(authDir);
-    const memo = findResource(resources, "workspace", "memo");
-    expect(memo.permission).toBe("authenticated");
-    expect(memo.access).toEqual({ adminGroups: ["staff"] });
-    expect(memo.fields.map((f) => f.name)).toEqual(["body"]);
-  });
-
-  it("JSDoc tags mirror every marker (@rastackPermission/@rastackAdminGroups/@owner)", () => {
-    const { resources } = analyzeProject(authDir);
-    const bulletin = findResource(resources, "workspace", "bulletin");
-    expect(bulletin.permission).toBe("public");
-    expect(bulletin.access).toEqual({
-      ownerField: "author",
-      adminGroups: ["staff", "ops"],
-    });
-  });
-});
-
-describe("interface entities — circular dependencies", () => {
-  it("reports a breakable cycle (optional self-FK) as a warning", () => {
-    const { diagnostics } = analyzeProject(cycleDir);
-    const cycle = diagnostics.find((d) =>
-      d.message.includes("Circular dependency"),
-    );
-    expect(cycle).toBeDefined();
-    expect(cycle!.severity).toBe("warning");
-    expect(cycle!.message).toContain("org.employee → org.employee");
-    expect(cycle!.message).toContain("org.employee.manager");
-  });
-
-  it("reports an unbreakable cycle (all FKs required) as an error", () => {
-    const { diagnostics } = analyzeProject(hardCycleDir);
-    const cycle = diagnostics.find((d) => d.severity === "error");
-    expect(cycle).toBeDefined();
-    expect(cycle!.message).toContain("Circular dependency");
-    expect(cycle!.message).toMatch(/paradox\.(chicken|egg)/);
-  });
-
-  it("compile() refuses to emit a manifest containing an unbreakable cycle", () => {
-    expect(() => compile(hardCycleDir, outDir)).toThrow(/Circular dependency/);
-  });
-
-  it("detectCycles also covers DSL-authored relations", () => {
-    const resources: ResourceModel[] = [
-      {
-        app: "a",
-        model: "x",
-        fields: [{ name: "y", type: "fk", relation: { app: "a", model: "y" } }],
-        relations: [{ field: "y", target: "a.y", kind: "fk" }],
-      },
-      {
-        app: "a",
-        model: "y",
-        fields: [{ name: "x", type: "fk", relation: { app: "a", model: "x" } }],
-        relations: [{ field: "x", target: "a.x", kind: "fk" }],
-      },
-    ];
-    const diagnostics = detectCycles(resources);
-    expect(diagnostics).toHaveLength(1);
-    expect(diagnostics[0].severity).toBe("error");
-  });
-});
-
-describe("interface entities — merging with the resource() DSL", () => {
-  it("prefers the explicit DSL definition when both define the same app.model", () => {
-    const { resources } = analyzeProject(mixedDir);
-    const airports = resources.filter(
-      (r) => r.app === "mixed" && r.model === "airport",
-    );
-    expect(airports).toHaveLength(1);
-    // The DSL definition (with admin config) won over the inferred interface.
-    expect(airports[0].admin).toEqual({ listDisplay: ["code"] });
-  });
-});
-
-describe("interface entities — OpenAPI emission", () => {
-  it("inferred resources reproduce the /api/{app}/v1/{model}/ contract", () => {
-    const { resources } = analyzeProject(appDir);
-    const doc = buildOpenApi(resources);
-
-    expect(doc.paths["/api/flights/v1/flight/"]).toBeDefined();
-    expect(doc.paths["/api/flights/v1/flight/{id}/"]).toBeDefined();
-    expect(doc.paths["/api/airports/v1/terminal/"]).toBeDefined();
-
-    // The inferred FK carries the relation extension the admin/codegen follow.
-    const flightSchema = doc.components.schemas.Flight;
-    expect(flightSchema.properties.terminal["x-rastack-relation"]).toEqual({
-      app: "airports",
-      model: "terminal",
-    });
-  });
-});