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

package/node_modules/@deterministic-code/deterministic-generators-common/typescript/validator/validators/DatasourceSeedsValidator.ts

@@ -0,0 +1,75 @@
+import { SpecValidator, type ParsedYaml } from "../SpecValidator.ts";
+import type { SpecValidationResult, ValidateOptions } from "../types.ts";
+import { parseYamlWithPositions } from "../yamlPositions.ts";
+import {
+  checkSeedSemantics,
+  companionError,
+  seedsNeedCompanions,
+  withSiblingCompanions,
+} from "../seedSemantics.ts";
+
+const MISSING_TYPES =
+  "types.yaml is required to validate seeds (pass types, or place types.yaml next to the seeds file)";
+
+async function checkSeeds(
+  parsed: ParsedYaml,
+  options?: ValidateOptions,
+): Promise<SpecValidationResult> {
+  const typesText = options?.types;
+  const datasourceText = options?.datasource;
+  if (typesText === undefined) {
+    if (!seedsNeedCompanions(parsed.data)) return { valid: true, errors: [] };
+    return companionError(parsed, MISSING_TYPES);
+  }
+
+  const typesValidator = new SpecValidator({
+    subdir: "backend",
+    name: "types.spec.yaml",
+  });
+  const typesResult = await typesValidator.validate(typesText);
+  if (!typesResult.valid) {
+    return companionError(
+      parsed,
+      `companion types.yaml is invalid: ${typesResult.errors[0]?.message}`,
+    );
+  }
+
+  if (datasourceText !== undefined) {
+    const datasourceValidator = new SpecValidator({
+      subdir: "backend",
+      name: "datasource.spec.yaml",
+    });
+    const datasourceResult = await datasourceValidator.validate(datasourceText);
+    if (!datasourceResult.valid) {
+      return companionError(
+        parsed,
+        `companion datasource.yaml is invalid: ${datasourceResult.errors[0]?.message}`,
+      );
+    }
+  }
+
+  return checkSeedSemantics(
+    parsed,
+    parseYamlWithPositions(typesText).doc.toJS(),
+    datasourceText !== undefined
+      ? parseYamlWithPositions(datasourceText).doc.toJS()
+      : undefined,
+  );
+}
+
+/**
+ * Live engine for `datasource_seeds.yaml`: JSON Schema first, then
+ * semantic checks against companion `types.yaml` and `datasource.yaml`.
+ */
+export class DatasourceSeedsValidator extends SpecValidator {
+  constructor() {
+    super(
+      {
+        subdir: "backend",
+        name: "datasource-seeds.spec.yaml",
+      },
+      checkSeeds,
+      withSiblingCompanions,
+    );
+  }
+}

package/node_modules/@deterministic-code/deterministic-generators-common/typescript/validator/validators/DatasourceValidator.ts

@@ -0,0 +1,39 @@
+import { SpecValidator, type ParsedYaml } from "../SpecValidator.ts";
+import type { SpecValidationResult, ValidateOptions } from "../types.ts";
+import { parseYamlWithPositions } from "../yamlPositions.ts";
+import { checkIncludeCycles } from "../includeSemantics.ts";
+import { checkIncludeFilters } from "../includeFilter.ts";
+import {
+  checkDatasourceModel,
+  withSiblingTypes,
+} from "../datasourceModelSemantics.ts";
+
+async function checkDatasource(
+  parsed: ParsedYaml,
+  options?: ValidateOptions,
+): Promise<SpecValidationResult> {
+  const typesText = options?.types;
+  const companion =
+    typesText === undefined
+      ? undefined
+      : parseYamlWithPositions(typesText).doc.toJS();
+  return checkDatasourceModel(parsed, companion);
+}
+
+/**
+ * Live engine for `datasource.yaml`: JSON Schema first, then uniqueness /
+ * identity / index checks, optional companion `types.yaml`, then include
+ * filters and `file:` cycles.
+ */
+export class DatasourceValidator extends SpecValidator {
+  constructor() {
+    super(
+      {
+        subdir: "backend",
+        name: "datasource.spec.yaml",
+      },
+      [checkDatasource, checkIncludeFilters, checkIncludeCycles],
+      withSiblingTypes,
+    );
+  }
+}

package/node_modules/@deterministic-code/deterministic-generators-common/typescript/validator/validators/FrontendBindingsValidator.ts

