@deterministic-code/datasources-cli 0.1.13 → 0.1.15

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

@@ -1,4 +1,5 @@
 import type { DatasourceFieldOverlay, DatasourceIndex, DatasourceTable, IDeterministic, Type, TypeField } from "@deterministic-code/deterministic-generators-common/parser";
+export { referenceTarget } from "./reference-target.js";
 /** Flattened `datasource.*` flags. Stored procedures are opt-in `"true"`. */
 export declare const datasourceSettings: (settings: Record<string, string>) => {
     useStoredProcedures: boolean;
@@ -28,7 +29,6 @@ export type SqlFile = {
     path: string;
     content: string;
 };
-export declare const referenceTarget: (references: NonNullable<TypeField["references"]>) => [string, string];
 /** Attach physical names and order parent tables before children. */
 export declare const buildLiveTables: (types: SqlTable[], mapping: {
     tableName: (table: SqlTable) => string;

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

@@ -1,4 +1,6 @@
 import { datasourceTypesOf, dictionaryUniqueColumns, identityColumns, persistedColumnFields, tableByName, } from "@deterministic-code/generators-common/spec-types";
+import { inferReferenceFieldTypes } from "./infer-reference-types.js";
+export { referenceTarget } from "./reference-target.js";
 /** Flattened `datasource.*` flags. Stored procedures are opt-in `"true"`. */
 export const datasourceSettings = (settings) => ({
     useStoredProcedures: String(settings["datasource.use_stored_procedures"]) === "true",
@@ -44,6 +46,7 @@ export const isGeneratedIdentity = (table) => {
 export const usesGeneratedIdColumn = (table, field) => field.isId === true && isGeneratedIdentity(table);
 export const sqlTablesFrom = (spec) => {
     requireIdIsId(spec);
+    spec = { ...spec, expandedTypes: inferReferenceFieldTypes(spec.expandedTypes) };
     const overlays = tableByName(spec);
     const byName = new Map(spec.expandedTypes.map((t) => [t.name, t]));
     return datasourceTypesOf(spec).map((type) => {
@@ -80,12 +83,6 @@ const referenceParents = (references) => {
         return [references[0]];
     return [references.split(".")[0]];
 };
-export const referenceTarget = (references) => {
-    if (Array.isArray(references))
-        return [references[0], references[1]];
-    const [table, col] = references.split(".");
-    return [table ?? "", col ?? ""];
-};
 const topoSort = (tables) => {
     const names = new Set(tables.map((t) => t.name));
     const deps = new Map(tables.map((t) => [

package/node_modules/@deterministic-code/datasources-code-generators/dist/sql/common/version-migrations.js

@@ -1,8 +1,7 @@
-import { parse, stringify } from "yaml";
+import { parse } from "yaml";
 import { CreateTableStatement } from "@deterministic-code/datasources";
 import { memoryReader } from "@deterministic-code/generators-common/deterministic-reader";
-import { DeterministicParser } from "@deterministic-code/deterministic-generators-common/parser";
-import { applyDocument, isObject, snapshotsEqual } from "./version-apply.js";
+import { DeterministicParser, VersionSnapshot } from "@deterministic-code/deterministic-generators-common/parser";
 import { createCasing } from "./default-casing.js";
 import { SqlMapping } from "./sql-mapping.js";
 import { buildLiveTables, sqlTablesFrom } from "./sql-schema.js";
@@ -23,11 +22,26 @@ export const versionDiffPaths = (settings) => (settings["version.diffs"] ?? "")
     .split("\n")
     .map((path) => path.trim())
     .filter((path) => versionDiff.test(path));
-const asDocument = (value, source) => isObject(value) ? value : (() => { throw new Error(`${source}: expected a mapping`); })();
+const own = (obj, key) => Object.prototype.hasOwnProperty.call(obj, key);
+const parseDiff = (text, source) => {
+    const value = parse(text);
+    if (value == null || typeof value !== "object" || Array.isArray(value))
+        throw new Error(`${source}: expected a mapping`);
+    return value;
+};
+const fold = (path, text) => VersionSnapshot.combine([{ [path]: { added: true, content: parse(text) } }]).yaml(path);
+const matches = (snapshot, path, live, whenMissing) => {
+    const has = own(snapshot.documents, path);
+    const text = live === undefined || live === "" ? whenMissing : live;
+    if (text === undefined || text === "")
+        return !has;
+    const snapshotYaml = has ? snapshot.yaml(path) : whenMissing === undefined ? undefined : fold(path, whenMissing);
+    return snapshotYaml !== undefined && snapshotYaml === fold(path, text);
+};
 const filesOf = (snapshot) => {
     const files = {};
-    for (const [path, value] of Object.entries(snapshot))
-        files[path] = stringify(value);
+    for (const path of Object.keys(snapshot.documents))
+        files[path] = snapshot.yaml(path);
     files["datasource.yaml"] ??= defaultDatasourceYaml;
     return files;
 };
@@ -37,7 +51,7 @@ const compile = async (snapshot, settings) => {
     const mapping = new SqlMapping(createCasing(settings), types);
     return { tables: buildLiveTables(types, mapping), mapping, seeds: spec.datasourceSeeds };
 };
-const emptySnapshot = (settings) => compile({}, settings);
+const emptySnapshot = (settings) => compile(VersionSnapshot.combine([]), settings);
 const pad = (n) => String(n).padStart(4, "0");
 const renderAll = (dialect, statements) => statements
     .map((statement) => renderSql(dialect, statement))
@@ -48,22 +62,19 @@ export const versionMigrationFiles = async (dialect, ctx, casing, live) => {
     const paths = versionDiffPaths(ctx.settings);
     if (paths.length === 0)
         return { files: [], count: 0 };
-    let before = {};
+    const diffs = [];
     const snapshots = [];
     for (const path of paths) {
         const text = await ctx.reader.read(path);
         if (text === "")
             continue;
-        before = applyDocument(before, asDocument(parse(text), path));
-        snapshots.push(before);
+        diffs.push(parseDiff(text, path));
+        snapshots.push(VersionSnapshot.combine(diffs));
     }
     if (snapshots.length === 0)
         return { files: [], count: 0 };
     const last = snapshots[snapshots.length - 1];
-    const liveTypes = live.typesYaml === undefined ? undefined : parse(live.typesYaml);
-    const liveDatasource = parse(live.datasourceYaml ?? defaultDatasourceYaml);
-    const snapshotDatasource = last["datasource.yaml"] ?? parse(defaultDatasourceYaml);
-    if (!snapshotsEqual(last["types.yaml"], liveTypes) || !snapshotsEqual(snapshotDatasource, liveDatasource)) {
+    if (!matches(last, "types.yaml", live.typesYaml, undefined) || !matches(last, "datasource.yaml", live.datasourceYaml, defaultDatasourceYaml)) {
         throw new Error("types.yaml or datasource.yaml differs from the frozen version diffs; run datasources version first");
     }
     const files = [];

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

@@ -1,6 +1,6 @@
 {
   "name": "@deterministic-code/datasources-code-generators",
-  "version": "0.1.2",
+  "version": "0.1.15",
   "type": "module",
   "exports": {
     ".": "./dist/generateSql.js",
@@ -9,15 +9,17 @@
     "./generate-stored-procedures": "./dist/generate-stored-procedures.js",
     "./sql/generate-stored-procedures": "./dist/sql/generate-stored-procedures.js",
     "./common/sql-dialect": "./dist/sql/common/sql-dialect.js",
-    "./sql/common/write-inclusion": "./dist/sql/common/write-inclusion.js"
+    "./sql/common/write-inclusion": "./dist/sql/common/write-inclusion.js",
+    "./sql/common/default-casing": "./dist/sql/common/default-casing.js",
+    "./sql/common/infer-reference-types": "./dist/sql/common/infer-reference-types.js"
   },
   "dependencies": {
-    "@deterministic-code/datasources": "^0.1.12",
-    "@deterministic-code/datasources-mysql": "^0.1.12",
-    "@deterministic-code/datasources-oracle": "^0.1.12",
-    "@deterministic-code/datasources-postgres": "^0.1.12",
-    "@deterministic-code/datasources-sqlite": "^0.1.12",
-    "@deterministic-code/datasources-sqlserver": "^0.1.12",
+    "@deterministic-code/datasources": "^0.1.14",
+    "@deterministic-code/datasources-mysql": "^0.1.14",
+    "@deterministic-code/datasources-oracle": "^0.1.14",
+    "@deterministic-code/datasources-postgres": "^0.1.14",
+    "@deterministic-code/datasources-sqlite": "^0.1.14",
+    "@deterministic-code/datasources-sqlserver": "^0.1.14",
     "@deterministic-code/deterministic-generators-common": "0.1.0",
     "@deterministic-code/generators-common": "0.0.1",
     "pluralize": "^8.0.0",

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

@@ -2,7 +2,7 @@
 
 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)
+- [`typescript/`](typescript) — npm package `@deterministic-code/deterministic-generators-common` (`DeterministicParser` and `VersionSnapshot` 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)
 
@@ -15,8 +15,68 @@ deterministic_generators_common = { git = "https://github.com/deterministic-code
 <ProjectReference Include="path/to/deterministic-generators-common/csharp/Deterministic.Generators.Common/Deterministic.Generators.Common.csproj" />
 ```
 
+```xml
+<PackageReference Include="Deterministic.Generators.Common" Version="0.1.1" />
+```
+
+TypeScript packs pin `#main`:
+
+```json
+"@deterministic-code/deterministic-generators-common": "github:deterministic-code/deterministic-generators-common#main"
+```
+
+C# first-party consumers use the `ProjectReference`. Out-of-repo C# can take the NuGet package.
+
+```text
+npm run publish:nuget                 # pack and smoke-test
+npm run publish:nuget -- --publish    # push to nuget.org (NUGET_API_KEY)
+```
+
 ```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
 ```
+
+## VersionSnapshot
+
+`VersionSnapshot` reconstructs specification YAML by folding every `deterministic/version-*/diff.yaml` in name order. Documents are the library YAML AST (`YamlValue` / `YamlMap` / `YamlSeq` / `YamlScalar`), not compiled `IDeterministic` and not `DeterministicParser` output.
+
+| API | Role |
+| --- | --- |
+| `Combine` / `combine` | Fold already-parsed diff trees (mappings), in order |
+| `Read` / `read` | Scan a `deterministic/` directory and fold matching version dirs |
+| `Documents` / `documents` | Reconstructed file path → tree |
+| `Yaml` / `yaml(path)` | Serialize one reconstructed file with the library serializer |
+
+Apply helpers are private instance methods. Version directories must match `^version-\d{8}T\d{6}Z-\d{3}$`. Missing or empty `diff.yaml` is skipped. A non-mapping diff throws `expected a mapping`. TypeScript `read` is async; C# and Rust `Read` are sync.
+
+```csharp
+var snapshot = VersionSnapshot.Read(deterministicRoot);
+var types = snapshot.Yaml("types.yaml");
+var datasource = snapshot.Yaml("datasource.yaml");
+```
+
+```typescript
+import { VersionSnapshot } from "@deterministic-code/deterministic-generators-common/parser";
+
+const snapshot = await VersionSnapshot.read(deterministicRoot);
+const types = snapshot.yaml("types.yaml");
+```
+
+```rust
+let snapshot = VersionSnapshot::read(deterministic_root)?;
+let types = snapshot.yaml("types.yaml")?;
+```
+
+`Combine` takes an ordered list of parsed mappings, not YAML strings. To compare a fold to a live file, wrap the live tree as `{ added: true, content }` and compare `Yaml` strings from the same serializer — do not string-compare authored YAML (comments and flow sequences differ).
+
+Per file key in a diff:
+
+- `{ added: true, content }` inserts `content` (`true` or the strings `"true"` / `"True"`).
+- `{ removed: true }` deletes the file.
+- Object merge: nested apply, `removed:` string list deletes keys, new keys are appended.
+- Keyed collections (sequence of single-key maps): `{ added, changed, removed }`. Added entries are prepended.
+- Otherwise the next value replaces.
+
+`Read` does not grow `IDeterministicReader`.

package/node_modules/@deterministic-code/deterministic-generators-common/typescript/parser/dist/specification-parser.js

@@ -1355,6 +1355,133 @@ var Parser = class {
     return nested;
   }
 };
+
+// node_modules/@deterministic-code/deterministic-generators-common/typescript/parser/version-snapshot.ts
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parse as parse2, stringify as stringify2 } from "yaml";
+var versionDir = /^version-\d{8}T\d{6}Z-\d{3}$/;
+var own = (obj, key) => Object.prototype.hasOwnProperty.call(obj, key);
+var VersionSnapshot = class _VersionSnapshot {
+  documents;
+  constructor(diffsInOrder) {
+    const docs = {};
+    for (const diff of diffsInOrder) {
+      if (diff == null) continue;
+      if (!this.isMap(diff)) throw new Error("expected a mapping");
+      for (const [path, envelope] of Object.entries(diff)) {
+        const next = this.applyFile(docs[path], envelope);
+        if (this.isNull(next)) delete docs[path];
+        else docs[path] = next;
+      }
+    }
+    this.documents = docs;
+  }
+  static combine(diffsInOrder) {
+    return new _VersionSnapshot(diffsInOrder);
+  }
+  static async read(deterministicRoot) {
+    const names = (await readdir(deterministicRoot, { withFileTypes: true })).filter((entry) => entry.isDirectory() && versionDir.test(entry.name)).map((entry) => entry.name).sort();
+    const snapshot = new _VersionSnapshot([]);
+    return _VersionSnapshot.combine(await Promise.all(names.map((name) => snapshot.diffOf(deterministicRoot, name))));
+  }
+  yaml(path) {
+    if (!own(this.documents, path)) throw new Error(`missing ${path}`);
+    return stringify2(this.documents[path]);
+  }
+  async diffOf(root, name) {
+    let text;
+    try {
+      text = await readFile(join(root, name, "diff.yaml"), "utf8");
+    } catch {
+      return void 0;
+    }
+    if (text === "") return void 0;
+    let rootValue;
+    try {
+      rootValue = parse2(text);
+    } catch (error) {
+      throw new Error(`${name}/diff.yaml: ${String(error)}`);
+    }
+    if (!this.isMap(rootValue)) throw new Error(`${name}/diff.yaml: expected a mapping`);
+    return rootValue;
+  }
+  applyFile(before, envelope) {
+    if (this.isNull(envelope)) return before;
+    if (this.isMap(envelope) && this.isTrue(envelope, "removed") && Object.keys(envelope).length === 1)
+      return void 0;
+    if (this.isMap(envelope) && this.isTrue(envelope, "added")) return envelope.content;
+    return this.apply(before, envelope);
+  }
+  apply(before, next) {
+    if (this.isNull(next)) return before;
+    if (this.isKeyed(before) && this.isMap(next) && this.isSplit(next)) return this.applyKeyed(before, next);
+    if (this.isMap(before) && this.isMap(next)) return this.applyObject(before, next);
+    return next;
+  }
+  applyKeyed(beforeVal, split) {
+    const removed = new Set(this.strings(split, "removed"));
+    const changed = new Map(
+      this.seq(split.changed).flatMap((entry) => {
+        const pair = this.firstPair(entry);
+        return pair ? [[pair.key, pair.value]] : [];
+      })
+    );
+    return [
+      ...this.seq(split.added),
+      ...beforeVal.flatMap((entry) => {
+        const pair = this.firstPair(entry);
+        if (!pair || removed.has(pair.key)) return [];
+        return [
+          changed.has(pair.key) ? { [pair.key]: this.apply(pair.value, changed.get(pair.key)) } : entry
+        ];
+      })
+    ];
+  }
+  applyObject(beforeVal, next) {
+    const removed = new Set(this.strings(next, "removed"));
+    const output = {};
+    for (const [key, value] of Object.entries(beforeVal)) {
+      if (removed.has(key)) continue;
+      output[key] = own(next, key) ? this.apply(value, next[key]) : value;
+    }
+    for (const [key, value] of Object.entries(next)) {
+      if (key === "removed" && Array.isArray(value)) continue;
+      if (!own(beforeVal, key)) output[key] = value;
+    }
+    return output;
+  }
+  isSplit(map) {
+    return Object.keys(map).every((key) => key === "added" || key === "changed" || key === "removed");
+  }
+  isKeyed(value) {
+    return Array.isArray(value) && value.length > 0 && value.every((item) => this.isMap(item) && Object.keys(item).length === 1);
+  }
+  seq(value) {
+    return Array.isArray(value) ? value : [];
+  }
+  strings(map, key) {
+    return this.seq(map[key]).map((item) => this.isScalar(item) ? String(item ?? "") : "");
+  }
+  firstPair(entry) {
+    if (!this.isMap(entry)) return void 0;
+    const key = Object.keys(entry)[0];
+    return key === void 0 ? void 0 : { key, value: entry[key] };
+  }
+  isMap(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+  }
+  isTrue(map, key) {
+    return map[key] === true || map[key] === "true" || map[key] === "True";
+  }
+  isNull(value) {
+    return value == null;
+  }
+  isScalar(value) {
+    return value == null || typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+  }
+};
 export {
-  DeterministicParser
+  DeterministicParser,
+  VersionSnapshot
 };

package/node_modules/@deterministic-code/deterministic-generators-common/typescript/parser/specification-parser.ts

@@ -1,5 +1,6 @@
 export type { IDeterministic } from "./deterministic.ts";
 export { DeterministicParser } from "./parser/specification-parser.ts";
+export { VersionSnapshot } from "./version-snapshot.ts";
 export type {
   CustomRouteEntry,
   CustomServiceEntry,

package/node_modules/@deterministic-code/deterministic-generators-common/typescript/parser/version-snapshot.ts

@@ -0,0 +1,154 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parse, stringify } from "yaml";
+import type { YamlMap, YamlValue } from "./yaml-node.ts";
+
+const versionDir = /^version-\d{8}T\d{6}Z-\d{3}$/;
+const own = (obj: object, key: string) => Object.prototype.hasOwnProperty.call(obj, key);
+
+export class VersionSnapshot {
+  readonly documents: Readonly<Record<string, YamlValue | undefined>>;
+
+  private constructor(diffsInOrder: Array<YamlValue | null | undefined>) {
+    const docs: Record<string, YamlValue | undefined> = {};
+    for (const diff of diffsInOrder) {
+      if (diff == null) continue;
+      if (!this.isMap(diff)) throw new Error("expected a mapping");
+      for (const [path, envelope] of Object.entries(diff)) {
+        const next = this.applyFile(docs[path], envelope);
+        if (this.isNull(next)) delete docs[path];
+        else docs[path] = next;
+      }
+    }
+    this.documents = docs;
+  }
+
+  static combine(diffsInOrder: Array<YamlValue | null | undefined>): VersionSnapshot {
+    return new VersionSnapshot(diffsInOrder);
+  }
+
+  static async read(deterministicRoot: string): Promise<VersionSnapshot> {
+    const names = (await readdir(deterministicRoot, { withFileTypes: true }))
+      .filter((entry) => entry.isDirectory() && versionDir.test(entry.name))
+      .map((entry) => entry.name)
+      .sort();
+    const snapshot = new VersionSnapshot([]);
+    return VersionSnapshot.combine(await Promise.all(names.map((name) => snapshot.diffOf(deterministicRoot, name))));
+  }
+
+  yaml(path: string): string {
+    if (!own(this.documents, path)) throw new Error(`missing ${path}`);
+    return stringify(this.documents[path]);
+  }
+
+  private async diffOf(root: string, name: string): Promise<YamlValue | undefined> {
+    let text: string;
+    try {
+      text = await readFile(join(root, name, "diff.yaml"), "utf8");
+    } catch {
+      return undefined;
+    }
+    if (text === "") return undefined;
+    let rootValue: YamlValue;
+    try {
+      rootValue = parse(text) as YamlValue;
+    } catch (error) {
+      throw new Error(`${name}/diff.yaml: ${String(error)}`);
+    }
+    if (!this.isMap(rootValue)) throw new Error(`${name}/diff.yaml: expected a mapping`);
+    return rootValue;
+  }
+
+  private applyFile(before: YamlValue | undefined, envelope: YamlValue | undefined): YamlValue | undefined {
+    if (this.isNull(envelope)) return before;
+    if (this.isMap(envelope) && this.isTrue(envelope, "removed") && Object.keys(envelope).length === 1)
+      return undefined;
+    if (this.isMap(envelope) && this.isTrue(envelope, "added")) return envelope.content;
+    return this.apply(before, envelope);
+  }
+
+  private apply(before: YamlValue | undefined, next: YamlValue | undefined): YamlValue | undefined {
+    if (this.isNull(next)) return before;
+    if (this.isKeyed(before) && this.isMap(next) && this.isSplit(next)) return this.applyKeyed(before, next);
+    if (this.isMap(before) && this.isMap(next)) return this.applyObject(before, next);
+    return next;
+  }
+
+  private applyKeyed(beforeVal: YamlMap[], split: YamlMap): YamlValue {
+    const removed = new Set(this.strings(split, "removed"));
+    const changed = new Map(
+      this.seq(split.changed).flatMap((entry) => {
+        const pair = this.firstPair(entry);
+        return pair ? [[pair.key, pair.value] as const] : [];
+      }),
+    );
+    return [
+      ...this.seq(split.added),
+      ...beforeVal.flatMap((entry) => {
+        const pair = this.firstPair(entry);
+        if (!pair || removed.has(pair.key)) return [];
+        return [
+          changed.has(pair.key)
+            ? { [pair.key]: this.apply(pair.value, changed.get(pair.key)) as YamlValue }
+            : entry,
+        ];
+      }),
+    ];
+  }
+
+  private applyObject(beforeVal: YamlMap, next: YamlMap): YamlMap {
+    const removed = new Set(this.strings(next, "removed"));
+    const output: Record<string, YamlValue> = {};
+    for (const [key, value] of Object.entries(beforeVal)) {
+      if (removed.has(key)) continue;
+      output[key] = (own(next, key) ? this.apply(value, next[key]) : value) as YamlValue;
+    }
+    for (const [key, value] of Object.entries(next)) {
+      if (key === "removed" && Array.isArray(value)) continue;
+      if (!own(beforeVal, key)) output[key] = value;
+    }
+    return output;
+  }
+
+  private isSplit(map: YamlMap) {
+    return Object.keys(map).every((key) => key === "added" || key === "changed" || key === "removed");
+  }
+
+  private isKeyed(value: YamlValue | undefined): value is YamlMap[] {
+    return (
+      Array.isArray(value) &&
+      value.length > 0 &&
+      value.every((item) => this.isMap(item) && Object.keys(item).length === 1)
+    );
+  }
+
+  private seq(value: YamlValue | undefined): YamlValue[] {
+    return Array.isArray(value) ? value : [];
+  }
+
+  private strings(map: YamlMap, key: string) {
+    return this.seq(map[key]).map((item) => (this.isScalar(item) ? String(item ?? "") : ""));
+  }
+
+  private firstPair(entry: YamlValue | undefined) {
+    if (!this.isMap(entry)) return undefined;
+    const key = Object.keys(entry)[0];
+    return key === undefined ? undefined : { key, value: entry[key] };
+  }
+
+  private isMap(value: YamlValue | undefined | null): value is YamlMap {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+  }
+
+  private isTrue(map: YamlMap, key: string) {
+    return map[key] === true || map[key] === "true" || map[key] === "True";
+  }
+
+  private isNull(value: YamlValue | undefined | null) {
+    return value == null;
+  }
+
+  private isScalar(value: YamlValue | undefined) {
+    return value == null || typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+  }
+}

package/node_modules/@deterministic-code/deterministic-generators-common/typescript/parser/yaml-node.ts

@@ -1,8 +1,8 @@
 import { parse } from "yaml";
 
 type YamlLiteral = string | number | boolean | null;
-type YamlMap = { readonly [key: string]: YamlValue };
-type YamlValue = YamlLiteral | YamlValue[] | YamlMap;
+export type YamlMap = { readonly [key: string]: YamlValue };
+export type YamlValue = YamlLiteral | YamlValue[] | YamlMap;
 type FieldDefault = YamlLiteral | YamlValue[] | YamlMap;
 type Named = { name: string; node: YamlNode };
 

package/node_modules/@deterministic-code/deterministic-specifications-typescript/README.md

@@ -2,7 +2,7 @@
 
 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)
+- [`typescript/`](typescript) — npm package `@deterministic-code/deterministic-generators-common` (`DeterministicParser` and `VersionSnapshot` 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)
 
@@ -15,8 +15,68 @@ deterministic_generators_common = { git = "https://github.com/deterministic-code
 <ProjectReference Include="path/to/deterministic-generators-common/csharp/Deterministic.Generators.Common/Deterministic.Generators.Common.csproj" />
 ```
 
+```xml
+<PackageReference Include="Deterministic.Generators.Common" Version="0.1.1" />
+```
+
+TypeScript packs pin `#main`:
+
+```json
+"@deterministic-code/deterministic-generators-common": "github:deterministic-code/deterministic-generators-common#main"
+```
+
+C# first-party consumers use the `ProjectReference`. Out-of-repo C# can take the NuGet package.
+
+```text
+npm run publish:nuget                 # pack and smoke-test
+npm run publish:nuget -- --publish    # push to nuget.org (NUGET_API_KEY)
+```
+
 ```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
 ```
+
+## VersionSnapshot
+
+`VersionSnapshot` reconstructs specification YAML by folding every `deterministic/version-*/diff.yaml` in name order. Documents are the library YAML AST (`YamlValue` / `YamlMap` / `YamlSeq` / `YamlScalar`), not compiled `IDeterministic` and not `DeterministicParser` output.
+
+| API | Role |
+| --- | --- |
+| `Combine` / `combine` | Fold already-parsed diff trees (mappings), in order |
+| `Read` / `read` | Scan a `deterministic/` directory and fold matching version dirs |
+| `Documents` / `documents` | Reconstructed file path → tree |
+| `Yaml` / `yaml(path)` | Serialize one reconstructed file with the library serializer |
+
+Apply helpers are private instance methods. Version directories must match `^version-\d{8}T\d{6}Z-\d{3}$`. Missing or empty `diff.yaml` is skipped. A non-mapping diff throws `expected a mapping`. TypeScript `read` is async; C# and Rust `Read` are sync.
+
+```csharp
+var snapshot = VersionSnapshot.Read(deterministicRoot);
+var types = snapshot.Yaml("types.yaml");
+var datasource = snapshot.Yaml("datasource.yaml");
+```
+
+```typescript
+import { VersionSnapshot } from "@deterministic-code/deterministic-generators-common/parser";
+
+const snapshot = await VersionSnapshot.read(deterministicRoot);
+const types = snapshot.yaml("types.yaml");
+```
+
+```rust
+let snapshot = VersionSnapshot::read(deterministic_root)?;
+let types = snapshot.yaml("types.yaml")?;
+```
+
+`Combine` takes an ordered list of parsed mappings, not YAML strings. To compare a fold to a live file, wrap the live tree as `{ added: true, content }` and compare `Yaml` strings from the same serializer — do not string-compare authored YAML (comments and flow sequences differ).
+
+Per file key in a diff:
+
+- `{ added: true, content }` inserts `content` (`true` or the strings `"true"` / `"True"`).
+- `{ removed: true }` deletes the file.
+- Object merge: nested apply, `removed:` string list deletes keys, new keys are appended.
+- Keyed collections (sequence of single-key maps): `{ added, changed, removed }`. Added entries are prepended.
+- Otherwise the next value replaces.
+
+`Read` does not grow `IDeterministicReader`.

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

@@ -1,5 +1,6 @@
 export type { IDeterministic } from "./deterministic.ts";
 export { DeterministicParser } from "./parser/specification-parser.ts";
+export { VersionSnapshot } from "./version-snapshot.ts";
 export type {
   CustomRouteEntry,
   CustomServiceEntry,