rastack 0.0.16 → 0.0.20

package/src/compile/analyze.ts

@@ -1,224 +1,224 @@
-import * as ts from "typescript";
-import {
-  AdminModel,
-  FieldModel,
-  RelationModel,
-  ResourceModel,
-  ScalarType,
-  SyncModel,
-} from "./model";
-import { resourceSourceFiles } from "./program";
-
-/**
- * Statically analyse resource definitions and produce the canonical model.
- *
- * The headline behaviour is **foreign-key inference from types**: for every
- * field we ask the `TypeChecker` for the field's type and, if that type is a
- * `Ref<App, Model>`, we recover the relation target from the `__app`/`__model`
- * string-literal type arguments. No runtime execution, no string heuristics on
- * the value — the relation is read straight out of the type system.
- */
-export function analyze(
-  program: ts.Program,
-  fileNames: string[],
-): ResourceModel[] {
-  const checker = program.getTypeChecker();
-  const resources: ResourceModel[] = [];
-
-  for (const sourceFile of resourceSourceFiles(program, fileNames)) {
-    ts.forEachChild(sourceFile, function walk(node) {
-      if (isResourceCall(node)) {
-        const model = analyzeResourceCall(node, checker);
-        if (model) resources.push(model);
-      }
-      ts.forEachChild(node, walk);
-    });
-  }
-
-  // Deterministic order: app, then model.
-  resources.sort((a, b) =>
-    a.app === b.app ? a.model.localeCompare(b.model) : a.app.localeCompare(b.app),
-  );
-  return resources;
-}
-
-function isResourceCall(node: ts.Node): node is ts.CallExpression {
-  return (
-    ts.isCallExpression(node) &&
-    ts.isIdentifier(node.expression) &&
-    node.expression.text === "resource" &&
-    node.arguments.length >= 3
-  );
-}
-
-function analyzeResourceCall(
-  call: ts.CallExpression,
-  checker: ts.TypeChecker,
-): ResourceModel | undefined {
-  const app = stringLiteralArg(call.arguments[0]);
-  const model = stringLiteralArg(call.arguments[1]);
-  const fieldsArg = call.arguments[2];
-  if (!app || !model || !fieldsArg || !ts.isObjectLiteralExpression(fieldsArg)) {
-    return undefined;
-  }
-
-  const fields: FieldModel[] = [];
-  const relations: RelationModel[] = [];
-
-  for (const prop of fieldsArg.properties) {
-    if (!ts.isPropertyAssignment(prop)) continue;
-    const name = propertyName(prop.name);
-    if (!name) continue;
-
-    const field = analyzeField(name, prop.initializer, checker);
-    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 = literalToValue(call.arguments[3]) ?? {};
-  return {
-    app,
-    model,
-    fields,
-    relations,
-    sync: normaliseSync(options.sync),
-    admin: normaliseAdmin(options.admin),
-    search: options.search,
-    ordering: options.ordering,
-    permission: options.permission,
-  };
-}
-
-/**
- * Resolve a single field from its initializer. FK detection is type-driven:
- * the initializer's *type* is inspected, and a `Ref` type yields a foreign key.
- */
-function analyzeField(
-  name: string,
-  initializer: ts.Expression,
-  checker: ts.TypeChecker,
-): FieldModel | undefined {
-  const fieldType = checker.getTypeAtLocation(initializer);
-
-  // Foreign key: the field type is Ref<App, Model>. Recover the target from
-  // the string-literal type arguments — this is the "infer FK from types" step.
-  if (fieldType.getProperty("__radRef")) {
-    const app = literalTypeProp(fieldType, "__app", checker, initializer);
-    const model = literalTypeProp(fieldType, "__model", checker, initializer);
-    if (app && model) {
-      return { name, type: "fk", relation: { app, model } };
-    }
-    return undefined;
-  }
-
-  // Scalar: the field type carries a `__radScalar` string-literal discriminant.
-  const scalar = literalTypeProp(fieldType, "__radScalar", checker, initializer);
-  if (!scalar) return undefined;
-
-  const field: FieldModel = { name, type: scalar as ScalarType };
-  applyConstraints(field, initializer);
-  return field;
-}
-
-/** Read scalar constraints (maxLength, unique, …) from the builder call args. */
-function applyConstraints(field: FieldModel, initializer: ts.Expression): void {
-  if (!ts.isCallExpression(initializer)) return;
-  const opts = literalToValue(initializer.arguments[0]);
-  if (!opts || typeof opts !== "object") return;
-  if (typeof opts.maxLength === "number") field.maxLength = opts.maxLength;
-  if (opts.unique === true) field.unique = true;
-  if (opts.primaryKey === true) field.primaryKey = true;
-  if (opts.null === true) field.null = true;
-  if (opts.default !== undefined) field.default = opts.default;
-}
-
-// -- type/AST helpers -------------------------------------------------------
-
-/** Read a string-literal-typed property (e.g. `__app: "airports"`) off a type. */
-function literalTypeProp(
-  type: ts.Type,
-  name: string,
-  checker: ts.TypeChecker,
-  location: ts.Node,
-): string | undefined {
-  const symbol = type.getProperty(name);
-  if (!symbol) return undefined;
-  const propType = checker.getTypeOfSymbolAtLocation(symbol, location);
-  if (propType.isStringLiteral()) return propType.value;
-  return undefined;
-}
-
-function stringLiteralArg(node: ts.Expression | undefined): string | undefined {
-  if (node && ts.isStringLiteralLike(node)) return node.text;
-  return undefined;
-}
-
-function propertyName(name: ts.PropertyName): string | undefined {
-  if (ts.isIdentifier(name) || ts.isStringLiteralLike(name)) return name.text;
-  return undefined;
-}
-
-/**
- * Evaluate a *static literal* AST node (string/number/bool/null/array/object)
- * into a JS value. Anything non-literal (a function, an identifier) yields
- * `undefined` — the options and constraint blocks are always literals.
- */
-function literalToValue(node: ts.Expression | undefined): any {
-  if (!node) return undefined;
-  if (ts.isStringLiteralLike(node)) return node.text;
-  if (ts.isNumericLiteral(node)) return Number(node.text);
-  if (node.kind === ts.SyntaxKind.TrueKeyword) return true;
-  if (node.kind === ts.SyntaxKind.FalseKeyword) return false;
-  if (node.kind === ts.SyntaxKind.NullKeyword) return null;
-  if (
-    ts.isPrefixUnaryExpression(node) &&
-    node.operator === ts.SyntaxKind.MinusToken
-  ) {
-    const inner = literalToValue(node.operand);
-    return typeof inner === "number" ? -inner : undefined;
-  }
-  if (ts.isArrayLiteralExpression(node)) {
-    return node.elements.map((el) => literalToValue(el));
-  }
-  if (ts.isObjectLiteralExpression(node)) {
-    const obj: any = {};
-    for (const p of node.properties) {
-      if (ts.isPropertyAssignment(p)) {
-        const key = propertyName(p.name);
-        if (key) obj[key] = literalToValue(p.initializer);
-      }
-    }
-    return obj;
-  }
-  return undefined;
-}
-
-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;
-}
-
-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;
-}
+import * as ts from "typescript";
+import {
+  AdminModel,
+  FieldModel,
+  RelationModel,
+  ResourceModel,
+  ScalarType,
+  SyncModel,
+} from "./model";
+import { resourceSourceFiles } from "./program";
+
+/**
+ * Statically analyse resource definitions and produce the canonical model.
+ *
+ * The headline behaviour is **foreign-key inference from types**: for every
+ * field we ask the `TypeChecker` for the field's type and, if that type is a
+ * `Ref<App, Model>`, we recover the relation target from the `__app`/`__model`
+ * string-literal type arguments. No runtime execution, no string heuristics on
+ * the value — the relation is read straight out of the type system.
+ */
+export function analyze(
+  program: ts.Program,
+  fileNames: string[],
+): ResourceModel[] {
+  const checker = program.getTypeChecker();
+  const resources: ResourceModel[] = [];
+
+  for (const sourceFile of resourceSourceFiles(program, fileNames)) {
+    ts.forEachChild(sourceFile, function walk(node) {
+      if (isResourceCall(node)) {
+        const model = analyzeResourceCall(node, checker);
+        if (model) resources.push(model);
+      }
+      ts.forEachChild(node, walk);
+    });
+  }
+
+  // Deterministic order: app, then model.
+  resources.sort((a, b) =>
+    a.app === b.app ? a.model.localeCompare(b.model) : a.app.localeCompare(b.app),
+  );
+  return resources;
+}
+
+function isResourceCall(node: ts.Node): node is ts.CallExpression {
+  return (
+    ts.isCallExpression(node) &&
+    ts.isIdentifier(node.expression) &&
+    node.expression.text === "resource" &&
+    node.arguments.length >= 3
+  );
+}
+
+function analyzeResourceCall(
+  call: ts.CallExpression,
+  checker: ts.TypeChecker,
+): ResourceModel | undefined {
+  const app = stringLiteralArg(call.arguments[0]);
+  const model = stringLiteralArg(call.arguments[1]);
+  const fieldsArg = call.arguments[2];
+  if (!app || !model || !fieldsArg || !ts.isObjectLiteralExpression(fieldsArg)) {
+    return undefined;
+  }
+
+  const fields: FieldModel[] = [];
+  const relations: RelationModel[] = [];
+
+  for (const prop of fieldsArg.properties) {
+    if (!ts.isPropertyAssignment(prop)) continue;
+    const name = propertyName(prop.name);
+    if (!name) continue;
+
+    const field = analyzeField(name, prop.initializer, checker);
+    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 = literalToValue(call.arguments[3]) ?? {};
+  return {
+    app,
+    model,
+    fields,
+    relations,
+    sync: normaliseSync(options.sync),
+    admin: normaliseAdmin(options.admin),
+    search: options.search,
+    ordering: options.ordering,
+    permission: options.permission,
+  };
+}
+
+/**
+ * Resolve a single field from its initializer. FK detection is type-driven:
+ * the initializer's *type* is inspected, and a `Ref` type yields a foreign key.
+ */
+function analyzeField(
+  name: string,
+  initializer: ts.Expression,
+  checker: ts.TypeChecker,
+): FieldModel | undefined {
+  const fieldType = checker.getTypeAtLocation(initializer);
+
+  // Foreign key: the field type is Ref<App, Model>. Recover the target from
+  // the string-literal type arguments — this is the "infer FK from types" step.
+  if (fieldType.getProperty("__radRef")) {
+    const app = literalTypeProp(fieldType, "__app", checker, initializer);
+    const model = literalTypeProp(fieldType, "__model", checker, initializer);
+    if (app && model) {
+      return { name, type: "fk", relation: { app, model } };
+    }
+    return undefined;
+  }
+
+  // Scalar: the field type carries a `__radScalar` string-literal discriminant.
+  const scalar = literalTypeProp(fieldType, "__radScalar", checker, initializer);
+  if (!scalar) return undefined;
+
+  const field: FieldModel = { name, type: scalar as ScalarType };
+  applyConstraints(field, initializer);
+  return field;
+}
+
+/** Read scalar constraints (maxLength, unique, …) from the builder call args. */
+function applyConstraints(field: FieldModel, initializer: ts.Expression): void {
+  if (!ts.isCallExpression(initializer)) return;
+  const opts = literalToValue(initializer.arguments[0]);
+  if (!opts || typeof opts !== "object") return;
+  if (typeof opts.maxLength === "number") field.maxLength = opts.maxLength;
+  if (opts.unique === true) field.unique = true;
+  if (opts.primaryKey === true) field.primaryKey = true;
+  if (opts.null === true) field.null = true;
+  if (opts.default !== undefined) field.default = opts.default;
+}
+
+// -- type/AST helpers -------------------------------------------------------
+
+/** Read a string-literal-typed property (e.g. `__app: "airports"`) off a type. */
+function literalTypeProp(
+  type: ts.Type,
+  name: string,
+  checker: ts.TypeChecker,
+  location: ts.Node,
+): string | undefined {
+  const symbol = type.getProperty(name);
+  if (!symbol) return undefined;
+  const propType = checker.getTypeOfSymbolAtLocation(symbol, location);
+  if (propType.isStringLiteral()) return propType.value;
+  return undefined;
+}
+
+function stringLiteralArg(node: ts.Expression | undefined): string | undefined {
+  if (node && ts.isStringLiteralLike(node)) return node.text;
+  return undefined;
+}
+
+function propertyName(name: ts.PropertyName): string | undefined {
+  if (ts.isIdentifier(name) || ts.isStringLiteralLike(name)) return name.text;
+  return undefined;
+}
+
+/**
+ * Evaluate a *static literal* AST node (string/number/bool/null/array/object)
+ * into a JS value. Anything non-literal (a function, an identifier) yields
+ * `undefined` — the options and constraint blocks are always literals.
+ */
+function literalToValue(node: ts.Expression | undefined): any {
+  if (!node) return undefined;
+  if (ts.isStringLiteralLike(node)) return node.text;
+  if (ts.isNumericLiteral(node)) return Number(node.text);
+  if (node.kind === ts.SyntaxKind.TrueKeyword) return true;
+  if (node.kind === ts.SyntaxKind.FalseKeyword) return false;
+  if (node.kind === ts.SyntaxKind.NullKeyword) return null;
+  if (
+    ts.isPrefixUnaryExpression(node) &&
+    node.operator === ts.SyntaxKind.MinusToken
+  ) {
+    const inner = literalToValue(node.operand);
+    return typeof inner === "number" ? -inner : undefined;
+  }
+  if (ts.isArrayLiteralExpression(node)) {
+    return node.elements.map((el) => literalToValue(el));
+  }
+  if (ts.isObjectLiteralExpression(node)) {
+    const obj: any = {};
+    for (const p of node.properties) {
+      if (ts.isPropertyAssignment(p)) {
+        const key = propertyName(p.name);
+        if (key) obj[key] = literalToValue(p.initializer);
+      }
+    }
+    return obj;
+  }
+  return undefined;
+}
+
+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;
+}
+
+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/compile/index.ts

