@deterministic-code/datasources-cli 0.0.0-stage → 0.1.3

package/node_modules/@deterministic-code/deterministic-specifications-typescript/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@deterministic-code/deterministic-generators-common",
+  "version": "0.1.0",
+  "description": "Parser and validators for the deterministic-specifications contract. The TypeScript library lives in typescript/; Rust and C# libraries live beside it.",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./typescript/validator/index.js",
+      "import": "./typescript/validator/dist/index.js"
+    },
+    "./parser": {
+      "types": "./typescript/parser/specification-parser.js",
+      "import": "./typescript/parser/dist/specification-parser.js"
+    }
+  },
+  "files": [
+    "typescript/validator/dist",
+    "typescript/validator/index.ts",
+    "typescript/validator/types.ts",
+    "typescript/validator/SpecValidator.ts",
+    "typescript/validator/validators",
+    "typescript/parser/dist",
+    "typescript/parser/*.ts",
+    "typescript/parser/parser"
+  ],
+  "dependencies": {
+    "ajv": "^8.18.0",
+    "pluralize": "^8.0.0",
+    "yaml": "^2.6.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deterministic-code/deterministic-generators-common.git"
+  },
+  "engines": {
+    "node": ">=22.18"
+  }
+}

package/node_modules/@deterministic-code/deterministic-specifications-typescript/typescript/parser/datasource-type-tree.ts

