rastack 0.0.49 → 0.0.51

package/src/define/manifest.ts

@@ -0,0 +1,278 @@
+/**
+ * The runtime manifest builder — `resource()` definitions are their own
+ * manifest, **no `rastack compile` step required**.
+ *
+ * The DSL values carry everything the canonical manifest needs at runtime
+ * (field kinds, constraint options, FK target thunks, resource options), so
+ * this module assembles the exact `schema.rastack.json` shape the compiler
+ * emits — same fields, same relations, same normalisation — as a pure
+ * function:
+ *
+ * ```tsx
+ * import { Airport, Terminal, Flight } from "./resources/airports";
+ *
+ * <RAStackProvider mode="local" manifest={[Airport, Terminal, Flight]}>
+ * ```
+ *
+ * The compiler (`tools/src/compile/analyze.ts`) imports the option
+ * normalisers below, so the two paths cannot drift: `rastack compile` remains
+ * the way to get class/interface entities, `openapi.json`, and the artifacts
+ * the Rust backend and admin read — but the typed hooks and the in-browser
+ * engine need only this.
+ *
+ * Everything here is browser-safe: no `typescript`, no filesystem.
+ */
+
+import type {
+  AccessModel,
+  AdminModel,
+  FieldModel,
+  Manifest,
+  RelationModel,
+  ResourceModel,
+  ScalarType,
+  SyncModel,
+} from "../compile/model";
+import { normalizeTransitions } from "../validate/transitions";
+import type { ResourceOptions, ResourceType } from "./index";
+
+/** Any `resource()` value, generics erased. */
+export type AnyResourceValue = ResourceType<string, string, any, any>;
+
+/** Everything `toManifest()` understands — see {@link toManifest}. */
+export type ManifestInput =
+  | Manifest
+  | object
+  | string
+  | AnyResourceValue
+  | readonly AnyResourceValue[];
+
+/** Whether a value is a `resource()` definition. */
+export function isResourceValue(value: unknown): value is AnyResourceValue {
+  return (
+    !!value &&
+    typeof value === "object" &&
+    (value as { __rastack?: unknown }).__rastack === "resource"
+  );
+}
+
+/**
+ * One `resource()` value → its canonical {@link ResourceModel} — the same
+ * shape `rastack compile` derives from the source, produced from the runtime
+ * value instead.
+ */
+export function resourceModel(res: AnyResourceValue): ResourceModel {
+  const fields: FieldModel[] = [];
+  const relations: RelationModel[] = [];
+
+  for (const [name, value] of Object.entries(
+    (res.fields ?? {}) as Record<string, unknown>,
+  )) {
+    const field = runtimeField(res, name, value);
+    if (!field) continue;
+    fields.push(field);
+    if (field.type === "fk" && field.relation) {
+      relations.push({
+        field: name,
+        target: `${field.relation.app}.${field.relation.model}`,
+        kind: "fk",
+      });
+    }
+  }
+
+  const options = (res.options ?? {}) as ResourceOptions;
+  const model: ResourceModel = {
+    app: res.app,
+    model: res.model,
+    fields,
+    relations,
+    sync: normaliseSync(options.sync),
+    admin: normaliseAdmin(options.admin),
+    search: options.search,
+    ordering: options.ordering,
+    permission: options.permission,
+    access: normaliseAccess(options.access),
+  };
+  applyTransitions(model, options.transitions);
+  return model;
+}
+
+/** Resolve one runtime field value to its {@link FieldModel}. */
+function runtimeField(
+  res: AnyResourceValue,
+  name: string,
+  value: unknown,
+): FieldModel | undefined {
+  if (!value || typeof value !== "object") return undefined;
+  const field = value as {
+    __rastackRef?: unknown;
+    __rastackScalar?: unknown;
+    target?: () => AnyResourceValue;
+    options?: Record<string, unknown>;
+  };
+
+  // Foreign key: the runtime value keeps the `() => Resource` thunk, so the
+  // relation target is recovered by calling it — the runtime twin of the
+  // compiler's "read the Ref<App, Model> type arguments" step.
+  if (field.__rastackRef === true) {
+    const target = field.target?.();
+    if (!isResourceValue(target)) {
+      throw new Error(
+        `manifestFromResources: ${res.app}.${res.model}.${name} is an s.ref(...) whose target thunk did not return a resource() value`,
+      );
+    }
+    return {
+      name,
+      type: "fk",
+      relation: { app: target.app, model: target.model },
+    };
+  }
+
+  if (typeof field.__rastackScalar !== "string") return undefined;
+  const model: FieldModel = {
+    name,
+    type: field.__rastackScalar as ScalarType,
+  };
+  // Constraint mapping mirrors the compiler's `applyConstraints` exactly.
+  const opts = field.options;
+  if (opts && typeof opts === "object") {
+    if (typeof opts.maxLength === "number") model.maxLength = opts.maxLength;
+    if (opts.unique === true) model.unique = true;
+    if (opts.primaryKey === true) model.primaryKey = true;
+    if (opts.null === true) model.null = true;
+    if (opts.default !== undefined) model.default = opts.default;
+  }
+  return model;
+}
+
+/**
+ * Assemble the canonical manifest from `resource()` values at runtime —
+ * accepts the values themselves, arrays of them, or whole module namespaces
+ * (`import * as resources from "./resources"`), in any mix. Output order
+ * matches the compiler's (app, then model), so the result is byte-for-byte
+ * the manifest `rastack compile` would emit for the same definitions.
+ */
+export function manifestFromResources(
+  ...inputs: Array<
+    AnyResourceValue | readonly AnyResourceValue[] | Record<string, unknown>
+  >
+): Manifest {
+  const resources: ResourceModel[] = collectResources(inputs).map(resourceModel);
+  resources.sort((a, b) =>
+    a.app === b.app ? a.model.localeCompare(b.model) : a.app.localeCompare(b.app),
+  );
+  return { version: 1, resources };
+}
+
+/** Flatten values / arrays / module namespaces into the resource list. */
+function collectResources(inputs: unknown[]): AnyResourceValue[] {
+  const out: AnyResourceValue[] = [];
+  const seen = new Set<AnyResourceValue>();
+  const push = (res: AnyResourceValue) => {
+    if (!seen.has(res)) {
+      seen.add(res);
+      out.push(res);
+    }
+  };
+  for (const input of inputs) {
+    if (isResourceValue(input)) {
+      push(input);
+    } else if (Array.isArray(input)) {
+      for (const item of input) if (isResourceValue(item)) push(item);
+    } else if (input && typeof input === "object") {
+      for (const item of Object.values(input)) {
+        if (isResourceValue(item)) push(item);
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * Normalise anything a provider may be handed as "the manifest": a compiled
+ * manifest (object or JSON string), a `resource()` value, an array of them,
+ * or a module namespace containing them. This is what lets
+ * `<RAStackProvider manifest={[Airport, Terminal]}>` work with no compiled
+ * `schema.rastack.json` anywhere.
+ */
+export function toManifest(
+  input: ManifestInput | null | undefined,
+): Manifest | undefined {
+  if (input === null || input === undefined) return undefined;
+  if (typeof input === "string") return JSON.parse(input) as Manifest;
+  if (Array.isArray(input) || isResourceValue(input)) {
+    return manifestFromResources(
+      input as AnyResourceValue | readonly AnyResourceValue[],
+    );
+  }
+  const record = input as Record<string, unknown>;
+  // A compiled manifest passes through untouched.
+  if (Array.isArray(record.resources)) return input as Manifest;
+  // A module namespace of resource() exports builds one.
+  const values = Object.values(record).filter(isResourceValue);
+  if (values.length) return manifestFromResources(values);
+  return input as Manifest;
+}
+
+// ---------------------------------------------------------------------------
+// Option normalisers — shared with the compiler (`compile/analyze.ts`), so
+// the runtime and compiled manifests can never disagree about a resource.
+// ---------------------------------------------------------------------------
+
+/**
+ * Attach a normalised `transitions` block to a resource and derive what the
+ * machine implies about its state field: the `states` become the field's
+ * allowed-value set (`enum` in OpenAPI, the `member` gate in validation), and
+ * `initial` becomes its default when the field doesn't declare one.
+ */
+export function applyTransitions(resource: ResourceModel, raw: unknown): void {
+  const transitions = normalizeTransitions(raw);
+  if (!transitions) return;
+  resource.transitions = transitions;
+
+  const stateField = resource.fields.find((f) => f.name === transitions.field);
+  if (stateField && stateField.type !== "fk") {
+    stateField.options = [...transitions.states];
+    if (stateField.default === undefined && transitions.initial !== undefined) {
+      stateField.default = transitions.initial;
+    }
+  }
+}
+
+export function normaliseSync(sync: any): SyncModel | undefined {
+  if (!sync || typeof sync !== "object") return undefined;
+  const mode = sync.mode === "local" ? "local" : "server";
+  if (mode === "server" && !sync.confirmed) {
+    // A bare server resource carries no sync semantics.
+    return undefined;
+  }
+  const model: SyncModel = { mode };
+  if (typeof sync.scope === "string") model.scope = sync.scope;
+  if (Array.isArray(sync.confirmed)) model.confirmed = sync.confirmed;
+  if (sync.load === "lazy") model.load = "lazy";
+  if (sync.clientIds === true) model.clientIds = true;
+  return model;
+}
+
+export function normaliseAccess(access: any): AccessModel | undefined {
+  if (!access || typeof access !== "object") return undefined;
+  const model: AccessModel = {};
+  if (typeof access.ownerField === "string") model.ownerField = access.ownerField;
+  if (access.scope === "owner" || access.scope === "shared") {
+    model.scope = access.scope;
+  }
+  if (Array.isArray(access.adminGroups)) {
+    model.adminGroups = access.adminGroups.filter(
+      (g: unknown) => typeof g === "string",
+    );
+  }
+  return Object.keys(model).length ? model : undefined;
+}
+
+export function normaliseAdmin(admin: any): AdminModel | false | undefined {
+  if (admin === false) return false;
+  if (!admin || typeof admin !== "object") return undefined;
+  const model: AdminModel = {};
+  if (Array.isArray(admin.listDisplay)) model.listDisplay = admin.listDisplay;
+  return model;
+}

package/src/import/tabular.ts

@@ -18,6 +18,7 @@ import {
   type FieldState,
   type RecordRun,
   type SpecRelation,
+  type TransitionsModel,
 } from "../validate";
 
 /** A parsed tabular source: one header row + string cell rows. */
@@ -36,7 +37,7 @@ export interface ColumnMapping {
 export interface ImportIssue {
   row: number;
   field: string;
-  gate: FieldState;
+  gate: FieldState | "transition";
   constraint: string;
   message: string;
 }
@@ -94,6 +95,12 @@ export interface ValidateDatasetOptions {
   relatedIds?: Record<string, Set<string>>;
   /** Custom FK resolver (wins over `relatedIds`). */
   resolveRelation?: (relation: SpecRelation, value: unknown) => boolean;
+  /**
+   * The resource's state machine (`schema.rastack.json` `transitions`).
+   * Imported rows are creates, so the record-level `transition` gate rejects
+   * rows born mid-machine (a state other than the initial one).
+   */
+  transitions?: TransitionsModel;
 }
 
 /**
@@ -108,7 +115,7 @@ export function validateDataset(
   options: ValidateDatasetOptions = {},
 ): ImportReport {
   const { columns, missingFields } = mapHeaders(data.headers, specs);
-  const machine = compileRecordMachine(specs);
+  const machine = compileRecordMachine(specs, options.transitions);
   const ctx = createDatasetContext(machine, options);
 
   const rows: RecordRun[] = [];

package/src/plugin/core.ts

@@ -0,0 +1,236 @@
+/**
+ * The dev-server schema compiler — the way around "classes need a compile
+ * step".
+ *
+ * Class/interface entities have no runtime shape (TypeScript erases their
+ * types), so *something* must run the `ts.Program` + `TypeChecker` to read
+ * fields, `DbConfig` brands and FK types off them. The insight is that it
+ * doesn't have to be a command the developer runs: this module packages the
+ * same `analyzeProject`/`compile` pass the CLI uses so it can live **inside
+ * the dev server that is already running** — a bundler plugin
+ * (`rastackPlugin`, Vite/Rollup-compatible) or a bare filesystem watcher
+ * (`startRastackWatcher`, for anything else). The schema recompiles on every
+ * save, the app imports it as the `virtual:rastack-manifest` module, and
+ * `rastack-env.d.ts` is rewritten so string-key row types stay fresh — the
+ * developer never runs `rastack compile`.
+ *
+ * Design mirrors the rest of `tools/src`: the decisions live here as pure
+ * (or thin-IO) functions, tested in `tools/test/plugin.spec.ts`; the plugin
+ * object in `./index.ts` is a shell over {@link createSchemaState}.
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import { analyzeProject, buildManifest, compile } from "../compile";
+import type { EntityDiagnostic, Manifest } from "../compile";
+
+/** The module id apps import the live manifest from. */
+export const VIRTUAL_MANIFEST_ID = "virtual:rastack-manifest";
+
+/** The resolved (bundler-internal) id — Rollup convention: `\0` prefix. */
+export const RESOLVED_MANIFEST_ID = "\0" + VIRTUAL_MANIFEST_ID;
+
+/**
+ * The auto-registration module the plugin injects into `index.html`: it sets
+ * `globalThis.__RASTACK_MANIFEST__` before the app boots, which is what lets
+ * `<RAStackProvider mode="local">` (and bare `useData(Airport)`) run with
+ * **no manifest wiring in app code at all**. Kept un-prefixed (no `\0`) so
+ * its dev-server URL is a plain `/@id/…`.
+ */
+export const VIRTUAL_REGISTER_ID = "virtual:rastack-manifest/register";
+
+/** The key the register module assigns (mirrored in `rastack/hooks`). */
+export const GLOBAL_MANIFEST_KEY = "__RASTACK_MANIFEST__";
+
+export interface RastackPluginOptions {
+  /**
+   * Directory (or single file) scanned for entities — classes, interfaces
+   * and `resource()` calls alike, recursively (co-located definitions work).
+   * Default `"resources"`; pass `"src"` (or `"."`) for co-located entities.
+   */
+  resourcesDir?: string;
+  /**
+   * Where the artifacts land: `schema.rastack.json`, `openapi.json`,
+   * `rastack-env.d.ts` (the string-key type registry) and
+   * `rastack-plugin.d.ts` (types for the virtual module). Default
+   * `".rastack"` — include it in `tsconfig.json` once.
+   */
+  outDir?: string;
+  /** Skip writing the artifacts to disk (virtual module only). Default false. */
+  emitFiles?: boolean;
+  /** Where compile problems are reported. Default `console.error`. */
+  onError?: (error: unknown) => void;
+}
+
+export interface ResolvedPluginOptions {
+  resourcesDir: string;
+  outDir: string;
+  emitFiles: boolean;
+  onError: (error: unknown) => void;
+}
+
+export function resolveOptions(
+  options: RastackPluginOptions = {},
+  root: string = process.cwd(),
+): ResolvedPluginOptions {
+  return {
+    resourcesDir: path.resolve(root, options.resourcesDir ?? "resources"),
+    outDir: path.resolve(root, options.outDir ?? ".rastack"),
+    emitFiles: options.emitFiles !== false,
+    onError:
+      options.onError ??
+      ((error) =>
+        console.error(
+          `[rastack] schema compile failed — serving the last good manifest\n` +
+            `${error instanceof Error ? error.message : String(error)}`,
+        )),
+  };
+}
+
+/**
+ * Whether a changed file should trigger a schema recompile: a `.ts`/`.tsx`
+ * source under the scanned directory that is not itself an emitted artifact.
+ */
+export function isEntitySource(
+  file: string,
+  options: Pick<ResolvedPluginOptions, "resourcesDir" | "outDir">,
+): boolean {
+  const resolved = path.resolve(file);
+  if (!/\.tsx?$/.test(resolved) || resolved.endsWith(".d.ts")) return false;
+  if (within(resolved, options.outDir)) return false;
+  return (
+    within(resolved, options.resourcesDir) || resolved === options.resourcesDir
+  );
+}
+
+function within(file: string, dir: string): boolean {
+  const rel = path.relative(dir, file);
+  return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
+}
+
+/** The virtual module's source — the manifest as a plain ES module. */
+export function manifestModuleCode(manifest: Manifest): string {
+  const json = JSON.stringify(manifest);
+  return (
+    `// virtual:rastack-manifest — compiled by the rastack dev-server plugin.\n` +
+    `const manifest = ${json};\n` +
+    `export default manifest;\n` +
+    `export { manifest };\n`
+  );
+}
+
+/**
+ * The register module's source: import the live manifest, publish it on the
+ * global the runtime falls back to. A separate module (rather than a side
+ * effect of the manifest module) so explicit `virtual:rastack-manifest`
+ * importers stay side-effect-free.
+ */
+export function registerModuleCode(): string {
+  return (
+    `// ${VIRTUAL_REGISTER_ID} — auto-injected by the rastack plugin.\n` +
+    `import manifest from ${JSON.stringify(VIRTUAL_MANIFEST_ID)};\n` +
+    `globalThis.${GLOBAL_MANIFEST_KEY} = manifest;\n` +
+    `export default manifest;\n`
+  );
+}
+
+/** Types for the virtual module, written once beside `rastack-env.d.ts`. */
+export function virtualModuleDts(): string {
+  return (
+    "// Generated by the rastack plugin — do not edit.\n" +
+    `declare module "${VIRTUAL_MANIFEST_ID}" {\n` +
+    '  const manifest: import("rastack/define").Manifest;\n' +
+    "  export default manifest;\n" +
+    "  export { manifest };\n" +
+    "}\n"
+  );
+}
+
+export interface SchemaState {
+  /**
+   * The virtual module's current source. Compiles (lazily) when stale; on a
+   * compile error reports via `onError` and keeps serving the last good
+   * manifest — a half-typed entity must not blank the running app.
+   */
+  code(): string;
+  /** The current manifest (same laziness/fallback as {@link code}). */
+  manifest(): Manifest;
+  /** Mark the schema stale — the next `code()`/`manifest()` recompiles. */
+  invalidate(): void;
+  /** The error from the most recent failed compile, if it is still failing. */
+  error(): unknown;
+  /** Non-error diagnostics from the last successful compile. */
+  diagnostics(): EntityDiagnostic[];
+  options: ResolvedPluginOptions;
+}
+
+/**
+ * The plugin's whole brain: lazy compile, invalidation, keep-last-good.
+ * Both the bundler plugin and the bare watcher drive this one object.
+ */
+export function createSchemaState(
+  options: RastackPluginOptions = {},
+  root?: string,
+): SchemaState {
+  const resolved = resolveOptions(options, root);
+  let current: { manifest: Manifest; diagnostics: EntityDiagnostic[] } | null =
+    null;
+  let stale = true;
+  let lastError: unknown = undefined;
+
+  const recompile = (): void => {
+    try {
+      const result = runCompile(resolved);
+      current = { manifest: result.manifest, diagnostics: result.diagnostics };
+      lastError = undefined;
+    } catch (error) {
+      lastError = error;
+      resolved.onError(error);
+      if (!current) throw error; // no last-good manifest to fall back to
+    } finally {
+      stale = false;
+    }
+  };
+
+  const ensure = (): { manifest: Manifest; diagnostics: EntityDiagnostic[] } => {
+    if (stale || !current) recompile();
+    return current!;
+  };
+
+  return {
+    code: () => manifestModuleCode(ensure().manifest),
+    manifest: () => ensure().manifest,
+    invalidate: () => {
+      stale = true;
+    },
+    error: () => lastError,
+    diagnostics: () => ensure().diagnostics,
+    options: resolved,
+  };
+}
+
+/**
+ * One compile pass: the same artifacts `rastack compile` writes (manifest,
+ * OpenAPI, `rastack-env.d.ts`), plus the virtual module's type declaration.
+ * With `emitFiles: false` it only analyses (nothing touches disk).
+ */
+export function runCompile(options: ResolvedPluginOptions): {
+  manifest: Manifest;
+  diagnostics: EntityDiagnostic[];
+} {
+  if (!options.emitFiles) {
+    // compile() always writes to disk; the analyse-only path applies the
+    // same error gate without touching the filesystem.
+    const { resources, diagnostics } = analyzeProject(options.resourcesDir);
+    const errors = diagnostics.filter((d) => d.severity === "error");
+    if (errors.length) throw new Error(errors.map((e) => e.message).join("\n"));
+    return { manifest: buildManifest(resources), diagnostics };
+  }
+
+  const result = compile(options.resourcesDir, options.outDir);
+  const dtsPath = path.join(options.outDir, "rastack-plugin.d.ts");
+  if (!fs.existsSync(dtsPath)) {
+    fs.writeFileSync(dtsPath, virtualModuleDts());
+  }
+  return { manifest: result.manifest, diagnostics: result.diagnostics };
+}