@aventara/prisma7-adapter 0.1.0-pilot.0

package/dist/discovery/schema-facts.interface.d.ts

@@ -0,0 +1,174 @@
+/**
+ * T-3, source **PSL** — the output of the bounded `schema.prisma` reader.
+ *
+ * Nothing here is imported from `@prisma/client`: these are this adapter's own
+ * facts over schema text, which is what keeps discovery a pure function of plain
+ * data and unit-testable without a generated client (T-3).
+ *
+ * Read `schema.reader.ts`'s header for the boundary these facts are drawn on:
+ * the reader **locates** tokens and never **evaluates** them.
+ */
+import type { PrismaReferentialAction } from "./discovery-artifact.interface.js";
+/** Where a fact — or an unhandled construct — was found. One-based lines, as `prisma validate` reports them. */
+export type PrismaSchemaSite = {
+    /** The schema file as the caller named it; a folder read names each member file (D-802, Prisma 7 folders). */
+    readonly file: string;
+    readonly line: number;
+};
+/**
+ * A construct the reader **does not recognise at all** — bucket 3 of the reader's
+ * three-way classification: a `type`/`view` block, an unrecognised `@relation`
+ * argument, or any attribute spelling added after 7.10.0.
+ *
+ * `@map`, `@@map`, `@@index` and `@@id`/`@@unique`'s `map:` are **not** here: they
+ * are recognised and deliberately discarded (bucket 2, the reader's explicit
+ * `DISCARDED_ATTRIBUTES` list), because their values appear nowhere on the 🟢
+ * generated surface. Recording them would fail the generate step on any schema
+ * that maps a column name. `name:` is **not** discarded — see
+ * {@link PrismaSchemaBlockIdentifier}.
+ *
+ * Bucket 3 is recorded rather than dropped because silently dropping an
+ * unrecognised attribute is how a grammar change becomes wrong output instead of
+ * a build stop. A non-empty `PrismaSchemaFacts.unhandled` FAILS the generate step
+ * (T-3.1 invariant 5).
+ */
+export type PrismaSchemaUnknown = {
+    readonly kind: PrismaSchemaUnknownKind;
+    /** The construct's spelling as PSL writes it: `@map`, `@@index`, `view`, `onDelete`. */
+    readonly spelling: string;
+    /** The whole construct as written, comments already removed. Opaque text; never parsed. */
+    readonly text: string;
+    /** The enclosing block's name, or `null` at the top level. */
+    readonly block: string | null;
+    readonly site: PrismaSchemaSite;
+};
+export type PrismaSchemaUnknownKind = 
+/** An `@…` on a field declaration. */
+"field-attribute"
+/** An `@@…` on its own line inside a block. */
+ | "block-attribute"
+/** A named argument of a recognised attribute that the reader neither models nor deliberately discards. */
+ | "attribute-argument"
+/** A top-level block whose keyword is neither `model`, `enum`, `generator` nor `datasource`. */
+ | "block"
+/** A line the reader could not classify at all. */
+ | "line";
+export type PrismaSchemaFacts = {
+    readonly enums: readonly PrismaSchemaEnum[];
+    readonly models: readonly PrismaSchemaModel[];
+    /** Attributes and blocks the reader does not recognise at all (a `type`/`view` block, an
+     *  unrecognised argument, any spelling added after 7.10.0). `@map`/`@@map`/`@@index` are
+     *  recognised and deliberately discarded instead, so they never appear here.
+     *  Never silently dropped: a non-empty list FAILS the generate step (T-3.1 invariant 5). */
+    readonly unhandled: readonly PrismaSchemaUnknown[];
+};
+export type PrismaSchemaEnum = {
+    readonly name: string;
+    /** Declaration order is semantic (§19.2); a member-level `@map` is discarded (bucket 2), not recorded. */
+    readonly values: readonly string[];
+    readonly site: PrismaSchemaSite;
+};
+/**
+ * A block-level uniqueness criterion — `@@id([…])` or `@@unique([…])` — as PSL
+ * states it: the members in **the attribute's own order**, and `name:`'s value
+ * when the attribute carries one.
+ *
+ * `name:` is carried rather than discarded because bucket 2's rule is that an
+ * attribute argument is discardable **iff its value appears nowhere on the 🟢
+ * surface**, and this one appears there twice. Measured at 7.10.0 (regenerated
+ * 2026-09-29): `@@unique([b, a], name: "altKey")` emits
+ * `altKey?: Prisma.NamedUniqueAltKeyCompoundUniqueInput` in `WhereUniqueInput`
+ * and keys `}, "id" | "altKey">`, and `@@id([a, b], name: "pk")` keys `}, "pk">`
+ * — the custom name **replaces** the positional `b_a` / `a_b` alias. `map:` does
+ * stay discarded: `named_idx` appears in the whole generated tree only in the 🛑
+ * `internal/class.ts` inline-schema blob.
+ *
+ * The list itself is read from the positional argument or from `fields:`,
+ * whichever the schema writes, and in whatever order the other arguments follow:
+ * `@@unique([b, a])`, `@@unique(fields: [b, a])` and
+ * `@@unique(name: "k", map: "m", fields: [b, a])` are all valid at 7.10.0 and the
+ * first two produce the identical generated key `b_a`.
+ *
+ * `null` means the attribute wrote no `name:`, not "the positional form": the
+ * positional key is derivable from `members`, and a name is derivable from
+ * nothing, so only the undecidable half is recorded. What derives the addressing
+ * key from the pair is `identifier.mapper.ts`.
+ */
+export type PrismaSchemaBlockIdentifier = {
+    /** Member order as written in the attribute's list. Never sorted. */
+    readonly members: readonly string[];
+    /** `name:`'s value, or `null` when the attribute wrote none. */
+    readonly name: string | null;
+};
+export type PrismaSchemaModel = {
+    readonly name: string;
+    readonly fields: readonly PrismaSchemaField[];
+    /** `@@id([…])` — members as written in the attribute's list, plus its `name:`. */
+    readonly blockId: PrismaSchemaBlockIdentifier | null;
+    /** `@@unique([…])` — members as written in the attribute's list, never the field order. */
+    readonly blockUniques: readonly PrismaSchemaBlockIdentifier[];
+    /** `@@ignore` */
+    readonly ignored: boolean;
+    readonly site: PrismaSchemaSite;
+};
+export type PrismaSchemaField = {
+    readonly name: string;
+    /** A built-in scalar, an enum name, or a model name. Which one it is, is not PSL's to say. */
+    readonly type: string;
+    /** `[]` */
+    readonly list: boolean;
+    /** `?` — the ONLY source of nullability (T-3.1 invariant 4). */
+    readonly optional: boolean;
+    /** `@id` */
+    readonly id: boolean;
+    /** `@unique` */
+    readonly unique: boolean;
+    /** `@updatedAt` */
+    readonly updatedAt: boolean;
+    /** `@default(…)`'s argument as RAW TEXT — matched against a table, never parsed (T-3.1 invariant 5). */
+    readonly defaultArgument: string | null;
+    readonly relation: PrismaSchemaRelation | null;
+    /**
+     * `@db.*` as written, e.g. `@db.Decimal(10, 2)`. Kept verbatim and never
+     * parsed. A native type is the **only** proof discovery accepts for
+     * `format` (C-809, spec §6.1 "when the adapter can prove the format");
+     * configuration may then override it, since `AdapterScalarField.format`
+     * and `FrameworkScalarFieldConfig.format` are separate members the
+     * compiler layers.
+     */
+    readonly native: readonly string[];
+    /** `@ignore` */
+    readonly ignored: boolean;
+    readonly site: PrismaSchemaSite;
+};
+export type PrismaSchemaRelation = {
+    /** `@relation("Name")` — the ONLY evidence pairing a back-reference with its forward reference. */
+    readonly name: string | null;
+    /** The FK scalar(s); read, used, then discarded (C-813). */
+    readonly fields: readonly string[] | null;
+    readonly references: readonly string[] | null;
+    /**
+     * `@relation(onDelete: …)`, in Aventara's words, **already resolved**: an
+     * absent argument carries Prisma's effective default rather than a third
+     * state, because an absent action and the explicitly-written default are one
+     * fact about what a delete does.
+     *
+     * `null` means **this edge is not the owning side** — it declares no
+     * `fields:`, so no foreign key and no action belong to it. PSL enforces that
+     * itself: `prisma validate` 7.10.0 answers *"The relation field `reqs` on
+     * Model `Alpha` must not specify the `onDelete` or `onUpdate` argument in the
+     * @relation attribute. You must only specify it on the opposite field `alpha`
+     * on model `Req`"*. `null` therefore reads as "ask the other edge", never as
+     * "no action applies". It is also what an unreadable action spelling leaves
+     * behind, and that case is recorded in `unhandled` and fails the generate
+     * step, so no consumer sees it.
+     *
+     * The inversion matters to every consumer: the action is declared on the
+     * CHILD and fires when the PARENT is deleted. Read with
+     * `PrismaSchemaField.type` — the target model — one owning edge says
+     * "deleting a `<type>` does `<onDelete>` to a row of the enclosing model".
+     */
+    readonly onDelete: PrismaReferentialAction | null;
+    /** `@relation(onUpdate: …)`, resolved the same way. Read independently of `onDelete`. */
+    readonly onUpdate: PrismaReferentialAction | null;
+};

