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

package/node_modules/@deterministic-code/datasources-code-generators/dist/sql/resources/sql.js

@@ -0,0 +1,6 @@
+import { readFile } from "node:fs/promises";
+const resource = (rel) => readFile(new URL(`../templates/create-sql/${rel}`, import.meta.url), "utf8");
+export const [migrationUpTmpl, migrationDownTmpl] = await Promise.all([
+    resource("migration-up.sql.tmpl"),
+    resource("migration-down.sql.tmpl"),
+]);

package/node_modules/@deterministic-code/datasources-code-generators/dist/sql/statements.d.ts

@@ -0,0 +1,28 @@
+import { CreateBulkCreateStoredProcedureStatement, CreateBulkDeleteStoredProcedureStatement, CreateBulkUpdateStoredProcedureStatement, CreateCreateStoredProcedureStatement, CreateDeleteStoredProcedureStatement, CreateIndexStatement, CreateReadStoredProcedureStatement, CreateTableStatement, CreateTriggerStatement, CreateUpdateStoredProcedureStatement, DeleteStatement, DropIndexStatement, DropRoutineStatement, DropTableStatement, DropTriggerStatement, ForeignKey, IdentityInsertStatement, InsertStatement, SelectStatement, UniqueConstraint, UpdateStatement, type Column, type RoutineParameter } from "@deterministic-code/datasources";
+import type { DatasourceIndex, TypeField } from "@deterministic-code/deterministic-generators-common/parser";
+import { type LiveTable } from "./common/sql-schema.js";
+import type { SqlMapping } from "./common/sql-mapping.js";
+import { type SqlDialect } from "./common/sql-dialect.js";
+export declare const columnOf: (dialect: SqlDialect, mapping: SqlMapping, table: LiveTable, field: TypeField) => Column;
+export declare const createTableStatementOf: (dialect: SqlDialect, table: LiveTable, mapping: SqlMapping) => CreateTableStatement;
+export declare const createIndexStatementOf: (dialect: SqlDialect, mapping: SqlMapping, table: LiveTable, idx: DatasourceIndex) => CreateIndexStatement;
+export declare const dropTableStatementOf: (dialect: SqlDialect, table: string) => DropTableStatement;
+export declare const dropIndexStatementOf: (dialect: SqlDialect, name: string, table: string) => DropIndexStatement;
+export declare const dropTriggerStatementOf: (dialect: SqlDialect, name: string, table: string) => DropTriggerStatement;
+export declare const uniqueConstraintOf: (dialect: SqlDialect, mapping: SqlMapping, table: LiveTable, field: TypeField) => UniqueConstraint;
+export declare const foreignKeyOf: (dialect: SqlDialect, mapping: SqlMapping, table: LiveTable, field: TypeField) => ForeignKey;
+export declare const createTriggerStatementOf: (dialect: SqlDialect, table: LiveTable, mapping: SqlMapping, key: string) => CreateTriggerStatement;
+export declare const seedInsertStatementOf: (table: LiveTable, mapping: SqlMapping, columns: string[], values: string[], dialect: SqlDialect) => InsertStatement;
+export declare const identityInsertStatementOf: (dialect: SqlDialect, table: LiveTable, mapping: SqlMapping, inserts: InsertStatement[], identity: boolean) => IdentityInsertStatement;
+export declare const findStatementOf: (dialect: SqlDialect, table: string, fields: string[], key: string) => SelectStatement;
+export declare const insertStatementOf: (table: string, fields: string[]) => InsertStatement;
+export declare const updateStatementOf: (table: string, fields: string[], keys: string[]) => UpdateStatement;
+export declare const deleteStatementOf: (table: string, keys: string[]) => DeleteStatement;
+export declare const dropRoutineStatementOf: (name: string) => DropRoutineStatement;
+export declare const createCreateStoredProcedureOf: (name: string, table: string, columns: readonly string[], parameters: readonly RoutineParameter[], key: string, keyType: string, writable: readonly string[], generatedKey?: boolean, auditUpdated?: string) => CreateCreateStoredProcedureStatement;
+export declare const createReadStoredProcedureOf: (name: string, table: string, columns: readonly string[], parameters: readonly RoutineParameter[], key: string, keyType: string, writable: readonly string[], byProperties?: readonly string[], generatedKey?: boolean, auditUpdated?: string) => CreateReadStoredProcedureStatement;
+export declare const createUpdateStoredProcedureOf: (name: string, table: string, columns: readonly string[], parameters: readonly RoutineParameter[], key: string, keyType: string, writable: readonly string[], byProperties?: readonly string[], generatedKey?: boolean, auditUpdated?: string) => CreateUpdateStoredProcedureStatement;
+export declare const createDeleteStoredProcedureOf: (name: string, table: string, columns: readonly string[], parameters: readonly RoutineParameter[], key: string, keyType: string, writable: readonly string[], byProperties?: readonly string[], generatedKey?: boolean, auditUpdated?: string) => CreateDeleteStoredProcedureStatement;
+export declare const createBulkCreateStoredProcedureOf: (name: string, table: string, columns: readonly RoutineParameter[], payload: RoutineParameter, key: string, keyType: string) => CreateBulkCreateStoredProcedureStatement;
+export declare const createBulkUpdateStoredProcedureOf: (name: string, table: string, columns: readonly RoutineParameter[], payload: RoutineParameter, key: string, keyType: string) => CreateBulkUpdateStoredProcedureStatement;
+export declare const createBulkDeleteStoredProcedureOf: (name: string, table: string, columns: readonly RoutineParameter[], payload: RoutineParameter, key: string, keyType: string) => CreateBulkDeleteStoredProcedureStatement;

