rastack 0.0.16

package/src/compile/openapi.ts

@@ -0,0 +1,266 @@
+import { FieldModel, ResourceModel } from "./model";
+
+/**
+ * Emit an OpenAPI 3 document from the analysed resources. The output reproduces
+ * the *exact* contract the existing `tools/` codegen and `stack/` runtime rely
+ * on — `/api/{app}/v1/{model}/` URL segments and the `x-rastack-sync*` vendor
+ * extensions — so those packages are unchanged. Foreign keys additionally carry
+ * a new `x-rastack-relation` extension so downstream tooling (and the admin) can
+ * follow relations.
+ */
+export function buildOpenApi(resources: ResourceModel[]): any {
+  const paths: Record<string, any> = {};
+  const schemas: Record<string, any> = {};
+
+  for (const resource of resources) {
+    const P = pascal(resource.model);
+    const listUrl = `/api/${resource.app}/v1/${resource.model}/`;
+    const detailUrl = `${listUrl}{id}/`;
+    const local = resource.sync?.mode === "local";
+
+    schemas[P] = readSchema(resource);
+    schemas[`Paginated${P}List`] = paginatedSchema(P);
+    schemas[`${P}Request`] = writeSchema(resource, false);
+    schemas[`Patched${P}Request`] = writeSchema(resource, true);
+
+    paths[listUrl] = {
+      get: syncStamp(
+        {
+          operationId: `list${P}`,
+          parameters: [
+            queryParam("page", "integer"),
+            queryParam("search", "string"),
+          ],
+          responses: jsonResponse("200", `Paginated${P}List`),
+        },
+        resource,
+        "list",
+      ),
+      post: syncStamp(
+        {
+          operationId: `create${P}`,
+          requestBody: jsonBody(`${P}Request`),
+          responses: jsonResponse("201", P),
+        },
+        resource,
+        "create",
+      ),
+    };
+
+    paths[detailUrl] = {
+      get: syncStamp(
+        {
+          operationId: `get${P}ById`,
+          parameters: [idParam()],
+          responses: jsonResponse("200", P),
+        },
+        resource,
+        "retrieve",
+      ),
+      put: syncStamp(
+        {
+          operationId: `update${P}`,
+          parameters: [idParam()],
+          requestBody: jsonBody(`${P}Request`),
+          responses: jsonResponse("200", P),
+        },
+        resource,
+        "update",
+      ),
+      patch: syncStamp(
+        {
+          operationId: `partialUpdate${P}`,
+          parameters: [idParam()],
+          requestBody: jsonBody(`Patched${P}Request`),
+          responses: jsonResponse("200", P),
+        },
+        resource,
+        "partial_update",
+      ),
+      delete: syncStamp(
+        {
+          operationId: `delete${P}`,
+          parameters: [idParam()],
+          responses: { "204": { description: "No response body" } },
+        },
+        resource,
+        "destroy",
+      ),
+    };
+  }
+
+  return {
+    openapi: "3.0.3",
+    info: { title: "React API Stack", version: "1.0.0" },
+    paths,
+    components: { schemas },
+  };
+}
+
+export function openApiToJson(doc: any): string {
+  return JSON.stringify(doc, null, 2) + "\n";
+}
+
+// -- schema builders --------------------------------------------------------
+
+function readSchema(resource: ResourceModel): any {
+  const properties: Record<string, any> = {
+    id: idProperty(resource),
+  };
+  const required: string[] = [];
+  for (const field of resource.fields) {
+    properties[field.name] = fieldProperty(field);
+    if (!field.null && field.default === undefined) required.push(field.name);
+  }
+  return { type: "object", properties, required };
+}
+
+function writeSchema(resource: ResourceModel, patched: boolean): any {
+  const properties: Record<string, any> = {};
+  const required: string[] = [];
+  for (const field of resource.fields) {
+    if (field.primaryKey) continue;
+    properties[field.name] = fieldProperty(field);
+    if (!patched && !field.null && field.default === undefined) {
+      required.push(field.name);
+    }
+  }
+  const schema: any = { type: "object", properties };
+  if (required.length) schema.required = required;
+  return schema;
+}
+
+function paginatedSchema(pascalModel: string): any {
+  return {
+    type: "object",
+    properties: {
+      count: { type: "integer" },
+      next: { type: "string", nullable: true },
+      previous: { type: "string", nullable: true },
+      results: {
+        type: "array",
+        items: { $ref: `#/components/schemas/${pascalModel}` },
+      },
+    },
+    required: ["count", "results"],
+  };
+}
+
+function fieldProperty(field: FieldModel): any {
+  if (field.type === "fk") {
+    return {
+      type: "integer",
+      "x-rastack-relation": field.relation,
+    };
+  }
+  const base = scalarProperty(field.type);
+  if (field.maxLength !== undefined) base.maxLength = field.maxLength;
+  if (field.null) base.nullable = true;
+  return base;
+}
+
+function idProperty(resource: ResourceModel): any {
+  const pk = resource.fields.find((f) => f.primaryKey);
+  if (pk) return { ...scalarProperty(pk.type), readOnly: true };
+  if (resource.sync?.clientIds) {
+    return { type: "string", format: "uuid" };
+  }
+  return { type: "integer", readOnly: true };
+}
+
+function scalarProperty(type: string): any {
+  switch (type) {
+    case "int":
+      return { type: "integer" };
+    case "float":
+      return { type: "number" };
+    case "bool":
+      return { type: "boolean" };
+    case "datetime":
+      return { type: "string", format: "date-time" };
+    case "uuid":
+      return { type: "string", format: "uuid" };
+    default:
+      return { type: "string" };
+  }
+}
+
+// -- operation helpers ------------------------------------------------------
+
+function jsonResponse(status: string, schemaName: string): any {
+  return {
+    [status]: {
+      description: "",
+      content: {
+        "application/json": {
+          schema: { $ref: `#/components/schemas/${schemaName}` },
+        },
+      },
+    },
+  };
+}
+
+function jsonBody(schemaName: string): any {
+  return {
+    required: true,
+    content: {
+      "application/json": {
+        schema: { $ref: `#/components/schemas/${schemaName}` },
+      },
+    },
+  };
+}
+
+function idParam(): any {
+  return {
+    name: "id",
+    in: "path",
+    required: true,
+    schema: { type: "string" },
+  };
+}
+
+function queryParam(name: string, type: string): any {
+  return { name, in: "query", required: false, schema: { type } };
+}
+
+/**
+ * Stamp the `x-rastack-sync*` vendor extensions on an operation of a local-mode
+ * resource. Ported from the old `python/rastack/spectacular.py` postprocess
+ * hook: confirmed operations become blocking client hooks, everything else on a
+ * local resource replicates.
+ */
+function syncStamp(operation: any, resource: ResourceModel, verb: string): any {
+  const sync = resource.sync;
+  if (!sync || sync.mode !== "local") return operation;
+
+  operation["x-rastack-sync"] = isConfirmed(sync.confirmed, verb, operation)
+    ? "confirmed"
+    : "local";
+  if (sync.load === "lazy") operation["x-rastack-sync-load"] = "lazy";
+  if (sync.clientIds) operation["x-rastack-sync-client-ids"] = true;
+  return operation;
+}
+
+function isConfirmed(
+  confirmed: string[] | undefined,
+  verb: string,
+  operation: any,
+): boolean {
+  if (!confirmed || !confirmed.length) return false;
+  for (const name of confirmed) {
+    if (name === verb) return true;
+    if (name === "update" && verb === "partial_update") return true;
+    if (operation.operationId && operation.operationId.includes(name)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function pascal(str: string): string {
+  return str
+    .split(/[-_]/)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join("");
+}

package/src/compile/program.ts

@@ -0,0 +1,40 @@
+import * as path from "path";
+import * as ts from "typescript";
+
+/**
+ * Build a `ts.Program` (and thus a `TypeChecker`) over a set of resource
+ * definition files. The DSL package (`rad-tools/define`) is mapped to the
+ * in-tree/installed sources via `paths` so both the shipped package name and
+ * the local demo/tests resolve without extra linking.
+ */
+export function createProgram(fileNames: string[]): ts.Program {
+  const defineDir = path.resolve(__dirname, "../define");
+
+  const options: ts.CompilerOptions = {
+    target: ts.ScriptTarget.ES2019,
+    module: ts.ModuleKind.CommonJS,
+    moduleResolution: ts.ModuleResolutionKind.Node10,
+    strict: true,
+    skipLibCheck: true,
+    esModuleInterop: true,
+    noEmit: true,
+    baseUrl: process.cwd(),
+    paths: {
+      "rad-tools/define": [defineDir],
+      "rad-tools/define/*": [defineDir + "/*"],
+    },
+  };
+
+  return ts.createProgram(fileNames, options);
+}
+
+/** Every non-declaration source file the program was rooted at. */
+export function resourceSourceFiles(
+  program: ts.Program,
+  fileNames: string[],
+): ts.SourceFile[] {
+  const wanted = new Set(fileNames.map((f) => path.resolve(f)));
+  return program
+    .getSourceFiles()
+    .filter((sf) => !sf.isDeclarationFile && wanted.has(path.resolve(sf.fileName)));
+}

package/src/csv-schema.ts

@@ -0,0 +1,187 @@
+import fs from "fs";
+import path from "path";
+import { minimatch } from "minimatch";
+import yaml from "js-yaml";
+
+export interface ColumnSchema {
+  name: string;
+  type: "integer" | "float" | "boolean" | "date" | "datetime" | "string";
+  nullable: boolean;
+  unique: boolean;
+  primaryKey: boolean;
+  pii: boolean;
+  piiReason?: string;
+}
+
+export interface TableSchema {
+  tableName: string;
+  sourceFile: string;
+  columns: ColumnSchema[];
+  rowCount: number;
+  fingerprint: string;
+}
+
+interface PiiConfig {
+  patterns: string[];
+  luhn_check: boolean;
+  require_policy: boolean;
+}
+
+const DEFAULT_PII_PATTERNS = [
+  "*passport*",
+  "*_no",
+  "*_number",
+  "ssn",
+  "national_id",
+  "date_of_birth",
+  "dob",
+  "email",
+  "*phone*",
+  "*credit_card*",
+  "*card_number*",
+  "ip_address",
+  "latitude",
+  "longitude",
+  "*salary*",
+  "*income*",
+];
+
+function loadPiiConfig(repoRoot: string): PiiConfig {
+  const configPath = path.join(repoRoot, ".rad", "pii-patterns.yml");
+  if (!fs.existsSync(configPath)) {
+    return { patterns: DEFAULT_PII_PATTERNS, luhn_check: true, require_policy: true };
+  }
+  return yaml.load(fs.readFileSync(configPath, "utf-8")) as PiiConfig;
+}
+
+function isPiiColumn(name: string, config: PiiConfig): string | null {
+  const lower = name.toLowerCase();
+  for (const pattern of config.patterns) {
+    if (minimatch(lower, pattern.toLowerCase())) {
+      return `matches PII pattern "${pattern}"`;
+    }
+  }
+  return null;
+}
+
+function luhnCheck(value: string): boolean {
+  const digits = value.replace(/\D/g, "");
+  if (digits.length < 13) return false;
+  let sum = 0;
+  let alternate = false;
+  for (let i = digits.length - 1; i >= 0; i--) {
+    let n = parseInt(digits[i], 10);
+    if (alternate) {
+      n *= 2;
+      if (n > 9) n -= 9;
+    }
+    sum += n;
+    alternate = !alternate;
+  }
+  return sum % 10 === 0;
+}
+
+function inferType(values: string[]): ColumnSchema["type"] {
+  const nonEmpty = values.filter((v) => v.trim() !== "" && v.toLowerCase() !== "null");
+  if (nonEmpty.length === 0) return "string";
+
+  if (nonEmpty.every((v) => /^\d+$/.test(v.trim()))) return "integer";
+  if (nonEmpty.every((v) => /^-?\d+(\.\d+)?$/.test(v.trim()))) return "float";
+  if (nonEmpty.every((v) => /^(true|false|yes|no|1|0)$/i.test(v.trim()))) return "boolean";
+  if (nonEmpty.every((v) => /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}/.test(v.trim()))) return "datetime";
+  if (nonEmpty.every((v) => /^\d{4}-\d{2}-\d{2}$/.test(v.trim()))) return "date";
+  return "string";
+}
+
+export function parseCsv(content: string): { headers: string[]; rows: string[][] } {
+  const lines = content.split(/\r?\n/).filter((l) => l.trim() !== "");
+  if (lines.length === 0) return { headers: [], rows: [] };
+
+  const splitLine = (line: string): string[] => {
+    const result: string[] = [];
+    let current = "";
+    let inQuotes = false;
+    for (let i = 0; i < line.length; i++) {
+      if (line[i] === '"') {
+        inQuotes = !inQuotes;
+      } else if (line[i] === "," && !inQuotes) {
+        result.push(current.trim());
+        current = "";
+      } else {
+        current += line[i];
+      }
+    }
+    result.push(current.trim());
+    return result;
+  };
+
+  const headers = splitLine(lines[0]);
+  const rows = lines.slice(1).map(splitLine);
+  return { headers, rows };
+}
+
+function fingerprint(schema: Omit<TableSchema, "fingerprint">): string {
+  const sig = schema.columns.map((c) => `${c.name}:${c.type}:${c.pii}`).join("|");
+  // Simple hash — not crypto, just change-detection
+  let h = 0;
+  for (let i = 0; i < sig.length; i++) {
+    h = (Math.imul(31, h) + sig.charCodeAt(i)) | 0;
+  }
+  return Math.abs(h).toString(16).padStart(8, "0");
+}
+
+export function inferSchema(
+  csvPath: string,
+  repoRoot: string,
+): { schema: TableSchema; piiViolations: { column: string; reason: string }[] } {
+  const content = fs.readFileSync(csvPath, "utf-8");
+  const { headers, rows } = parseCsv(content);
+  const piiConfig = loadPiiConfig(repoRoot);
+  const tableName = path.basename(csvPath, ".csv");
+
+  const piiViolations: { column: string; reason: string }[] = [];
+
+  const columns: ColumnSchema[] = headers.map((name, i) => {
+    const values = rows.map((r) => r[i] ?? "");
+    const type = inferType(values);
+    const nullable = values.some((v) => v.trim() === "" || v.toLowerCase() === "null");
+    const nonEmpty = values.filter((v) => v.trim() !== "");
+    const unique = new Set(nonEmpty).size === nonEmpty.length;
+    const isPrimary = name.toLowerCase() === "id";
+
+    // PII: column name pattern match
+    let pii = false;
+    let piiReason: string | undefined;
+    const nameReason = isPiiColumn(name, piiConfig);
+    if (nameReason) {
+      pii = true;
+      piiReason = nameReason;
+    }
+
+    // PII: Luhn check on string columns that look numeric
+    if (!pii && piiConfig.luhn_check && type === "string") {
+      const luhnHits = values.filter((v) => v.trim() !== "" && luhnCheck(v));
+      if (luhnHits.length > values.length * 0.5) {
+        pii = true;
+        piiReason = "majority of values pass Luhn check (possible card numbers)";
+      }
+    }
+
+    if (pii && piiReason) {
+      piiViolations.push({ column: name, reason: piiReason });
+    }
+
+    return { name, type, nullable, unique, primaryKey: isPrimary, pii, piiReason };
+  });
+
+  const base = { tableName, sourceFile: csvPath, columns, rowCount: rows.length };
+  return { schema: { ...base, fingerprint: fingerprint(base) }, piiViolations };
+}
+
+export function discoverCsvFiles(dir: string): string[] {
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir)
+    .filter((f) => f.endsWith(".csv"))
+    .map((f) => path.join(dir, f));
+}

package/src/define/index.ts

@@ -0,0 +1,162 @@
+/**
+ * rad-tools authoring DSL — the TypeScript-first source of truth.
+ *
+ * Resources are authored as plain TypeScript. The compiler
+ * (`tools/src/compile`) reads these definitions and, crucially, **infers
+ * foreign-key relations directly from the field types** via the TypeScript type
+ * checker: a field whose type is a {@link Ref} to another {@link ResourceType}
+ * is recorded as a foreign key, with the target app/model recovered from the
+ * `Ref`'s string-literal type arguments.
+ *
+ * ```ts
+ * import { resource, s } from "rad-tools/define";
+ *
+ * export const Airport = resource("airports", "airport", {
+ *   code: s.string({ maxLength: 3, unique: true }),
+ *   name: s.string({ maxLength: 120 }),
+ * }, { search: ["code", "name"], admin: { listDisplay: ["code", "name"] } });
+ *
+ * export const Terminal = resource("airports", "terminal", {
+ *   airport: s.ref(() => Airport),   // FK inferred from the type of this field
+ *   label: s.string({ maxLength: 20 }),
+ * });
+ * ```
+ */
+
+/** A scalar field. The literal `__radScalar` type is what the compiler reads. */
+export interface Scalar<T extends string> {
+  readonly __radScalar: T;
+}
+
+/**
+ * A foreign-key field. `App`/`Model` are carried as string-literal type
+ * arguments so the compiler can recover the relation target purely from types.
+ */
+export interface Ref<App extends string, Model extends string> {
+  readonly __radRef: true;
+  readonly __app: App;
+  readonly __model: Model;
+}
+
+export interface StringOptions {
+  maxLength?: number;
+  unique?: boolean;
+  primaryKey?: boolean;
+  default?: string;
+  null?: boolean;
+}
+
+export interface NumberOptions {
+  unique?: boolean;
+  primaryKey?: boolean;
+  default?: number;
+  null?: boolean;
+}
+
+export interface BoolOptions {
+  default?: boolean;
+  null?: boolean;
+}
+
+export interface DateOptions {
+  autoNow?: boolean;
+  autoNowAdd?: boolean;
+  null?: boolean;
+}
+
+/**
+ * Field builders. Each returns a phantom value whose *type* encodes the field
+ * kind; the runtime object is never used at compile time (the compiler analyses
+ * the source, it does not execute it) but is real so the DSL is also usable at
+ * runtime if a consumer wants it.
+ */
+export const s = {
+  string(_opts?: StringOptions): Scalar<"string"> {
+    return { __radScalar: "string" } as Scalar<"string">;
+  },
+  int(_opts?: NumberOptions): Scalar<"int"> {
+    return { __radScalar: "int" } as Scalar<"int">;
+  },
+  float(_opts?: NumberOptions): Scalar<"float"> {
+    return { __radScalar: "float" } as Scalar<"float">;
+  },
+  bool(_opts?: BoolOptions): Scalar<"bool"> {
+    return { __radScalar: "bool" } as Scalar<"bool">;
+  },
+  datetime(_opts?: DateOptions): Scalar<"datetime"> {
+    return { __radScalar: "datetime" } as Scalar<"datetime">;
+  },
+  uuid(_opts?: StringOptions): Scalar<"uuid"> {
+    return { __radScalar: "uuid" } as Scalar<"uuid">;
+  },
+  /**
+   * A foreign key. The target is `() => SomeResource`; the compiler resolves
+   * the relation from the *type* `Ref<App, Model>` this returns — it does not
+   * need to run the thunk.
+   */
+  ref<A extends string, M extends string>(
+    _thunk: () => ResourceType<A, M, any>,
+  ): Ref<A, M> {
+    return { __radRef: true } as Ref<A, M>;
+  },
+};
+
+export type AnyField = Scalar<string> | Ref<string, string>;
+
+/** Local-first sync configuration (mirrors the old Python `class Sync:`). */
+export interface SyncOptions {
+  mode?: "server" | "local";
+  scope?: string;
+  confirmed?: string[];
+  load?: "instant" | "lazy";
+  clientIds?: boolean;
+}
+
+export interface ResourceOptions {
+  /** DRF-style search fields. */
+  search?: string[];
+  /** Orderable fields. */
+  ordering?: string[];
+  /** Admin config, or `false` to opt out of the admin. */
+  admin?: { listDisplay?: string[] } | false;
+  /** Local-first replication config. */
+  sync?: SyncOptions;
+  /** Access policy (secure by default). */
+  permission?: "authenticatedOrReadOnly" | "authenticated" | "public";
+}
+
+/**
+ * A resource definition. `App`/`Model` are preserved as string-literal type
+ * arguments so a {@link Ref} to this resource carries a recoverable target.
+ */
+export interface ResourceType<App extends string, Model extends string, F> {
+  readonly __rad: "resource";
+  readonly __app: App;
+  readonly __model: Model;
+  readonly app: App;
+  readonly model: Model;
+  readonly fields: F;
+  readonly options: ResourceOptions;
+}
+
+/** Define a resource. Capture app/model as literal types for FK inference. */
+export function resource<
+  App extends string,
+  Model extends string,
+  F extends Record<string, AnyField>,
+>(
+  app: App,
+  model: Model,
+  fields: F,
+  options: ResourceOptions = {},
+): ResourceType<App, Model, F> {
+  return {
+    __rad: "resource",
+    __app: app,
+    __model: model,
+    app,
+    model,
+    fields,
+    options,
+  };
+}

package/src/entity-generation/delete-method.ts

@@ -0,0 +1,37 @@
+import { capitaliseFirstLetter } from "../schema/capitalise-first-letter";
+
+export function generateDeleteAPIMethod(
+  url: string,
+  operationId: string,
+  listQueryCacheKey?: string,
+): [string, Set<string>] {
+  const operationIdUpper = capitaliseFirstLetter(operationId);
+
+  let urlStructure = `'${url}'`;
+  const pathParams =
+    url.match(/{([^}]+)}/g)?.map((param) => param.slice(1, -1)) || [];
+
+  if (pathParams.length > 0) {
+    urlStructure = url.replace(/{([^}]+)}/g, "${$1}");
+    const paramList = pathParams.join(", ");
+    urlStructure = `(${paramList}) => \`${urlStructure}\``;
+  }
+
+  const importStatements = new Set<string>();
+  importStatements.add(`useDeleteQuery`);
+
+  const cacheKeyLine = listQueryCacheKey
+    ? `\n    listQueryCacheKey: ${listQueryCacheKey},`
+    : "";
+
+  return [
+    `
+export function use${operationIdUpper}() {
+  return useDeleteQuery({
+    deleteUrl: ${urlStructure},${cacheKeyLine}
+  });
+}
+`,
+    importStatements,
+  ];
+}