@suss/contract-prisma 0.22.3 → 0.23.0

package/README.md

@@ -16,13 +16,20 @@ The behavior is in `metadata.storageContract`:
 
 - `fieldSet: "exhaustive"`. A Prisma model declares every column its table has, so a column the code touches and this list leaves out is unknown rather than merely unlisted.
 - `fields`, one entry per column, with the Prisma type, whether the field is optional (`nullable`), and `primary` / `unique` from the `@id` and `@unique` field attributes. Scalar fields (`Int`, `BigInt`, `Float`, `Decimal`, `String`, `Boolean`, `DateTime`, `Json`, `Bytes`) and enum fields are columns.
-- Relation fields also appear, marked `derived`, because the Prisma client accepts them in an `include` or a `select` even though no column of that name exists. Leaving them out of a contract that calls itself exhaustive would report working code as reading an undeclared field. When the model stores the foreign key, the columns listed in `@relation(fields: [...])` come along as `relationKey`. Prisma allows that argument on one side of a relation only, so the other side and every implicit many-to-many have no key: connecting a row there changes a join-table entry rather than a column of this model.
+- Relation fields also appear, marked `derived`, because the Prisma client accepts them in an `include` or a `select` even though no column of that name exists. Leaving them out of a contract that calls itself exhaustive would report working code as reading an undeclared field. When the model stores the foreign key, the columns listed in `@relation(fields: [...])` come along as `relationKey`. Prisma allows that argument on one side of a relation only, so the other side and every implicit many-to-many have no key.
+- A many-to-many relation with no explicit join model gets a `joinContainer` entry instead, saying which table Prisma manages for it. See below.
 - A model with any relation also gets a derived `_count` entry, which is what the client exposes for relation counts.
 - `indexes`, from `@@index([...])` (not unique), `@@unique([...])`, and `@@id([...])` (both unique).
 - `physicalTable`, when `@@map("...")` gives the table a SQL name different from the model name. That is the bridge to code speaking SQL names directly, such as Drizzle's `pgTable("users")` or a raw query.
 
 These summaries have no inputs and no transitions. A table is a shape the code agrees with, not a function that returns something. Confidence is `declared` at `high`, since the schema says all of this outright.
 
+### Implicit many-to-many join tables
+
+Two list fields pointing at each other with neither side declaring `@relation(fields: [...])` are Prisma's implicit many-to-many: Prisma creates and manages the join table itself, and the schema never declares a model for it. This reader emits a summary for that table too, with the boundary Prisma would create: container `_Name` when the fields carry `@relation("Name")`, or `_FirstToSecond` with the two model names in alphabetical order otherwise, and two columns, `A` and `B`, keyed to whichever model sorts first and second. Each side of the relation gets `joinContainer` set to that table's own container name, so a `connect`, `disconnect` or `set` through the field counts as a write there instead of going unrecorded.
+
+An explicit join model, the kind written out by hand to carry extra columns, already has a boundary through the ordinary model path above and gets none of this.
+
 ## What it does not read
 
 - **Non-relational providers.** A MongoDB schema comes back empty; document storage semantics are separate work.

package/dist/index.cjs

@@ -85,6 +85,21 @@ function prismaSchemaToSummaries(source, options = {}) {
   const sourceFile = options.source ?? "schema.prisma";
   const scope = options.scope ?? "default";
   const summaries = [];
+  const models = list.filter(
+    (node) => node.type === "model"
+  );
+  const relations = implicitManyToManyRelations(models, modelNames);
+  const joinContainerByField = /* @__PURE__ */ new Map();
+  for (const relation of relations) {
+    joinContainerByField.set(
+      `${relation.leftModel}.${relation.leftField}`,
+      relation.joinTable
+    );
+    joinContainerByField.set(
+      `${relation.rightModel}.${relation.rightField}`,
+      relation.joinTable
+    );
+  }
   for (const node of list) {
     const n = node;
     if (n.type !== "model" && n.type !== "view") {
@@ -98,12 +113,132 @@ function prismaSchemaToSummaries(source, options = {}) {
         enumNames,
         storageSystem,
         scope,
-        sourceFile
+        sourceFile,
+        joinContainerByField
       })
     );
   }
