@prisma-next/sql-contract 0.3.0-dev.14 → 0.3.0-dev.147

package/src/validate.ts

@@ -0,0 +1,227 @@
+import type {
+  ColumnDefaultLiteralInputValue,
+  Contract,
+  ContractField,
+  ContractModel,
+  JsonValue,
+} from '@prisma-next/contract/types';
+import {
+  ContractValidationError,
+  validateContract as frameworkValidateContract,
+} from '@prisma-next/contract/validate-contract';
+import type { CodecLookup } from '@prisma-next/framework-components/codec';
+import type { SqlModelStorage, SqlStorage, StorageColumn, StorageTable } from './types';
+import { validateSqlContract, validateStorageSemantics } from './validators';
+
+type SqlValidationContract = Contract<SqlStorage, Record<string, ContractModel<SqlModelStorage>>>;
+
+function validateModelStorageReferences(contract: SqlValidationContract): void {
+  for (const [modelName, model] of Object.entries(contract.models)) {
+    const storageTable = model.storage.table;
+
+    const table = contract.storage.tables[storageTable] as
+      | (typeof contract.storage.tables)[string]
+      | undefined;
+    if (!table) {
+      throw new ContractValidationError(
+        `Model "${modelName}" references non-existent table "${storageTable}"`,
+        'storage',
+      );
+    }
+
+    const columnNames = new Set(Object.keys(table.columns));
+    for (const [fieldName, field] of Object.entries(model.storage.fields)) {
+      if (!columnNames.has(field.column)) {
+        throw new ContractValidationError(
+          `Model "${modelName}" field "${fieldName}" references non-existent column "${field.column}" in table "${storageTable}"`,
+          'storage',
+        );
+      }
+    }
+
+    const JSON_NATIVE_TYPES = new Set(['json', 'jsonb']);
+    for (const [fieldName, domainField] of Object.entries(model.fields)) {
+      const f = domainField as ContractField;
+      if (f.type?.kind !== 'valueObject') continue;
+      const storageField = model.storage.fields[fieldName];
+      if (!storageField) continue;
+      const column = table.columns[storageField.column];
+      if (!column) continue;
+      if (!JSON_NATIVE_TYPES.has(column.nativeType)) {
+        throw new ContractValidationError(
+          `Model "${modelName}" field "${fieldName}" is a value object but storage column "${storageField.column}" has nativeType "${column.nativeType}" (expected json or jsonb)`,
+          'storage',
+        );
+      }
+    }
+  }
+}
+
+function validateContractLogic(contract: Contract<SqlStorage>): void {
+  const tableNames = new Set(Object.keys(contract.storage.tables));
+
+  for (const [tableName, table] of Object.entries(contract.storage.tables)) {
+    const columnNames = new Set(Object.keys(table.columns));
+
+    if (table.primaryKey) {
+      for (const colName of table.primaryKey.columns) {
+        if (!columnNames.has(colName)) {
+          throw new ContractValidationError(
+            `Table "${tableName}" primaryKey references non-existent column "${colName}"`,
+            'storage',
+          );
+        }
+      }
+    }
+
+    for (const unique of table.uniques) {
+      for (const colName of unique.columns) {
+        if (!columnNames.has(colName)) {
+          throw new ContractValidationError(
+            `Table "${tableName}" unique constraint references non-existent column "${colName}"`,
+            'storage',
+          );
+        }
+      }
+    }
+
+    for (const index of table.indexes) {
+      for (const colName of index.columns) {
+        if (!columnNames.has(colName)) {
+          throw new ContractValidationError(
+            `Table "${tableName}" index references non-existent column "${colName}"`,
+            'storage',
+          );
+        }
+      }
+    }
+
+    for (const [colName, column] of Object.entries(table.columns)) {
+      if (!column.nullable && column.default?.kind === 'literal' && column.default.value === null) {
+        throw new ContractValidationError(
+          `Table "${tableName}" column "${colName}" is NOT NULL but has a literal null default`,
+          'storage',
+        );
+      }
+    }
+
+    for (const fk of table.foreignKeys) {
+      for (const colName of fk.columns) {
+        if (!columnNames.has(colName)) {
+          throw new ContractValidationError(
+            `Table "${tableName}" foreignKey references non-existent column "${colName}"`,
+            'storage',
+          );
+        }
+      }
+
+      if (!tableNames.has(fk.references.table)) {
+        throw new ContractValidationError(
+          `Table "${tableName}" foreignKey references non-existent table "${fk.references.table}"`,
+          'storage',
+        );
+      }
+
+      const referencedTable = contract.storage.tables[fk.references.table];
+      if (!referencedTable) continue;
+      const referencedColumnNames = new Set(Object.keys(referencedTable.columns));
+      for (const colName of fk.references.columns) {
+        if (!referencedColumnNames.has(colName)) {
+          throw new ContractValidationError(
+            `Table "${tableName}" foreignKey references non-existent column "${colName}" in table "${fk.references.table}"`,
+            'storage',
+          );
+        }
+      }
+
+      if (fk.columns.length !== fk.references.columns.length) {
+        throw new ContractValidationError(
+          `Table "${tableName}" foreignKey column count (${fk.columns.length}) does not match referenced column count (${fk.references.columns.length})`,
+          'storage',
+        );
+      }
+    }
+  }
+}
+
+function validateSqlStorage(contract: Contract): void {
+  const sqlContract = validateSqlContract<SqlValidationContract>(contract);
+  validateContractLogic(sqlContract);
+  validateModelStorageReferences(sqlContract);
+  const semanticErrors = validateStorageSemantics(sqlContract.storage);
+  if (semanticErrors.length > 0) {
+    throw new ContractValidationError(
+      `Contract semantic validation failed: ${semanticErrors.join('; ')}`,
+      'storage',
+    );
+  }
+}
+
+function decodeContractDefaults<T extends Contract<SqlStorage>>(
+  contract: T,
+  codecLookup: CodecLookup,
+): T {
+  const tables = contract.storage.tables;
+  let tablesChanged = false;
+  const decodedTables: Record<string, StorageTable> = {};
+
+  for (const [tableName, table] of Object.entries(tables)) {
+    let columnsChanged = false;
+    const decodedColumns: Record<string, StorageColumn> = {};
+
+    for (const [columnName, column] of Object.entries(table.columns)) {
+      if (column.default?.kind === 'literal') {
+        const codec = codecLookup.get(column.codecId);
+        if (codec) {
+          const decodedValue = codec.decodeJson(
+            column.default.value as JsonValue,
+          ) as ColumnDefaultLiteralInputValue;
+          if (decodedValue !== column.default.value) {
+            columnsChanged = true;
+            decodedColumns[columnName] = {
+              ...column,
+              default: { kind: 'literal', value: decodedValue },
+            };
+            continue;
+          }
+        }
+      }
+      decodedColumns[columnName] = column;
+    }
+
+    if (columnsChanged) {
+      tablesChanged = true;
+      decodedTables[tableName] = { ...table, columns: decodedColumns };
+    } else {
+      decodedTables[tableName] = table;
+    }
+  }
+
+  if (!tablesChanged) {
+    return contract;
+  }
+
+  return {
+    ...contract,
+    storage: {
+      ...contract.storage,
+      tables: decodedTables,
+    },
+  } as T;
+}
+
+export function validateContract<TContract extends Contract<SqlStorage>>(
+  value: unknown,
+  codecLookup: CodecLookup,
+): TContract {
+  const validated = frameworkValidateContract<TContract>(value, validateSqlStorage);
+  try {
+    return decodeContractDefaults(validated, codecLookup);
+  } catch (error) {
+    if (error instanceof ContractValidationError) throw error;
+    throw new ContractValidationError(
+      error instanceof Error ? error.message : String(error),
+      'storage',
+    );
+  }
+}

