@prisma-next/sql-contract-psl 0.14.0-dev.7 → 0.14.0-dev.9

package/dist/provider.mjs

@@ -1,4 +1,4 @@
-import { t as interpretPslDocumentToSqlContract } from "./interpreter-kDkm5opL.mjs";
+import { t as interpretPslDocumentToSqlContract } from "./interpreter-CygvamTk.mjs";
 import { buildSymbolTable, rangeToPslSpan } from "@prisma-next/psl-parser";
 import { ifDefined } from "@prisma-next/utils/defined";
 import { notOk, ok } from "@prisma-next/utils/result";

package/package.json

@@ -1,25 +1,25 @@
 {
   "name": "@prisma-next/sql-contract-psl",
-  "version": "0.14.0-dev.7",
+  "version": "0.14.0-dev.9",
   "license": "Apache-2.0",
   "type": "module",
   "sideEffects": false,
   "description": "PSL-to-SQL ContractIR interpreter for Prisma Next",
   "dependencies": {
-    "@prisma-next/config": "0.14.0-dev.7",
-    "@prisma-next/contract": "0.14.0-dev.7",
-    "@prisma-next/framework-components": "0.14.0-dev.7",
-    "@prisma-next/psl-parser": "0.14.0-dev.7",
-    "@prisma-next/sql-contract": "0.14.0-dev.7",
-    "@prisma-next/sql-contract-ts": "0.14.0-dev.7",
-    "@prisma-next/utils": "0.14.0-dev.7",
+    "@prisma-next/config": "0.14.0-dev.9",
+    "@prisma-next/contract": "0.14.0-dev.9",
+    "@prisma-next/framework-components": "0.14.0-dev.9",
+    "@prisma-next/psl-parser": "0.14.0-dev.9",
+    "@prisma-next/sql-contract": "0.14.0-dev.9",
+    "@prisma-next/sql-contract-ts": "0.14.0-dev.9",
+    "@prisma-next/utils": "0.14.0-dev.9",
     "pathe": "^2.0.3"
   },
   "devDependencies": {
-    "@prisma-next/contract-authoring": "0.14.0-dev.7",
-    "@prisma-next/test-utils": "0.14.0-dev.7",
-    "@prisma-next/tsconfig": "0.14.0-dev.7",
-    "@prisma-next/tsdown": "0.14.0-dev.7",
+    "@prisma-next/contract-authoring": "0.14.0-dev.9",
+    "@prisma-next/test-utils": "0.14.0-dev.9",
+    "@prisma-next/tsconfig": "0.14.0-dev.9",
+    "@prisma-next/tsdown": "0.14.0-dev.9",
     "arktype": "^2.2.0",
     "tsdown": "0.22.1",
     "typescript": "5.9.3",

package/src/interpreter.ts

@@ -1061,6 +1061,7 @@ function buildModelNodeFromPsl(input: BuildModelNodeInput): BuildModelNodeResult
       declaringModelName: model.name,
       declaringFieldName: relationAttribute.field.name,
       declaringTableName: tableName,
+      ...ifDefined('declaringNamespaceId', input.modelNamespaceIds.get(model.name)),
       targetModelName: targetMapping.model.name,
       targetTableName: targetMapping.tableName,
       ...ifDefined('targetNamespaceId', targetNamespaceId),
@@ -1860,10 +1861,20 @@ export function interpretPslDocumentToSqlContract(
     }
   }
 
-  const { modelRelations, fkRelationsByPair } = indexFkRelations({ fkRelationMetadata });
+  const { modelRelations, fkRelationsByPair, fkRelationsByDeclaringModel } = indexFkRelations({
+    fkRelationMetadata,
+  });
+  const modelIdColumns = new Map<string, readonly string[]>();
+  for (const modelNode of modelNodes) {
+    if (modelNode.id) {
+      modelIdColumns.set(modelNode.modelName, modelNode.id.columns);
+    }
+  }
   applyBackrelationCandidates({
     backrelationCandidates,
     fkRelationsByPair,
+    fkRelationsByDeclaringModel,
+    modelIdColumns,
     modelRelations,
     diagnostics,
     sourceId,

package/src/psl-relation-resolution.ts

@@ -41,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. */
@@ -240,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) {
@@ -273,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;
@@ -291,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.`,
@@ -313,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,