+  for (const relation of relations) {
+    summaries.push(
+      buildJoinTableSummary({ relation, storageSystem, scope, sourceFile })
+    );
+  }
   return summaries;
 }
+function implicitManyToManyRelations(models, modelNames) {
+  const byName = new Map(models.map((model) => [model.name, model]));
+  const found = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const model of models) {
+    for (const property of model.properties) {
+      if (property.type !== "field") {
+        continue;
+      }
+      const field = property;
+      if (field.array !== true || !modelNames.has(field.fieldType) || relationKeyOf(field) !== null) {
+        continue;
+      }
+      const target = byName.get(field.fieldType);
+      if (target === void 0) {
+        continue;
+      }
+      const relationName = relationNameOf(field);
+      const counterpart = counterpartField(
+        target,
+        model.name,
+        field.name,
+        relationName
+      );
+      if (counterpart === null) {
+        continue;
+      }
+      const signature = pairSignature(
+        { model: model.name, field: field.name },
+        { model: field.fieldType, field: counterpart.name }
+      );
+      if (seen.has(signature)) {
+        continue;
+      }
+      seen.add(signature);
+      found.push({
+        leftModel: model.name,
+        leftField: field.name,
+        rightModel: field.fieldType,
+        rightField: counterpart.name,
+        relationName,
+        joinTable: joinTableName(model.name, field.fieldType, relationName)
+      });
+    }
+  }
+  return found;
+}
+function counterpartField(target, backTo, ownFieldName, relationName) {
+  for (const property of target.properties) {
+    if (property.type !== "field") {
+      continue;
+    }
+    const field = property;
+    if (target.name === backTo && field.name === ownFieldName) {
+      continue;
+    }
+    if (field.array === true && field.fieldType === backTo && relationKeyOf(field) === null && relationNameOf(field) === relationName) {
+      return field;
+    }
+  }
+  return null;
+}
+function pairSignature(a, b) {
+  const label = (side) => `${side.model}.${side.field}`;
+  return [label(a), label(b)].sort().join("|");
+}
+function joinTableName(leftModel, rightModel, relationName) {
+  if (relationName !== null) {
+    return `_${relationName}`;
+  }
+  const [first, second] = [leftModel, rightModel].sort();
+  return `_${first}To${second}`;
+}
+function buildJoinTableSummary(opts) {
+  const [modelA, modelB] = [
+    opts.relation.leftModel,
+    opts.relation.rightModel
+  ].sort();
+  return {
+    kind: "library",
+    location: {
+      file: opts.sourceFile,
+      range: { start: 1, end: 1 },
+      exportName: null
+    },
+    identity: {
+      name: opts.relation.joinTable,
+      exportPath: null,
+      boundaryBinding: (0, import_behavioral_ir.storageBinding)({
+        recognition: "prisma",
+        storageSystem: opts.storageSystem,
+        scope: opts.scope,
+        container: opts.relation.joinTable
+      })
+    },
+    inputs: [],
+    transitions: [],
+    gaps: [],
+    confidence: { source: "declared", level: "high" },
+    metadata: {
+      storageContract: {
+        fieldSet: "exhaustive",
+        fields: [
+          { name: "A", type: modelA, nullable: false, primary: true },
+          { name: "B", type: modelB, nullable: false, primary: true }
+        ],
+        indexes: [
+          { fields: ["A", "B"], unique: true },
+          { fields: ["B"], unique: false }
+        ]
+      }
+    }
+  };
+}
 function prismaSchemaFileToSummaries(schemaPath, options = {}) {
   if (!import_node_fs.default.existsSync(schemaPath)) {
     throw new Error(`Prisma schema not found: ${schemaPath}`);
@@ -126,7 +261,8 @@ function buildModelSummary(opts) {
       if (column !== null) {
         columns.push(column);
       }
-      const related = relationField(field, opts.modelNames);
+      const joinContainer = opts.joinContainerByField.get(`${opts.model.name}.${field.name}`) ?? null;
+      const related = relationField(field, opts.modelNames, joinContainer);
       if (related !== null) {
         hasRelation = true;
         columns.push(related);
@@ -180,7 +316,7 @@ function buildModelSummary(opts) {
     }
   };
 }
-function relationField(field, modelNames) {
+function relationField(field, modelNames, joinContainer) {
   if (!modelNames.has(field.fieldType)) {
     return null;
   }
@@ -190,15 +326,21 @@ function relationField(field, modelNames) {
     type: field.array === true ? `${field.fieldType}[]` : field.fieldType,
     nullable: field.optional === true,
     derived: true,
-    ...key === null ? {} : { relationKey: key }
+    ...key === null ? {} : { relationKey: key },
+    ...joinContainer === null ? {} : { joinContainer }
   };
 }
+function relationAttributeOf(field) {
+  return (field.attributes ?? []).find((attr) => attr.name === "relation");
+}
 function relationKeyOf(field) {
-  const relation = (field.attributes ?? []).find(
-    (attr) => attr.name === "relation"
-  );
+  const relation = relationAttributeOf(field);
   return relation === void 0 ? null : readKeyedArrayArg(relation, "fields");
 }
+function relationNameOf(field) {
+  const relation = relationAttributeOf(field);
+  return relation === void 0 ? null : readStringArg(relation);
+}
 function fieldToColumn(field, modelNames, enumNames) {
   if (field.array === true) {
     return null;

package/dist/index.js

@@ -50,6 +50,21 @@ function prismaSchemaToSummaries(source, options = {}) {
   const sourceFile = options.source ?? "schema.prisma";
   const scope = options.scope ?? "default";
   const summaries = [];
+  const models = list.filter(
+    (node) => node.type === "model"
+  );
+  const relations = implicitManyToManyRelations(models, modelNames);
+  const joinContainerByField = /* @__PURE__ */ new Map();
+  for (const relation of relations) {
+    joinContainerByField.set(
+      `${relation.leftModel}.${relation.leftField}`,
+      relation.joinTable
+    );
+    joinContainerByField.set(
+      `${relation.rightModel}.${relation.rightField}`,
+      relation.joinTable
+    );
+  }
   for (const node of list) {
     const n = node;
     if (n.type !== "model" && n.type !== "view") {
@@ -63,12 +78,132 @@ function prismaSchemaToSummaries(source, options = {}) {
         enumNames,
         storageSystem,
         scope,
-        sourceFile
+        sourceFile,
+        joinContainerByField
       })
     );
   }
+  for (const relation of relations) {
+    summaries.push(
+      buildJoinTableSummary({ relation, storageSystem, scope, sourceFile })
+    );
+  }
   return summaries;
 }
+function implicitManyToManyRelations(models, modelNames) {
+  const byName = new Map(models.map((model) => [model.name, model]));
+  const found = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const model of models) {
+    for (const property of model.properties) {
+      if (property.type !== "field") {
+        continue;
+      }
+      const field = property;
+      if (field.array !== true || !modelNames.has(field.fieldType) || relationKeyOf(field) !== null) {
+        continue;
+      }
+      const target = byName.get(field.fieldType);
+      if (target === void 0) {
+        continue;
+      }
+      const relationName = relationNameOf(field);
+      const counterpart = counterpartField(
+        target,
+        model.name,
+        field.name,
+        relationName
+      );
+      if (counterpart === null) {
+        continue;
+      }
+      const signature = pairSignature(
+        { model: model.name, field: field.name },
+        { model: field.fieldType, field: counterpart.name }
+      );
+      if (seen.has(signature)) {
+        continue;
+      }
+      seen.add(signature);
+      found.push({
+        leftModel: model.name,
+        leftField: field.name,
+        rightModel: field.fieldType,
+        rightField: counterpart.name,
+        relationName,
+        joinTable: joinTableName(model.name, field.fieldType, relationName)
+      });
+    }
+  }
+  return found;
+}
+function counterpartField(target, backTo, ownFieldName, relationName) {
+  for (const property of target.properties) {
+    if (property.type !== "field") {
+      continue;
+    }
+    const field = property;
+    if (target.name === backTo && field.name === ownFieldName) {
+      continue;
+    }
+    if (field.array === true && field.fieldType === backTo && relationKeyOf(field) === null && relationNameOf(field) === relationName) {
+      return field;
+    }
+  }
+  return null;
+}
+function pairSignature(a, b) {
+  const label = (side) => `${side.model}.${side.field}`;
+  return [label(a), label(b)].sort().join("|");
+}
+function joinTableName(leftModel, rightModel, relationName) {
+  if (relationName !== null) {
+    return `_${relationName}`;
+  }
+  const [first, second] = [leftModel, rightModel].sort();
+  return `_${first}To${second}`;
+}
+function buildJoinTableSummary(opts) {
+  const [modelA, modelB] = [
+    opts.relation.leftModel,
+    opts.relation.rightModel
+  ].sort();
+  return {
+    kind: "library",
+    location: {
+      file: opts.sourceFile,
+      range: { start: 1, end: 1 },
+      exportName: null
+    },
+    identity: {
+      name: opts.relation.joinTable,
+      exportPath: null,
+      boundaryBinding: storageBinding({
+        recognition: "prisma",
+        storageSystem: opts.storageSystem,
+        scope: opts.scope,
+        container: opts.relation.joinTable
+      })
+    },
+    inputs: [],
+    transitions: [],
+    gaps: [],
+    confidence: { source: "declared", level: "high" },
+    metadata: {
+      storageContract: {
+        fieldSet: "exhaustive",
+        fields: [
+          { name: "A", type: modelA, nullable: false, primary: true },
+          { name: "B", type: modelB, nullable: false, primary: true }
+        ],
+        indexes: [
+          { fields: ["A", "B"], unique: true },
+          { fields: ["B"], unique: false }
+        ]
+      }
+    }
+  };
+}
 function prismaSchemaFileToSummaries(schemaPath, options = {}) {
   if (!fs.existsSync(schemaPath)) {
     throw new Error(`Prisma schema not found: ${schemaPath}`);
@@ -91,7 +226,8 @@ function buildModelSummary(opts) {
       if (column !== null) {
         columns.push(column);
       }
-      const related = relationField(field, opts.modelNames);
+      const joinContainer = opts.joinContainerByField.get(`${opts.model.name}.${field.name}`) ?? null;
+      const related = relationField(field, opts.modelNames, joinContainer);
       if (related !== null) {
         hasRelation = true;
         columns.push(related);
@@ -145,7 +281,7 @@ function buildModelSummary(opts) {
     }
   };
 }
-function relationField(field, modelNames) {
+function relationField(field, modelNames, joinContainer) {
   if (!modelNames.has(field.fieldType)) {
     return null;
   }
@@ -155,15 +291,21 @@ function relationField(field, modelNames) {
     type: field.array === true ? `${field.fieldType}[]` : field.fieldType,
     nullable: field.optional === true,
     derived: true,
-    ...key === null ? {} : { relationKey: key }
+    ...key === null ? {} : { relationKey: key },
+    ...joinContainer === null ? {} : { joinContainer }
   };
 }
+function relationAttributeOf(field) {
+  return (field.attributes ?? []).find((attr) => attr.name === "relation");
+}
 function relationKeyOf(field) {
-  const relation = (field.attributes ?? []).find(
-    (attr) => attr.name === "relation"
-  );
+  const relation = relationAttributeOf(field);
   return relation === void 0 ? null : readKeyedArrayArg(relation, "fields");
 }
+function relationNameOf(field) {
+  const relation = relationAttributeOf(field);
+  return relation === void 0 ? null : readStringArg(relation);
+}
 function fieldToColumn(field, modelNames, enumNames) {
   if (field.array === true) {
     return null;

package/package.json

@@ -1,15 +1,16 @@
 {
   "name": "@suss/contract-prisma",
-  "version": "0.22.3",
+  "version": "0.23.0",
   "type": "module",
-  "description": "Generate suss behavioral summaries from Prisma schema declarations.",
+  "description": "Turn a Prisma schema into a suss contract and check it against the queries your code runs on those tables.",
   "keywords": [
     "suss",
-    "behavioral-summary",
+    "static-analysis",
     "prisma",
     "orm",
-    "storage",
-    "contract"
+    "database",
+    "api-contract",
+    "api-drift"
   ],
   "license": "Apache-2.0",
   "author": "Nimbus Cloud AI LLC",
@@ -47,7 +48,7 @@
   },
   "dependencies": {
     "@mrleebo/prisma-ast": "^0.15.0",
-    "@suss/behavioral-ir": "0.22.3"
+    "@suss/behavioral-ir": "0.23.0"
   },
   "devDependencies": {
     "tsup": "*",