@@ -0,0 +1,330 @@
+import { stringify } from "yaml";
+import type { Type } from "./specification.ts";
+
+export type DatasourceTypeTree = { [name: string]: DatasourceTypeTree };
+
+export type DatasourceTypeGraphEdge = {
+  from: string;
+  to: string;
+};
+
+export type DatasourceTypeGraph = {
+  nodes: string[];
+  edges: DatasourceTypeGraphEdge[];
+};
+
+export type DatasourceTypeHierarchies = {
+  firstParentTree: DatasourceTypeTree;
+  allParentsTree: DatasourceTypeTree;
+  graph: DatasourceTypeGraph;
+};
+
+const ROOT = "root";
+
+const refTargets = (references: string | [string, string]): string[] =>
+  (Array.isArray(references) ? references : [references]).map(
+    (ref) => ref.split(".")[0] || "",
+  );
+
+const referencedParents = (
+  type: Type,
+  typeNames: ReadonlySet<string>,
+): string[] => {
+  const parents: string[] = [];
+  const seen = new Set<string>();
+  for (const field of type.fields) {
+    if (field.references === undefined) continue;
+    for (const parent of refTargets(field.references)) {
+      if (
+        parent.length === 0 ||
+        parent === type.name ||
+        !typeNames.has(parent) ||
+        seen.has(parent)
+      ) {
+        continue;
+      }
+      seen.add(parent);
+      parents.push(parent);
+    }
+  }
+  return parents;
+};
+
+const addChild = (
+  children: Map<string, string[]>,
+  parent: string,
+  child: string,
+): void => {
+  const list = children.get(parent);
+  if (list === undefined) {
+    children.set(parent, [child]);
+    return;
+  }
+  if (!list.includes(child)) list.push(child);
+};
+
+/** Child → parent edges. Each SCC id maps to its members. */
+const stronglyConnected = (
+  names: readonly string[],
+  parentsOf: (name: string) => readonly string[],
+): Map<string, number> => {
+  let index = 0;
+  let sccCount = 0;
+  const indices = new Map<string, number>();
+  const lows = new Map<string, number>();
+  const stack: string[] = [];
+  const onStack = new Set<string>();
+  const sccId = new Map<string, number>();
+
+  const connect = (v: string): void => {
+    indices.set(v, index);
+    lows.set(v, index);
+    index += 1;
+    stack.push(v);
+    onStack.add(v);
+    for (const w of parentsOf(v)) {
+      if (!indices.has(w)) {
+        connect(w);
+        const vLow = lows.get(v);
+        const wLow = lows.get(w);
+        if (vLow !== undefined && wLow !== undefined) {
+          lows.set(v, Math.min(vLow, wLow));
+        }
+      } else if (onStack.has(w)) {
+        const vLow = lows.get(v);
+        const wIndex = indices.get(w);
+        if (vLow !== undefined && wIndex !== undefined) {
+          lows.set(v, Math.min(vLow, wIndex));
+        }
+      }
+    }
+    if (lows.get(v) === indices.get(v)) {
+      let w: string;
+      do {
+        w = stack.pop()!;
+        onStack.delete(w);
+        sccId.set(w, sccCount);
+      } while (w !== v);
+      sccCount += 1;
+    }
+  };
+
+  for (const name of names) {
+    if (!indices.has(name)) connect(name);
+  }
+  return sccId;
+};
+
+/** SCCs with no parent outside the component are top-level; those types point at root. */
+const sccsWithExternalParent = (
+  parentLists: ReadonlyMap<string, readonly string[]>,
+  sccId: ReadonlyMap<string, number>,
+): Set<number> => {
+  const hasExternal = new Set<number>();
+  for (const [name, parents] of parentLists) {
+    const from = sccId.get(name)!;
+    for (const parent of parents) {
+      const to = sccId.get(parent);
+      if (to !== undefined && to !== from) hasExternal.add(from);
+    }
+  }
+  return hasExternal;
+};
+
+const buildNode = (
+  children: Map<string, string[]>,
+  name: string,
+  path: ReadonlySet<string>,
+): DatasourceTypeTree => {
+  const node: DatasourceTypeTree = {};
+  for (const child of children.get(name) ?? []) {
+    if (path.has(child)) continue;
+    node[child] = buildNode(children, child, new Set([...path, child]));
+  }
+  return node;
+};
+
+const chosenParents = (
+  types: readonly Type[],
+  multiParent: "first" | "all",
+): Map<string, readonly string[]> => {
+  const typeNames = new Set(types.map((type) => type.name));
+  const parentLists = new Map<string, readonly string[]>();
+  for (const type of types) {
+    const parents = referencedParents(type, typeNames);
+    parentLists.set(
+      type.name,
+      multiParent === "all" ? parents : parents.slice(0, 1),
+    );
+  }
+  return parentLists;
+};
+
+const buildTree = (
+  types: readonly Type[],
+  parentLists: ReadonlyMap<string, readonly string[]>,
+): DatasourceTypeTree => {
+  const names = types.map((type) => type.name);
+  const sccId = stronglyConnected(names, (name) => parentLists.get(name)!);
+  const hasExternalParent = sccsWithExternalParent(parentLists, sccId);
+  const children = new Map<string, string[]>();
+  for (const type of types) {
+    const scc = sccId.get(type.name)!;
+    const parents = parentLists.get(type.name)!;
+    if (!hasExternalParent.has(scc)) {
+      addChild(children, ROOT, type.name);
+      continue;
+    }
+    for (const parent of parents) {
+      addChild(children, parent, type.name);
+    }
+  }
+  return { [ROOT]: buildNode(children, ROOT, new Set([ROOT])) };
+};
+
+export const datasourceTypeTree = (
+  types: readonly Type[],
+  options: { multiParent?: "first" | "all" } = {},
+): DatasourceTypeTree =>
+  buildTree(types, chosenParents(types, options.multiParent ?? "first"));
+
+/** Each type appears once; first `references` parent wins. Cycle tops point at root. */
+export const datasourceTypeTreeFirst = (
+  types: readonly Type[],
+): DatasourceTypeTree => datasourceTypeTree(types, { multiParent: "first" });
+
+/** A type with several parents is nested under each of them. */
+export const datasourceTypeTreeAll = (
+  types: readonly Type[],
+): DatasourceTypeTree => datasourceTypeTree(types, { multiParent: "all" });
+
+/** Child → parent edges. Parentless types point at root; cycles and multi-parent are kept. */
+export const datasourceTypeGraph = (
+  types: readonly Type[],
+): DatasourceTypeGraph => {
+  const parentLists = chosenParents(types, "all");
+  const nodes = [ROOT, ...types.map((type) => type.name)];
+  const edges: DatasourceTypeGraphEdge[] = [];
+  for (const type of types) {
+    const parents = parentLists.get(type.name)!;
+    if (parents.length === 0) {
+      edges.push({ from: type.name, to: ROOT });
+      continue;
+    }
+    for (const parent of parents) {
+      edges.push({ from: type.name, to: parent });
+    }
+  }
+  return { nodes, edges };
+};
+
+export const datasourceTypeHierarchies = (
+  types: readonly Type[],
+): DatasourceTypeHierarchies => ({
+  firstParentTree: datasourceTypeTreeFirst(types),
+  allParentsTree: datasourceTypeTreeAll(types),
+  graph: datasourceTypeGraph(types),
+});
+
+/** Pre-order walk of the first-parent tree (parent before children, authored sibling order). */
+export const datasourceTypeOrder = (
+  types: readonly Type[],
+): string[] => {
+  const names: string[] = [];
+  const walk = (node: DatasourceTypeTree) => {
+    for (const [name, child] of Object.entries(node)) {
+      names.push(name);
+      walk(child);
+    }
+  };
+  walk(datasourceTypeTreeFirst(types)[ROOT]!);
+  return names;
+};
+
+/**
+ * All in-set `references` parents of `name`, recursively, parent before child.
+ * Does not include `name`. Self-edges and cycles are skipped.
+ */
+export const datasourceTypeAncestry = (
+  types: readonly Type[],
+  name: string,
+): string[] => {
+  const parentLists = chosenParents(types, "all");
+  if (!parentLists.has(name)) return [];
+  const out: string[] = [];
+  const seen = new Set<string>();
+  const walk = (current: string, path: ReadonlySet<string>): void => {
+    for (const parent of parentLists.get(current)!) {
+      if (path.has(parent) || seen.has(parent)) continue;
+      walk(parent, new Set([...path, current]));
+      seen.add(parent);
+      out.push(parent);
+    }
+  };
+  walk(name, new Set([name]));
+  return out;
+};
+
+/** Rank by tree order; names that inherit a type sort just after that type. */
+export const compareByDatasourceTypeOrder = (
+  types: readonly Type[],
+  inheritOf: (name: string) => string | null | undefined = () => undefined,
+): ((a: string, b: string) => number) => {
+  const order = datasourceTypeOrder(types);
+  const rank = new Map(order.map((name, i) => [name, i]));
+  const key = (name: string): [number, string] => {
+    const direct = rank.get(name);
+    if (direct !== undefined) return [direct * 2, name];
+    const inherit = inheritOf(name);
+    if (inherit !== null && inherit !== undefined) {
+      const parent = rank.get(inherit);
+      if (parent !== undefined) return [parent * 2 + 1, name];
+    }
+    return [order.length * 2, name];
+  };
+  return (a, b) => {
+    const [ia, na] = key(a);
+    const [ib, nb] = key(b);
+    return ia - ib || na.localeCompare(nb);
+  };
+};
+
+export const datasourceTypeTreeYaml = (tree: DatasourceTypeTree): string =>
+  stringify(tree);
+
+export const datasourceTypeTreeJson = (tree: DatasourceTypeTree): string =>
+  `${JSON.stringify(tree, null, 2)}\n`;
+
+const xmlElement = (
+  name: string,
+  children: DatasourceTypeTree,
+  indent: string,
+): string => {
+  const keys = Object.keys(children);
+  if (keys.length === 0) return `${indent}<${name}/>\n`;
+  const inner = keys
+    .map((key) => xmlElement(key, children[key]!, `${indent}  `))
+    .join("");
+  return `${indent}<${name}>\n${inner}${indent}</${name}>\n`;
+};
+
+export const datasourceTypeTreeXml = (tree: DatasourceTypeTree): string =>
+  Object.keys(tree)
+    .map((key) => xmlElement(key, tree[key]!, ""))
+    .join("");
+
+export const datasourceTypeGraphYaml = (graph: DatasourceTypeGraph): string =>
+  stringify(graph);
+
+export const datasourceTypeGraphJson = (graph: DatasourceTypeGraph): string =>
+  `${JSON.stringify(graph, null, 2)}\n`;
+
+export const datasourceTypeGraphXml = (graph: DatasourceTypeGraph): string => {
+  const nodes = graph.nodes
+    .map((name) => `    <node>${name}</node>\n`)
+    .join("");
+  const edges = graph.edges
+    .map((edge) => `    <edge from="${edge.from}" to="${edge.to}"/>\n`)
+    .join("");
+  return `<graph>\n  <nodes>\n${nodes}  </nodes>\n  <edges>\n${edges}  </edges>\n</graph>\n`;
+};

