@aventara/prisma7-adapter 0.1.0-pilot.0

package/dist/generate/index.js

@@ -0,0 +1,65 @@
+import { createPrismaModelComposer } from "../discovery/model.discoverer.js";
+import { resolveProviderProfile } from "../provider/provider-profile.js";
+import { runPrismaGenerateStep } from "./prisma.generate.js";
+/**
+ * F-805 — the package's **second published entry**: `@aventara/prisma7-adapter/generate`.
+ *
+ * # Why a second entry rather than a second package or a wider `"."`
+ *
+ * The runtime entry (`"."`) depends on `@aventara/core` and the caller's own
+ * generated client, and on nothing else. The generate path needs `typescript`
+ * (the types reader builds a real TypeScript program over the generated tree) and
+ * `prisma` (the step runs `prisma generate` itself, so that both sources describe
+ * one instant). Those two are declared as **optional peer dependencies**, not as
+ * dependencies, and the split is what keeps the plan's guarantee that *no
+ * compiler, no parser and no Prisma tooling enters the deployed runtime*: a
+ * consumer who imports only `"."` never loads a module that names either, and an
+ * optional peer is not installed on their behalf.
+ *
+ * The published build therefore carries both halves and the `exports` map is what
+ * separates them. Nothing reachable from `"."` imports anything under
+ * `generate/`; `artifact.loader.spec.ts` asserts that from the import graph
+ * rather than from this paragraph.
+ *
+ * # What this entry is for
+ *
+ * Producing the discovery artifact `createPrismaAdapter({ discovery })` requires,
+ * from the consumer's own `schema.prisma` and their own generated client. The
+ * `aventara-prisma7-generate` binary (`discovery.cli.ts`) is this function with an
+ * argument parser in front of it; this module is the same thing for a consumer who
+ * already has a build script and would rather call it.
+ *
+ * Everything the step itself exposes is re-exported, because the seams are the
+ * point: a consumer with an unusual toolchain can supply their own
+ * {@link PrismaGenerateToolchain}, and one with their own composition rules can
+ * call {@link runPrismaGenerateStep} directly.
+ */
+export { createPrismaModelComposer, PrismaModelCompositionError, } from "../discovery/model.discoverer.js";
+export { createPrismaGenerateToolchain, PINNED_PRISMA_MAJOR, PrismaGenerateStepError, runPrismaGenerateStep, } from "./prisma.generate.js";
+/**
+ * The generate step, wired: provider profile → transaction capability →
+ * composition → the step.
+ *
+ * Every decision stays where it already lived. This function resolves the profile
+ * and builds the composer; it makes no judgement of its own, which is why there is
+ * nothing here to test beyond that it is the wiring the CLI and the repository's
+ * own `generate` script both use.
+ */
+export async function generatePrismaDiscoveryArtifact(request) {
+    const profile = resolveProviderProfile({
+        provider: request.provider,
+        driver: request.driver,
+    });
+    return runPrismaGenerateStep({
+        schema: request.schema,
+        clientDirectory: request.clientDirectory,
+        provider: request.provider,
+        artifactFile: request.artifactFile,
+        composeModel: createPrismaModelComposer({
+            transactions: profile.transactions,
+        }),
+        ...(request.toolchain === undefined
+            ? {}
+            : { toolchain: request.toolchain }),
+    });
+}

package/dist/generate/node-version.guard.d.ts

@@ -0,0 +1,8 @@
+/** The sentence a bin answers on `version`, or `undefined` when `range` admits it. */
+export declare function nodeVersionRefusal(bin: string, packageName: string, range: string, version: string): string | undefined;
+/**
+ * Reads the manifest at `manifestUrl`; on a Node its `engines.node` does not
+ * admit, writes the sentence to stderr, sets exit code 1 and answers `true` —
+ * the bin then loads nothing else.
+ */
+export declare function refuseUnsupportedNode(bin: string, manifestUrl: URL): boolean;

package/dist/generate/node-version.guard.js

