rastack 0.0.22 → 0.0.23

package/src/compile/entities.ts

@@ -0,0 +1,602 @@
+import * as path from "path";
+import * as ts from "typescript";
+import { FieldModel, RelationModel, ResourceModel, ScalarType } from "./model";
+import { resourceSourceFiles } from "./program";
+
+/**
+ * Interface-driven resource inference — "the entities in the app are a list of
+ * interfaces".
+ *
+ * Instead of (or alongside) the `resource()` DSL, an app can describe its data
+ * as plain TypeScript interfaces and consume them through typed hooks. The
+ * analyser works the resource graph out from the *usage*:
+ *
+ * 1. **Roots come from the hooks.** Every hook call that carries a type
+ *    argument — `useEntityList<Airport>(…)`, `useQuery<Terminal>(…)` — marks
+ *    the interface behind that type argument as an entity. An interface can
+ *    also opt in explicitly with a `@rastackResource` JSDoc tag.
+ * 2. **Datatypes come from the interfaces.** Each property's TypeScript type
+ *    maps to a manifest scalar (`string` → string, `number` → float,
+ *    `boolean` → bool, `Date` → datetime). Constraints are carried in the
+ *    type system with `DbConfig` brands from `rastack/types` —
+ *    `code: string & Unique & MaxLength<3>`, `age: Int` — or, equivalently,
+ *    as JSDoc tags (`@unique`, `@maxLength 3`, `@int`, `@uuid`, `@default`).
+ *    Optional / `| null` properties become nullable fields.
+ * 3. **Foreign keys come from the type system.** A property whose type is
+ *    another entity interface is a foreign key, and the referenced interface
+ *    is pulled into the resource graph transitively — the closure of the
+ *    hook-rooted interfaces is the app's resource set.
+ * 4. **Circular dependencies are detected.** The FK graph is walked for
+ *    cycles; a cycle is an *error* when every edge in it is required (no row
+ *    could ever be inserted) and a *warning* when it is breakable through a
+ *    nullable field (e.g. an optional self-referencing `manager`).
+ *
+ * ```ts
+ * // entities/airports.ts
+ * export interface Airport {
+ *   code: string;   // JSDoc tags refine: @maxLength 3, @unique
+ *   name: string;
+ * }
+ * export interface Terminal {
+ *   airport: Airport;   // FK — inferred from the property type
+ *   label: string;
+ * }
+ *
+ * // app/screen.tsx — the hook call is what roots the graph
+ * const terminals = useEntityList<Terminal>("terminals");
+ * // → resources: airports.terminal (root) + airports.airport (transitive)
+ * ```
+ *
+ * Naming: `model` is the lower-camel interface name (a leading `I` prefix as
+ * in generated `IFlight` interfaces is stripped, so hook usage of generated
+ * types round-trips onto the same resource); `app` defaults to the defining
+ * file's basename. Both are overridable with `@rastackApp` / `@rastackModel` tags.
+ */
+
+export interface EntityDiagnostic {
+  severity: "error" | "warning";
+  message: string;
+}
+
+export interface EntityAnalysis {
+  resources: ResourceModel[];
+  diagnostics: EntityDiagnostic[];
+}
+
+export function analyzeEntities(
+  program: ts.Program,
+  fileNames: string[],
+): EntityAnalysis {
+  const checker = program.getTypeChecker();
+  const diagnostics: EntityDiagnostic[] = [];
+  const sourceFiles = resourceSourceFiles(program, fileNames);
+  const scanned = new Set(sourceFiles.map((sf) => path.resolve(sf.fileName)));
+
+  // Every interface declared in the scanned files is a *candidate* entity.
+  const candidates = new Set<ts.InterfaceDeclaration>();
+  for (const sf of sourceFiles) {
+    ts.forEachChild(sf, function walk(node) {
+      if (ts.isInterfaceDeclaration(node)) candidates.add(node);
+      ts.forEachChild(node, walk);
+    });
+  }
+
+  // 1. Roots: interfaces used as type arguments of hook calls, plus explicit
+  //    `@rastackResource` opt-ins.
+  const roots: ts.InterfaceDeclaration[] = [];
+  const rooted = new Set<ts.InterfaceDeclaration>();
+  const addRoot = (decl: ts.InterfaceDeclaration) => {
+    if (!rooted.has(decl)) {
+      rooted.add(decl);
+      roots.push(decl);
+    }
+  };
+  for (const sf of sourceFiles) {
+    ts.forEachChild(sf, function walk(node) {
+      if (ts.isCallExpression(node) && isHookCall(node)) {
+        for (const typeArg of node.typeArguments ?? []) {
+          const decl = interfaceBehindTypeNode(typeArg, checker, scanned);
+          if (decl && candidates.has(decl)) addRoot(decl);
+        }
+      }
+      ts.forEachChild(node, walk);
+    });
+  }
+  for (const decl of candidates) {
+    if (jsdocTags(decl).has("rastackresource")) addRoot(decl);
+  }
+
+  // 2. Transitive closure over FK references: an entity's interface-typed
+  //    property pulls the referenced interface in as an entity too.
+  const propsByDecl = new Map<ts.InterfaceDeclaration, PropInfo[]>();
+  const analyzed = (decl: ts.InterfaceDeclaration): PropInfo[] => {
+    let props = propsByDecl.get(decl);
+    if (!props) {
+      props = analyzeProperties(decl, checker, scanned);
+      propsByDecl.set(decl, props);
+    }
+    return props;
+  };
+
+  const included: ts.InterfaceDeclaration[] = [];
+  const seen = new Set<ts.InterfaceDeclaration>();
+  const queue = [...roots];
+  while (queue.length) {
+    const decl = queue.shift()!;
+    if (seen.has(decl)) continue;
+    seen.add(decl);
+    included.push(decl);
+    for (const prop of analyzed(decl)) {
+      if (prop.target && candidates.has(prop.target) && !seen.has(prop.target)) {
+        queue.push(prop.target);
+      }
+    }
+  }
+
+  // 3. Build the canonical models.
+  const namingByDecl = new Map(
+    included.map((decl) => [decl, entityNaming(decl)] as const),
+  );
+  const resources: ResourceModel[] = [];
+  for (const decl of included) {
+    const naming = namingByDecl.get(decl)!;
+    const key = `${naming.app}.${naming.model}`;
+    const fields: FieldModel[] = [];
+    const relations: RelationModel[] = [];
+
+    for (const prop of analyzed(decl)) {
+      if (prop.skip) {
+        diagnostics.push({ severity: "warning", message: `${key}.${prop.name}: ${prop.skip}` });
+        continue;
+      }
+      if (prop.inverse) continue; // has-many arrays are the reverse side of a FK
+      if (prop.target) {
+        const target = namingByDecl.get(prop.target);
+        if (!target) continue; // unreachable: closure included every target
+        const field: FieldModel = {
+          name: prop.name,
+          type: "fk",
+          relation: { app: target.app, model: target.model },
+        };
+        if (prop.nullable) field.null = true;
+        fields.push(field);
+        relations.push({
+          field: prop.name,
+          target: `${target.app}.${target.model}`,
+          kind: "fk",
+        });
+      } else if (prop.field) {
+        fields.push(prop.field);
+      }
+    }
+
+    resources.push({
+      app: naming.app,
+      model: naming.model,
+      fields,
+      relations,
+      search: naming.search,
+      permission: naming.permission,
+    });
+  }
+
+  resources.sort((a, b) =>
+    a.app === b.app ? a.model.localeCompare(b.model) : a.app.localeCompare(b.app),
+  );
+  return { resources, diagnostics };
+}
+
+// -- hooks -------------------------------------------------------------------
+
+/** A React-style hook call: `useX(...)` or `obj.useX(...)` with type args. */
+function isHookCall(call: ts.CallExpression): boolean {
+  if (!call.typeArguments?.length) return false;
+  const callee = call.expression;
+  const name = ts.isIdentifier(callee)
+    ? callee.text
+    : ts.isPropertyAccessExpression(callee)
+      ? callee.name.text
+      : undefined;
+  return !!name && /^use[A-Z0-9_]/.test(name);
+}
+
+/** Resolve a type node to an interface declared in one of the scanned files. */
+function interfaceBehindTypeNode(
+  node: ts.TypeNode,
+  checker: ts.TypeChecker,
+  scanned: Set<string>,
+): ts.InterfaceDeclaration | undefined {
+  return interfaceBehindType(checker.getTypeFromTypeNode(node), scanned);
+}
+
+function interfaceBehindType(
+  type: ts.Type,
+  scanned: Set<string>,
+): ts.InterfaceDeclaration | undefined {
+  const symbol = type.aliasSymbol ?? type.getSymbol();
+  for (const decl of symbol?.declarations ?? []) {
+    if (
+      ts.isInterfaceDeclaration(decl) &&
+      scanned.has(path.resolve(decl.getSourceFile().fileName))
+    ) {
+      return decl;
+    }
+  }
+  return undefined;
+}
+
+// -- property analysis --------------------------------------------------------
+
+interface PropInfo {
+  name: string;
+  nullable: boolean;
+  /** Scalar field (mutually exclusive with `target`). */
+  field?: FieldModel;
+  /** FK target interface (relation resolved after naming). */
+  target?: ts.InterfaceDeclaration;
+  /** `Entity[]` — the reverse side of a FK; contributes no column. */
+  inverse?: boolean;
+  /** Unsupported type — reported as a warning and skipped. */
+  skip?: string;
+}
+
+function analyzeProperties(
+  decl: ts.InterfaceDeclaration,
+  checker: ts.TypeChecker,
+  scanned: Set<string>,
+): PropInfo[] {
+  const props: PropInfo[] = [];
+  for (const member of decl.members) {
+    if (!ts.isPropertySignature(member) || !member.type) continue;
+    const name =
+      ts.isIdentifier(member.name) || ts.isStringLiteralLike(member.name)
+        ? member.name.text
+        : undefined;
+    if (!name) continue;
+    props.push(analyzeProperty(name, member, checker, scanned));
+  }
+  return props;
+}
+
+function analyzeProperty(
+  name: string,
+  member: ts.PropertySignature,
+  checker: ts.TypeChecker,
+  scanned: Set<string>,
+): PropInfo {
+  let nullable = !!member.questionToken;
+
+  // Unwrap parens and unions: strip null/undefined (→ nullable), and require a
+  // single remaining arm (unions of string literals collapse to `string`).
+  let typeNode = unwrapParens(member.type!);
+  if (ts.isUnionTypeNode(typeNode)) {
+    const arms = typeNode.types.filter((t) => {
+      const isNullish =
+        (ts.isLiteralTypeNode(t) && t.literal.kind === ts.SyntaxKind.NullKeyword) ||
+        t.kind === ts.SyntaxKind.UndefinedKeyword;
+      if (isNullish) nullable = true;
+      return !isNullish;
+    });
+    if (arms.length > 1 && arms.every(isStringish)) {
+      return scalarProp(name, "string", configFromTags(jsdocTags(member)), nullable);
+    }
+    if (arms.length !== 1) {
+      return { name, nullable, skip: "unsupported union type — skipped" };
+    }
+    typeNode = unwrapParens(arms[0]);
+  }
+
+  // Arrays: `Entity[]` is the reverse side of a FK — it contributes no column
+  // but is intentionally not an error. Arrays of scalars have no manifest shape.
+  const element = arrayElement(typeNode);
+  if (element) {
+    if (interfaceBehindTypeNode(element, checker, scanned)) {
+      return { name, nullable, inverse: true };
+    }
+    return { name, nullable, skip: "array fields are not supported — skipped" };
+  }
+
+  const type = checker.getTypeFromTypeNode(typeNode);
+  const base = classifyType(type, scanned);
+  if (base === undefined) {
+    return { name, nullable, skip: "unsupported type — skipped" };
+  }
+  if (typeof base !== "string") {
+    return { name, nullable, target: base }; // entity interface → FK
+  }
+
+  const config = {
+    ...configFromTags(jsdocTags(member)),
+    ...configFromType(type, checker, member),
+  };
+  return scalarProp(name, base, config, nullable);
+}
+
+/**
+ * What a property type *is*: a manifest scalar, an entity interface (→ FK), or
+ * unsupported. Intersections classify by their first classifiable constituent,
+ * which is what lets `DbConfig` brands ride along — `string & Unique` is a
+ * string; the brand carries configuration, not a datatype.
+ */
+function classifyType(
+  type: ts.Type,
+  scanned: Set<string>,
+): ScalarType | ts.InterfaceDeclaration | undefined {
+  if (type.flags & ts.TypeFlags.StringLike) return "string";
+  if (type.flags & ts.TypeFlags.NumberLike) return "float";
+  if (type.flags & ts.TypeFlags.BooleanLike) return "bool";
+  if (type.isIntersection()) {
+    for (const part of type.types) {
+      const classified = classifyType(part, scanned);
+      if (classified) return classified;
+    }
+    return undefined;
+  }
+  if (type.getProperty("__rastackDb")) return undefined; // a bare config brand
+  const decl = interfaceBehindType(type, scanned);
+  if (decl) return decl;
+  if (type.getSymbol()?.getName() === "Date") return "datetime";
+  return undefined;
+}
+
+/** Build a scalar field, letting the column config refine type + constraints. */
+function scalarProp(
+  name: string,
+  base: ScalarType,
+  config: ColumnConfig,
+  nullable: boolean,
+): PropInfo {
+  let type = base;
+  if (base === "float" && config.int) type = "int";
+  if (base === "string" && config.uuid) type = "uuid";
+  if (base === "string" && config.datetime) type = "datetime";
+
+  const field: FieldModel = { name, type };
+  if (config.maxLength !== undefined) field.maxLength = config.maxLength;
+  if (config.unique) field.unique = true;
+  if (config.primaryKey) field.primaryKey = true;
+  if (nullable) field.null = true;
+  if (config.default !== undefined) field.default = config.default;
+  return { name, nullable, field };
+}
+
+// -- column configuration -------------------------------------------------------
+
+/** Column constraints, sourced from `DbConfig` brand types and/or JSDoc tags. */
+interface ColumnConfig {
+  int?: boolean;
+  uuid?: boolean;
+  datetime?: boolean;
+  maxLength?: number;
+  unique?: boolean;
+  primaryKey?: boolean;
+  default?: unknown;
+}
+
+/**
+ * Config carried in the type system: intersecting a property type with
+ * `DbConfig` brands (`string & Unique & MaxLength<3>`, or a custom
+ * `interface Registration extends DbConfig<{…}>`) surfaces a phantom
+ * `__rastackDb` property whose literal type arguments are the configuration.
+ */
+function configFromType(
+  type: ts.Type,
+  checker: ts.TypeChecker,
+  location: ts.Node,
+): ColumnConfig {
+  const config: ColumnConfig = {};
+  const symbol = type.getProperty("__rastackDb");
+  if (!symbol) return config;
+  const carrier = checker
+    .getTypeOfSymbolAtLocation(symbol, location)
+    .getNonNullableType();
+  const prop = (name: string): ts.Type | undefined => {
+    const p = carrier.getProperty(name);
+    return p && checker.getTypeOfSymbolAtLocation(p, location);
+  };
+
+  if (prop("int")) config.int = true;
+  if (prop("uuid")) config.uuid = true;
+  if (prop("datetime")) config.datetime = true;
+  if (prop("unique")) config.unique = true;
+  if (prop("primaryKey")) config.primaryKey = true;
+  const maxLength = prop("maxLength");
+  if (maxLength?.isNumberLiteral()) config.maxLength = maxLength.value;
+  const dflt = prop("default");
+  const value = dflt ? literalValue(dflt, checker) : undefined;
+  if (value !== undefined) config.default = value;
+  return config;
+}
+
+/** Config carried as JSDoc tags (`@unique`, `@maxLength 3`, `@default x`). */
+function configFromTags(tags: Map<string, string>): ColumnConfig {
+  const config: ColumnConfig = {};
+  if (tags.has("int")) config.int = true;
+  if (tags.has("uuid")) config.uuid = true;
+  if (tags.has("datetime")) config.datetime = true;
+  if (tags.has("unique")) config.unique = true;
+  if (tags.has("primarykey")) config.primaryKey = true;
+  const maxLength = Number(tags.get("maxlength"));
+  if (Number.isFinite(maxLength) && maxLength > 0) config.maxLength = maxLength;
+  const dflt = tags.get("default");
+  if (dflt !== undefined) {
+    try {
+      config.default = JSON.parse(dflt);
+    } catch {
+      config.default = dflt;
+    }
+  }
+  return config;
+}
+
+/** The JS value of a literal type (`"active"`, `0`, `true`), else undefined. */
+function literalValue(
+  type: ts.Type,
+  checker: ts.TypeChecker,
+): string | number | boolean | undefined {
+  if (type.isStringLiteral() || type.isNumberLiteral()) return type.value;
+  if (type.flags & ts.TypeFlags.BooleanLiteral) {
+    return checker.typeToString(type) === "true";
+  }
+  return undefined;
+}
+
+function unwrapParens(node: ts.TypeNode): ts.TypeNode {
+  while (ts.isParenthesizedTypeNode(node)) node = node.type;
+  return node;
+}
+
+/** `string`, a string-literal type, or a template literal type. */
+function isStringish(node: ts.TypeNode): boolean {
+  if (node.kind === ts.SyntaxKind.StringKeyword) return true;
+  if (ts.isLiteralTypeNode(node) && ts.isStringLiteralLike(node.literal)) return true;
+  return ts.isTemplateLiteralTypeNode(node);
+}
+
+/** Element type of `T[]` / `Array<T>` / `ReadonlyArray<T>`, else undefined. */
+function arrayElement(node: ts.TypeNode): ts.TypeNode | undefined {
+  if (ts.isArrayTypeNode(node)) return node.elementType;
+  if (
+    ts.isTypeReferenceNode(node) &&
+    ts.isIdentifier(node.typeName) &&
+    (node.typeName.text === "Array" || node.typeName.text === "ReadonlyArray") &&
+    node.typeArguments?.length === 1
+  ) {
+    return node.typeArguments[0];
+  }
+  return undefined;
+}
+
+// -- naming -------------------------------------------------------------------
+
+interface EntityNaming {
+  app: string;
+  model: string;
+  search?: string[];
+  permission?: ResourceModel["permission"];
+}
+
+function entityNaming(decl: ts.InterfaceDeclaration): EntityNaming {
+  const tags = jsdocTags(decl);
+  const raw = decl.name.text;
+  // Generated entity interfaces are `I`-prefixed (`IFlight`); strip the prefix
+  // so hook usage of generated types resolves to the same resource.
+  const stripped = /^I[A-Z]/.test(raw) ? raw.slice(1) : raw;
+  const model =
+    tags.get("rastackmodel") || stripped.charAt(0).toLowerCase() + stripped.slice(1);
+  const app =
+    tags.get("rastackapp") ||
+    path
+      .basename(decl.getSourceFile().fileName)
+      .replace(/\.(ts|tsx)$/, "")
+      .toLowerCase();
+
+  const naming: EntityNaming = { app, model };
+  const search = tags.get("rastacksearch");
+  if (search) naming.search = search.split(",").map((s) => s.trim()).filter(Boolean);
+  const permission = tags.get("rastackpermission");
+  if (
+    permission === "authenticatedOrReadOnly" ||
+    permission === "authenticated" ||
+    permission === "public"
+  ) {
+    naming.permission = permission;
+  }
+  return naming;
+}
+
+/** All JSDoc tags on a node, keyed by lower-cased tag name → comment text. */
+function jsdocTags(node: ts.Node): Map<string, string> {
+  const tags = new Map<string, string>();
+  for (const tag of ts.getJSDocTags(node)) {
+    const text = ts.getTextOfJSDocComment(tag.comment) ?? "";
+    tags.set(tag.tagName.text.toLowerCase(), text.trim());
+  }
+  return tags;
+}
+
+// -- circular-dependency detection ---------------------------------------------
+
+/**
+ * Detect cycles in the FK graph. Works on the *merged* resource set, so cycles
+ * authored through the `resource()` DSL are caught too. A cycle every edge of
+ * which is required is an error — no row of any resource in the cycle could
+ * ever be inserted. A cycle containing at least one nullable FK (an optional
+ * interface property) is breakable and reported as a warning.
+ */
+export function detectCycles(resources: ResourceModel[]): EntityDiagnostic[] {
+  interface Edge {
+    from: string;
+    to: string;
+    field: string;
+    nullable: boolean;
+  }
+  const adjacency = new Map<string, Edge[]>();
+  for (const r of resources) {
+    const from = `${r.app}.${r.model}`;
+    const edges: Edge[] = [];
+    for (const rel of r.relations) {
+      const field = r.fields.find((f) => f.name === rel.field);
+      edges.push({
+        from,
+        to: rel.target,
+        field: rel.field,
+        nullable: field?.null === true,
+      });
+    }
+    adjacency.set(from, edges);
+  }
+
+  const diagnostics: EntityDiagnostic[] = [];
+  const reported = new Set<string>();
+  const state = new Map<string, 1 | 2>(); // 1 = on stack, 2 = done
+  const stack: { node: string; edgeIn?: Edge }[] = [];
+
+  const reportCycle = (closingEdge: Edge): void => {
+    const start = stack.findIndex((frame) => frame.node === closingEdge.to);
+    const nodes = stack.slice(start).map((frame) => frame.node);
+    const edges = [
+      ...stack.slice(start + 1).map((frame) => frame.edgeIn!),
+      closingEdge,
+    ];
+    const key = [...nodes].sort().join("|");
+    if (reported.has(key)) return;
+    reported.add(key);
+
+    const chain = [...nodes, closingEdge.to].join(" → ");
+    const breakable = edges.find((e) => e.nullable);
+    diagnostics.push(
+      breakable
+        ? {
+            severity: "warning",
+            message:
+              `Circular dependency: ${chain} — breakable via nullable ` +
+              `field ${breakable.from}.${breakable.field}.`,
+          }
+        : {
+            severity: "error",
+            message:
+              `Circular dependency: ${chain} — every foreign key in the ` +
+              `cycle is required, so no row can ever be inserted. Make ` +
+              `one of the fields optional to break the cycle.`,
+          },
+    );
+  };
+
+  const visit = (node: string, edgeIn?: Edge): void => {
+    state.set(node, 1);
+    stack.push({ node, edgeIn });
+    for (const edge of adjacency.get(node) ?? []) {
+      const targetState = state.get(edge.to);
+      if (targetState === 1) reportCycle(edge);
+      else if (targetState !== 2) visit(edge.to, edge);
+    }
+    stack.pop();
+    state.set(node, 2);
+  };
+
+  for (const node of adjacency.keys()) {
+    if (!state.has(node)) visit(node);
+  }
+  return diagnostics;
+}