@prisma-next/sql-contract-psl 0.14.0-dev.1 → 0.14.0-dev.10

package/src/psl-named-type-resolution.ts

@@ -0,0 +1,250 @@
+import type { ContractSourceDiagnostic } from '@prisma-next/config/config-types';
+import type { AuthoringContributions } from '@prisma-next/framework-components/authoring';
+import type { ResolvedAttribute, ScalarSymbol, TypeAliasSymbol } from '@prisma-next/psl-parser';
+import type { StorageTypeInstance } from '@prisma-next/sql-contract/types';
+import {
+  type ColumnDescriptor,
+  checkUncomposedNamespace,
+  instantiatePslTypeConstructor,
+  reportUncomposedNamespace,
+  resolveDbNativeTypeAttribute,
+  resolvePslTypeConstructorDescriptor,
+  toNamedTypeFieldDescriptor,
+} from './psl-column-resolution';
+
+type NamedTypeSymbol = ScalarSymbol | TypeAliasSymbol;
+
+export interface ResolveNamedTypeDeclarationsInput {
+  readonly declarations: readonly NamedTypeSymbol[];
+  readonly sourceId: string;
+  readonly enumTypeDescriptors: ReadonlyMap<string, ColumnDescriptor>;
+  readonly scalarTypeDescriptors: ReadonlyMap<string, ColumnDescriptor>;
+  readonly composedExtensions: ReadonlySet<string>;
+  readonly familyId: string;
+  readonly targetId: string;
+  readonly authoringContributions: AuthoringContributions | undefined;
+  readonly diagnostics: ContractSourceDiagnostic[];
+}
+
+function validateNamedTypeAttributes(input: {
+  readonly declaration: NamedTypeSymbol;
+  readonly sourceId: string;
+  readonly diagnostics: ContractSourceDiagnostic[];
+  readonly composedExtensions: ReadonlySet<string>;
+  readonly authoringContributions: AuthoringContributions | undefined;
+  readonly allowDbNativeType: boolean;
+  readonly familyId: string;
+  readonly targetId: string;
+}): {
+  readonly dbNativeTypeAttribute: ResolvedAttribute | undefined;
+  readonly hasUnsupportedNamedTypeAttribute: boolean;
+} {
+  const dbNativeTypeAttributes = input.allowDbNativeType
+    ? input.declaration.attributes.filter((attribute) => attribute.name.startsWith('db.'))
+    : [];
+  const [dbNativeTypeAttribute, ...extraDbNativeTypeAttributes] = dbNativeTypeAttributes;
+  let hasUnsupportedNamedTypeAttribute = false;
+
+  for (const extra of extraDbNativeTypeAttributes) {
+    input.diagnostics.push({
+      code: 'PSL_INVALID_ATTRIBUTE_ARGUMENT',
+      message: `Named type "${input.declaration.name}" can declare at most one @db.* attribute`,
+      sourceId: input.sourceId,
+      span: extra.span,
+    });
+    hasUnsupportedNamedTypeAttribute = true;
+  }
+
+  for (const attribute of input.declaration.attributes) {
+    if (input.allowDbNativeType && attribute.name.startsWith('db.')) {
+      continue;
+    }
+
+    const uncomposedNamespace = checkUncomposedNamespace(attribute.name, input.composedExtensions, {
+      familyId: input.familyId,
+      targetId: input.targetId,
+      authoringContributions: input.authoringContributions,
+    });
+    if (uncomposedNamespace) {
+      reportUncomposedNamespace({
+        subjectLabel: `Attribute "@${attribute.name}"`,
+        namespace: uncomposedNamespace,
+        sourceId: input.sourceId,
+        span: attribute.span,
+        diagnostics: input.diagnostics,
+      });
+      hasUnsupportedNamedTypeAttribute = true;
+      continue;
+    }
+
+    input.diagnostics.push({
+      code: 'PSL_UNSUPPORTED_NAMED_TYPE_ATTRIBUTE',
+      message: `Named type "${input.declaration.name}" uses unsupported attribute "${attribute.name}"`,
+      sourceId: input.sourceId,
+      span: attribute.span,
+    });
+    hasUnsupportedNamedTypeAttribute = true;
+  }
+
+  return { dbNativeTypeAttribute, hasUnsupportedNamedTypeAttribute };
+}
+
+export function resolveNamedTypeDeclarations(input: ResolveNamedTypeDeclarationsInput): {
+  readonly storageTypes: Record<string, StorageTypeInstance>;
+  readonly namedTypeDescriptors: Map<string, ColumnDescriptor>;
+} {
+  const storageTypeEntries: [string, StorageTypeInstance][] = [];
+  const namedTypeDescriptors = new Map<string, ColumnDescriptor>();
+
+  for (const declaration of input.declarations) {
+    if (declaration.isConstructor) {
+      const typeConstructor = declaration.typeConstructor;
+      if (typeConstructor === undefined) {
+        input.diagnostics.push({
+          code: 'PSL_UNSUPPORTED_NAMED_TYPE_BASE',
+          message: `Named type "${declaration.name}" must declare a base type or constructor`,
+          sourceId: input.sourceId,
+          span: declaration.span,
+        });
+        continue;
+      }
+
+      const { hasUnsupportedNamedTypeAttribute } = validateNamedTypeAttributes({
+        declaration,
+        sourceId: input.sourceId,
+        diagnostics: input.diagnostics,
+        composedExtensions: input.composedExtensions,
+        authoringContributions: input.authoringContributions,
+        allowDbNativeType: false,
+        familyId: input.familyId,
+        targetId: input.targetId,
+      });
+      if (hasUnsupportedNamedTypeAttribute) {
+        continue;
+      }
+
+      const helperPath = typeConstructor.path.join('.');
+      const descriptor = resolvePslTypeConstructorDescriptor({
+        call: typeConstructor,
+        authoringContributions: input.authoringContributions,
+        composedExtensions: input.composedExtensions,
+        familyId: input.familyId,
+        targetId: input.targetId,
+        diagnostics: input.diagnostics,
+        sourceId: input.sourceId,
+        unsupportedCode: 'PSL_UNSUPPORTED_NAMED_TYPE_CONSTRUCTOR',
+        unsupportedMessage: `Named type "${declaration.name}" references unsupported constructor "${helperPath}"`,
+      });
+      if (!descriptor) {
+        continue;
+      }
+
+      const storageType = instantiatePslTypeConstructor({
+        call: typeConstructor,
+        descriptor,
+        diagnostics: input.diagnostics,
+        sourceId: input.sourceId,
+        entityLabel: `Named type "${declaration.name}"`,
+      });
+      if (!storageType) {
+        continue;
+      }
+
+      namedTypeDescriptors.set(
+        declaration.name,
+        toNamedTypeFieldDescriptor(declaration.name, storageType),
+      );
+      storageTypeEntries.push([
+        declaration.name,
+        {
+          kind: 'codec-instance',
+          codecId: storageType.codecId,
+          nativeType: storageType.nativeType,
+          typeParams: storageType.typeParams ?? {},
+        },
+      ]);
+      continue;
+    }
+
+    const baseType = declaration.baseType;
+    if (baseType === undefined) {
+      input.diagnostics.push({
+        code: 'PSL_UNSUPPORTED_NAMED_TYPE_BASE',
+        message: `Named type "${declaration.name}" must declare a base type or constructor`,
+        sourceId: input.sourceId,
+        span: declaration.span,
+      });
+      continue;
+    }
+
+    const baseDescriptor =
+      input.enumTypeDescriptors.get(baseType) ?? input.scalarTypeDescriptors.get(baseType);
+    if (!baseDescriptor) {
+      input.diagnostics.push({
+        code: 'PSL_UNSUPPORTED_NAMED_TYPE_BASE',
+        message: `Named type "${declaration.name}" references unsupported base type "${baseType}"`,
+        sourceId: input.sourceId,
+        span: declaration.span,
+      });
+      continue;
+    }
+
+    const { dbNativeTypeAttribute, hasUnsupportedNamedTypeAttribute } = validateNamedTypeAttributes(
+      {
+        declaration,
+        sourceId: input.sourceId,
+        diagnostics: input.diagnostics,
+        composedExtensions: input.composedExtensions,
+        authoringContributions: input.authoringContributions,
+        allowDbNativeType: true,
+        familyId: input.familyId,
+        targetId: input.targetId,
+      },
+    );
+    if (hasUnsupportedNamedTypeAttribute) {
+      continue;
+    }
+
+    if (dbNativeTypeAttribute) {
+      const descriptor = resolveDbNativeTypeAttribute({
+        attribute: dbNativeTypeAttribute,
+        baseType,
+        baseDescriptor,
+        diagnostics: input.diagnostics,
+        sourceId: input.sourceId,
+        entityLabel: `Named type "${declaration.name}"`,
+      });
+      if (!descriptor) {
+        continue;
+      }
+      namedTypeDescriptors.set(
+        declaration.name,
+        toNamedTypeFieldDescriptor(declaration.name, descriptor),
+      );
+      storageTypeEntries.push([
+        declaration.name,
+        {
+          kind: 'codec-instance',
+          codecId: descriptor.codecId,
+          nativeType: descriptor.nativeType,
+          typeParams: descriptor.typeParams ?? {},
+        },
+      ]);
+      continue;
+    }
+
+    const descriptor = toNamedTypeFieldDescriptor(declaration.name, baseDescriptor);
+    namedTypeDescriptors.set(declaration.name, descriptor);
+    storageTypeEntries.push([
+      declaration.name,
+      {
+        kind: 'codec-instance',
+        codecId: baseDescriptor.codecId,
+        nativeType: baseDescriptor.nativeType,
+        typeParams: {},
+      },
+    ]);
+  }
+
+  return { storageTypes: Object.fromEntries(storageTypeEntries), namedTypeDescriptors };
+}