@@ -0,0 +1,11 @@
+import { SpecValidator } from "../SpecValidator.ts";
+
+/** Live engine for `frontend/bindings.yaml`. */
+export class FrontendBindingsValidator extends SpecValidator {
+  constructor() {
+    super({
+      subdir: "frontend",
+      name: "bindings.spec.yaml",
+    });
+  }
+}

package/node_modules/@deterministic-code/deterministic-generators-common/typescript/validator/validators/RoutesApiValidator.test.ts

@@ -0,0 +1,59 @@
+import { dirname, join } from "node:path";
+import { describe, expect, test } from "vitest";
+import { RoutesApiValidator } from "../index.ts";
+import { findAncestorPath } from "../resolveSpecPath.ts";
+
+const MINIMAL = `version: 1.0.0
+routes: []
+components: {}
+`;
+
+const validator = () => new RoutesApiValidator();
+
+describe("RoutesApiValidator", () => {
+  test("validate accepts a minimal document", async () => {
+    expect(await validator().validate(MINIMAL)).toEqual({
+      valid: true,
+      errors: [],
+    });
+  });
+
+  test("validateFile accepts the kitchen-sink sample", async () => {
+    const samples = await findAncestorPath("samples/valid");
+    if (!samples) throw new Error("samples/valid not found");
+    const path = join(dirname(samples), "valid", "routes_api.yaml");
+    expect(await validator().validateFile(path)).toEqual({
+      valid: true,
+      errors: [],
+    });
+  });
+
+  test("validate rejects a missing components map", async () => {
+    const result = await validator().validate(
+      "version: 1.0.0\nroutes: []\n",
+    );
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => /components/.test(e.message))).toBe(true);
+  });
+
+  test("validate rejects a duplicate route name", async () => {
+    const result = await validator().validate(`version: 1.0.0
+routes:
+  - health:
+      path: /api/health
+      method: GET
+      entity: null
+      isCustom: true
+  - health:
+      path: /api/health
+      method: GET
+      entity: null
+      isCustom: true
+components: {}
+`);
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => /duplicate route/.test(e.message))).toBe(
+      true,
+    );
+  });
+});

package/node_modules/@deterministic-code/deterministic-generators-common/typescript/validator/validators/RoutesApiValidator.ts

@@ -0,0 +1,18 @@
+import { SpecValidator } from "../SpecValidator.ts";
+import { checkRouteModel } from "../routeModelSemantics.ts";
+
+/**
+ * Live engine for the routes-api IR: JSON Schema first, then unique
+ * route names.
+ */
+export class RoutesApiValidator extends SpecValidator {
+  constructor() {
+    super(
+      {
+        subdir: "backend",
+        name: "routes-api.spec.yaml",
+      },
+      checkRouteModel,
+    );
+  }
+}

package/node_modules/@deterministic-code/deterministic-generators-common/typescript/validator/validators/RoutesValidator.ts

@@ -0,0 +1,24 @@
+import { SpecValidator } from "../SpecValidator.ts";
+import {
+  checkIncludeCycles,
+  withIncludeFilePath,
+} from "../includeSemantics.ts";
+import { checkRouteModel } from "../routeModelSemantics.ts";
+import { checkIncludeFilters } from "../includeFilter.ts";
+
+/**
+ * Live engine for `routes.yaml`: JSON Schema first, then unique route names
+ * and exclusive custom-route dispatch, then a walk of `file:` includes.
+ */
+export class RoutesValidator extends SpecValidator {
+  constructor() {
+    super(
+      {
+        subdir: "backend",
+        name: "routes.spec.yaml",
+      },
+      [checkRouteModel, checkIncludeFilters, checkIncludeCycles],
+      withIncludeFilePath,
+    );
+  }
+}

package/node_modules/@deterministic-code/deterministic-generators-common/typescript/validator/validators/ServicesValidator.ts

@@ -0,0 +1,24 @@
+import { SpecValidator } from "../SpecValidator.ts";
+import {
+  checkIncludeCycles,
+  withIncludeFilePath,
+} from "../includeSemantics.ts";
+import { checkServiceModel } from "../serviceModelSemantics.ts";
+import { checkIncludeFilters } from "../includeFilter.ts";
+
+/**
+ * Live engine for `services.yaml`: JSON Schema first, then unique service
+ * names, then a walk of `file:` includes.
+ */
+export class ServicesValidator extends SpecValidator {
+  constructor() {
+    super(
+      {
+        subdir: "backend",
+        name: "services.spec.yaml",
+      },
+      [checkServiceModel, checkIncludeFilters, checkIncludeCycles],
+      withIncludeFilePath,
+    );
+  }
+}

