@suss/contract-prisma 0.33.0 → 0.34.0

package/README.md

@@ -1,43 +1,43 @@
 # @suss/contract-prisma
 
-Part of [suss](https://github.com/nimbuscloud-ai/suss), which reads both sides of every call in a repository and says where the two disagree.
+Part of [suss](https://github.com/nimbuscloud-ai/suss), which reads both sides of every call in a repository and reports where the two disagree.
 
-Generate suss `BehavioralSummary[]` from a [Prisma](https://www.prisma.io/) schema. A `schema.prisma` file declares every table an application has and every column on it, which is the contract the code reads and writes against. This reader turns that declaration into storage boundaries, so a query touching a column nobody declared becomes a finding.
+This package builds suss `BehavioralSummary[]` from a [Prisma](https://www.prisma.io/) schema. A `schema.prisma` file declares every table an application has and every column on it, and the code reads and writes against that. This reader turns the schema into storage boundaries, so a query that touches a column nobody declared becomes a finding.
 
 ## What this package reads
 
-`@suss/contract-prisma` parses `schema.prisma` with [`@mrleebo/prisma-ast`](https://github.com/MrLeebo/prisma-ast), a parser that does not pull in the Prisma runtime, so reading a schema never requires a generated client or a database connection.
+`@suss/contract-prisma` parses `schema.prisma` with [`@mrleebo/prisma-ast`](https://github.com/MrLeebo/prisma-ast), a parser that does not pull in the Prisma runtime. Reading a schema never needs a generated client or a database connection.
 
-The `datasource` block decides whether anything comes out. A `provider` of `postgresql`, `postgres`, `mysql`, or `sqlite` sets the storage system on every boundary. Any other provider (MongoDB, for instance) returns an empty array, since document semantics are a different boundary kind.
+The `datasource` block decides whether anything comes out. A `provider` of `postgresql`, `postgres`, `mysql` or `sqlite` sets the storage system on every boundary. Any other provider, such as MongoDB, returns an empty array, since document storage is a different kind of boundary.
 
 ## What it produces
 
-One `library`-kind summary per `model` and per `view`, with a storage boundary binding: `recognition: "prisma"`, the storage system from the datasource, a scope, and the model name as the container. The checker's storage pass pairs those against `interaction(class: "storage-access")` effects the adapters find in code. A monorepo with several Prisma schemas should pass a distinct `scope` per schema so pairings stay separate; it defaults to `"default"`.
+One `library`-kind summary per `model` and per `view`, with a storage boundary binding: `recognition: "prisma"`, the storage system from the datasource, a scope, and the model name as the container. The checker's storage pass pairs these with the `interaction(class: "storage-access")` effects the adapters find in code. In a monorepo with several Prisma schemas, pass a different `scope` for each schema so their pairings stay separate. The default is `"default"`.
 
 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.
+- `fieldSet: "exhaustive"`. A Prisma model declares every column its table has, so a column the code touches that is missing from this list is unknown, and not 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.
-- 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.
+- Relation fields appear too, 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 marked exhaustive would report working code as reading an undeclared field. When the model stores the foreign key, the columns listed in `@relation(fields: [...])` are included as `relationKey`. Prisma only allows that argument on one side of a relation, so the other side, and every implicit many-to-many, has no key.
+- A many-to-many relation with no explicit join model gets a `joinContainer` entry instead, which gives the table Prisma manages for it. See below.
+- A model with any relation also gets a derived `_count` entry, since the client exposes relation counts under that name.
+- `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 lets it pair with code that uses 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.
+These summaries have no inputs and no transitions. A table is a set of columns the code has to agree with, and it does not return anything the way a function does. Confidence is `declared` at `high`, since the schema states all of this explicitly.
 
 ### 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.
+When two list fields point at each other and neither side declares `@relation(fields: [...])`, that is 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 produces a summary for that table too, with the boundary Prisma would create. The container is `_Name` when the fields have `@relation("Name")`, and otherwise `_FirstToSecond`, with the two model names in alphabetical order. The table has 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 container name, so a `connect`, `disconnect` or `set` through the field counts as a write there and is not lost.
 
-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.
+An explicit join model, the kind written out by hand to add extra columns, already has a boundary through the ordinary model path above, and none of this applies to it.
 
 ## What it does not read
 
-- **Non-relational providers.** A MongoDB schema comes back empty; document storage semantics are separate work.
-- **Composite types and unsupported field types.** A field whose type is neither a scalar, an enum, nor another model (`Unsupported(...)`, a Mongo composite type, or a typo) is skipped rather than guessed at.
+- **Non-relational providers.** A MongoDB schema comes back empty. Document storage is separate work.
+- **Composite types and unsupported field types.** A field whose type is not a scalar, an enum or another model is skipped, so the reader never guesses. That covers `Unsupported(...)`, a Mongo composite type, and a typo.
 - **Array scalar fields.** `String[]` is dropped along with relation lists, because the walk treats every array field as a relation array.
-- **Native type attributes.** `@db.VarChar(255)` and friends are not recorded; the field's Prisma type is what comes through.
+- **Native type attributes.** `@db.VarChar(255)` and similar are not recorded. The field's Prisma type is what comes through.
 - **`generator` blocks, the datasource URL, and relation cardinality** as behavior of their own.
 
 ## Worked example
@@ -66,7 +66,7 @@ suss check summaries/db.json summaries/app.json
 
 The `User` summary declares `id` (primary), `email` (unique), a nullable `name`, the derived `posts` relation, a derived `_count`, an index on `email`, and `physicalTable: "users"`.
 
-Or programmatically:
+Or from code:
 
 ```ts
 import { prismaSchemaFileToSummaries } from "@suss/contract-prisma";
@@ -78,7 +78,7 @@ const summaries = prismaSchemaFileToSummaries("prisma/schema.prisma", {
 
 ## Where it fits in suss
 
-Depends only on `@suss/behavioral-ir` (for the IR types it produces) and `@mrleebo/prisma-ast` (for parsing). It does not extract from source code and is independent of the language adapters. The Prisma pattern pack is what finds the query call sites this contract pairs against.
+The package depends only on `@suss/behavioral-ir`, for the IR types it produces, and `@mrleebo/prisma-ast`, for parsing. It does not extract from source code and does not use the language adapters. The Prisma pattern pack finds the query call sites that this contract pairs with.
 
 ## More
 

package/dist/index.d.cts

@@ -1,21 +1,32 @@
 import { BehavioralSummary } from '@suss/behavioral-ir';
 
+/**
+ * Reads a Prisma schema into one storage summary per model and view, plus
+ * one per implicit many-to-many join table. The checker's storage pass
+ * pairs these with the `storage-access` interactions found in code.
+ *
+ * `@mrleebo/prisma-ast` parses the schema, so no Prisma runtime or
+ * generated client is needed. A schema whose datasource is not relational,
+ * such as MongoDB, comes back empty. The README lists what else is left out.
+ */
+
 interface PrismaSchemaToSummariesOptions {
-    /** Override the source-file path recorded on each summary. */
+    /** The path recorded on each summary, in place of the default. */
     source?: string;
     /**
-     * Scope identifier: defaults to `"default"` for single-schema
-     * projects. Monorepos with multiple Prisma schemas should pass
-     * distinct values per schema so pairings stay separate.
+     * Defaults to `"default"`. With several Prisma schemas in one repo, give
+     * each its own scope so their pairings stay separate.
      */
     scope?: string;
 }
 /**
- * Convert an in-memory Prisma schema source into `BehavioralSummary[]`.
+ * Converts Prisma schema text into summaries. Returns an empty array when
+ * the datasource is not relational.
  */
 declare function prismaSchemaToSummaries(source: string, options?: PrismaSchemaToSummariesOptions): BehavioralSummary[];
 /**
- * Convert a Prisma schema file on disk into `BehavioralSummary[]`.
+ * Reads a Prisma schema file and converts it. Throws when the file does
+ * not exist.
  */
 declare function prismaSchemaFileToSummaries(schemaPath: string, options?: PrismaSchemaToSummariesOptions): BehavioralSummary[];
 

package/dist/index.d.ts

@@ -1,21 +1,32 @@
 import { BehavioralSummary } from '@suss/behavioral-ir';
 
+/**
+ * Reads a Prisma schema into one storage summary per model and view, plus
+ * one per implicit many-to-many join table. The checker's storage pass
+ * pairs these with the `storage-access` interactions found in code.
+ *
+ * `@mrleebo/prisma-ast` parses the schema, so no Prisma runtime or
+ * generated client is needed. A schema whose datasource is not relational,
+ * such as MongoDB, comes back empty. The README lists what else is left out.
+ */
+
 interface PrismaSchemaToSummariesOptions {
-    /** Override the source-file path recorded on each summary. */
+    /** The path recorded on each summary, in place of the default. */
     source?: string;
     /**
-     * Scope identifier: defaults to `"default"` for single-schema
-     * projects. Monorepos with multiple Prisma schemas should pass
-     * distinct values per schema so pairings stay separate.
+     * Defaults to `"default"`. With several Prisma schemas in one repo, give
+     * each its own scope so their pairings stay separate.
      */
     scope?: string;
 }
 /**
- * Convert an in-memory Prisma schema source into `BehavioralSummary[]`.
+ * Converts Prisma schema text into summaries. Returns an empty array when
+ * the datasource is not relational.
  */
 declare function prismaSchemaToSummaries(source: string, options?: PrismaSchemaToSummariesOptions): BehavioralSummary[];
 /**
- * Convert a Prisma schema file on disk into `BehavioralSummary[]`.
+ * Reads a Prisma schema file and converts it. Throws when the file does
+ * not exist.
  */
 declare function prismaSchemaFileToSummaries(schemaPath: string, options?: PrismaSchemaToSummariesOptions): BehavioralSummary[];
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suss/contract-prisma",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "type": "module",
   "description": "Turn a Prisma schema into a suss contract and check it against the queries your code runs on those tables.",
   "keywords": [
@@ -14,7 +14,7 @@
   ],
   "license": "Apache-2.0",
   "author": "Nimbus Cloud AI LLC",
-  "homepage": "https://github.com/nimbuscloud-ai/suss/tree/main/packages/contract/prisma#readme",
+  "homepage": "https://suss.sh",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nimbuscloud-ai/suss.git",
@@ -48,7 +48,7 @@
   },
   "dependencies": {
     "@mrleebo/prisma-ast": "^0.15.0",
-    "@suss/behavioral-ir": "0.33.0"
+    "@suss/behavioral-ir": "0.34.0"
   },
   "devDependencies": {
     "tsup": "*",