package/src/psl-relation-resolution.ts

@@ -1,10 +1,11 @@
 import type { ContractSourceDiagnostic } from '@prisma-next/config/config-types';
 import type { AuthoringContributions } from '@prisma-next/framework-components/authoring';
-import type { PslAttribute, PslField, PslSpan } from '@prisma-next/psl-parser';
+import type { FieldSymbol, PslSpan, ResolvedAttribute } from '@prisma-next/psl-parser';
 import type { ReferentialAction } from '@prisma-next/sql-contract/types';
 import type { RelationNode } from '@prisma-next/sql-contract-ts/contract-builder';
 import { assertDefined, invariant } from '@prisma-next/utils/assertions';
 import { ifDefined } from '@prisma-next/utils/defined';
+
 import {
   getNamedArgument,
   getPositionalArgumentEntry,
@@ -40,6 +41,8 @@ export type FkRelationMetadata = {
   readonly declaringModelName: string;
   readonly declaringFieldName: string;
   readonly declaringTableName: string;
+  /** Resolved namespace coordinate of the declaring model, when known. */
+  readonly declaringNamespaceId?: string;
   readonly targetModelName: string;
   readonly targetTableName: string;
   /** Resolved namespace coordinate of the related model, when known. */
@@ -52,7 +55,7 @@ export type FkRelationMetadata = {
 export type ModelBackrelationCandidate = {
   readonly modelName: string;
   readonly tableName: string;
-  readonly field: PslField;
+  readonly field: FieldSymbol;
   readonly targetModelName: string;
   readonly relationName?: string;
 };
@@ -88,7 +91,7 @@ export function normalizeReferentialAction(input: {
 }
 
 export function parseRelationAttribute(input: {
-  readonly attribute: PslAttribute;
+  readonly attribute: ResolvedAttribute;
   readonly modelName: string;
   readonly fieldName: string;
   readonly sourceId: string;
@@ -239,11 +242,20 @@ export function indexFkRelations(input: {
 }): {
   readonly modelRelations: Map<string, ModelRelationMetadata[]>;
   readonly fkRelationsByPair: Map<string, FkRelationMetadata[]>;
+  readonly fkRelationsByDeclaringModel: Map<string, FkRelationMetadata[]>;
 } {
   const modelRelations = new Map<string, ModelRelationMetadata[]>();
   const fkRelationsByPair = new Map<string, FkRelationMetadata[]>();
+  const fkRelationsByDeclaringModel = new Map<string, FkRelationMetadata[]>();
 
   for (const relation of input.fkRelationMetadata) {
+    const declaringFkRelations = fkRelationsByDeclaringModel.get(relation.declaringModelName);
+    if (declaringFkRelations) {
+      declaringFkRelations.push(relation);
+    } else {
+      fkRelationsByDeclaringModel.set(relation.declaringModelName, [relation]);
+    }
+
     const existing = modelRelations.get(relation.declaringModelName);
     const current = existing ?? [];
     if (!existing) {
@@ -272,12 +284,217 @@ export function indexFkRelations(input: {
     pairRelations.push(relation);
   }
 
-  return { modelRelations, fkRelationsByPair };
+  return { modelRelations, fkRelationsByPair, fkRelationsByDeclaringModel };
+}
+
+type JunctionFkPair = {
+  readonly parentFk: FkRelationMetadata;
+  readonly childFk: FkRelationMetadata;
+  /**
+   * The child FK's junction columns reordered to the target model's
+   * id-column order, so positional pairing against the target id stays
+   * faithful to the authored references regardless of declaration order.
+   */
+  readonly childColumnsInTargetIdOrder: readonly string[];
+};
+
+function idColumnsAreExactlyFkPair(
+  idColumns: readonly string[],
+  parentColumns: readonly string[],
+  childColumns: readonly string[],
+): boolean {
+  if (idColumns.length !== parentColumns.length + childColumns.length) {
+    return false;
+  }
+  const fkColumns = new Set([...parentColumns, ...childColumns]);
+  if (fkColumns.size !== parentColumns.length + childColumns.length) {
+    return false;
+  }
+  return idColumns.every((column) => fkColumns.has(column));
+}
+
+/**
+ * Reorders the child FK's junction columns into the target model's id-column
+ * order. Returns undefined unless the FK references exactly the target's full
+ * id, because downstream consumers pair `through.childColumns` positionally
+ * against the target id columns — an FK referencing anything else (a non-id
+ * unique, a partial id) would produce a silently wrong join.
+ */
+function childColumnsInTargetIdOrder(
+  childFk: FkRelationMetadata,
+  targetIdColumns: readonly string[],
+): readonly string[] | undefined {
+  if (childFk.referencedColumns.length !== targetIdColumns.length) {
+    return undefined;
+  }
+  const localByReferenced = new Map<string, string>();
+  for (const [index, referencedColumn] of childFk.referencedColumns.entries()) {
+    const localColumn = childFk.localColumns[index];
+    if (localColumn === undefined) {
+      return undefined;
+    }
+    localByReferenced.set(referencedColumn, localColumn);
+  }
+  if (localByReferenced.size !== targetIdColumns.length) {
+    return undefined;
+  }
+  const ordered: string[] = [];
+  for (const idColumn of targetIdColumns) {
+    const localColumn = localByReferenced.get(idColumn);
+    if (localColumn === undefined) {
+      return undefined;
+    }
+    ordered.push(localColumn);
+  }
+  return ordered;
+}
+
+/**
+ * A model that carries an FK back to the candidate's model and an FK to the
+ * candidate's target model — i.e. it is junction-shaped for this candidate —
+ * but was declined as a many-to-many junction. The reason drives a
+ * junction-specific diagnostic that is more actionable than the generic
+ * orphaned-backrelation message.
+ */
+type JunctionNearMiss = {
+  readonly junctionModelName: string;
+  readonly reason: 'id-not-fk-covering' | 'target-fk-not-id';
+};
+
+/**
+ * Finds explicit junction models that connect a bare backrelation list field
+ * to its target model: a model whose composite id columns are exactly the FK
+ * columns of one relation back to the candidate's model (the parent side) and
+ * one relation to the candidate's target model (the child side). The child
+ * FK must reference exactly the target model's id columns; its junction
+ * columns are carried in target-id order on the pair. A relation name on the
+ * list field pins the parent-side FK relation, which is how self-referential
+ * many-to-many sides are disambiguated.
+ *
+ * Alongside the recognised pairs, returns junction-shaped near-misses (models
+ * that link both sides but were declined) so the caller can emit a
+ * junction-specific diagnostic instead of the generic orphaned-list message.
+ */
+function findJunctionFkPairs(input: {
+  readonly candidate: ModelBackrelationCandidate;
+  readonly fkRelationsByDeclaringModel: ReadonlyMap<string, readonly FkRelationMetadata[]>;
+  readonly modelIdColumns: ReadonlyMap<string, readonly string[]>;
+}): { readonly pairs: JunctionFkPair[]; readonly nearMisses: JunctionNearMiss[] } {
+  const targetIdColumns = input.modelIdColumns.get(input.candidate.targetModelName);
+  if (!targetIdColumns || targetIdColumns.length === 0) {
+    return { pairs: [], nearMisses: [] };
+  }
+  const pairs: JunctionFkPair[] = [];
+  const nearMisses: JunctionNearMiss[] = [];
+  for (const [junctionModelName, junctionFks] of input.fkRelationsByDeclaringModel) {
+    const idColumns = input.modelIdColumns.get(junctionModelName);
+    for (const parentFk of junctionFks) {
+      if (parentFk.targetModelName !== input.candidate.modelName) {
+        continue;
+      }
+      if (
+        input.candidate.relationName !== undefined &&
+        parentFk.relationName !== input.candidate.relationName
+      ) {
+        continue;
+      }
+      for (const childFk of junctionFks) {
+        if (childFk === parentFk || childFk.targetModelName !== input.candidate.targetModelName) {
+          continue;
+        }
+        // The model links both sides, so it is junction-shaped for this
+        // candidate: record why it is declined rather than silently skipping.
+        if (
+          !idColumns ||
+          !idColumnsAreExactlyFkPair(idColumns, parentFk.localColumns, childFk.localColumns)
+        ) {
+          nearMisses.push({ junctionModelName, reason: 'id-not-fk-covering' });
+          continue;
+        }
+        const orderedChildColumns = childColumnsInTargetIdOrder(childFk, targetIdColumns);
+        if (!orderedChildColumns) {
+          nearMisses.push({ junctionModelName, reason: 'target-fk-not-id' });
+          continue;
+        }
+        pairs.push({ parentFk, childFk, childColumnsInTargetIdOrder: orderedChildColumns });
+      }
+    }
+  }
+  return { pairs, nearMisses };
+}
+
+function junctionNearMissDiagnostic(
+  candidate: ModelBackrelationCandidate,
+  nearMiss: JunctionNearMiss,
+  sourceId: string,
+): ContractSourceDiagnostic {
+  const listField = `${candidate.modelName}.${candidate.field.name}`;
+  const data = {
+    listField,
+    junctionModel: nearMiss.junctionModelName,
+    targetModel: candidate.targetModelName,
+  };
+  if (nearMiss.reason === 'target-fk-not-id') {
+    return {
+      code: 'PSL_JUNCTION_TARGET_FK_NOT_ID',
+      message: `Backrelation list field "${listField}" found junction model "${nearMiss.junctionModelName}", but its foreign key to "${candidate.targetModelName}" does not reference "${candidate.targetModelName}"'s @id. The junction's target-side foreign key must reference "${candidate.targetModelName}"'s full @id columns for many-to-many recognition.`,
+      sourceId,
+      span: candidate.field.span,
+      data,
+    };
+  }
+  return {
+    code: 'PSL_JUNCTION_ID_NOT_FK_COVERING',
+    message: `Backrelation list field "${listField}" found junction-shaped model "${nearMiss.junctionModelName}" linking "${candidate.modelName}" and "${candidate.targetModelName}", but its id does not cover exactly its foreign-key columns. Declare @@id([...]) on "${nearMiss.junctionModelName}" listing exactly the two foreign-key columns for many-to-many recognition.`,
+    sourceId,
+    span: candidate.field.span,
+    data,
+  };
+}
+
+function manyToManyRelationNode(
+  candidate: ModelBackrelationCandidate,
+  pair: JunctionFkPair,
+): ModelRelationMetadata {
+  return {
+    fieldName: candidate.field.name,
+    toModel: pair.childFk.targetModelName,
+    toTable: pair.childFk.targetTableName,
+    ...ifDefined('toNamespaceId', pair.childFk.targetNamespaceId),
+    cardinality: 'N:M',
+    on: {
+      parentTable: candidate.tableName,
+      parentColumns: pair.parentFk.referencedColumns,
+      childTable: pair.parentFk.declaringTableName,
+      childColumns: pair.parentFk.localColumns,
+    },
+    through: {
+      table: pair.parentFk.declaringTableName,
+      ...ifDefined('namespaceId', pair.parentFk.declaringNamespaceId),
+      parentColumns: pair.parentFk.localColumns,
+      childColumns: pair.childColumnsInTargetIdOrder,
+    },
+  };
+}
+
+function relationsForModel(
+  modelRelations: Map<string, ModelRelationMetadata[]>,
+  modelName: string,
+): ModelRelationMetadata[] {
+  const existing = modelRelations.get(modelName);
+  if (existing) {
+    return existing;
+  }
+  const created: ModelRelationMetadata[] = [];
+  modelRelations.set(modelName, created);
+  return created;
 }
 
 export function applyBackrelationCandidates(input: {
   readonly backrelationCandidates: readonly ModelBackrelationCandidate[];
   readonly fkRelationsByPair: Map<string, readonly FkRelationMetadata[]>;
+  readonly fkRelationsByDeclaringModel: ReadonlyMap<string, readonly FkRelationMetadata[]>;
+  readonly modelIdColumns: ReadonlyMap<string, readonly string[]>;
   readonly modelRelations: Map<string, ModelRelationMetadata[]>;
   readonly diagnostics: ContractSourceDiagnostic[];
   readonly sourceId: string;
@@ -290,6 +507,32 @@ export function applyBackrelationCandidates(input: {
       : [...pairMatches];
 
     if (matches.length === 0) {
+      const { pairs: junctionPairs, nearMisses } = findJunctionFkPairs({
+        candidate,
+        fkRelationsByDeclaringModel: input.fkRelationsByDeclaringModel,
+        modelIdColumns: input.modelIdColumns,
+      });
+      const junctionPair = junctionPairs[0];
+      if (junctionPairs.length === 1 && junctionPair) {
+        relationsForModel(input.modelRelations, candidate.modelName).push(
+          manyToManyRelationNode(candidate, junctionPair),
+        );
+        continue;
+      }
+      if (junctionPairs.length > 1) {
+        input.diagnostics.push({
+          code: 'PSL_AMBIGUOUS_BACKRELATION_LIST',
+          message: `Backrelation list field "${candidate.modelName}.${candidate.field.name}" matches multiple junction FK pairs for a many-to-many relation. Add @relation(name: "...") (or @relation("...")) to the list field and the junction FK-side relation pointing back at "${candidate.modelName}" to disambiguate.`,
+          sourceId: input.sourceId,
+          span: candidate.field.span,
+        });
+        continue;
+      }
+      const nearMiss = nearMisses[0];
+      if (nearMiss) {
+        input.diagnostics.push(junctionNearMissDiagnostic(candidate, nearMiss, input.sourceId));
+        continue;
+      }
       input.diagnostics.push({
         code: 'PSL_ORPHANED_BACKRELATION_LIST',
         message: `Backrelation list field "${candidate.modelName}.${candidate.field.name}" has no matching FK-side relation on model "${candidate.targetModelName}". Add @relation(fields: [...], references: [...]) on the FK-side relation or use an explicit join model for many-to-many.`,
@@ -312,15 +555,11 @@ export function applyBackrelationCandidates(input: {
     const matched = matches[0];
     assertDefined(matched, 'Backrelation matching requires a defined relation match');
 
-    const existing = input.modelRelations.get(candidate.modelName);
-    const current = existing ?? [];
-    if (!existing) {
-      input.modelRelations.set(candidate.modelName, current);
-    }
-    current.push({
+    relationsForModel(input.modelRelations, candidate.modelName).push({
       fieldName: candidate.field.name,
       toModel: matched.declaringModelName,
       toTable: matched.declaringTableName,
+      ...ifDefined('toNamespaceId', matched.declaringNamespaceId),
       cardinality: '1:N',
       on: {
         parentTable: candidate.tableName,
@@ -334,7 +573,7 @@ export function applyBackrelationCandidates(input: {
 
 export function validateNavigationListFieldAttributes(input: {
   readonly modelName: string;
-  readonly field: PslField;
+  readonly field: FieldSymbol;
   readonly sourceId: string;
   readonly composedExtensions: Set<string>;
   readonly authoringContributions: AuthoringContributions | undefined;