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

package/node_modules/@deterministic-code/deterministic-specifications-typescript/typescript/validator/SpecValidator.ts

@@ -0,0 +1,260 @@
+import { readFile } from "node:fs/promises";
+import Ajv2020 from "ajv/dist/2020.js";
+import { parseDocument } from "yaml";
+import type {
+  AjvError,
+  AjvLike,
+  SpecValidationError,
+  SpecValidationResult,
+  ValidateFn,
+  ValidateOptions,
+} from "./types.ts";
+import { parseYamlWithPositions, positionFor } from "./yamlPositions.ts";
+import { resolveSpecPath } from "./resolveSpecPath.ts";
+import { isSpecRef, type SpecRef } from "./specVersion.ts";
+
+type SpecPathFn = () => Promise<string>;
+type SpecPathSource = string | SpecPathFn | SpecRef;
+type AjvCtorType = new (opts: unknown) => AjvLike;
+type YamlDoc = ReturnType<typeof parseYamlWithPositions>["doc"];
+type YamlLines = ReturnType<typeof parseYamlWithPositions>["lineCounter"];
+
+export type ParsedYaml = {
+  doc: YamlDoc;
+  lineCounter: YamlLines;
+  data: unknown;
+};
+
+export function yamlErrorOffset(
+  pos: readonly number[] | undefined | null,
+): number {
+  return pos ? pos[0] : 0;
+}
+
+function yamlParseErrors(
+  doc: YamlDoc,
+  lineCounter: YamlLines,
+): SpecValidationError[] {
+  return doc.errors.map((e): SpecValidationError => {
+    const { line, col } = lineCounter.linePos(yamlErrorOffset(e.pos));
+    return { line, col, instancePath: "", message: e.message };
+  });
+}
+
+function specError(
+  doc: YamlDoc,
+  lineCounter: YamlLines,
+  instancePath: string,
+  message: string,
+): SpecValidationError {
+  const { line, col } = positionFor(doc, lineCounter, instancePath);
+  return { line, col, instancePath, message };
+}
+
+export function versionFail(
+  doc: YamlDoc,
+  lineCounter: YamlLines,
+  message: string,
+): SpecValidationResult {
+  return {
+    valid: false,
+    errors: [specError(doc, lineCounter, "/version", message)],
+  };
+}
+
+function readYaml(text: string): ParsedYaml & {
+  errors: SpecValidationError[];
+} {
+  const { doc, lineCounter } = parseYamlWithPositions(text);
+  return {
+    doc,
+    lineCounter,
+    errors: yamlParseErrors(doc, lineCounter),
+    data: doc.toJS(),
+  };
+}
+
+/** CJS/ESM interop: `ajv/dist/2020.js` may be the class or `{ default: class }`. */
+export function resolveAjvCtor(mod: unknown): AjvCtorType {
+  const withDefault = mod as { default?: AjvCtorType };
+  return (withDefault.default ?? (mod as AjvCtorType)) as AjvCtorType;
+}
+
+function newAjv(): AjvLike {
+  return new (resolveAjvCtor(Ajv2020))({ allErrors: true, strict: false });
+}
+
+const AJV_PARAM_SUFFIX: Array<[string, (v: unknown) => string]> = [
+  ["additionalProperty", (v) => `(property: ${String(v)})`],
+  ["missingProperty", (v) => `(missing: ${String(v)})`],
+  ["allowedValues", (v) => `(allowed: ${(v as unknown[]).join(", ")})`],
+];
+
+function ajvParamSuffix(params?: Record<string, unknown>): string {
+  if (!params) return "";
+  for (const [key, fmt] of AJV_PARAM_SUFFIX) {
+    if (params[key]) return ` ${fmt(params[key])}`;
+  }
+  return "";
+}
+
+export function formatAjvError(e: AjvError): string {
+  const where = e.instancePath || "(root)";
+  if (e.keyword === "not" && e.instancePath.endsWith("/is_id")) {
+    return `${where} ids and is_id are mutually exclusive`;
+  }
+  return `${where} ${e.message}${ajvParamSuffix(e.params)}`;
+}
+
+export function errorFromUnknown(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+/** Extra checks run after JSON Schema succeeds. First failure wins. */
+export type AfterSchemaFn = (
+  parsed: ParsedYaml,
+  options?: ValidateOptions,
+) => SpecValidationResult | Promise<SpecValidationResult>;
+
+/** Injects path-derived options when {@link FileValidator.validateFile} is used. */
+export type FileOptionsFn = (
+  path: string,
+  options?: ValidateOptions,
+) => ValidateOptions | Promise<ValidateOptions | undefined> | undefined;
+
+async function firstFailure(
+  checks: readonly AfterSchemaFn[],
+  parsed: ParsedYaml,
+  options?: ValidateOptions,
+): Promise<SpecValidationResult> {
+  for (const check of checks) {
+    const result = await check(parsed, options);
+    if (!result.valid) return result;
+  }
+  return { valid: true, errors: [] };
+}
+
+/**
+ * Shared parse + file entry: YAML syntax errors are mapped here; subclasses
+ * implement {@link check} against the parsed document.
+ */
+export abstract class FileValidator {
+  readonly #fileOptions?: FileOptionsFn;
+
+  constructor(fileOptions?: FileOptionsFn) {
+    this.#fileOptions = fileOptions;
+  }
+
+  async validate(
+    text: string,
+    options?: ValidateOptions,
+  ): Promise<SpecValidationResult> {
+    const { doc, lineCounter, errors, data } = readYaml(text);
+    if (errors.length > 0) return { valid: false, errors };
+    return this.check({ doc, lineCounter, data }, text, options);
+  }
+
+  protected abstract check(
+    parsed: ParsedYaml,
+    text: string,
+    options?: ValidateOptions,
+  ): Promise<SpecValidationResult>;
+
+  protected async optionsForFile(
+    path: string,
+    options?: ValidateOptions,
+  ): Promise<ValidateOptions | undefined> {
+    return this.#fileOptions ? this.#fileOptions(path, options) : options;
+  }
+
+  async validateFile(
+    path: string,
+    options?: ValidateOptions,
+  ): Promise<SpecValidationResult> {
+    return this.validate(
+      await readFile(path, "utf8"),
+      await this.optionsForFile(path, options),
+    );
+  }
+}
+
+/**
+ * Validates a `deterministic/*.yaml` document against one strict JSON Schema
+ * (draft 2020-12, authored in YAML). The base class carries AJV compilation
+ * and source-position mapping so every error reports `{ line, col }`.
+ *
+ * Pass a `{ subdir, name }` ref to resolve the live spec file. Pass an
+ * absolute path (or path thunk) to validate against a spec that lives
+ * outside this package.
+ *
+ * Optional `afterSchema` checks run only after JSON Schema succeeds.
+ * `fileOptions` is applied by {@link FileValidator.validateFile}.
+ */
+export class SpecValidator extends FileValidator {
+  readonly #specRef: SpecRef | null;
+  readonly #resolveFixedPath: SpecPathFn | null;
+  readonly #compiled = new Map<string, ValidateFn>();
+  readonly #afterSchema: readonly AfterSchemaFn[];
+
+  constructor(
+    specPath: SpecPathSource,
+    afterSchema: AfterSchemaFn | readonly AfterSchemaFn[] = [],
+    fileOptions?: FileOptionsFn,
+  ) {
+    super(fileOptions);
+    this.#afterSchema = Array.isArray(afterSchema) ? afterSchema : [afterSchema];
+    if (isSpecRef(specPath)) {
+      this.#specRef = specPath;
+      this.#resolveFixedPath = null;
+    } else {
+      this.#specRef = null;
+      this.#resolveFixedPath =
+        typeof specPath === "string" ? async () => specPath : specPath;
+    }
+  }
+
+  protected async check(
+    parsed: ParsedYaml,
+    _text: string,
+    options?: ValidateOptions,
+  ): Promise<SpecValidationResult> {
+    const { doc, lineCounter, data } = parsed;
+    const resolved = await this.#resolvePath(data, doc, lineCounter);
+    if (!("path" in resolved)) return resolved;
+
+    const validate = await this.#compiledSpec(resolved.path);
+    if (validate(data)) return firstFailure(this.#afterSchema, parsed, options);
+
+    return {
+      valid: false,
+      errors: validate.errors!.map((e) =>
+        specError(doc, lineCounter, e.instancePath, formatAjvError(e)),
+      ),
+    };
+  }
+
+  async #resolvePath(
+    _data: unknown,
+    doc: YamlDoc,
+    lineCounter: YamlLines,
+  ): Promise<{ path: string } | SpecValidationResult> {
+    if (this.#resolveFixedPath) {
+      return { path: await this.#resolveFixedPath() };
+    }
+    const ref = this.#specRef!;
+    try {
+      return { path: await resolveSpecPath(ref.subdir, ref.name) };
+    } catch (err) {
+      return versionFail(doc, lineCounter, errorFromUnknown(err));
+    }
+  }
+
+  async #compiledSpec(specPath: string): Promise<ValidateFn> {
+    const hit = this.#compiled.get(specPath);
+    if (hit) return hit;
+    const specText = await readFile(specPath, "utf8");
+    const compiled = newAjv().compile(parseDocument(specText).toJS());
+    this.#compiled.set(specPath, compiled);
+    return compiled;
+  }
+}

package/node_modules/@deterministic-code/deterministic-specifications-typescript/typescript/validator/index.ts

@@ -0,0 +1,12 @@
+export { SpecValidator } from "./SpecValidator.ts";
+export { TypesValidator } from "./validators/TypesValidator.ts";
+export { DatasourceValidator } from "./validators/DatasourceValidator.ts";
+export { DatasourceSeedsValidator } from "./validators/DatasourceSeedsValidator.ts";
+export { RoutesValidator } from "./validators/RoutesValidator.ts";
+export { RoutesApiValidator } from "./validators/RoutesApiValidator.ts";
+export { ServicesValidator } from "./validators/ServicesValidator.ts";
+export { FrontendBindingsValidator } from "./validators/FrontendBindingsValidator.ts";
+export type {
+  SpecValidationError,
+  SpecValidationResult,
+} from "./types.ts";

package/node_modules/@deterministic-code/deterministic-specifications-typescript/typescript/validator/types.ts

@@ -0,0 +1,47 @@
+export interface Position {
+  line: number;
+  col: number;
+}
+
+export interface SpecValidationError {
+  line: number;
+  col: number;
+  instancePath: string;
+  message: string;
+}
+
+export interface SpecValidationResult {
+  valid: boolean;
+  errors: SpecValidationError[];
+}
+
+export interface ValidateOptions {
+  /** Companion `types.yaml` text. Required for non-empty seeds. */
+  types?: string;
+  /** Path to companion `types.yaml`. Ignored when `types` is set. */
+  typesPath?: string;
+  /** Companion `datasource.yaml` text. Required for non-empty seeds. */
+  datasource?: string;
+  /** Path to companion `datasource.yaml`. Ignored when `datasource` is set. */
+  datasourcePath?: string;
+  /** Absolute path of the document being validated. Set by `validateFile`. */
+  includeFilePath?: string;
+  /** Directory used to resolve `file:` includes. Set by `validateFile`. */
+  includeBasePath?: string;
+}
+
+export interface AjvError {
+  keyword: string;
+  instancePath: string;
+  message?: string;
+  params?: Record<string, unknown>;
+}
+
+export interface ValidateFn {
+  (data: unknown): boolean;
+  errors?: AjvError[] | null;
+}
+
+export interface AjvLike {
+  compile(schema: unknown): ValidateFn;
+}

package/node_modules/@deterministic-code/deterministic-specifications-typescript/typescript/validator/validators/DatasourceSeedsValidator.test.ts

@@ -0,0 +1,385 @@
+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 { DatasourceSeedsValidator } from "../index.ts";
+import { DatasourceSeedsValidator as Engine } from "./DatasourceSeedsValidator.ts";
+
+const TYPES = `version: 1.0.0
+types:
+  - user:
+      fields:
+        - email:
+            type: string
+            size: 256
+        - nickname:
+            type: string
+            size: 64
+            is_nullable: true
+        - active:
+            type: boolean
+            default_value: true
+        - score:
+            type: integer
+            is_nullable: true
+`;
+
+const validator = () => new DatasourceSeedsValidator();
+
+async function check(seeds: string, types = TYPES) {
+  return validator().validate(seeds, { types });
+}
+
+describe("DatasourceSeedsValidator semantics", () => {
+  test("accepts a row that omits a nullable field", async () => {
+    const result = await check(`version: 1.0.0
+seeds:
+  - user:
+      - id1:
+          email: a@b.c
+`);
+    expect(result).toEqual({ valid: true, errors: [] });
+  });
+
+  test("accepts a row that omits a field with a default_value", async () => {
+    const result = await check(`version: 1.0.0
+seeds:
+  - user:
+      - id1:
+          email: a@b.c
+`);
+    expect(result.errors.filter((e) => /active/.test(e.message))).toEqual([]);
+    expect(result.valid).toBe(true);
+  });
+
+  test("accepts null on a nullable field", async () => {
+    const result = await check(`version: 1.0.0
+seeds:
+  - user:
+      - id1:
+          email: a@b.c
+          nickname: null
+          score: null
+`);
+    expect(result).toEqual({ valid: true, errors: [] });
+  });
+
+  test("rejects a missing non-nullable field with no default", async () => {
+    const result = await check(`version: 1.0.0
+seeds:
+  - user:
+      - id1:
+          nickname: al
+`);
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => /missing required field 'email'/.test(e.message))).toBe(
+      true,
+    );
+  });
+
+  test("rejects null on a non-nullable field", async () => {
+    const result = await check(`version: 1.0.0
+seeds:
+  - user:
+      - id1:
+          email: null
+`);
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => /not nullable/.test(e.message))).toBe(true);
+  });
+
+  test("rejects an unknown table", async () => {
+    const result = await check(`version: 1.0.0
+seeds:
+  - account:
+      - id1:
+          email: a@b.c
+`);
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => /unknown type 'account'/.test(e.message))).toBe(
+      true,
+    );
+  });
+
+  test("rejects an unknown field", async () => {
+    const result = await check(`version: 1.0.0
+seeds:
+  - user:
+      - id1:
+          email: a@b.c
+          extra: true
+`);
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => /unknown field 'extra'/.test(e.message))).toBe(
+      true,
+    );
+  });
+
+  test("rejects a value that does not match the field type", async () => {
+    const result = await check(`version: 1.0.0
+seeds:
+  - user:
+      - id1:
+          email: a@b.c
+          score: "yes"
+`);
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => /must be integer/.test(e.message))).toBe(true);
+  });
+
+  test("rejects non-empty seeds when types.yaml is missing", async () => {
+    const result = await validator().validate(`version: 1.0.0
+seeds:
+  - user:
+      - id1:
+          email: a@b.c
+`);
+    expect(result.valid).toBe(false);
+    expect(result.errors[0]?.message).toMatch(/types.yaml is required/);
+  });
+
+  test("accepts empty seeds without types.yaml", async () => {
+    expect(
+      await validator().validate("version: 1.0.0\nseeds: []\n"),
+    ).toEqual({ valid: true, errors: [] });
+  });
+
+  test("validateFile loads a sibling types.yaml", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "seeds-sibling-"));
+    try {
+      await writeFile(join(dir, "types.yaml"), TYPES);
+      const path = join(dir, "datasource_seeds.yaml");
+      await writeFile(
+        path,
+        `version: 1.0.0
+seeds:
+  - user:
+      - id1:
+          email: a@b.c
+`,
+      );
+      expect((await validator().validateFile(path)).valid).toBe(true);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("validateFile reads typesPath when no sibling is present", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "seeds-path-"));
+    try {
+      const typesPath = join(dir, "types.yaml");
+      await writeFile(typesPath, TYPES);
+      const path = join(dir, "datasource_seeds.yaml");
+      await writeFile(
+        path,
+        `version: 1.0.0
+seeds:
+  - user:
+      - id1:
+          email: a@b.c
+`,
+      );
+      expect(
+        (await validator().validateFile(path, { typesPath }))
+          .valid,
+      ).toBe(true);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("validateFile without companion types fails for non-empty seeds", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "seeds-missing-"));
+    try {
+      const path = join(dir, "datasource_seeds.yaml");
+      await writeFile(
+        path,
+        `version: 1.0.0
+seeds:
+  - user:
+      - id1:
+          email: a@b.c
+`,
+      );
+      const result = await validator().validateFile(path);
+      expect(result.valid).toBe(false);
+      expect(result.errors[0]?.message).toMatch(/types.yaml is required/);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("rejects an invalid companion datasource.yaml document", async () => {
+    const result = await validator().validate(
+      `version: 1.0.0
+seeds:
+  - user:
+      - id1:
+          email: a@b.c
+`,
+      {
+        types: TYPES,
+        datasource: "version: 1.0.0\nnot_types: 1\n",
+      },
+    );
+    expect(result.valid).toBe(false);
+    expect(result.errors[0]?.message).toMatch(
+      /companion datasource.yaml is invalid/,
+    );
+  });
+
+  test("rejects an invalid companion types.yaml document", async () => {
+    const result = await check(
+      `version: 1.0.0
+seeds:
+  - user:
+      - id1:
+          email: a@b.c
+`,
+      "version: 1.0.0\nnot_types: 1\n",
+    );
+    expect(result.valid).toBe(false);
+    expect(result.errors[0]?.message).toMatch(/companion types.yaml is invalid/);
+  });
+
+  test("rejects a duplicate table and duplicate seed id", async () => {
+    const result = await check(`version: 1.0.0
+seeds:
+  - user:
+      - id1:
+          email: a@b.c
+      - id1:
+          email: b@c.d
+  - user:
+      - id2:
+          email: c@d.e
+`);
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => /duplicate seed id/.test(e.message))).toBe(
+      true,
+    );
+    expect(result.errors.some((e) => /duplicate seed table/.test(e.message))).toBe(
+      true,
+    );
+  });
+
+  test("rejects auto-injected columns in a seed row", async () => {
+    const result = await check(`version: 1.0.0
+seeds:
+  - user:
+      - id1:
+          email: a@b.c
+          id: 1
+`);
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => /auto-injected/.test(e.message))).toBe(true);
+  });
+
+  test("type-checks integers, unsigned values, decimals, and reference fields", async () => {
+    const types = `version: 1.0.0
+types:
+  - user:
+      fields:
+        - email:
+            type: string
+            size: 256
+        - count:
+            type: integer
+        - visits:
+            type: unsignedinteger
+            default_value: 0
+        - big:
+            type: biginteger
+            default_value: "0"
+        - price:
+            type: decimal
+            default_value: 0
+        - parent_id:
+            references: user.id
+            is_nullable: true
+        - email_ref:
+            references: user.email
+            is_nullable: true
+`;
+    const ok = await check(
+      `version: 1.0.0
+seeds:
+  - user:
+      - id1:
+          email: a@b.c
+          count: 2
+          visits: 1
+          big: "9"
+          price: 1.5
+          parent_id: 1
+          email_ref: a@b.c
+`,
+      types,
+    );
+    expect(ok).toEqual({ valid: true, errors: [] });
+
+    const bad = await check(
+      `version: 1.0.0
+seeds:
+  - user:
+      - id1:
+          email: a@b.c
+          count: 1.5
+          visits: -1
+          big: true
+          price: false
+          parent_id: "x"
+`,
+      types,
+    );
+    expect(bad.valid).toBe(false);
+    expect(bad.errors.some((e) => /count/.test(e.message))).toBe(true);
+    expect(bad.errors.some((e) => /visits/.test(e.message))).toBe(true);
+  });
+
+  test("engine validateFile loads a sibling types.yaml", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "seeds-engine-"));
+    try {
+      await writeFile(join(dir, "types.yaml"), TYPES);
+      const path = join(dir, "datasource_seeds.yaml");
+      await writeFile(
+        path,
+        `version: 1.0.0
+seeds:
+  - user:
+      - id1:
+          email: a@b.c
+`,
+      );
+      expect((await new Engine().validateFile(path)).valid).toBe(true);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("rejects a float/number typed as a string", async () => {
+    const types = `version: 1.0.0
+types:
+  - sample:
+      fields:
+        - ratio:
+            type: float
+        - amount:
+            type: number
+`;
+    const result = await check(
+      `version: 1.0.0
+seeds:
+  - sample:
+      - id1:
+          ratio: "1.5"
+          amount: "2"
+`,
+      types,
+    );
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => /must be number/.test(e.message))).toBe(
+      true,
+    );
+  });
+});