package/node_modules/@deterministic-code/datasources-code-generators/dist/sql/statements.js

@@ -0,0 +1,81 @@
+import { ColumnDefault, CreateBulkCreateStoredProcedureStatement, CreateBulkDeleteStoredProcedureStatement, CreateBulkUpdateStoredProcedureStatement, CreateCreateStoredProcedureStatement, CreateDeleteStoredProcedureStatement, CreateIndexStatement, CreateReadStoredProcedureStatement, CreateTableStatement, CreateTriggerStatement, CreateUpdateStoredProcedureStatement, DeleteStatement, DropIndexStatement, DropRoutineStatement, DropTableStatement, DropTriggerStatement, ForeignKey, IdentityInsertStatement, InsertStatement, NotNull, PrimaryKey, SelectStatement, UniqueConstraint, UpdateStatement, Operator, Where, eq, } from "@deterministic-code/datasources";
+import { isPkField } from "@deterministic-code/generators-common/spec-types";
+import { converterFieldOf } from "./common/converter-field.js";
+import { fieldOverlay, overlayOf, tableIdentity, usesGeneratedIdColumn, } from "./common/sql-schema.js";
+import { dialectDriver, mapColumnType, q, sqlDefault, } from "./common/sql-dialect.js";
+export const columnOf = (dialect, mapping, table, field) => {
+    const overlay = fieldOverlay(table, field.name);
+    const converterField = converterFieldOf(field);
+    const generated = usesGeneratedIdColumn(table, field);
+    const identity = generated && field.type !== "uuid" && field.type !== "string";
+    const named = mapping.constraintName(table, mapping.fieldStem(table, field.name), "default_constraint");
+    const utcNow = dialectDriver(dialect).defaultValueConverter.convert("datetime", "UtcNow");
+    const newId = dialectDriver(dialect).defaultValueConverter.convert("uuid", "NewId");
+    const fromSpec = sqlDefault(dialect, converterField);
+    const defaultExpr = fromSpec ??
+        (field.name === "created" || field.name === "updated" ? utcNow : null) ??
+        (field.name === "uuid" || (generated && field.type === "uuid") ? newId : null);
+    const keys = tableIdentity(table);
+    return {
+        name: q(dialect, mapping.columnName(table, field.name)),
+        type: mapColumnType(dialect, converterField),
+        ...(defaultExpr ? { default: new ColumnDefault(defaultExpr, q(dialect, named)) } : {}),
+        ...(!field.isNullable || keys.includes(field.name) ? { notNull: new NotNull() } : {}),
+        ...(identity ? { identity: true } : {}),
+    };
+};
+export const createTableStatementOf = (dialect, table, mapping) => {
+    const keys = tableIdentity(table);
+    const columns = table.fields.map((field) => columnOf(dialect, mapping, table, field));
+    const uniques = table.fields
+        .filter((field) => fieldOverlay(table, field.name)?.isUnique === true || field.name === "uuid")
+        .map((field) => new UniqueConstraint(q(dialect, mapping.constraintName(table, mapping.fieldStem(table, field.name), "unique_constraint")), [q(dialect, mapping.columnName(table, field.name))]));
+    const foreignKeys = table.fields
+        .filter((field) => field.references !== undefined)
+        .map((field) => {
+        const ref = mapping.resolveReference(field.references);
+        return new ForeignKey(q(dialect, mapping.constraintName(table, mapping.fieldStem(table, field.name), "foreign_key")), [q(dialect, mapping.columnName(table, field.name))], q(dialect, ref.tableName), [q(dialect, ref.columnName)]);
+    });
+    const pk = keys.length > 1
+        ? [new PrimaryKey(q(dialect, mapping.constraintName(table, "primary_key")), keys.map((key) => q(dialect, mapping.columnName(table, key))))]
+        : keys.length === 1 && table.fields.some((field) => isPkField(field, table, overlayOf(table)))
+            ? [new PrimaryKey(q(dialect, mapping.constraintName(table, "primary_key")), [q(dialect, mapping.columnName(table, keys[0]))])]
+            : [];
+    return new CreateTableStatement(q(dialect, table.tableName), columns, [...pk, ...uniques, ...foreignKeys]);
+};
+export const createIndexStatementOf = (dialect, mapping, table, idx) => new CreateIndexStatement(q(dialect, mapping.constraintName(table, idx.name, "index")), q(dialect, table.tableName), idx.fields.map((column) => q(dialect, mapping.columnName(table, column))), idx.isUnique);
+export const dropTableStatementOf = (dialect, table) => new DropTableStatement(q(dialect, table));
+export const dropIndexStatementOf = (dialect, name, table) => new DropIndexStatement(q(dialect, name), q(dialect, table));
+export const dropTriggerStatementOf = (dialect, name, table) => new DropTriggerStatement(q(dialect, name), q(dialect, table));
+export const uniqueConstraintOf = (dialect, mapping, table, field) => new UniqueConstraint(q(dialect, mapping.constraintName(table, mapping.fieldStem(table, field.name), "unique_constraint")), [q(dialect, mapping.columnName(table, field.name))]);
+export const foreignKeyOf = (dialect, mapping, table, field) => {
+    const ref = mapping.resolveReference(field.references);
+    return new ForeignKey(q(dialect, mapping.constraintName(table, mapping.fieldStem(table, field.name), "foreign_key")), [q(dialect, mapping.columnName(table, field.name))], q(dialect, ref.tableName), [q(dialect, ref.columnName)]);
+};
+export const createTriggerStatementOf = (dialect, table, mapping, key) => new CreateTriggerStatement(q(dialect, table.tableName), q(dialect, mapping.triggerName(table)), q(dialect, mapping.columnName(table, "updated")), q(dialect, mapping.columnName(table, key)), dialectDriver(dialect).defaultValueConverter.convert("datetime", "UtcNow") ?? "");
+export const seedInsertStatementOf = (table, mapping, columns, values, dialect) => new InsertStatement(q(dialect, table.tableName), columns.map((column, i) => ({
+    name: q(dialect, mapping.columnName(table, column)),
+    value: values[i] ?? "NULL",
+})));
+export const identityInsertStatementOf = (dialect, table, mapping, inserts, identity) => {
+    const keys = tableIdentity(table);
+    return new IdentityInsertStatement(table.tableName, mapping.columnName(table, keys[0] ?? "id"), inserts, identity);
+};
+export const findStatementOf = (dialect, table, fields, key) => new SelectStatement({
+    table: q(dialect, table),
+    fields: fields.map((field) => `t.${q(dialect, field)}`),
+    where: new Where(eq(`t.${q(dialect, key)}`, key)),
+});
+export const insertStatementOf = (table, fields) => new InsertStatement(table, fields.map((name) => ({ name, value: name })));
+const equalsWhere = ([first, ...rest]) => new Where(rest.reduce((condition, column) => new Operator.And(condition, eq(column, column)), eq(first, first)));
+export const updateStatementOf = (table, fields, keys) => new UpdateStatement(table, fields.map((name) => ({ name, value: name })), equalsWhere(keys));
+export const deleteStatementOf = (table, keys) => new DeleteStatement(table, equalsWhere(keys));
+export const dropRoutineStatementOf = (name) => new DropRoutineStatement(name);
+const rowArgs = (name, table, columns, parameters, key, keyType, writable, generatedKey = false, auditUpdated) => [name, table, columns, parameters, key, keyType, writable, generatedKey, auditUpdated];
+export const createCreateStoredProcedureOf = (name, table, columns, parameters, key, keyType, writable, generatedKey = false, auditUpdated) => new CreateCreateStoredProcedureStatement(...rowArgs(name, table, columns, parameters, key, keyType, writable, generatedKey, auditUpdated));
+export const createReadStoredProcedureOf = (name, table, columns, parameters, key, keyType, writable, byProperties = [], generatedKey = false, auditUpdated) => new CreateReadStoredProcedureStatement(name, table, columns, parameters, key, keyType, writable, byProperties, generatedKey, auditUpdated);
+export const createUpdateStoredProcedureOf = (name, table, columns, parameters, key, keyType, writable, byProperties = [], generatedKey = false, auditUpdated) => new CreateUpdateStoredProcedureStatement(name, table, columns, parameters, key, keyType, writable, byProperties, generatedKey, auditUpdated);
+export const createDeleteStoredProcedureOf = (name, table, columns, parameters, key, keyType, writable, byProperties = [], generatedKey = false, auditUpdated) => new CreateDeleteStoredProcedureStatement(name, table, columns, parameters, key, keyType, writable, byProperties, generatedKey, auditUpdated);
+export const createBulkCreateStoredProcedureOf = (name, table, columns, payload, key, keyType) => new CreateBulkCreateStoredProcedureStatement(name, table, columns, payload, key, keyType);
+export const createBulkUpdateStoredProcedureOf = (name, table, columns, payload, key, keyType) => new CreateBulkUpdateStoredProcedureStatement(name, table, columns, payload, key, keyType);
+export const createBulkDeleteStoredProcedureOf = (name, table, columns, payload, key, keyType) => new CreateBulkDeleteStoredProcedureStatement(name, table, columns, payload, key, keyType);