@@ -1,86 +1,86 @@
-import * as fs from "fs";
-import * as path from "path";
-import { analyze } from "./analyze";
-import { buildManifest, manifestToJson } from "./manifest";
-import { Manifest, ResourceModel } from "./model";
-import { buildOpenApi, openApiToJson } from "./openapi";
-import { createProgram } from "./program";
-
-export { analyze } from "./analyze";
-export { buildManifest } from "./manifest";
-export { buildOpenApi } from "./openapi";
-export * from "./model";
-
-export interface CompileResult {
-  manifest: Manifest;
-  openapi: any;
-  files: string[];
-}
-
-/** List every `.ts` resource file under a directory (or accept explicit files). */
-export function resolveResourceFiles(input: string): string[] {
-  const stat = fs.existsSync(input) ? fs.statSync(input) : undefined;
-  if (stat?.isFile()) return [path.resolve(input)];
-  if (stat?.isDirectory()) {
-    return fs
-      .readdirSync(input)
-      .filter((f) => f.endsWith(".ts") && !f.endsWith(".d.ts"))
-      .map((f) => path.resolve(input, f))
-      .sort();
-  }
-  throw new Error(`No such resources path: ${input}`);
-}
-
-/** Analyse resource definitions into the canonical model (no file output). */
-export function analyzeResources(input: string): ResourceModel[] {
-  const files = resolveResourceFiles(input);
-  const program = createProgram(files);
-  return analyze(program, files);
-}
-
-/** Compile resource definitions to a manifest + OpenAPI, writing both to disk. */
-export function compile(input: string, outDir: string): CompileResult {
-  const resources = analyzeResources(input);
-  const manifest = buildManifest(resources);
-  const openapi = buildOpenApi(resources);
-
-  fs.mkdirSync(outDir, { recursive: true });
-  const manifestPath = path.join(outDir, "schema.rad.json");
-  const openapiPath = path.join(outDir, "openapi.json");
-  fs.writeFileSync(manifestPath, manifestToJson(manifest), { flag: "w" });
-  fs.writeFileSync(openapiPath, openApiToJson(openapi), { flag: "w" });
-
-  return { manifest, openapi, files: [manifestPath, openapiPath] };
-}
-
-// -- introspection (replaces `manage.py rastack check|list|urls`) -----------
-
-/** Detect duplicate `app.model` definitions and dangling FK targets. */
-export function collisions(resources: ResourceModel[]): string[] {
-  const errors: string[] = [];
-  const seen = new Map<string, number>();
-  const keys = new Set(resources.map((r) => `${r.app}.${r.model}`));
-
-  for (const r of resources) {
-    const key = `${r.app}.${r.model}`;
-    seen.set(key, (seen.get(key) ?? 0) + 1);
-    for (const rel of r.relations) {
-      if (!keys.has(rel.target)) {
-        errors.push(
-          `${key}.${rel.field} references unknown resource ${rel.target}.`,
-        );
-      }
-    }
-  }
-  for (const [key, count] of seen) {
-    if (count > 1) errors.push(`Duplicate resource ${key} defined ${count} times.`);
-  }
-  return errors;
-}
-
-export function urlsFor(resources: ResourceModel[]): string[] {
-  return resources.flatMap((r) => [
-    `/api/${r.app}/v1/${r.model}/`,
-    `/api/${r.app}/v1/${r.model}/{id}/`,
-  ]);
-}
+import * as fs from "fs";
+import * as path from "path";
+import { analyze } from "./analyze";
+import { buildManifest, manifestToJson } from "./manifest";
+import { Manifest, ResourceModel } from "./model";
+import { buildOpenApi, openApiToJson } from "./openapi";
+import { createProgram } from "./program";
+
+export { analyze } from "./analyze";
+export { buildManifest } from "./manifest";
+export { buildOpenApi } from "./openapi";
+export * from "./model";
+
+export interface CompileResult {
+  manifest: Manifest;
+  openapi: any;
+  files: string[];
+}
+
+/** List every `.ts` resource file under a directory (or accept explicit files). */
+export function resolveResourceFiles(input: string): string[] {
+  const stat = fs.existsSync(input) ? fs.statSync(input) : undefined;
+  if (stat?.isFile()) return [path.resolve(input)];
+  if (stat?.isDirectory()) {
+    return fs
+      .readdirSync(input)
+      .filter((f) => f.endsWith(".ts") && !f.endsWith(".d.ts"))
+      .map((f) => path.resolve(input, f))
+      .sort();
+  }
+  throw new Error(`No such resources path: ${input}`);
+}
+
+/** Analyse resource definitions into the canonical model (no file output). */
+export function analyzeResources(input: string): ResourceModel[] {
+  const files = resolveResourceFiles(input);
+  const program = createProgram(files);
+  return analyze(program, files);
+}
+
+/** Compile resource definitions to a manifest + OpenAPI, writing both to disk. */
+export function compile(input: string, outDir: string): CompileResult {
+  const resources = analyzeResources(input);
+  const manifest = buildManifest(resources);
+  const openapi = buildOpenApi(resources);
+
+  fs.mkdirSync(outDir, { recursive: true });
+  const manifestPath = path.join(outDir, "schema.rad.json");
+  const openapiPath = path.join(outDir, "openapi.json");
+  fs.writeFileSync(manifestPath, manifestToJson(manifest), { flag: "w" });
+  fs.writeFileSync(openapiPath, openApiToJson(openapi), { flag: "w" });
+
+  return { manifest, openapi, files: [manifestPath, openapiPath] };
+}
+
+// -- introspection (replaces `manage.py rastack check|list|urls`) -----------
+
+/** Detect duplicate `app.model` definitions and dangling FK targets. */
+export function collisions(resources: ResourceModel[]): string[] {
+  const errors: string[] = [];
+  const seen = new Map<string, number>();
+  const keys = new Set(resources.map((r) => `${r.app}.${r.model}`));
+
+  for (const r of resources) {
+    const key = `${r.app}.${r.model}`;
+    seen.set(key, (seen.get(key) ?? 0) + 1);
+    for (const rel of r.relations) {
+      if (!keys.has(rel.target)) {
+        errors.push(
+          `${key}.${rel.field} references unknown resource ${rel.target}.`,
+        );
+      }
+    }
+  }
+  for (const [key, count] of seen) {
+    if (count > 1) errors.push(`Duplicate resource ${key} defined ${count} times.`);
+  }
+  return errors;
+}
+
+export function urlsFor(resources: ResourceModel[]): string[] {
+  return resources.flatMap((r) => [
+    `/api/${r.app}/v1/${r.model}/`,
+    `/api/${r.app}/v1/${r.model}/{id}/`,
+  ]);
+}

package/src/compile/manifest.ts

@@ -1,10 +1,10 @@
-import { Manifest, ResourceModel } from "./model";
-
-/** Assemble the canonical manifest from analysed resources. */
-export function buildManifest(resources: ResourceModel[]): Manifest {
-  return { version: 1, resources };
-}
-
-export function manifestToJson(manifest: Manifest): string {
-  return JSON.stringify(manifest, null, 2) + "\n";
-}
+import { Manifest, ResourceModel } from "./model";
+
+/** Assemble the canonical manifest from analysed resources. */
+export function buildManifest(resources: ResourceModel[]): Manifest {
+  return { version: 1, resources };
+}
+
+export function manifestToJson(manifest: Manifest): string {
+  return JSON.stringify(manifest, null, 2) + "\n";
+}