package/node_modules/@deterministic-code/deterministic-generators-common/typescript/validator/validators/TypesValidator.test.ts

@@ -0,0 +1,140 @@
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+import { TypesValidator } from "./TypesValidator.ts";
+import { TypesValidator as Engine } from "./TypesValidator.ts";
+
+const MINIMAL = `version: 1.0.0
+types:
+  - user:
+      fields:
+        - email:
+            type: string
+            size: 64
+`;
+
+const validator = () => new TypesValidator();
+
+async function withDir<T>(fn: (dir: string) => Promise<T>): Promise<T> {
+  const dir = await mkdtemp(join(tmpdir(), "types-includes-"));
+  try {
+    return await fn(dir);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+}
+
+describe("TypesValidator include cycles", () => {
+  test("validate() does not resolve file includes", async () => {
+    const result = await validator().validate(`version: 1.0.0
+includes:
+  - file: missing.yaml
+types: []
+`);
+    expect(result).toEqual({ valid: true, errors: [] });
+  });
+
+  test("validateFile accepts multiple real parents", async () => {
+    await withDir(async (dir) => {
+      await writeFile(join(dir, "identity.yaml"), MINIMAL);
+      await writeFile(
+        join(dir, "billing.yaml"),
+        `version: 1.0.0
+types:
+  - account:
+      fields:
+        - name:
+            type: string
+            size: 32
+`,
+      );
+      const path = join(dir, "types.yaml");
+      await writeFile(
+        path,
+        `version: 1.0.0
+includes:
+  - file: identity.yaml
+  - file: billing.yaml
+types:
+  - invoice:
+      fields:
+        - total:
+            type: float
+`,
+      );
+      expect((await validator().validateFile(path)).valid).toBe(true);
+    });
+  });
+
+  test("validateFile rejects a circular include", async () => {
+    await withDir(async (dir) => {
+      await writeFile(
+        join(dir, "parent.yaml"),
+        `version: 1.0.0
+includes:
+  - file: child.yaml
+types: []
+`,
+      );
+      const path = join(dir, "child.yaml");
+      await writeFile(
+        path,
+        `version: 1.0.0
+includes:
+  - file: parent.yaml
+types: []
+`,
+      );
+      const result = await validator().validateFile(path);
+      expect(result.valid).toBe(false);
+      expect(result.errors[0]?.message).toMatch(/circular include:/);
+    });
+  });
+
+  test("validateFile rejects a missing include file", async () => {
+    await withDir(async (dir) => {
+      const path = join(dir, "types.yaml");
+      await writeFile(
+        path,
+        `version: 1.0.0
+includes:
+  - file: nope.yaml
+types: []
+`,
+      );
+      const result = await validator().validateFile(path);
+      expect(result.valid).toBe(false);
+      expect(result.errors[0]?.message).toContain("include file not found");
+    });
+  });
+
+  test("schema errors win over include checks", async () => {
+    await withDir(async (dir) => {
+      const path = join(dir, "types.yaml");
+      await writeFile(path, "version: 1.0.0\ntypes: not-a-list\n");
+      const result = await validator().validateFile(path);
+      expect(result.valid).toBe(false);
+      expect(result.errors.some((e) => /circular|not found/.test(e.message))).toBe(
+        false,
+      );
+    });
+  });
+
+  test("live engine validateFile also walks includes", async () => {
+    await withDir(async (dir) => {
+      const path = join(dir, "self.yaml");
+      await writeFile(
+        path,
+        `version: 1.0.0
+includes:
+  - file: self.yaml
+types: []
+`,
+      );
+      const result = await new Engine().validateFile(path);
+      expect(result.valid).toBe(false);
+      expect(result.errors[0]?.message).toMatch(/circular include:/);
+    });
+  });
+});

package/node_modules/@deterministic-code/deterministic-generators-common/typescript/validator/validators/TypesValidator.ts

@@ -0,0 +1,31 @@
+import { SpecValidator } from "../SpecValidator.ts";
+import { checkFieldDefaultSemantics } from "../fieldDefaultSemantics.ts";
+import { checkTypeModel } from "../typeModelSemantics.ts";
+import {
+  checkIncludeCycles,
+  withIncludeFilePath,
+} from "../includeSemantics.ts";
+import { checkIncludeFilters } from "../includeFilter.ts";
+
+/**
+ * Live engine for `types.yaml`: JSON Schema first, then default_value
+ * tokens/ranges, then inherit/union/reference checks, then include
+ * filters and `file:` cycles.
+ */
+export class TypesValidator extends SpecValidator {
+  constructor() {
+    super(
+      {
+        subdir: "backend",
+        name: "types.spec.yaml",
+      },
+      [
+        checkFieldDefaultSemantics,
+        checkTypeModel,
+        checkIncludeFilters,
+        checkIncludeCycles,
+      ],
+      withIncludeFilePath,
+    );
+  }
+}

package/node_modules/@deterministic-code/deterministic-generators-common/typescript/validator/validators/engines.ts

@@ -0,0 +1,7 @@
+export { TypesValidator } from "./TypesValidator.ts";
+export { DatasourceValidator } from "./DatasourceValidator.ts";
+export { DatasourceSeedsValidator } from "./DatasourceSeedsValidator.ts";
+export { RoutesValidator } from "./RoutesValidator.ts";
+export { RoutesApiValidator } from "./RoutesApiValidator.ts";
+export { ServicesValidator } from "./ServicesValidator.ts";
+export { FrontendBindingsValidator } from "./FrontendBindingsValidator.ts";

package/node_modules/@deterministic-code/deterministic-generators-common/typescript/validator/validators/validator.test.ts

@@ -0,0 +1,229 @@
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, test } from "vitest";
+import { TypesValidator } from "./TypesValidator.ts";
+import { DatasourceSeedsValidator } from "./DatasourceSeedsValidator.ts";
+import { DatasourceValidator } from "./DatasourceValidator.ts";
+import { FrontendBindingsValidator } from "./FrontendBindingsValidator.ts";
+import { RoutesApiValidator } from "./RoutesApiValidator.ts";
+import { RoutesValidator } from "./RoutesValidator.ts";
+import { ServicesValidator } from "./ServicesValidator.ts";
+import { VALIDATOR_ENGINES } from "../specVersion.ts";
+
+const yaml = (body: string) => `version: 1.0.0\n${body}`;
+
+const VALID_BODY = `types:
+  - user:
+      fields:
+        - email:
+            type: string
+`;
+
+const ENGINES = {
+  TypesValidator,
+  DatasourceValidator,
+  DatasourceSeedsValidator,
+  RoutesValidator,
+  RoutesApiValidator,
+  ServicesValidator,
+  FrontendBindingsValidator,
+} as const;
+
+const MINIMAL: Record<string, string> = {
+  DatasourceSeedsValidator: "seeds: []\n",
+  DatasourceValidator: "types: []\n",
+  ServicesValidator: "services: []\n",
+  FrontendBindingsValidator: "datasources: []\n",
+  RoutesValidator: "routes: []\n",
+  RoutesApiValidator: "routes: []\ncomponents: {}\n",
+};
+
+describe("live engines", () => {
+  const datasource = new TypesValidator();
+
+  test("accepts a valid types document", async () => {
+    expect(await datasource.validate(yaml(VALID_BODY))).toEqual({
+      valid: true,
+      errors: [],
+    });
+  });
+
+  test("reports a positioned error for a missing top-level required key", async () => {
+    const result = await datasource.validate("not_types: 1\n");
+    expect(result.valid).toBe(false);
+    expect(result.errors[0]).toMatchObject({
+      line: expect.any(Number),
+      col: expect.any(Number),
+      message: expect.any(String),
+    });
+  });
+
+  test("reports only the unexpected type property", async () => {
+    const result = await datasource.validate(
+      yaml(`types:
+  - base:
+      tags: [view_type]
+      tags2: [x]
+      fields:
+        - name:
+            type: string
+`),
+    );
+    expect(result.valid).toBe(false);
+    expect(result.errors.map((e) => e.message)).toEqual([
+      "/types/0/base must NOT have additional properties (property: tags2)",
+    ]);
+  });
+
+  test("accepts a type that has tags and no inherits, union, or fields", async () => {
+    expect(
+      await datasource.validate(yaml("types:\n  - user:\n      tags: [view_type]\n")),
+    ).toEqual({ valid: true, errors: [] });
+  });
+
+  test("rejects dictionary without fields", async () => {
+    const result = await datasource.validate(
+      yaml("types:\n  - settings:\n      inherits: dictionary\n"),
+    );
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => /fields/.test(e.message))).toBe(true);
+    expect(result.errors.some((e) => /oneOf|exactly one/.test(e.message))).toBe(
+      false,
+    );
+  });
+
+  test("rejects a leftover one_of on an inherit type", async () => {
+    const result = await datasource.validate(
+      yaml("types:\n  - user:\n      inherits: set\n      one_of: [a, b]\n"),
+    );
+    expect(result.valid).toBe(false);
+    expect(result.errors.length).toBeGreaterThan(0);
+  });
+
+  test("accepts unsigned integer-family field types", async () => {
+    const result = await datasource.validate(
+      yaml(`types:
+  - sample:
+      fields:
+        - count:
+            type: unsignedinteger
+            default_value: 0
+        - big_count:
+            type: unsignedbiginteger
+            default_value: "18446744073709551615"
+        - small_count:
+            type: unsignedsmallinteger
+            min_size: 0
+`),
+    );
+    expect(result).toEqual({ valid: true, errors: [] });
+  });
+
+  test("rejects a negative default_value on unsignedinteger", async () => {
+    const result = await datasource.validate(
+      yaml(`types:
+  - sample:
+      fields:
+        - count:
+            type: unsignedinteger
+            default_value: -1
+`),
+    );
+    expect(result.valid).toBe(false);
+    expect(result.errors.length).toBeGreaterThan(0);
+  });
+
+  test("reports a positioned error for a field-shape mismatch", async () => {
+    const result = await datasource.validate(
+      yaml(
+        "types:\n  - user:\n      fields:\n        - email:\n            bogus_field_key: true\n",
+      ),
+    );
+    expect(result.valid).toBe(false);
+    expect(result.errors[0]).toMatchObject({
+      instancePath: expect.any(String),
+    });
+  });
+
+  test("reports a type mismatch (scalar where an array is required)", async () => {
+    const result = await datasource.validate(yaml("types: not-a-list\n"));
+    expect(result.valid).toBe(false);
+    expect(result.errors.length).toBeGreaterThan(0);
+  });
+
+  test("an empty document is invalid", async () => {
+    const result = await datasource.validate("");
+    expect(result.valid).toBe(false);
+    expect(result.errors.length).toBeGreaterThan(0);
+  });
+
+  test("reports a positioned parse error for unterminated input", async () => {
+    const result = await datasource.validate("foo: [unterminated\n");
+    expect(result.valid).toBe(false);
+    expect(result.errors[0]).toMatchObject({
+      instancePath: "",
+      message: expect.any(String),
+      line: expect.any(Number),
+      col: expect.any(Number),
+    });
+  });
+
+  test("validateFile reads a valid file from disk", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "spec-validate-"));
+    try {
+      const path = join(dir, "valid.yaml");
+      await writeFile(path, yaml(VALID_BODY));
+      expect((await datasource.validateFile(path)).valid).toBe(true);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("validateFile reports positioned errors for an invalid file", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "spec-validate-"));
+    try {
+      const path = join(dir, "invalid.yaml");
+      await writeFile(path, "not_types: 1\n");
+      const result = await datasource.validateFile(path);
+      expect(result.valid).toBe(false);
+      expect(result.errors.length).toBeGreaterThan(0);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("other spec validators accept a minimal document", async () => {
+    for (const [className, body] of Object.entries(MINIMAL)) {
+      const Ctor = ENGINES[className as keyof typeof ENGINES];
+      expect((await new Ctor().validate(yaml(body))).valid).toBe(true);
+    }
+  });
+
+  test("TypesValidator rejects a leftover one_of property", async () => {
+    const result = await new TypesValidator().validate(
+      yaml("types:\n  - foo:\n      one_of: [a]\n      fields: []\n"),
+    );
+    expect(result.valid).toBe(false);
+    expect(result.errors.length).toBeGreaterThan(0);
+  });
+
+  test("RoutesValidator rejects a nested route-shape mismatch", async () => {
+    const result = await new RoutesValidator().validate(
+      yaml(
+        "routes:\n  - custom_route:\n      methods: [GET]\n      path: /x\n      bogus: true\n",
+      ),
+    );
+    expect(result.valid).toBe(false);
+    expect(result.errors.length).toBeGreaterThan(0);
+  });
+
+  test("every spec validator rejects an empty document", async () => {
+    for (const [className] of VALIDATOR_ENGINES) {
+      const Ctor = ENGINES[className];
+      const result = await new Ctor().validate("");
+      expect(result.valid).toBe(false);
+      expect(result.errors.length).toBeGreaterThan(0);
+    }
+  });
+});

package/node_modules/@deterministic-code/deterministic-specifications-typescript/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
+```