package/node_modules/@deterministic-code/datasources-code-generators/dist/sql/templates/create-sql/migration-down.sql.tmpl

@@ -0,0 +1,6 @@
+-- Rollback initial migration for {{dialect}}
+
+-- DROP tables (reverse dependency order)
+{{#dropStatements}}
+{{{.}}}
+{{/dropStatements}}

package/node_modules/@deterministic-code/datasources-code-generators/dist/sql/templates/create-sql/migration-up.sql.tmpl

@@ -0,0 +1,18 @@
+-- Generated initial migration for {{dialect}}
+
+{{{preamble}}}-- Create added tables
+{{#tables}}
+{{{createTable}}}
+{{#indexesBlock}}
+{{{indexesBlock}}}
+{{/indexesBlock}}
+{{#trigger}}
+{{{trigger}}}
+{{/trigger}}
+
+{{/tables}}{{#hasSeeds}}
+-- Seed data
+{{#seedBlocks}}
+{{{.}}}
+{{/seedBlocks}}
+{{/hasSeeds}}

package/node_modules/@deterministic-code/datasources-code-generators/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@deterministic-code/datasources-code-generators",
+  "version": "0.1.2",
+  "type": "module",
+  "exports": {
+    ".": "./dist/generateSql.js",
+    "./generate-sql": "./dist/generate-sql.js",
+    "./generate-stored-procedures": "./dist/generate-stored-procedures.js",
+    "./common/sql-dialect": "./dist/sql/common/sql-dialect.js",
+    "./sql/dialect-converters": "./dist/sql/dialect-converters.js"
+  },
+  "dependencies": {
+    "@deterministic-code/datasources": "^0.1.2",
+    "@deterministic-code/datasources-mysql": "^0.1.2",
+    "@deterministic-code/datasources-oracle": "^0.1.2",
+    "@deterministic-code/datasources-postgres": "^0.1.2",
+    "@deterministic-code/datasources-sqlite": "^0.1.2",
+    "@deterministic-code/datasources-sqlserver": "^0.1.2",
+    "@deterministic-code/deterministic-generators-common": "0.1.0",
+    "@deterministic-code/generators-common": "0.0.1",
+    "pluralize": "^8.0.0",
+    "yaml": "^2.6.0"
+  }
+}

package/node_modules/@deterministic-code/deterministic-generators-common/README.md

@@ -0,0 +1,22 @@
+# deterministic-generators-common
+
+Parser and validators for the [deterministic-specifications](https://github.com/deterministic-code/deterministic-specifications) contract. Each language is its own library. Specs and samples stay in the specifications repo; these libraries only read them.
+
+- [`typescript/`](typescript) — npm package `@deterministic-code/deterministic-generators-common` (`DeterministicParser` on the `./parser` export, validators on the package root)
+- [`rust/`](rust) — crate `deterministic_generators_common` (path/git dependency)
+- [`csharp/`](csharp) — `Deterministic.Generators.Common` (`net10.0` class library)
+
+```toml
+# Cargo.toml
+deterministic_generators_common = { git = "https://github.com/deterministic-code/deterministic-generators-common", subdirectory = "rust" }
+```
+
+```xml
+<ProjectReference Include="path/to/deterministic-generators-common/csharp/Deterministic.Generators.Common/Deterministic.Generators.Common.csproj" />
+```
+
+```text
+npm test                         # TypeScript parser + validator (100% coverage)
+sh rust/coverage.sh              # cargo llvm-cov, 100% lines + functions
+dotnet test csharp/Deterministic.Generators.Common.slnx --settings csharp/coverlet.runsettings
+```

package/node_modules/@deterministic-code/deterministic-generators-common/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-generators-common/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-generators-common/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-generators-common/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;
+  }
+}