feat(mongo-family)!: from/to relation syntax; reject legacy fields/references

tensordreams · tensordreams · commit 3a71c139ec05 · 2026-07-01T16:32:01.000+02:00
S1a/S1b taught the SQL PSL resolver to accept only @relation(from:, to:). The Mongo family has its own PSL relation parser (contract-psl/psl-helpers.ts, parseRelationAttribute) that read only fields:/references: and ignored from:/to:, so Mongo schemas were left on the legacy vocabulary. Mirror the SQL change in the Mongo interpreter: - parseRelationAttribute now reads from:/to:, rejects fields:/references: with the PSL_LEGACY_FIELDS_REFERENCES diagnostic (the same open-string code SQL uses), and supports bare or bracketed values. Omitting to: infers the referenced column(s) from the target model's @id (resolveTargetIdFieldNames); a to: without a from: is rejected. The interpreter caller resolves the inferred references against the target model and routes legacy/invalid relations away from backrelation handling. - Migrate every Mongo-family authored schema, migration snapshot, inline-PSL test, and the Mongo CLI init template from fields:/references: to from:/to:. from/to lowers byte-identically to fields/references, so only .prisma source spelling changes — no contract.json, migration metadata, or hash drift (verified: migrations:regen:examples re-parses the migrated Mongo snapshots and re-emits the start/end contracts with zero artifact diff). @relation(name:) is untouched. Signed-off-by: Alexey Orlenko's AI Agent <robot@aqrln.net>
diff --git a/examples/mongo-blog-leaderboard/src/contract.prisma b/examples/mongo-blog-leaderboard/src/contract.prisma
@@ -22,7 +22,7 @@ model Post {
   kind      String
   authorId  ObjectId
   createdAt DateTime
-  author    User     @relation(fields: [authorId], references: [id])
+  author    User     @relation(from: [authorId], to: [id])
 
   @@discriminator(kind)
   @@index([authorId])
diff --git a/examples/mongo-demo/migrations/app/20260409T1030_migration/contract.prisma b/examples/mongo-demo/migrations/app/20260409T1030_migration/contract.prisma
@@ -24,7 +24,7 @@ model Post {
   kind      String
   authorId  ObjectId
   createdAt DateTime
-  author    User @relation(fields: [authorId], references: [id])
+  author    User @relation(from: [authorId], to: [id])
   @@discriminator(kind)
   @@map("posts")
 }
diff --git a/examples/mongo-demo/migrations/app/20260626T1605_add_user_role_enum/contract.prisma b/examples/mongo-demo/migrations/app/20260626T1605_add_user_role_enum/contract.prisma
@@ -32,7 +32,7 @@ model Post {
   kind      String
   authorId  ObjectId
   createdAt DateTime
-  author    User @relation(fields: [authorId], references: [id])
+  author    User @relation(from: [authorId], to: [id])
   @@discriminator(kind)
   @@map("posts")
 }
diff --git a/examples/mongo-demo/src/contract.prisma b/examples/mongo-demo/src/contract.prisma
@@ -32,7 +32,7 @@ model Post {
   kind      String
   authorId  ObjectId
   createdAt DateTime
-  author    User @relation(fields: [authorId], references: [id])
+  author    User @relation(from: [authorId], to: [id])
   @@discriminator(kind)
   @@index([authorId])
   @@index([createdAt(sort: Desc), authorId])
diff --git a/examples/retail-store/migrations/app/20260513T0505_initial/contract.prisma b/examples/retail-store/migrations/app/20260513T0505_initial/contract.prisma
@@ -77,7 +77,7 @@ model Cart {
   id     ObjectId   @id @map("_id")
   userId ObjectId
   items  CartItem[]
-  user   User       @relation(fields: [userId], references: [id])
+  user   User       @relation(from: [userId], to: [id])
   @@map("carts")
   @@unique([userId])
 }
@@ -89,7 +89,7 @@ model Order {
   shippingAddress String
   type            String
   statusHistory   StatusEntry[]
-  user            User             @relation(fields: [userId], references: [id])
+  user            User             @relation(from: [userId], to: [id])
   invoices        Invoice[]
   @@map("orders")
   @@index([userId])
@@ -114,7 +114,7 @@ model Invoice {
   tax      Float
   total    Float
   issuedAt DateTime
-  order    Order             @relation(fields: [orderId], references: [id])
+  order    Order             @relation(from: [orderId], to: [id])
   @@map("invoices")
   @@index([orderId])
   @@index([issuedAt(sort: Desc)], sparse: true)
diff --git a/examples/retail-store/migrations/app/20260513T0507_add_product_category_index/contract.prisma b/examples/retail-store/migrations/app/20260513T0507_add_product_category_index/contract.prisma
@@ -78,7 +78,7 @@ model Cart {
   id     ObjectId   @id @map("_id")
   userId ObjectId
   items  CartItem[]
-  user   User       @relation(fields: [userId], references: [id])
+  user   User       @relation(from: [userId], to: [id])
   @@map("carts")
   @@unique([userId])
 }
@@ -90,7 +90,7 @@ model Order {
   shippingAddress String
   type            String
   statusHistory   StatusEntry[]
-  user            User             @relation(fields: [userId], references: [id])
+  user            User             @relation(from: [userId], to: [id])
   invoices        Invoice[]
   @@map("orders")
   @@index([userId])
@@ -115,7 +115,7 @@ model Invoice {
   tax      Float
   total    Float
   issuedAt DateTime
-  order    Order             @relation(fields: [orderId], references: [id])
+  order    Order             @relation(from: [orderId], to: [id])
   @@map("invoices")
   @@index([orderId])
   @@index([issuedAt(sort: Desc)], sparse: true)
diff --git a/examples/retail-store/migrations/app/20260513T0508_backfill_product_status/contract.prisma b/examples/retail-store/migrations/app/20260513T0508_backfill_product_status/contract.prisma
@@ -80,7 +80,7 @@ model Cart {
   id     ObjectId   @id @map("_id")
   userId ObjectId
   items  CartItem[]
-  user   User       @relation(fields: [userId], references: [id])
+  user   User       @relation(from: [userId], to: [id])
   @@map("carts")
   @@unique([userId])
 }
@@ -92,7 +92,7 @@ model Order {
   shippingAddress String
   type            String
   statusHistory   StatusEntry[]
-  user            User             @relation(fields: [userId], references: [id])
+  user            User             @relation(from: [userId], to: [id])
   invoices        Invoice[]
   @@map("orders")
   @@index([userId])
@@ -117,7 +117,7 @@ model Invoice {
   tax      Float
   total    Float
   issuedAt DateTime
-  order    Order             @relation(fields: [orderId], references: [id])
+  order    Order             @relation(from: [orderId], to: [id])
   @@map("invoices")
   @@index([orderId])
   @@index([issuedAt(sort: Desc)], sparse: true)
diff --git a/examples/retail-store/src/contract.prisma b/examples/retail-store/src/contract.prisma
@@ -93,7 +93,7 @@ model Cart {
   id     ObjectId   @id @map("_id")
   userId ObjectId
   items  CartItem[]
-  user   User       @relation(fields: [userId], references: [id])
+  user   User       @relation(from: [userId], to: [id])
   @@map("carts")
   @@unique([userId])
 }
@@ -105,7 +105,7 @@ model Order {
   shippingAddress String
   type            OrderType
   statusHistory   StatusEntry[]
-  user            User             @relation(fields: [userId], references: [id])
+  user            User             @relation(from: [userId], to: [id])
   invoices        Invoice[]
   @@map("orders")
   @@index([userId])
@@ -130,7 +130,7 @@ model Invoice {
   tax      Float
   total    Float
   issuedAt DateTime
-  order    Order             @relation(fields: [orderId], references: [id])
+  order    Order             @relation(from: [orderId], to: [id])
   @@map("invoices")
   @@index([orderId])
   @@index([issuedAt(sort: Desc)], sparse: true)
diff --git a/packages/1-framework/3-tooling/cli/src/commands/init/templates/code-templates.ts b/packages/1-framework/3-tooling/cli/src/commands/init/templates/code-templates.ts
@@ -150,7 +150,7 @@ model Post {
   id       ObjectId @id @map("_id")
   title    String
   content  String?
-  author   User     @relation(fields: [authorId], references: [id])
+  author   User     @relation(from: [authorId], to: [id])
   authorId ObjectId
   @@map("posts")
 }
diff --git a/packages/1-framework/3-tooling/cli/test/commands/init/__snapshots__/templates.test.ts.snap b/packages/1-framework/3-tooling/cli/test/commands/init/__snapshots__/templates.test.ts.snap
@@ -247,7 +247,7 @@ model Post {
   id       ObjectId @id @map("_id")
   title    String
   content  String?
-  author   User     @relation(fields: [authorId], references: [id])
+  author   User     @relation(from: [authorId], to: [id])
   authorId ObjectId
   @@map("posts")
 }
diff --git a/packages/2-mongo-family/2-authoring/contract-psl/src/interpreter.ts b/packages/2-mongo-family/2-authoring/contract-psl/src/interpreter.ts
@@ -60,6 +60,7 @@ import {
   parseIndexFieldList,
   parseQuotedStringLiteral,
   parseRelationAttribute,
+  resolveTargetIdFieldNames,
 } from './psl-helpers';
 
 export interface InterpretPslDocumentToMongoContractInput {
@@ -1001,9 +1002,39 @@ export function interpretPslDocumentToMongoContract(
 
     for (const field of Object.values(pslModel.fields)) {
       if (isRelationField(field, modelNames)) {
-        const relation = parseRelationAttribute(field.attributes);
+        const diagnosticsBefore = diagnostics.length;
+        const relation = parseRelationAttribute({
+          attributes: field.attributes,
+          modelName: pslModel.name,
+          fieldName: field.name,
+          sourceId,
+          diagnostics,
+        });
+        if (diagnostics.length > diagnosticsBefore) {
+          // The relation attribute was rejected (legacy fields:/references:, a
+          // to: without a from:, a malformed value). The pushed diagnostic fails
+          // the interpret; the field carries no usable FK or backrelation shape.
+          continue;
+        }
 
-        if (field.list || !(relation?.fields && relation?.references)) {
+        const targetModel = allModels.find((m) => m.name === field.typeName);
+
+        let references = relation?.references;
+        if (relation?.fields && relation.referencesInferred) {
+          const targetIdFields = targetModel ? resolveTargetIdFieldNames(targetModel) : undefined;
+          if (!targetIdFields) {
+            diagnostics.push({
+              code: 'PSL_INVALID_RELATION_ATTRIBUTE',
+              message: `Relation field "${pslModel.name}.${field.name}" omits to: but target model "${field.typeName}" declares no @id to infer the referenced field(s) from`,
+              sourceId,
+              span: field.span,
+            });
+            continue;
+          }
+          references = targetIdFields;
+        }
+
+        if (field.list || !(relation?.fields && references)) {
           backrelationCandidates.push({
             modelName: pslModel.name,
             fieldName: field.name,
@@ -1015,33 +1046,30 @@ export function interpretPslDocumentToMongoContract(
           continue;
         }
 
-        if (relation?.fields && relation?.references) {
-          const localMapped = relation.fields.map((f) => fieldMappings.pslNameToMapped.get(f) ?? f);
+        const localMapped = relation.fields.map((f) => fieldMappings.pslNameToMapped.get(f) ?? f);
 
-          const targetModel = allModels.find((m) => m.name === field.typeName);
-          const targetFieldMappings = targetModel ? resolveFieldMappings(targetModel) : undefined;
-          const targetMapped = relation.references.map(
-            (f) => targetFieldMappings?.pslNameToMapped.get(f) ?? f,
-          );
+        const targetFieldMappings = targetModel ? resolveFieldMappings(targetModel) : undefined;
+        const targetMapped = references.map(
+          (f) => targetFieldMappings?.pslNameToMapped.get(f) ?? f,
+        );
 
-          relations[field.name] = {
-            to: mongoCrossRef(field.typeName),
-            cardinality: 'N:1' as const,
-            on: {
-              localFields: localMapped,
-              targetFields: targetMapped,
-            },
-          };
-
-          allFkRelations.push({
-            declaringModel: pslModel.name,
-            fieldName: field.name,
-            targetModel: field.typeName,
-            ...ifDefined('relationName', relation.relationName),
+        relations[field.name] = {
+          to: mongoCrossRef(field.typeName),
+          cardinality: 'N:1' as const,
+          on: {
             localFields: localMapped,
             targetFields: targetMapped,
-          });
-        }
+          },
+        };
+
+        allFkRelations.push({
+          declaringModel: pslModel.name,
+          fieldName: field.name,
+          targetModel: field.typeName,
+          ...(relation.relationName !== undefined ? { relationName: relation.relationName } : {}),
+          localFields: localMapped,
+          targetFields: targetMapped,
+        });
         continue;
       }
 
@@ -1155,7 +1183,7 @@ export function interpretPslDocumentToMongoContract(
     if (matches.length === 0) {
       diagnostics.push({
         code: 'PSL_ORPHANED_BACKRELATION',
-        message: `Backrelation list field "${candidate.modelName}.${candidate.fieldName}" 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.`,
+        message: `Backrelation list field "${candidate.modelName}.${candidate.fieldName}" has no matching FK-side relation on model "${candidate.targetModelName}". Add @relation(from: [...], to: [...]) on the FK-side relation or use an explicit join model for many-to-many.`,
         sourceId,
         span: candidate.field.span,
       });
diff --git a/packages/2-mongo-family/2-authoring/contract-psl/src/psl-helpers.ts b/packages/2-mongo-family/2-authoring/contract-psl/src/psl-helpers.ts
diff --git a/packages/2-mongo-family/2-authoring/contract-psl/test/interpreter.test.ts b/packages/2-mongo-family/2-authoring/contract-psl/test/interpreter.test.ts
diff --git a/test/integration/test/authoring/side-by-side/mongo/contract.prisma b/test/integration/test/authoring/side-by-side/mongo/contract.prisma
diff --git a/test/integration/test/cli.emit-command.additional.test.ts b/test/integration/test/cli.emit-command.additional.test.ts

Original file line number	Diff line number	Diff line change
`@@ -24,7 +24,7 @@ model Post {`
`24`	`24`	`kind String`
`25`	`25`	`authorId ObjectId`
`26`	`26`	`createdAt DateTime`
`27`		`- author User @relation(fields: [authorId], references: [id])`
	`27`	`+ author User @relation(from: [authorId], to: [id])`
`28`	`28`	`@@discriminator(kind)`
`29`	`29`	`@@map("posts")`
`30`	`30`	`}`
Original file line number	Diff line number	Diff line change
`@@ -32,7 +32,7 @@ model Post {`
`32`	`32`	`kind String`
`33`	`33`	`authorId ObjectId`
`34`	`34`	`createdAt DateTime`
`35`		`- author User @relation(fields: [authorId], references: [id])`
	`35`	`+ author User @relation(from: [authorId], to: [id])`
`36`	`36`	`@@discriminator(kind)`
`37`	`37`	`@@map("posts")`
`38`	`38`	`}`
Original file line number	Diff line number	Diff line change
`@@ -150,7 +150,7 @@ model Post {`
`150`	`150`	`id ObjectId @id @map("_id")`
`151`	`151`	`title String`
`152`	`152`	`content String?`
`153`		`- author User @relation(fields: [authorId], references: [id])`
	`153`	`+ author User @relation(from: [authorId], to: [id])`
`154`	`154`	`authorId ObjectId`
`155`	`155`	`@@map("posts")`
`156`	`156`	`}`
Original file line number	Diff line number	Diff line change
`@@ -247,7 +247,7 @@ model Post {`
`247`	`247`	`id ObjectId @id @map("_id")`
`248`	`248`	`title String`
`249`	`249`	`content String?`
`250`		`- author User @relation(fields: [authorId], references: [id])`
	`250`	`+ author User @relation(from: [authorId], to: [id])`
`251`	`251`	`authorId ObjectId`
`252`	`252`	`@@map("posts")`
`253`	`253`	`}`