rastack 0.0.58 → 0.0.60

package/test/typed-hooks.spec.ts

@@ -1,412 +0,0 @@
-/**
- * The pure cores behind `useData(Entity)` / `useForm(Entity)`: resolving a
- * plain TypeScript type to its manifest resource, deriving the write schema
- * (and its form field structures) from the manifest at runtime, and the
- * type-level transition names. The React shells around these are thin; the
- * decisions all live here.
- */
-
-import { mkdirSync, readFileSync, rmSync, writeFileSync, existsSync } from "fs";
-import { join } from "path";
-import {
-  entityModelName,
-  humanizeName,
-  isEntityRef,
-  resolveEntityRef,
-} from "../hooks/entity";
-import { useData } from "../hooks/data";
-import type { RowForKey } from "../hooks/registry";
-import { compile } from "../src/compile";
-import { initialValuesFromResource } from "../hooks/form/entity-form";
-import { getFieldMachine, getFieldStructure } from "../hooks/form/structure";
-import { writeSchema } from "../src/compile/openapi";
-import type { Manifest, ResourceModel } from "../src/compile/model";
-import { resource, s, type TransitionNamesOf } from "../src/define";
-import { runFieldMachine } from "../src/validate";
-
-const airport: ResourceModel = {
-  app: "airports",
-  model: "airport",
-  fields: [
-    { name: "code", type: "string", maxLength: 3, unique: true },
-    { name: "name", type: "string", maxLength: 120 },
-  ],
-  relations: [],
-  admin: { listDisplay: ["code", "name"] },
-};
-
-const flight: ResourceModel = {
-  app: "airports",
-  model: "flight",
-  fields: [
-    { name: "number", type: "string", maxLength: 8 },
-    {
-      name: "status",
-      type: "string",
-      options: ["scheduled", "boarding", "departed"],
-      default: "scheduled",
-    },
-    { name: "active", type: "bool" },
-    { name: "airport", type: "fk", relation: { app: "airports", model: "airport" } },
-  ],
-  relations: [{ field: "airport", target: "airports.airport", kind: "fk" }],
-  transitions: {
-    field: "status",
-    states: ["scheduled", "boarding", "departed"],
-    initial: "scheduled",
-    on: {
-      board: { from: ["scheduled"], to: "boarding" },
-      depart: { from: ["boarding"], to: "departed" },
-    },
-  },
-};
-
-const manifest: Manifest = { version: 1, resources: [airport, flight] };
-
-describe("resolveEntityRef — a type names its resource", () => {
-  it("resolves a class by its (compiler-normalised) name", () => {
-    class Airport {
-      code!: string;
-    }
-    const resolved = resolveEntityRef(Airport, manifest);
-    expect(resolved).toMatchObject({
-      app: "airports",
-      model: "airport",
-      key: "airports.airport",
-      listUrl: "/api/airports/v1/airport/",
-    });
-    expect(resolved.detailUrl(7)).toBe("/api/airports/v1/airport/7/");
-    expect(resolved.resource).toBe(airport);
-  });
-
-  it("strips the generated `I` prefix, like the compiler does", () => {
-    expect(entityModelName("IFlight")).toBe("flight");
-    expect(entityModelName("Flight")).toBe("flight");
-    expect(entityModelName("Item")).toBe("item"); // `It` is not an I-prefix… but `Item` is I+tem
-  });
-
-  it("resolves a `resource()` value directly — manifest optional", () => {
-    const Flight = resource("airports", "flight", {
-      number: s.string({ maxLength: 8 }),
-    });
-    expect(resolveEntityRef(Flight, manifest).resource).toBe(flight);
-    // Without a manifest the value is *its own* manifest: URLs resolve and
-    // the resource model is synthesised from the definition's runtime shape.
-    const bare = resolveEntityRef(Flight);
-    expect(bare.listUrl).toBe("/api/airports/v1/flight/");
-    expect(bare.resource).toMatchObject({
-      app: "airports",
-      model: "flight",
-      fields: [{ name: "number", type: "string", maxLength: 8 }],
-    });
-  });
-
-  it("carries a resource()'s transitions even without a manifest", () => {
-    const Flight = resource(
-      "airports",
-      "flight",
-      { status: s.string({ maxLength: 20 }) },
-      {
-        transitions: {
-          field: "status",
-          states: ["scheduled", "boarding"],
-          on: { board: { from: "scheduled", to: "boarding" } },
-        },
-      },
-    );
-    const resolved = resolveEntityRef(Flight);
-    expect(resolved.transitions).toMatchObject({
-      on: { board: { from: ["scheduled"], to: "boarding" } },
-    });
-  });
-
-  it('resolves "app.model" and bare "model" strings', () => {
-    expect(resolveEntityRef("airports.flight", manifest).resource).toBe(flight);
-    expect(resolveEntityRef("flight", manifest).model).toBe("flight");
-    expect(() => resolveEntityRef("airports.spaceship", manifest)).toThrow(
-      /no resource "airports.spaceship"/,
-    );
-  });
-
-  it("fails loudly on ambiguity and missing manifests", () => {
-    const two: Manifest = {
-      version: 1,
-      resources: [flight, { ...flight, app: "cargo" }],
-    };
-    expect(() => resolveEntityRef("flight", two)).toThrow(/"app.model"/);
-    class Flight {
-      number!: string;
-    }
-    expect(() => resolveEntityRef(Flight, two)).toThrow(/airports\.flight, cargo\.flight/);
-    expect(() => resolveEntityRef(Flight)).toThrow(/manifest/);
-  });
-
-  it("classifies entity refs vs. legacy form props", () => {
-    expect(isEntityRef("airports.flight")).toBe(true);
-    expect(isEntityRef(class A {})).toBe(true);
-    expect(isEntityRef({ app: "a", model: "b" })).toBe(true);
-    expect(isEntityRef({ formValues: {}, mutations: {} })).toBe(false);
-  });
-});
-
-describe("useForm(Entity) — the manifest-derived form core", () => {
-  it("derives form-friendly initial values from the resource", () => {
-    expect(initialValuesFromResource(flight)).toEqual({
-      number: "",
-      status: "scheduled", // the machine's initial state, via the field default
-      active: false,
-      airport: "",
-    });
-  });
-
-  it("derives the same write schema the OpenAPI contract publishes", () => {
-    const schema = writeSchema(flight, false);
-    expect(schema.properties.status.enum).toEqual([
-      "scheduled",
-      "boarding",
-      "departed",
-    ]);
-    expect(schema.properties.airport["x-rastack-relation"]).toEqual({
-      app: "airports",
-      model: "airport",
-    });
-    expect(schema["x-rastack-transitions"]).toBe(flight.transitions);
-  });
-
-  it("renders the state field as a select and runs its member gate", () => {
-    const schema = writeSchema(flight, false);
-
-    const structure = getFieldStructure(schema, "status");
-    expect(structure.type).toBe("select");
-    expect(structure.options).toEqual([
-      { label: "scheduled", value: "scheduled" },
-      { label: "boarding", value: "boarding" },
-      { label: "departed", value: "departed" },
-    ]);
-
-    const machine = getFieldMachine(schema, "status")!;
-    expect(machine.states).toContain("member");
-    expect(runFieldMachine(machine, "boarding").state).toBe("valid");
-    expect(runFieldMachine(machine, "teleported").state).toBe("invalid");
-  });
-
-  it("humanises transition names into button labels", () => {
-    expect(humanizeName("board")).toBe("Board");
-    expect(humanizeName("close_out")).toBe("Close out");
-    expect(humanizeName("markShipped")).toBe("Mark shipped");
-  });
-});
-
-describe("TransitionNamesOf — transition names are literal types", () => {
-  it("reads names from a resource()'s options and a class's static block", () => {
-    const Flight = resource(
-      "airports",
-      "flight",
-      { status: s.string({ maxLength: 20 }) },
-      {
-        transitions: {
-          field: "status",
-          states: ["scheduled", "boarding", "departed"],
-          initial: "scheduled",
-          on: {
-            board: { from: "scheduled", to: "boarding" },
-            depart: { from: "boarding", to: "departed" },
-          },
-        },
-      },
-    );
-    type FlightNames = TransitionNamesOf<typeof Flight>;
-    const boardName: FlightNames = "board";
-    const departName: FlightNames = "depart";
-    // @ts-expect-error — "explode" is not a declared transition
-    const bad: FlightNames = "explode";
-    expect([boardName, departName, bad]).toBeDefined();
-
-    class Order {
-      status = "draft";
-      static transitions = {
-        field: "status",
-        states: ["draft", "placed"],
-        initial: "draft",
-        on: { place: { from: "draft", to: "placed" } },
-      };
-    }
-    type OrderNames = TransitionNamesOf<typeof Order>;
-    const placeName: OrderNames = "place";
-    expect(placeName).toBe("place");
-
-    class Plain {
-      name!: string;
-    }
-    type None = TransitionNamesOf<typeof Plain>; // resolves to never
-    const nothing: None[] = [];
-    expect(nothing).toEqual([]);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Row inference — no type argument needed
-// ---------------------------------------------------------------------------
-
-// What `rastack compile` emits as rastack-env.d.ts (declaration merging into
-// the registry) — hand-rolled here so the inference is exercised in-test.
-declare module "../hooks/registry" {
-  interface EntityTypes {
-    "airports.terminal": { id: number; label: string; airport: number };
-  }
-}
-
-describe("row inference — the type argument is not needed", () => {
-  it("a registered \"app.model\" string resolves its row type", () => {
-    type TerminalRow = RowForKey<"airports.terminal">;
-    const row: TerminalRow = { id: 1, label: "T1", airport: 2 };
-    // @ts-expect-error — `label` is required on the registered row type
-    const missing: TerminalRow = { id: 1, airport: 2 };
-    expect([row, missing]).toBeDefined();
-  });
-
-  it("a resource() value derives its row type from its fields", () => {
-    const Flight = resource("airports", "flight", {
-      number: s.string({ maxLength: 8 }),
-      seats: s.int(),
-      gate: s.string({ maxLength: 5, null: true }),
-      active: s.bool(),
-    });
-    type FlightRow = import("../src/define").RowOf<typeof Flight>;
-    const row: FlightRow = {
-      id: 1,
-      number: "BA1",
-      seats: 180,
-      gate: null, // `null: true` → `string | null`
-      active: true,
-    };
-    // @ts-expect-error — `seats` is a number
-    const wrong: FlightRow = { ...row, seats: "lots" };
-    // @ts-expect-error — `number` is not nullable
-    const wrongNull: FlightRow = { ...row, number: null };
-    expect([row, wrong, wrongNull]).toBeDefined();
-  });
-
-  // Type-level only — never executed (useData is a React hook).
-  function _typeOnly() {
-    const terminals = useData("airports.terminal");
-    const rows: Array<{ id: number; label: string; airport: number }> | undefined =
-      terminals.data;
-    // @ts-expect-error — rows are Terminal-shaped, not Airport-shaped
-    const wrong: Array<{ code: string }> | undefined = terminals.data;
-    return { rows, wrong };
-  }
-
-  it("keeps the explicit generic and unregistered strings working", () => {
-    expect(typeof _typeOnly).toBe("function");
-    function _fallbacks() {
-      interface IGate {
-        id: number;
-        number: string;
-      }
-      const explicit = useData<IGate>("airports.gate"); // unregistered → explicit
-      const gates: IGate[] | undefined = explicit.data;
-      const loose = useData("airports.gate"); // unregistered, no generic → any
-      const anything: undefined | Array<{ whatever: boolean }> = loose.data;
-      return { gates, anything };
-    }
-    expect(typeof _fallbacks).toBe("function");
-  });
-});
-
-describe("rastack compile — the emitted rastack-env.d.ts registry", () => {
-  const workRoot = join(__dirname, "registry-fixtures");
-  const resourcesDir = join(workRoot, "resources");
-  const outDir = join(workRoot, ".rastack");
-
-  beforeAll(() => {
-    mkdirSync(resourcesDir, { recursive: true });
-    writeFileSync(
-      join(resourcesDir, "entities.ts"),
-      `
-export class Airport {
-  code!: string;
-  name!: string;
-}
-
-// Not exported — cannot be imported by the registry, so it is skipped.
-class Secret {
-  token!: string;
-}
-export const _root = [Airport, Secret];
-
-export interface Terminal {
-  id: number;
-  label: string;
-}
-`,
-    );
-    writeFileSync(
-      join(resourcesDir, "flights.ts"),
-      `
-import { resource, s } from "rastack/define";
-
-export const Flight = resource("airports", "flight", {
-  number: s.string({ maxLength: 8 }),
-});
-`,
-    );
-    // The dotted string argument roots the Terminal interface — no type
-    // argument, no JSDoc tag.
-    writeFileSync(
-      join(workRoot, "screen.tsx"),
-      `
-export function Screen() {
-  const terminals = useData("entities.terminal");
-  return terminals;
-}
-declare function useData(key: string): unknown;
-`,
-    );
-  });
-
-  afterAll(() => {
-    rmSync(workRoot, { recursive: true, force: true });
-  });
-
-  it("roots interfaces from dotted string hook arguments and registers every exported entity", () => {
-    const result = compile(workRoot, outDir);
-
-    // The string argument rooted the interface into the manifest…
-    expect(
-      result.manifest.resources.some(
-        (r) => r.app === "entities" && r.model === "terminal",
-      ),
-    ).toBe(true);
-
-    // …and the registry maps keys to the caller's own types.
-    const envPath = join(outDir, "rastack-env.d.ts");
-    expect(result.files).toContain(envPath);
-    const dts = readFileSync(envPath, "utf8");
-    expect(dts).toContain('declare module "rastack/hooks/registry"');
-    expect(dts).toContain(
-      '"entities.airport": import("../resources/entities").Airport;',
-    );
-    expect(dts).toContain(
-      '"entities.terminal": import("../resources/entities").Terminal;',
-    );
-    // DSL consts register through RowOf so string refs infer for them too.
-    expect(dts).toContain(
-      '"airports.flight": import("rastack/define").RowOf<typeof import("../resources/flights").Flight>;',
-    );
-    // Unexported declarations are skipped.
-    expect(dts).not.toContain("Secret");
-  });
-
-  it("emits no registry when nothing is exported", () => {
-    const emptyDir = join(workRoot, "empty");
-    mkdirSync(join(emptyDir, "src"), { recursive: true });
-    writeFileSync(
-      join(emptyDir, "src", "none.ts"),
-      `export const nothing = 1;\n`,
-    );
-    const out = join(emptyDir, "out");
-    compile(emptyDir, out);
-    expect(existsSync(join(out, "rastack-env.d.ts"))).toBe(false);
-  });
-});

package/test/update.spec.ts

@@ -1,152 +0,0 @@
-import {
-  compareSemver,
-  globalPrefixFromPackageDir,
-  installSpec,
-  npmBinary,
-  npmInstallArgs,
-  npmShellCommand,
-  npmSpawnShell,
-  parseUpdateFlags,
-  sanitizeVersion,
-  updateAvailable,
-} from "../src/update";
-
-describe("update — flag parsing", () => {
-  it("defaults to a latest, non-check, non-dry-run update", () => {
-    expect(parseUpdateFlags([])).toEqual({
-      version: "latest",
-      check: false,
-      dryRun: false,
-    });
-  });
-
-  it("takes a bare positional as the target version", () => {
-    expect(parseUpdateFlags(["0.0.40"]).version).toBe("0.0.40");
-  });
-
-  it("accepts --version / --to and the check + dry-run flags", () => {
-    expect(parseUpdateFlags(["--version", "1.2.3"]).version).toBe("1.2.3");
-    expect(parseUpdateFlags(["--to", "1.2.3"]).version).toBe("1.2.3");
-    expect(parseUpdateFlags(["--check"]).check).toBe(true);
-    expect(parseUpdateFlags(["--dry-run"]).dryRun).toBe(true);
-    expect(parseUpdateFlags(["--print"]).dryRun).toBe(true);
-  });
-});
-
-describe("update — npm spec + args", () => {
-  it("installs bare `rastack` for latest, pinned otherwise", () => {
-    expect(installSpec("latest")).toBe("rastack");
-    expect(installSpec("")).toBe("rastack");
-    expect(installSpec("0.0.40")).toBe("rastack@0.0.40");
-  });
-
-  it("builds a quiet global install argv", () => {
-    expect(npmInstallArgs("latest")).toEqual([
-      "install",
-      "-g",
-      "rastack",
-      "--no-fund",
-      "--no-audit",
-      "--loglevel=error",
-    ]);
-    expect(npmInstallArgs("0.0.40")[2]).toBe("rastack@0.0.40");
-  });
-
-  it("spawns npm.cmd on Windows and plain npm elsewhere", () => {
-    // npm is a `.cmd` shim on Windows; execFile (no shell) can't launch a bare
-    // `npm` there, so the wrapper must target `npm.cmd`. POSIX keeps `npm`.
-    expect(npmBinary("win32")).toBe("npm.cmd");
-    expect(npmBinary("linux")).toBe("npm");
-    expect(npmBinary("darwin")).toBe("npm");
-  });
-
-  it("runs npm through a shell only on Windows", () => {
-    // A `.cmd` shim can't be spawned directly since the Node CVE-2024-27980 fix
-    // (spawnSync npm.cmd EINVAL) — it must go through cmd.exe. POSIX spawns npm
-    // directly so there is no shell and no injection surface.
-    expect(npmSpawnShell("win32")).toBe(true);
-    expect(npmSpawnShell("linux")).toBe(false);
-    expect(npmSpawnShell("darwin")).toBe(false);
-  });
-
-  it("joins the shell command as one string (avoids the Node DEP0190 warning)", () => {
-    // The Windows path runs npm via `execSync(<string>)` rather than
-    // `execFileSync(npm, args, { shell: true })`, which Node 22+ deprecates
-    // (args concatenated, not escaped). The sanitized version keeps it safe.
-    expect(npmShellCommand("npm.cmd", npmInstallArgs("latest"))).toBe(
-      "npm.cmd install -g rastack --no-fund --no-audit --loglevel=error",
-    );
-    expect(npmShellCommand("npm.cmd", npmInstallArgs("0.0.42"))).toContain(
-      "rastack@0.0.42",
-    );
-  });
-});
-
-describe("update — version sanitization", () => {
-  it("keeps valid semver, dist-tags, and pinned versions", () => {
-    expect(sanitizeVersion("latest")).toBe("latest");
-    expect(sanitizeVersion("next")).toBe("next");
-    expect(sanitizeVersion("0.0.40")).toBe("0.0.40");
-    expect(sanitizeVersion("1.2.3-beta.1")).toBe("1.2.3-beta.1");
-  });
-
-  it("falls back to latest for empty or shell-unsafe input", () => {
-    expect(sanitizeVersion(undefined)).toBe("latest");
-    expect(sanitizeVersion("")).toBe("latest");
-    // Shell metacharacters must never reach the Windows shell-spawned npm.
-    expect(sanitizeVersion("0.0.40; rm -rf /")).toBe("latest");
-    expect(sanitizeVersion("$(whoami)")).toBe("latest");
-    expect(sanitizeVersion("a b")).toBe("latest");
-  });
-
-  it("is applied when parsing the bare positional and --version", () => {
-    expect(parseUpdateFlags(["0.0.40; evil"]).version).toBe("latest");
-    expect(parseUpdateFlags(["--version", "&& evil"]).version).toBe("latest");
-    expect(parseUpdateFlags(["0.0.40"]).version).toBe("0.0.40");
-  });
-});
-
-describe("update — global prefix derivation", () => {
-  it("derives the per-user prefix from a POSIX global install", () => {
-    expect(
-      globalPrefixFromPackageDir("/home/me/.rastack/lib/node_modules/rastack"),
-    ).toBe("/home/me/.rastack");
-  });
-
-  it("derives the prefix from a Windows global install", () => {
-    expect(
-      globalPrefixFromPackageDir(
-        "C:\\Users\\me\\.rastack\\node_modules\\rastack",
-      ),
-    ).toBe("C:\\Users\\me\\.rastack");
-  });
-
-  it("prefers the lib/node_modules layout when both could match", () => {
-    // POSIX path also contains `/node_modules/` — the lib form must win so the
-    // prefix is the install root, not `<root>/lib`.
-    expect(
-      globalPrefixFromPackageDir("/opt/tools/lib/node_modules/rastack"),
-    ).toBe("/opt/tools");
-  });
-
-  it("returns null for a source checkout (not under node_modules)", () => {
-    expect(
-      globalPrefixFromPackageDir("/home/me/src/reactapistack/tools"),
-    ).toBeNull();
-  });
-});
-
-describe("update — semver comparison", () => {
-  it("orders versions numerically, ignoring a `v` prefix and pre-release", () => {
-    expect(compareSemver("0.0.9", "0.0.10")).toBe(-1);
-    expect(compareSemver("v1.2.0", "1.2.0")).toBe(0);
-    expect(compareSemver("2.0.0", "1.9.9")).toBe(1);
-    expect(compareSemver("1.0.0-beta", "1.0.0")).toBe(0);
-  });
-
-  it("reports whether an update is available", () => {
-    expect(updateAvailable("0.0.33", "0.0.40")).toBe(true);
-    expect(updateAvailable("0.0.40", "0.0.40")).toBe(false);
-    expect(updateAvailable("0.1.0", "0.0.40")).toBe(false);
-  });
-});