package/src/validators.ts

@@ -1,23 +1,86 @@
+import type { Contract } from '@prisma-next/contract/types';
+import { ContractValidationError } from '@prisma-next/contract/validate-contract';
 import { type } from 'arktype';
 import type {
   ForeignKey,
   ForeignKeyReferences,
-  Index,
-  ModelDefinition,
-  ModelField,
-  ModelStorage,
   PrimaryKey,
-  SqlContract,
+  ReferentialAction,
   SqlStorage,
-  StorageColumn,
-  StorageTable,
+  StorageTypeInstance,
   UniqueConstraint,
 } from './types';
 
-const StorageColumnSchema = type.declare<StorageColumn>().type({
+type ColumnDefaultLiteral = {
+  readonly kind: 'literal';
+  readonly value: string | number | boolean | Record<string, unknown> | unknown[] | null;
+};
+type ColumnDefaultFunction = { readonly kind: 'function'; readonly expression: string };
+const literalKindSchema = type("'literal'");
+const functionKindSchema = type("'function'");
+const generatorKindSchema = type("'generator'");
+const generatorIdSchema = type('string').narrow((value, ctx) => {
+  return /^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(value) ? true : ctx.mustBe('a flat generator id');
+});
+
+export const ColumnDefaultLiteralSchema = type.declare<ColumnDefaultLiteral>().type({
+  kind: literalKindSchema,
+  value: 'string | number | boolean | null | unknown[] | Record<string, unknown>',
+});
+
+export const ColumnDefaultFunctionSchema = type.declare<ColumnDefaultFunction>().type({
+  kind: functionKindSchema,
+  expression: 'string',
+});
+
+export const ColumnDefaultSchema = ColumnDefaultLiteralSchema.or(ColumnDefaultFunctionSchema);
+
+const ExecutionMutationDefaultValueSchema = type({
+  '+': 'reject',
+  kind: generatorKindSchema,
+  id: generatorIdSchema,
+  'params?': 'Record<string, unknown>',
+});
+
+const ExecutionMutationDefaultSchema = type({
+  '+': 'reject',
+  ref: {
+    '+': 'reject',
+    table: 'string',
+    column: 'string',
+  },
+  'onCreate?': ExecutionMutationDefaultValueSchema,
+  'onUpdate?': ExecutionMutationDefaultValueSchema,
+});
+
+const ExecutionSchema = type({
+  '+': 'reject',
+  executionHash: 'string',
+  mutations: {
+    '+': 'reject',
+    defaults: ExecutionMutationDefaultSchema.array().readonly(),
+  },
+});
+
+const StorageColumnSchema = type({
+  '+': 'reject',
   nativeType: 'string',
   codecId: 'string',
   nullable: 'boolean',
+  'typeParams?': 'Record<string, unknown>',
+  'typeRef?': 'string',
+  'default?': ColumnDefaultSchema,
+}).narrow((col, ctx) => {
+  if (col.typeParams !== undefined && col.typeRef !== undefined) {
+    return ctx.mustBe('a column with either typeParams or typeRef, not both');
+  }
+  return true;
+});
+
+const StorageTypeInstanceSchema = type.declare<StorageTypeInstance>().type({
+  codecId: 'string',
+  nativeType: 'string',
+  typeParams: 'Record<string, unknown>',
 });
 
 const PrimaryKeySchema = type.declare<PrimaryKey>().type({
@@ -30,23 +93,34 @@ const UniqueConstraintSchema = type.declare<UniqueConstraint>().type({
   'name?': 'string',
 });
 
-const IndexSchema = type.declare<Index>().type({
+export const IndexSchema = type({
   columns: type.string.array().readonly(),
   'name?': 'string',
+  'using?': 'string',
+  'config?': 'Record<string, unknown>',
 });
 
-const ForeignKeyReferencesSchema = type.declare<ForeignKeyReferences>().type({
+export const ForeignKeyReferencesSchema = type.declare<ForeignKeyReferences>().type({
   table: 'string',
   columns: type.string.array().readonly(),
 });
 
-const ForeignKeySchema = type.declare<ForeignKey>().type({
+export const ReferentialActionSchema = type
+  .declare<ReferentialAction>()
+  .type("'noAction' | 'restrict' | 'cascade' | 'setNull' | 'setDefault'");
+
+export const ForeignKeySchema = type.declare<ForeignKey>().type({
   columns: type.string.array().readonly(),
   references: ForeignKeyReferencesSchema,
   'name?': 'string',
+  'onDelete?': ReferentialActionSchema,
+  'onUpdate?': ReferentialActionSchema,
+  constraint: 'boolean',
+  index: 'boolean',
 });
 
-const StorageTableSchema = type.declare<StorageTable>().type({
+const StorageTableSchema = type({
+  '+': 'reject',
   columns: type({ '[string]': StorageColumnSchema }),
   'primaryKey?': PrimaryKeySchema,
   uniques: UniqueConstraintSchema.array().readonly(),
@@ -54,38 +128,97 @@ const StorageTableSchema = type.declare<StorageTable>().type({
   foreignKeys: ForeignKeySchema.array().readonly(),
 });
 
-const StorageSchema = type.declare<SqlStorage>().type({
+const StorageSchema = type({
+  '+': 'reject',
+  storageHash: 'string',
   tables: type({ '[string]': StorageTableSchema }),
+  'types?': type({ '[string]': StorageTypeInstanceSchema }),
 });
 
-const ModelFieldSchema = type.declare<ModelField>().type({
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isContractFieldType(value: unknown): boolean {
+  if (!isPlainRecord(value)) return false;
+  const kind = value['kind'];
+  if (kind === 'scalar') {
+    if (typeof value['codecId'] !== 'string') return false;
+    const typeParams = value['typeParams'];
+    if (typeParams !== undefined && !isPlainRecord(typeParams)) return false;
+    return true;
+  }
+  if (kind === 'valueObject') {
+    return typeof value['name'] === 'string';
+  }
+  if (kind === 'union') {
+    const members = value['members'];
+    if (!Array.isArray(members)) return false;
+    return members.every((m) => isContractFieldType(m));
+  }
+  return false;
+}
+
+const ContractFieldTypeSchema = type('unknown').narrow((value, ctx) =>
+  isContractFieldType(value) ? true : ctx.mustBe('scalar, valueObject, or union field type'),
+);
+
+const ModelFieldSchema = type({
+  '+': 'reject',
+  nullable: 'boolean',
+  type: ContractFieldTypeSchema,
+  'many?': 'true',
+  'dict?': 'true',
+});
+
+const ModelStorageFieldSchema = type({
   column: 'string',
+  'codecId?': 'string',
+  'nullable?': 'boolean',
 });
 
-const ModelStorageSchema = type.declare<ModelStorage>().type({
+const ModelStorageSchema = type({
   table: 'string',
+  fields: type({ '[string]': ModelStorageFieldSchema }),
 });
 
-const ModelSchema = type.declare<ModelDefinition>().type({
+const ModelSchema = type({
   storage: ModelStorageSchema,
-  fields: type({ '[string]': ModelFieldSchema }),
-  relations: type({ '[string]': 'unknown' }),
+  'fields?': type({ '[string]': ModelFieldSchema }),
+  'relations?': type({ '[string]': 'unknown' }),
+  'discriminator?': 'unknown',
+  'variants?': 'unknown',
+  'base?': 'string',
+  'owner?': 'string',
+});
+
+const ContractMetaSchema = type({
+  '[string]': 'unknown',
 });
 
 const SqlContractSchema = type({
-  'schemaVersion?': "'1'",
+  '+': 'reject',
   target: 'string',
   targetFamily: "'sql'",
-  coreHash: 'string',
-  'profileHash?': 'string',
+  'coreHash?': 'string',
+  profileHash: 'string',
   'capabilities?': 'Record<string, Record<string, boolean>>',
   'extensionPacks?': 'Record<string, unknown>',
-  'meta?': 'Record<string, unknown>',
-  'sources?': 'Record<string, unknown>',
+  'meta?': ContractMetaSchema,
+  'roots?': 'Record<string, string>',
   models: type({ '[string]': ModelSchema }),
+  'valueObjects?': 'Record<string, unknown>',
   storage: StorageSchema,
+  'execution?': ExecutionSchema,
 });
 
+// NOTE: StorageColumnSchema, StorageTableSchema, and StorageSchema use bare type()
+// instead of type.declare<T>().type() because the ColumnDefault union's value field
+// includes bigint | Date (runtime-only types after decoding) which cannot be expressed
+// in Arktype's JSON validation DSL. The `as SqlStorage` cast in validateStorage() bridges
+// the gap between the JSON-safe Arktype output and the runtime TypeScript type.
+// See decodeContractDefaults() in validate.ts for the decoding step.
+
 /**
  * Validates the structural shape of SqlStorage using Arktype.
  *
@@ -99,17 +232,10 @@ export function validateStorage(value: unknown): SqlStorage {
     const messages = result.map((p: { message: string }) => p.message).join('; ');
     throw new Error(`Storage validation failed: ${messages}`);
   }
-  return result;
+  return result as SqlStorage;
 }
 
-/**
- * Validates the structural shape of ModelDefinition using Arktype.
- *
- * @param value - The model value to validate
- * @returns The validated model if structure is valid
- * @throws Error if the model structure is invalid
- */
-export function validateModel(value: unknown): ModelDefinition {
+export function validateModel(value: unknown): unknown {
   const result = ModelSchema(value);
   if (result instanceof type.errors) {
     const messages = result.map((p: { message: string }) => p.message).join('; ');
@@ -119,37 +245,161 @@ export function validateModel(value: unknown): ModelDefinition {
 }
 
 /**
- * Validates the structural shape of a SqlContract using Arktype.
- *
- * **Responsibility: Validation Only**
- * This function validates that the contract has the correct structure and types.
- * It does NOT normalize the contract - normalization must happen in the contract builder.
+ * Validates the structural shape of an SQL contract using Arktype.
  *
- * The contract passed to this function must already be normalized (all required fields present).
- * If normalization is needed, it should be done by the contract builder before calling this function.
- *
- * This ensures all required fields are present and have the correct types.
+ * Ensures all required fields are present and have the correct types,
+ * including SQL-specific storage structure (tables, columns, constraints).
  *
  * @param value - The contract value to validate (typically from a JSON import)
  * @returns The validated contract if structure is valid
- * @throws Error if the contract structure is invalid
+ * @throws ContractValidationError if the contract structure is invalid
  */
-export function validateSqlContract<T extends SqlContract<SqlStorage>>(value: unknown): T {
-  // Check targetFamily first to provide a clear error message for unsupported target families
+export function validateSqlContract<T extends Contract<SqlStorage>>(value: unknown): T {
+  if (typeof value !== 'object' || value === null) {
+    throw new ContractValidationError(
+      'Contract structural validation failed: value must be an object',
+      'structural',
+    );
+  }
+
   const rawValue = value as { targetFamily?: string };
   if (rawValue.targetFamily !== undefined && rawValue.targetFamily !== 'sql') {
-    throw new Error(`Unsupported target family: ${rawValue.targetFamily}`);
+    throw new ContractValidationError(
+      `Unsupported target family: ${rawValue.targetFamily}`,
+      'structural',
+    );
   }
 
   const contractResult = SqlContractSchema(value);
 
   if (contractResult instanceof type.errors) {
     const messages = contractResult.map((p: { message: string }) => p.message).join('; ');
-    throw new Error(`Contract structural validation failed: ${messages}`);
+    throw new ContractValidationError(
+      `Contract structural validation failed: ${messages}`,
+      'structural',
+    );
+  }
+
+  // Arktype's inferred output type differs from T due to exactOptionalPropertyTypes
+  // and branded hash types — the runtime value is structurally compatible after validation
+  return contractResult as unknown as T;
+}
+
+/**
+ * Validates semantic constraints on SqlStorage that cannot be expressed in Arktype schemas.
+ *
+ * Returns an array of human-readable error strings. Empty array = valid.
+ *
+ * Currently checks:
+ * - duplicate named primary key / unique / index / foreign key objects within a table
+ * - duplicate unique, index, or foreign key declarations within a table
+ * - `setNull` referential action on a non-nullable FK column (would fail at runtime)
+ * - `setDefault` referential action on a non-nullable FK column without a DEFAULT (would fail at runtime)
+ */
+export function validateStorageSemantics(storage: SqlStorage): string[] {
+  const errors: string[] = [];
+
+  for (const [tableName, table] of Object.entries(storage.tables)) {
+    const namedObjects = new Map<string, string[]>();
+    const registerNamedObject = (kind: string, name: string | undefined) => {
+      if (!name) return;
+      namedObjects.set(name, [...(namedObjects.get(name) ?? []), kind]);
+    };
+
+    registerNamedObject('primary key', table.primaryKey?.name);
+    for (const unique of table.uniques) {
+      registerNamedObject('unique constraint', unique.name);
+    }
+    for (const index of table.indexes) {
+      registerNamedObject('index', index.name);
+    }
+    for (const fk of table.foreignKeys) {
+      registerNamedObject('foreign key', fk.name);
+    }
+
+    for (const [name, kinds] of namedObjects) {
+      if (kinds.length > 1) {
+        errors.push(
+          `Table "${tableName}": named object "${name}" is declared multiple times (${kinds.join(', ')})`,
+        );
+      }
+    }
+
+    const seenUniqueDefinitions = new Set<string>();
+    for (const unique of table.uniques) {
+      const signature = JSON.stringify({ columns: unique.columns });
+      if (seenUniqueDefinitions.has(signature)) {
+        errors.push(
+          `Table "${tableName}": duplicate unique constraint definition on columns [${unique.columns.join(', ')}]`,
+        );
+        continue;
+      }
+      seenUniqueDefinitions.add(signature);
+    }
+
+    const seenIndexDefinitions = new Set<string>();
+    for (const index of table.indexes) {
+      const signature = JSON.stringify({
+        columns: index.columns,
+        using: index.using ?? null,
+        config: index.config ?? null,
+      });
+      if (seenIndexDefinitions.has(signature)) {
+        errors.push(
+          `Table "${tableName}": duplicate index definition on columns [${index.columns.join(', ')}]`,
+        );
+        continue;
+      }
+      seenIndexDefinitions.add(signature);
+    }
+
+    const seenForeignKeyDefinitions = new Set<string>();
+    for (const fk of table.foreignKeys) {
+      const signature = JSON.stringify({
+        columns: fk.columns,
+        references: fk.references,
+        onDelete: fk.onDelete ?? null,
+        onUpdate: fk.onUpdate ?? null,
+        constraint: fk.constraint,
+        index: fk.index,
+      });
+      if (seenForeignKeyDefinitions.has(signature)) {
+        errors.push(
+          `Table "${tableName}": duplicate foreign key definition on columns [${fk.columns.join(', ')}]`,
+        );
+        continue;
+      }
+      seenForeignKeyDefinitions.add(signature);
+    }
+
+    for (const fk of table.foreignKeys) {
+      for (const colName of fk.columns) {
+        const column = table.columns[colName];
+        if (!column) continue;
+
+        if (fk.onDelete === 'setNull' && !column.nullable) {
+          errors.push(
+            `Table "${tableName}": onDelete setNull on foreign key column "${colName}" which is NOT NULL`,
+          );
+        }
+        if (fk.onUpdate === 'setNull' && !column.nullable) {
+          errors.push(
+            `Table "${tableName}": onUpdate setNull on foreign key column "${colName}" which is NOT NULL`,
+          );
+        }
+        if (fk.onDelete === 'setDefault' && !column.nullable && column.default === undefined) {
+          errors.push(
+            `Table "${tableName}": onDelete setDefault on foreign key column "${colName}" which is NOT NULL and has no DEFAULT`,
+          );
+        }
+        if (fk.onUpdate === 'setDefault' && !column.nullable && column.default === undefined) {
+          errors.push(
+            `Table "${tableName}": onUpdate setDefault on foreign key column "${colName}" which is NOT NULL and has no DEFAULT`,
+          );
+        }
+      }
+    }
   }
 
-  // After validation, contractResult matches the schema and preserves the input structure
-  // TypeScript needs an assertion here due to exactOptionalPropertyTypes differences
-  // between Arktype's inferred type and the generic T, but runtime-wise they're compatible
-  return contractResult as T;
+  return errors;
 }

package/dist/exports/factories.d.ts

@@ -1,2 +0,0 @@
-export { col, contract, fk, index, model, pk, storage, table, unique, } from '../factories';
-//# sourceMappingURL=factories.d.ts.map

package/dist/exports/factories.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"factories.d.ts","sourceRoot":"","sources":["../../src/exports/factories.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,GAAG,EACH,QAAQ,EACR,EAAE,EACF,KAAK,EACL,KAAK,EACL,EAAE,EACF,OAAO,EACP,KAAK,EACL,MAAM,GACP,MAAM,cAAc,CAAC"}