package/node_modules/@deterministic-code/deterministic-specifications-typescript/typescript/parser/deterministic-reader.ts

@@ -0,0 +1,63 @@
+import { access, readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+
+/** Host-supplied access to the deterministic YAML tree (disk, memory, zip, …). */
+export type IDeterministicReader = {
+  read: (name: string) => Promise<string>;
+  exists: (name: string) => Promise<boolean>;
+};
+
+type Source = {
+  read: (name: string) => Promise<string>;
+  exists: (name: string) => Promise<boolean>;
+};
+
+class DeterministicReader implements IDeterministicReader {
+  #source: Source;
+
+  constructor(source: Source) {
+    this.#source = source;
+  }
+
+  read(name: string): Promise<string> {
+    return this.#source.read(name);
+  }
+
+  exists(name: string): Promise<boolean> {
+    return this.#source.exists(name);
+  }
+}
+
+export const memoryReader = (
+  files: Record<string, string>,
+): IDeterministicReader =>
+  new DeterministicReader({
+    read: async (name) => {
+      if (!(name in files)) {
+        throw new Error(`deterministic reader: missing ${name}`);
+      }
+      return files[name];
+    },
+    exists: async (name) => name in files,
+  });
+
+export const fileReader = (root: string): IDeterministicReader => {
+  const dir = resolve(root);
+  return new DeterministicReader({
+    read: async (name) => {
+      try {
+        return await readFile(join(dir, name), "utf8");
+      } catch {
+        throw new Error(`deterministic reader: missing ${name} in ${dir}`);
+      }
+    },
+    exists: async (name) => {
+      try {
+        await access(join(dir, name));
+        return true;
+      } catch {
+        return false;
+      }
+    },
+  });
+};

package/node_modules/@deterministic-code/deterministic-specifications-typescript/typescript/parser/deterministic.ts

@@ -0,0 +1,35 @@
+import type {
+  DatasourceTable,
+  ParsedRoutes,
+  ParsedServices,
+  SeedRow,
+  Type,
+} from "./specification.ts";
+
+/** Parsed deterministic YAML. One parse, then properties for each document. */
+export type IDeterministic = {
+  types: Type[];
+  expandedTypes: Type[];
+  datasource: DatasourceTable[];
+  datasourceSeeds: Map<string, SeedRow[]>;
+  services: ParsedServices;
+  routes: ParsedRoutes;
+};
+
+export class Deterministic implements IDeterministic {
+  readonly types: Type[];
+  readonly expandedTypes: Type[];
+  readonly datasource: DatasourceTable[];
+  readonly datasourceSeeds: Map<string, SeedRow[]>;
+  readonly services: ParsedServices;
+  readonly routes: ParsedRoutes;
+
+  constructor(args: IDeterministic) {
+    this.types = args.types;
+    this.expandedTypes = args.expandedTypes;
+    this.datasource = args.datasource;
+    this.datasourceSeeds = args.datasourceSeeds;
+    this.services = args.services;
+    this.routes = args.routes;
+  }
+}

package/node_modules/@deterministic-code/deterministic-specifications-typescript/typescript/parser/ensure-health.ts

@@ -0,0 +1,57 @@
+import { Deterministic, type IDeterministic } from "./deterministic.ts";
+import type {
+  CustomRouteEntry,
+  CustomServiceEntry,
+} from "./specification.ts";
+
+export const HEALTH_SERVICE_NAME = "HealthCheckService";
+export const HEALTH_SERVICE_METHOD = "check";
+export const HEALTH_ROUTE_NAME = "getHealth";
+export const HEALTH_ROUTE_PATH = "/api/health";
+
+const seedService = (): CustomServiceEntry => ({
+  name: HEALTH_SERVICE_NAME,
+  methods: [HEALTH_SERVICE_METHOD],
+});
+
+const seedRoute = (): CustomRouteEntry => ({
+  name: HEALTH_ROUTE_NAME,
+  path: HEALTH_ROUTE_PATH,
+  method: "GET",
+  entity: null,
+});
+
+const prepend = <T>(
+  list: T[],
+  match: (item: T) => boolean,
+  seed: T,
+): T[] => {
+  const idx = list.findIndex(match);
+  if (idx === 0) return [...list];
+  if (idx > 0) {
+    return [list[idx]!, ...list.slice(0, idx), ...list.slice(idx + 1)];
+  }
+  return [seed, ...list];
+};
+
+/** Product default: HealthCheckService + GET /api/health first in customs. */
+export const ensureHealth = (deterministic: IDeterministic): IDeterministic =>
+  new Deterministic({
+    ...deterministic,
+    services: {
+      ...deterministic.services,
+      customs: prepend(
+        deterministic.services.customs,
+        (s) => s.name === HEALTH_SERVICE_NAME,
+        seedService(),
+      ),
+    },
+    routes: {
+      ...deterministic.routes,
+      customs: prepend(
+        deterministic.routes.customs,
+        (r) => r.path === HEALTH_ROUTE_PATH,
+        seedRoute(),
+      ),
+    },
+  });

package/node_modules/@deterministic-code/deterministic-specifications-typescript/typescript/parser/parser/compile-filter.ts

@@ -0,0 +1,90 @@
+const ACCESSORS = new Set(["type", "tag", "inherits"]);
+const ALLOWED_INTERNAL = new Set([
+  "__name",
+  "__tags",
+  "__inherits",
+  "includes",
+  "true",
+  "false",
+  "null",
+  "undefined",
+  ...ACCESSORS,
+]);
+
+export type FilterCandidate = {
+  name: string;
+  tags: string[];
+  inherits?: string;
+};
+
+export type FilterPredicate = (cand: FilterCandidate) => boolean;
+
+type CompiledExpr = (
+  name: string,
+  tags: string[],
+  inherits: string,
+) => boolean;
+
+const assertKnownIdents = (s: string, contextLabel: string): void => {
+  for (const ident of s.match(/[A-Za-z_][A-Za-z0-9_]*/g) ?? []) {
+    if (ident.startsWith("__STR")) continue;
+    if (ALLOWED_INTERNAL.has(ident)) continue;
+    throw new Error(
+      `${contextLabel}: unknown identifier or syntax near "${ident}". Supported: \`type == "name"\`, \`tag == "kind"\`, \`inherits == "parent"\`, logical && / ||, parens.`,
+    );
+  }
+};
+
+const compileExpr = (s: string, contextLabel: string): CompiledExpr => {
+  try {
+    return new Function(
+      "__name",
+      "__tags",
+      "__inherits",
+      `return (${s});`,
+    ) as CompiledExpr;
+  } catch (e) {
+    throw new Error(
+      `${contextLabel} is not a valid expression: ${(e as Error).message}`,
+    );
+  }
+};
+
+const rewriteDslToJs = (input: string): string =>
+  input
+    .replace(/\btype\s*(==|!=)\s*(__STR\d+__)/g, (_, op, idx) => {
+      const jsOp = op === "==" ? "===" : "!==";
+      return `(__name ${jsOp} ${idx})`;
+    })
+    .replace(/\btag\s*==\s*(__STR\d+__)/g, (_, idx) => `__tags.includes(${idx})`)
+    .replace(/\btag\s*!=\s*(__STR\d+__)/g, (_, idx) => `!__tags.includes(${idx})`)
+    .replace(/\binherits\s*(==|!=)\s*(__STR\d+__)/g, (_, op, idx) => {
+      const jsOp = op === "==" ? "===" : "!==";
+      return `(__inherits ${jsOp} ${idx})`;
+    });
+
+export const compileFilter = (
+  filterExpr: string | null | undefined,
+  contextLabel = "filter",
+): FilterPredicate => {
+  if (!filterExpr) return () => true;
+
+  const placeholders: string[] = [];
+  const withStrings = filterExpr.replace(/"[^"]*"/g, (m) => {
+    placeholders.push(m);
+    return `__STR${placeholders.length - 1}__`;
+  });
+  const rewritten = rewriteDslToJs(withStrings);
+  assertKnownIdents(rewritten, contextLabel);
+  const restored = rewritten.replace(
+    /__STR(\d+)__/g,
+    (_, idx) => placeholders[Number(idx)]!,
+  );
+  const fn = compileExpr(restored, contextLabel);
+  return (cand) =>
+    Boolean(fn(cand.name, cand.tags, cand.inherits ?? ""));
+};
+
+export const compileTypesFilter = (
+  filterExpr: string | null | undefined,
+): FilterPredicate => compileFilter(filterExpr, "types.filter");