package/dist/discovery/schema-facts.interface.js

@@ -0,0 +1,11 @@
+/**
+ * T-3, source **PSL** — the output of the bounded `schema.prisma` reader.
+ *
+ * Nothing here is imported from `@prisma/client`: these are this adapter's own
+ * facts over schema text, which is what keeps discovery a pure function of plain
+ * data and unit-testable without a generated client (T-3).
+ *
+ * Read `schema.reader.ts`'s header for the boundary these facts are drawn on:
+ * the reader **locates** tokens and never **evaluates** them.
+ */
+export {};

package/dist/discovery/schema.reader.d.ts

@@ -0,0 +1,162 @@
+import type { PrismaSchemaFacts } from "./schema-facts.interface.js";
+/**
+ * T-3, source **PSL** — the bounded `schema.prisma` reader.
+ *
+ * # The boundary, and why this file is a reader and not a parser
+ *
+ * It **locates** tokens and never **evaluates** them.
+ *
+ * PSL's model body is line-oriented by the language's own rule, not by this
+ * reader's assumption. Re-measured against `prisma` 7.10.0 on 2026-09-28, all
+ * four constructs that would let a declaration legally span lines are
+ * **rejected** with `Error code: P1012` — so the classic regex-parser failure
+ * cannot occur:
+ *
+ * 1. a wrapped `@@unique([…])` — the error COUNT is layout-dependent, the
+ *    rejection is not. A two-line wrap (`@@unique([x,` / `y])`) gives 2 errors,
+ *    both `error: Error validating: This line is not a valid field or attribute
+ *    definition.`; a four-line wrap gives 4 — three of that sentence plus one
+ *    `Error validating model "A": This field declaration is invalid. It is
+ *    either missing a name or a type.`
+ * 2. a wrapped field attribute (`@default(uuid())` on the line below `id String @id`)
+ *    — 1 error, `This line is not a valid field or attribute definition.`
+ * 3. two block attributes on one line (`@@unique([x]) @@index([y])`) — 1 error,
+ *    `This line is not a valid field or attribute definition.`
+ * 4. a split field declaration (`id` then `String @id`) — 2 errors, **both**
+ *    `Error validating model "A": This field declaration is invalid. It is either
+ *    missing a name or a type.`
+ *
+ * **Correction to the plan's wording (2026-09-28, re-measured, not inherited).**
+ * The plan and T-3 previously said all four are rejected *with* `P1012 … This
+ * line is not a valid field or attribute definition`. All four are indeed
+ * `P1012`, **and the line-oriented conclusion holds unchanged** — the design did
+ * not move. But case 4 never emits that sentence at all (it emits *"This field
+ * declaration is invalid. It is either missing a name or a type."* twice), and
+ * case 1 emits a second, different sentence besides it. The evidence supports the
+ * rule; the single-sentence attribution does not, and the plan now says so.
+ *
+ * Re-running it: `prisma` lives at `packages/prisma7-adapter/node_modules/.bin/
+ * prisma`, not the worktree root. Invoked from the root it silently produces no
+ * output, which looks exactly like "no errors".
+ *
+ * # What crossing the boundary would mean
+ *
+ * The day this reader **evaluates** — resolving `env()`, interpreting
+ * `dbgenerated(…)`, modelling `type`/`view` blocks, following `@@schema`, or
+ * reconstructing relations without `@relation` names — it has become a parser and
+ * needs a different decision. Hence:
+ *
+ * - `@default`'s argument is kept as **raw text** and matched against a table
+ *   downstream, never parsed (T-3.1 invariant 5).
+ * - `@db.*` is kept **as written** and never parsed. It is the only proof
+ *   discovery accepts for `format` (C-809); configuration overrides it later.
+ * - a field's `type` stays the written token — `Grade` is not resolved to the
+ *   enum, which is also why a schema **folder** needs no linker (below).
+ * - an attribute is classified three ways, not two (below), and only the third
+ *   class is recorded in `unhandled`. A non-empty `unhandled` fails the generate
+ *   step: silently dropping an **unrecognised** attribute is how a grammar change
+ *   becomes wrong output instead of a build stop. The version fence is what
+ *   converts a grammar change from silent wrongness into a build stop.
+ *
+ * # The three-way classification (corrected 2026-09-28)
+ *
+ * 1. **recognised and modelled** — `FIELD_ATTRIBUTES`, `BLOCK_ATTRIBUTES`,
+ *    `@db.*` and `RELATION_ARGUMENTS`.
+ * 2. **recognised and deliberately discarded**, via the explicit
+ *    `DISCARDED_ATTRIBUTES` / `DISCARDED_BLOCK_ATTRIBUTE_ARGUMENTS` lists —
+ *    `@map`, `@@map`, `@@index`, and `@@id`/`@@unique`'s `map:` argument. The
+ *    rule is one line long: an argument is discardable **iff its value appears
+ *    nowhere on the 🟢 surface**. The list being explicit is the point: the
+ *    discard is a decision a reader can see and audit, not an omission. That
+ *    rule is also what took `name:` back OFF this list (2026-09-29): its value
+ *    is a `WhereUniqueInput` key and an `AtLeast` key, so it is carried on
+ *    `PrismaSchemaBlockIdentifier`.
+ * 3. **unrecognised** — on neither list, therefore `unhandled`, therefore a build
+ *    stop.
+ *
+ * # Surface-invisibility was EVIDENCE, not the meaning (2026-09-29)
+ *
+ * Bucket 2's rule reads "discardable iff the value appears nowhere on the 🟢
+ * surface", and `@relation(onDelete: Cascade)` passes that test: measured at
+ * 7.10.0, `Cascade` reaches nothing but the 🛑 `internal/class.ts` inline-schema
+ * blob. It is still **not** discardable, and this is the first construct where
+ * the test and the rule it stands for come apart.
+ *
+ * The rule's *reason* was that such attributes configure the database below the
+ * ORM entrypoint and therefore carry no framework meaning. A referential action
+ * fails that reason while passing the test: it changes what a delete **does** —
+ * rows disappear that the caller never named — which is exactly what a
+ * transaction planner must reason about before it agrees to run a plan. So
+ * invisibility on the generated types is *evidence* for "no framework meaning",
+ * and evidence can be outweighed; it was never the meaning itself. `@map` and
+ * `@@index` remain discarded because they fail the test AND the reason.
+ * `@relation`'s `map:` joins them: a foreign-key constraint name is genuinely
+ * DB-side, and it was bucket 3 until now, which made `@relation(map: …)` — valid
+ * PSL — a build stop on its own.
+ *
+ * Actions are read on both arguments and carried **resolved**: an absent
+ * argument is not a third state, it is Prisma's effective default, measured
+ * rather than assumed (see `REFERENTIAL_ACTIONS` and
+ * `resolvePrismaReferentialDefaults`).
+ *
+ * Bucket 2 previously did not exist, and a field-level `@map` landed in
+ * `unhandled`: the framework would have refused to build against any schema that
+ * maps a column name, which is most real Prisma schemas. It was invisible only
+ * because both Phase 8 schemas use zero `@map`. The enum **member**-level `@map`
+ * discard, which T-3's `PrismaSchemaEnum` and Task 3's enum-mapper case already
+ * required, folds into bucket 2 and stops being a special case.
+ *
+ * # Arguments are located by NAME, never by position (added 2026-09-29)
+ *
+ * PSL lets the same argument list arrive positionally or named, and lets the
+ * named arguments come in any order. Measured against `prisma validate` 7.10.0
+ * and against a generated client on 2026-09-29: `@@unique([b, a])`,
+ * `@@unique(fields: [b, a])`, `@@unique(name: "k", map: "m", fields: [b, a])`
+ * and every other permutation are accepted, and the client keys the unnamed ones
+ * `b_a` and the named ones `k` regardless of the order they were written in. The
+ * spelling is therefore not a fact about the schema, and a reader that took the
+ * list to be the FIRST argument read `@@unique(fields: [b, a])` as one member
+ * called `fields: [b, a]` — silently, with `unhandled` empty — so the generate
+ * step refused a schema Prisma accepts. ARGUMENT order does not matter; MEMBER
+ * order inside the list still does, because it is part of the identity and of
+ * the addressing key.
+ *
+ * The same rule applies to `@relation`, which mixes a positional argument (the
+ * relation name) with named ones; it was already order-independent and its FK
+ * read was unaffected.
+ *
+ * A list whose members are not plain field names — `@@unique([a(sort: Desc)])`,
+ * valid PSL at 7.10.0 — cannot be located without evaluating, so it is bucket 3
+ * rather than a guess.
+ *
+ * # One deliberate non-recording beyond the buckets
+ *
+ * `generator` and `datasource` block bodies are skipped, not recorded: they are
+ * tooling configuration, not model content, and their contents are exactly what
+ * this reader must not evaluate (`env()` lives there).
+ *
+ * # A schema folder is readdir plus merge
+ *
+ * Prisma 7 accepts a folder (`prisma validate --schema <folder>` verified at
+ * 7.10.0). Blocks are file-local and references are by name, so there is no
+ * cross-file grammar and **no linker**: reading a folder appends each file's
+ * facts in filename order and nothing is rewritten. Every fact keeps the file and
+ * line it was written on.
+ */
+export type PrismaSchemaSource = {
+    readonly file: string;
+    readonly text: string;
+};
+export declare class PrismaSchemaReaderError extends Error {
+    readonly name = "PrismaSchemaReaderError";
+}
+/**
+ * Reads a schema file, or a schema **folder** (Prisma 7 accepts either).
+ * A folder is read as readdir-plus-merge in filename order.
+ */
+export declare function readPrismaSchema(location: string): Promise<PrismaSchemaFacts>;
+/**
+ * The reader proper, over text already in hand. Merging several sources is
+ * concatenation: blocks are file-local and references are by name.
+ */
+export declare function readPrismaSchemaSources(sources: readonly PrismaSchemaSource[]): PrismaSchemaFacts;