@@ -0,0 +1,59 @@
+// biome-ignore lint/style/useNodejsImportProtocol: Node 14.0–14.13.0 resolves no "node:" specifier in an ES module, and this module runs on the Nodes the packages do not support.
+import { readFileSync } from "fs";
+function versionOf(text) {
+    const match = /^v?(\d+)\.(\d+)\.(\d+)/.exec(text);
+    if (match === null) {
+        throw new Error(`"${text}" is not a Node version`);
+    }
+    return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+function compareVersions(left, right) {
+    for (let index = 0; index < 3; index += 1) {
+        const difference = left[index] - right[index];
+        if (difference !== 0) {
+            return difference;
+        }
+    }
+    return 0;
+}
+/**
+ * Whether `range` admits `version`. Reads `^x.y.z` (the same major, from the
+ * floor; majors ≥ 1) and `>=x.y.z`, joined by `||`; anything else throws rather
+ * than admit or refuse by guess.
+ */
+function admits(range, version) {
+    return range.split("||").some((part) => {
+        const comparator = /^\s*(\^|>=)(\d+\.\d+\.\d+)\s*$/.exec(part);
+        if (comparator === null) {
+            throw new Error(`engines.node "${range}": the bin's Node guard reads only "^x.y.z" and ">=x.y.z" joined by "||"`);
+        }
+        const floor = versionOf(comparator[2]);
+        return (compareVersions(version, floor) >= 0 &&
+            (comparator[1] === ">=" || version[0] === floor[0]));
+    });
+}
+/** The sentence a bin answers on `version`, or `undefined` when `range` admits it. */
+export function nodeVersionRefusal(bin, packageName, range, version) {
+    return admits(range, versionOf(version))
+        ? undefined
+        : `${bin}: Node ${version} is not supported; ${packageName} needs Node ${range}.`;
+}
+/**
+ * Reads the manifest at `manifestUrl`; on a Node its `engines.node` does not
+ * admit, writes the sentence to stderr, sets exit code 1 and answers `true` —
+ * the bin then loads nothing else.
+ */
+export function refuseUnsupportedNode(bin, manifestUrl) {
+    const manifest = JSON.parse(readFileSync(manifestUrl, "utf8"));
+    const range = manifest.engines === undefined ? undefined : manifest.engines.node;
+    if (range === undefined) {
+        throw new Error(`${manifest.name} declares no engines.node for its bin's Node guard`);
+    }
+    const refusal = nodeVersionRefusal(bin, manifest.name, range, process.version);
+    if (refusal === undefined) {
+        return false;
+    }
+    process.stderr.write(`${refusal}\n`);
+    process.exitCode = 1;
+    return true;
+}

package/dist/generate/prisma-cli.resolver.d.ts

@@ -0,0 +1,48 @@
+/**
+ * D11 — which Prisma CLI the generate step runs.
+ *
+ * `prisma`'s `latest` is a Prisma 8 release candidate (plan B32), so `npm i
+ * prisma` in a Prisma 7 project now installs a CLI this adapter's readers were
+ * never written against. Prisma's own upgrade path keeps the Prisma 7 CLI side by
+ * side as **`@prisma/prisma7`**, bin `prisma7` — the same CLI under a
+ * version-specific name. So, in this order:
+ *
+ * 1. `@prisma/prisma7` installed → its `prisma7` bin runs, provided the `prisma`
+ *    it wraps is in the declared range;
+ * 2. otherwise `prisma`, **only** when its version is in the adapter's declared
+ *    range (`peerDependencies.prisma`, read by the caller);
+ * 3. otherwise a refusal naming both, with the install command.
+ *
+ * # Where it looks
+ *
+ * Each package is looked up first from this module — the adapter's own install,
+ * where an optional peer is linked — and then from the project the step runs in
+ * (its working directory), where a strict installer such as pnpm leaves a
+ * package the adapter does not declare. A found package is followed to its real
+ * path, so the `prisma` that `@prisma/prisma7` wraps is the one beside it and not
+ * a `prisma` 8 hoisted next to the link.
+ */
+export type PrismaCli = {
+    /** The package whose bin runs: `@prisma/prisma7` or `prisma`. */
+    readonly package: "@prisma/prisma7" | "prisma";
+    /** The bin's JavaScript entry, run with the current `node`. */
+    readonly entry: string;
+    /** The `prisma` version that bin is: what the artifact is stamped with. */
+    readonly version: string;
+};
+export type PrismaCliResolution = {
+    readonly kind: "found";
+    readonly cli: PrismaCli;
+} | {
+    readonly kind: "refused";
+    readonly reason: string;
+};
+/**
+ * The Prisma CLI to run, or why there is none. `searchFrom` holds the places to
+ * resolve from, in order — a module URL or a path of a file in the directory to
+ * start from; `range` is the adapter's declared `prisma` range.
+ */
+export declare function resolvePrismaCli(input: {
+    readonly searchFrom: readonly string[];
+    readonly range: string;
+}): PrismaCliResolution;

package/dist/generate/prisma-cli.resolver.js

@@ -0,0 +1,95 @@
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { satisfiesDeclaredRange } from "./declared-support.reader.js";
+/**
+ * The first `node_modules/<name>/package.json` on the way up from each place in
+ * turn — Node's own lookup order, walked by hand because the manifest is all
+ * that is wanted: no `exports` map can hide it, and no `NODE_PATH` can answer
+ * from outside the install (a test runner sets one, and a resolution answered
+ * through it has produced a false green in this package before).
+ */
+function locate(name, searchFrom) {
+    for (const base of searchFrom) {
+        let directory = path.dirname(base.startsWith("file:") ? fileURLToPath(base) : base);
+        for (;;) {
+            if (path.basename(directory) !== "node_modules") {
+                const manifest = path.join(directory, "node_modules", name, "package.json");
+                if (existsSync(manifest)) {
+                    const real = realpathSync(manifest);
+                    return {
+                        directory: path.dirname(real),
+                        manifest: JSON.parse(readFileSync(real, "utf8")),
+                    };
+                }
+            }
+            const parent = path.dirname(directory);
+            if (parent === directory) {
+                break;
+            }
+            directory = parent;
+        }
+    }
+    return undefined;
+}
+function versionOf(located) {
+    return typeof located.manifest.version === "string"
+        ? located.manifest.version
+        : "with no version";
+}
+function binEntry(located, bin) {
+    const declared = located.manifest.bin;
+    const relative = typeof declared === "string"
+        ? declared
+        : typeof declared === "object" && declared !== null
+            ? declared[bin]
+            : undefined;
+    return typeof relative === "string"
+        ? path.join(located.directory, relative)
+        : undefined;
+}
+/**
+ * The Prisma CLI to run, or why there is none. `searchFrom` holds the places to
+ * resolve from, in order — a module URL or a path of a file in the directory to
+ * start from; `range` is the adapter's declared `prisma` range.
+ */
+export function resolvePrismaCli(input) {
+    const install = `\`npm i -D "@prisma/prisma7@${input.range}"\``;
+    const prisma7 = locate("@prisma/prisma7", input.searchFrom);
+    if (prisma7 !== undefined) {
+        // The version is the wrapped CLI's, looked up from beside the wrapper.
+        const wrapped = locate("prisma", [
+            path.join(prisma7.directory, "package.json"),
+        ]);
+        const entry = binEntry(prisma7, "prisma7");
+        const version = wrapped === undefined ? undefined : versionOf(wrapped);
+        if (entry !== undefined &&
+            version !== undefined &&
+            satisfiesDeclaredRange(version, input.range)) {
+            return {
+                kind: "found",
+                cli: { package: "@prisma/prisma7", entry, version },
+            };
+        }
+        return {
+            kind: "refused",
+            reason: `the installed \`@prisma/prisma7\` ${versionOf(prisma7)} does not run a \`prisma\` in this adapter's declared range ${input.range}; install one that does: ${install}.`,
+        };
+    }
+    const prisma = locate("prisma", input.searchFrom);
+    if (prisma === undefined) {
+        return {
+            kind: "refused",
+            reason: `neither \`@prisma/prisma7\` nor \`prisma\` is installed where this adapter can resolve it; install the Prisma 7 CLI in this adapter's declared range ${input.range}: \`npm i -D "prisma@${input.range}"\`, or beside a Prisma 8 install ${install}.`,
+        };
+    }
+    const version = versionOf(prisma);
+    const entry = binEntry(prisma, "prisma");
+    if (!satisfiesDeclaredRange(version, input.range) || entry === undefined) {
+        return {
+            kind: "refused",
+            reason: `the installed \`prisma\` ${version} is outside this adapter's declared range ${input.range}, and \`@prisma/prisma7\` — the Prisma 7 CLI under its own name, bin \`prisma7\` — is not installed beside it; install it: ${install}.`,
+        };
+    }
+    return { kind: "found", cli: { package: "prisma", entry, version } };
+}

package/dist/generate/prisma.generate.d.ts

@@ -0,0 +1,164 @@
+import type { PrismaCapabilitySurface } from "../discovery/capability-surface.interface.js";
+import type { PrismaAdapterModel, PrismaReferentialActionTable, PrismaTranslationTable } from "../discovery/discovery-artifact.interface.js";
+import type { PrismaSchemaFacts } from "../discovery/schema-facts.interface.js";
+import type { PrismaProvider } from "../provider/provider-profile.js";
+import type { PrismaEntityAbsence } from "./existence.gate.js";
+import { type PrismaCli } from "./prisma-cli.resolver.js";
+import type { PrismaReaderExemption } from "./reader-crosscheck.js";
+/**
+ * Task 3 — the adapter's **generate step**: a devDependency-only executable and
+ * the only module that runs `prisma` or spawns a process. Nothing under
+ * `execution/`, and nothing in `discovery/artifact.loader.ts`, imports it; the
+ * package's build `exclude` keeps `src/generate/**` out of `dist` entirely, so
+ * a deployed application never carries `typescript`, a PSL reader or a child
+ * process.
+ *
+ * **The order is fixed, and each step earns its place:**
+ *
+ * 1. **The pinned `prisma` major** (C-846). PSL's grammar and the generated
+ *    client's shape are version-bound; a major this reader has never seen must
+ *    stop the build rather than produce a wrong `AdapterModel` from a grammar
+ *    nobody read.
+ * 2. **`@prisma/client/runtime/client` resolves** (§1.2 item 16). This one is
+ *    first among equals, because its failure is *silent*: every generated file
+ *    opens `// @ts-nocheck`, so with the runtime unresolvable a TypeScript
+ *    program over the generated tree reports **zero** diagnostics while
+ *    `FieldRef` degrades to its uninstantiated form and `JsonValue` stops being
+ *    a union — flipping a types-derived nullability from `true` to `false` with
+ *    nothing anywhere to say so **[RUN8]**. The guard is therefore a module
+ *    *resolution*, never a diagnostic count: a diagnostic count is exactly the
+ *    instrument that reads clean in this failure.
+ * 3. **`prisma generate`**, run by this step itself. The two sources must
+ *    describe one instant; a client generated by some earlier command may
+ *    describe an older schema, and nothing downstream could tell.
+ * 4. **Both sources read in that same run** — PSL for the semantic model, the
+ *    🟢 generated types for the capability surface and for existence.
+ * 5. **The structural checks, in that order.** The existence gate first (T-3.1
+ *    invariant 3), because it decides *which* entities exist and a cross-check
+ *    of an entity nobody admitted is noise; then the reader-versus-reader
+ *    cross-check (`reader-crosscheck.ts`), which answers the reverse direction
+ *    the gate hands it and every other fact both sources carry. Its findings
+ *    stop the step; its two documented exemptions are reported and carried out
+ *    on the result.
+ * 6. **Emit** one TypeScript module (ADR 0009).
+ *
+ * The plan's §9 sketch puts the runtime check *after* `prisma generate`; the
+ * order above is the brief's, and it is the better one — module resolution
+ * walks `node_modules` upward from the client directory and does not need the
+ * directory populated, so nothing is gained by generating output first that the
+ * step is about to refuse to read.
+ *
+ * **The two readers fail differently, and the step keeps them different.** A
+ * PSL `unhandled` entry means *I located a token I do not model*: there is a
+ * construct, a spelling and a site to report, so they are aggregated and
+ * reported together. A types-reader failure means *I cannot read the surface at
+ * all*: there is nothing to record, so it throws. Inventing an `unhandled`
+ * vocabulary for the type surface would be a second parallel representation of
+ * "something went wrong" for no gain.
+ */
+/** The `prisma` major this reader's grammar was written against (C-846). */
+export declare const PINNED_PRISMA_MAJOR = 7;
+export declare class PrismaGenerateStepError extends Error {
+    readonly name = "PrismaGenerateStepError";
+}
+/**
+ * What composition produces: the three halves the artifact carries.
+ *
+ * They are composed together and emitted apart. The `model` is core's — hashed
+ * and Contract-bound — while `translation` is the adapter's Prisma addressing and
+ * `referentialActions` is what the schema's resolved `@relation(onDelete:)` and
+ * `@relation(onUpdate:)` arguments say. Neither of the latter two is part of the
+ * model, so both stay out of the hash: a `@@unique(name:)` rename must not move
+ * the Contract identity, and core has no referential-action vocabulary for a
+ * Contract to carry. All three come from one pass over one field list, so they
+ * cannot disagree about which identifiers or which edges exist.
+ */
+export type PrismaComposedArtifact = {
+    readonly model: PrismaAdapterModel;
+    readonly translation: PrismaTranslationTable;
+    readonly referentialActions: PrismaReferentialActionTable;
+};
+/**
+ * Composition of the two readers' facts into the artifact's two halves.
+ *
+ * It is a parameter rather than a call, because composition is
+ * `discovery/model.discoverer.ts`'s (Task 6) and this step's job is order and
+ * refusal over external effects. The step hands over only what it has verified:
+ * both readers' output, and the resource names the existence gate admitted.
+ */
+export type PrismaModelComposer = (input: {
+    readonly facts: PrismaSchemaFacts;
+    readonly surface: PrismaCapabilitySurface;
+    readonly admitted: readonly string[];
+}) => PrismaComposedArtifact;
+/**
+ * The step's external world, in one record.
+ *
+ * Every member is an effect this package does not own — a child process, a
+ * version on disk, a module resolution, a file write — which is why they are
+ * injectable: the step's contract is the *order* it performs them in and the
+ * points at which it refuses, and neither is observable when the effects are
+ * unobservable. {@link createPrismaGenerateToolchain} is the real one.
+ */
+export type PrismaGenerateToolchain = {
+    readonly installedPrismaVersion: () => Promise<string>;
+    readonly clientRuntimeResolves: (clientDirectory: string) => boolean;
+    readonly runPrismaGenerate: (schema: string) => Promise<void>;
+    readonly readSchema: (location: string) => Promise<PrismaSchemaFacts>;
+    readonly readSurface: (clientDirectory: string) => PrismaCapabilitySurface;
+    readonly writeArtifact: (file: string, source: string) => Promise<void>;
+};
+export type PrismaGenerateRequest = {
+    /** The `schema.prisma` file, or a Prisma 7 schema folder. */
+    readonly schema: string;
+    /** The generator's `output` directory: the 🟢 files' root. */
+    readonly clientDirectory: string;
+    readonly provider: PrismaProvider;
+    /** Where the emitted TypeScript artifact module is written. */
+    readonly artifactFile: string;
+    readonly composeModel: PrismaModelComposer;
+    readonly toolchain?: PrismaGenerateToolchain;
+};
+export type PrismaGenerateResult = {
+    readonly artifactFile: string;
+    /** The emitted module's exact bytes. */
+    readonly source: string;
+    readonly modelHash: string;
+    /** Resource names the 🟢 types admitted, in PSL declaration order. */
+    readonly admitted: readonly string[];
+    /** PSL-only entities the schema itself explained away. */
+    readonly excluded: readonly PrismaEntityAbsence[];
+    /**
+     * Reader disagreements that are understood — the `Json` nullability one and
+     * C-815's unexplained `AtLeast` key. Carried out rather than swallowed, so a
+     * caller can print them and a spec can assert them by name and reason.
+     */
+    readonly exemptions: readonly PrismaReaderExemption[];
+};
+/**
+ * The Prisma CLI this step runs, chosen as D11 states (`prisma-cli.resolver.ts`):
+ * `@prisma/prisma7`'s `prisma7` when it is installed, else `prisma` when its
+ * version is in the adapter's declared range, else a refusal naming both. Looked
+ * up from this package — where an optional peer is linked — and then from the
+ * project the step runs in.
+ */
+export declare function resolveInstalledPrismaCli(): PrismaCli;
+/**
+ * The version fence's input: the version of the Prisma CLI this step runs, which
+ * is the tool that produces the client and the grammar the PSL reader was
+ * written against. (`@prisma/client`'s version is a different fact, fenced at
+ * load time against the artifact — see `discovery/artifact.loader.ts`.)
+ */
+export declare function readInstalledPrismaVersion(): Promise<string>;
+/**
+ * Whether `@prisma/client/runtime/client` resolves from inside the generated
+ * tree — the single question §1.2 item 16 turns on.
+ *
+ * Asked as a module resolution, never as a diagnostic count, and asked from a
+ * file path *inside* `clientDirectory` because resolution walks `node_modules`
+ * upward from the importer. The directory need not exist yet: resolution is a
+ * path question, which is what lets this fence run before `prisma generate`.
+ */
+export declare function clientRuntimeResolves(clientDirectory: string): boolean;
+export declare function createPrismaGenerateToolchain(): PrismaGenerateToolchain;
+export declare function runPrismaGenerateStep(request: PrismaGenerateRequest): Promise<PrismaGenerateResult>;