@prisma/orm-mongo 8.0.0-rc.5 → 8.0.0-rc.5-dev.2

package/skills/prisma-8/upgrading/extension/upgrades/0.8-to-0.9/strip-inline-contracts.ts

@@ -0,0 +1,226 @@
+/**
+ * Removes the inlined `fromContract` / `toContract` fields from every
+ * committed `migration.json` manifest reachable from the project root.
+ *
+ * Background: starting at the 0.9 release, `migration.json` no longer
+ * carries `fromContract` / `toContract` (the schema rejects them as
+ * unknown keys). The destination contract continues to live next door
+ * as `end-contract.json` (and the source as `start-contract.json`); the
+ * manifest copy was redundant. `migrationHash` is unaffected — it was
+ * already computed without those two fields, so stripping them does
+ * not change the stored hash.
+ *
+ * Behaviour:
+ * - Walks the project root recursively, ignoring `node_modules`, `.git`,
+ *   `dist`, and `build`. Picks up every file named `migration.json`
+ *   whose JSON object has the migration-manifest shape (`from`, `to`,
+ *   and `migrationHash` keys). Other `migration.json` files (e.g.
+ *   unrelated artefacts that happen to share the name) are skipped.
+ * - Manifests that already lack both removed keys are left untouched.
+ * - Manifests with either removed key are rewritten with the two key /
+ *   value spans excised at the text level, so the formatting of all
+ *   surviving fields (whitespace, inline-vs-multiline arrays, key
+ *   ordering, trailing newline) is preserved byte-for-byte. Only the
+ *   key being removed and its trailing comma+newline disappear from
+ *   the diff.
+ * - Idempotent: re-running the script after success is a no-op.
+ *
+ * Flags:
+ *   --check   dry-run; exit 1 if any manifest still needs fixing.
+ */
+import { readdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+const REMOVED_KEYS = ['fromContract', 'toContract'] as const;
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build']);
+
+const dryRun = process.argv.includes('--check');
+const projectRoot = process.cwd();
+
+interface Result {
+  readonly path: string;
+  readonly status: 'already-clean' | 'needs-fix' | 'fixed';
+  readonly removed: readonly string[];
+}
+
+async function findManifests(root: string): Promise<string[]> {
+  const out: string[] = [];
+
+  async function walk(dir: string): Promise<void> {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        if (SKIP_DIRS.has(entry.name)) continue;
+        await walk(join(dir, entry.name));
+      } else if (entry.isFile() && entry.name === 'migration.json') {
+        const path = join(dir, entry.name);
+        try {
+          const parsed: unknown = JSON.parse(await readFile(path, 'utf-8'));
+          if (looksLikeMigrationManifest(parsed)) out.push(path);
+        } catch {
+          // Not valid JSON, or not the manifest shape — skip silently.
+        }
+      }
+    }
+  }
+
+  await walk(root);
+  return out.sort();
+}
+
+function looksLikeMigrationManifest(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== 'object' || value === null) return false;
+  const obj = value as Record<string, unknown>;
+  return 'from' in obj && 'to' in obj && 'migrationHash' in obj;
+}
+
+/**
+ * Find the end index (exclusive) of a JSON value starting at `start`
+ * inside `text`. Handles strings, numbers, booleans, null, arrays, and
+ * objects. Brace / bracket nesting is tracked while respecting string
+ * literals (with escapes). Throws if `text` is not well-formed JSON
+ * starting at `start`.
+ */
+function jsonValueEnd(text: string, start: number): number {
+  const head = text[start];
+  let depth = 0;
+  let inString = false;
+  let inEscape = false;
+
+  if (head === '"') {
+    let i = start + 1;
+    while (i < text.length) {
+      const ch = text[i];
+      if (inEscape) inEscape = false;
+      else if (ch === '\\') inEscape = true;
+      else if (ch === '"') return i + 1;
+      i += 1;
+    }
+    throw new Error(`Unterminated string starting at ${start}`);
+  }
+
+  if (head === '{' || head === '[') {
+    let i = start;
+    while (i < text.length) {
+      const ch = text[i];
+      if (inString) {
+        if (inEscape) inEscape = false;
+        else if (ch === '\\') inEscape = true;
+        else if (ch === '"') inString = false;
+      } else {
+        if (ch === '"') inString = true;
+        else if (ch === '{' || ch === '[') depth += 1;
+        else if (ch === '}' || ch === ']') {
+          depth -= 1;
+          if (depth === 0) return i + 1;
+        }
+      }
+      i += 1;
+    }
+    throw new Error(`Unterminated container starting at ${start}`);
+  }
+
+  let i = start;
+  while (i < text.length && !',}\n\r\t '.includes(text[i] ?? '')) i += 1;
+  return i;
+}
+
+/**
+ * Remove a top-level key (and its `: value` and trailing comma) from a
+ * pretty-printed JSON object text. Returns the new text. If the key
+ * isn't present, returns the input unchanged.
+ *
+ * Preserves all surrounding whitespace and the formatting of every
+ * other field byte-for-byte. Handles both "key in the middle" (eats the
+ * trailing comma + newline) and "key at the end" (eats the leading
+ * comma + newline).
+ */
+function removeTopLevelKey(text: string, key: string): string {
+  const needle = `"${key}"`;
+  const keyIndex = text.indexOf(needle);
+  if (keyIndex < 0) return text;
+
+  let cursor = keyIndex + needle.length;
+  while (cursor < text.length && /\s/.test(text[cursor] ?? '')) cursor += 1;
+  if (text[cursor] !== ':') {
+    throw new Error(`Expected ':' after ${needle} at ${cursor}`);
+  }
+  cursor += 1;
+  while (cursor < text.length && /\s/.test(text[cursor] ?? '')) cursor += 1;
+
+  const valueEnd = jsonValueEnd(text, cursor);
+
+  let removeStart = keyIndex;
+  let removeEnd = valueEnd;
+
+  if (text[removeEnd] === ',') {
+    removeEnd += 1;
+    if (text[removeEnd] === '\n') removeEnd += 1;
+    let lineStart = removeStart;
+    while (lineStart > 0 && text[lineStart - 1] !== '\n') lineStart -= 1;
+    if (text.slice(lineStart, removeStart).trim() === '') removeStart = lineStart;
+  } else {
+    let back = removeStart - 1;
+    while (back > 0 && /[ \t]/.test(text[back] ?? '')) back -= 1;
+    if (text[back] === '\n') {
+      let prev = back - 1;
+      while (prev > 0 && /[ \t]/.test(text[prev] ?? '')) prev -= 1;
+      if (text[prev] === ',') {
+        removeStart = prev;
+        if (text[removeEnd] === '\n') removeEnd += 1;
+      }
+    }
+  }
+
+  return text.slice(0, removeStart) + text.slice(removeEnd);
+}
+
+async function processManifest(path: string): Promise<Result> {
+  const raw = await readFile(path, 'utf-8');
+  const data: Record<string, unknown> = JSON.parse(raw);
+  const removed = REMOVED_KEYS.filter((key) => key in data);
+  if (removed.length === 0) return { path, status: 'already-clean', removed: [] };
+
+  let stripped = raw;
+  for (const key of removed) stripped = removeTopLevelKey(stripped, key);
+
+  // Sanity: stripped output must still be valid JSON and must agree on
+  // every field except the two we removed.
+  const reparsed: Record<string, unknown> = JSON.parse(stripped);
+  for (const key of removed) {
+    if (key in reparsed) {
+      throw new Error(`Internal: ${key} survived strip in ${path}`);
+    }
+  }
+
+  if (!dryRun) await writeFile(path, stripped, 'utf-8');
+  return { path, status: dryRun ? 'needs-fix' : 'fixed', removed };
+}
+
+const manifests = await findManifests(projectRoot);
+if (manifests.length === 0) {
+  console.error(`No migration.json files found under ${projectRoot}.`);
+  process.exit(1);
+}
+
+let changed = 0;
+let alreadyClean = 0;
+for (const path of manifests) {
+  const result = await processManifest(path);
+  const rel = path.slice(projectRoot.length + 1);
+  if (result.status === 'already-clean') {
+    alreadyClean += 1;
+    console.log(`OK    ${rel}  (already clean)`);
+  } else {
+    changed += 1;
+    const verb = dryRun ? 'WOULD FIX' : 'FIXED';
+    console.log(`${verb} ${rel}  (removed: ${result.removed.join(', ')})`);
+  }
+}
+
+console.log();
+console.log(
+  `${manifests.length} manifest(s) scanned: ${changed} ${dryRun ? 'needing fix' : 'fixed'}, ${alreadyClean} already clean.`,
+);
+
+if (dryRun && changed > 0) process.exit(1);

package/skills/prisma-8/upgrading/extension/upgrades/0.9-to-0.10/instructions.md

@@ -0,0 +1,150 @@
+---
+from: "0.9"
+to: "0.10"
+changes:
+  - id: stamp-storage-types-kind-on-contract-snapshots
+    summary: Stamp the `kind` discriminator (`"codec-instance"` / `"postgres-enum"`) on every entry in `storage.types` inside every committed `start-contract.json` / `end-contract.json` snapshot (extension seed migrations included). The SQL family's contract serializer is now strict — untagged entries fail to load with a deserializer diagnostic naming the offending entry.
+    detection:
+      glob: "**/migrations/**/{start,end}-contract.json"
+      contains:
+        - '"codecId"'
+      anyMatch: true
+    script: ./stamp-storage-types-kind.ts
+  - id: stamp-storage-types-kind-in-source
+    summary: Wrap untagged codec-triple inputs to `SqlStorage` (or any builder that materialises `storage.types`) with `toStorageTypeInstance(...)`, and use the target-specific `PostgresEnumType` class for Postgres-enum entries — the `SqlStorage` constructor now throws on untagged entries instead of papering over them.
+    detection:
+      glob: "**/*.{ts,tsx}"
+      contains:
+        - "storage.types"
+        - "codecId"
+      anyMatch: true
+---
+
+# 0.9 → 0.10 — Extension-author upgrade instructions
+
+## `stamp-storage-types-kind-on-contract-snapshots`
+
+Starting at the 0.10 release, the SQL family's contract serializer (`familyInstance.validateContract`, the seam every on-disk contract read now crosses) is **strict** about the `storage.types` polymorphic slot. Every entry must carry a `kind` discriminator (`"codec-instance"` for codec triples, `"postgres-enum"` for Postgres enums). The previous silent fallthrough in `normaliseTypeEntry` that quietly accepted untagged codec triples is gone.
+
+This applies to **seed migrations** shipped inside an extension package (e.g. `migrations/<edge-id>/{start,end}-contract.json` shipped under `packages/<extension>/migrations/`) just as it does to user-app migrations. Any extension that ships seed `*-contract.json` snapshots with untagged `storage.types` entries will fail to load under 0.10 with a `Contract validation failed` envelope.
+
+Before 0.10, seed snapshots looked like this:
+
+```jsonc
+{
+  "storage": {
+    "types": {
+      "Embedding1536": {
+        "codecId": "pg/vector@1",
+        "nativeType": "vector",
+        "typeParams": { "length": 1536 }
+      }
+    }
+  }
+}
+```
+
+Starting at 0.10 the same entries must look like this:
+
+```jsonc
+{
+  "storage": {
+    "types": {
+      "Embedding1536": {
+        "kind": "codec-instance",
+        "codecId": "pg/vector@1",
+        "nativeType": "vector",
+        "typeParams": { "length": 1536 }
+      }
+    }
+  }
+}
+```
+
+Postgres-enum entries undergo a structural change (the `name` is lifted from the entry's map key, `values` is hoisted out of `typeParams`, `typeParams` is dropped). See the user-facing entry (`../../../app/upgrades/0.9-to-0.10/instructions.md`) for the before/after on the enum shape — the on-disk transformation is identical for both audiences.
+
+### What `stamp-storage-types-kind.ts` does
+
+The colocated script walks the project root, descends into every directory named `migrations/` (skipping `node_modules`, `.git`, `dist`, `build`), and rewrites every `start-contract.json` and `end-contract.json` whose `storage.types` slot has at least one untagged entry:
+
+- **Already-stamped entries** are left untouched (idempotent — safe to re-run).
+- **`pg/enum@1`** entries are rewritten as the `"postgres-enum"` shape (lifts `name` from the map key, hoists `values` out of `typeParams`, drops `typeParams`).
+- **Every other codecId** is rewritten as the `"codec-instance"` shape (`kind` prepended; `codecId`, `nativeType`, `typeParams` preserved verbatim).
+- The whole snapshot is re-serialised via a JSON pretty-printer that mirrors the CLI's authoring shape (multi-line objects, inline short arrays of primitives) — the diff outside `storage.types` is zero on CLI-authored snapshots.
+- A `--check` flag turns the script into a dry-run; lists affected snapshots and exits non-zero if any still need fixing.
+
+If a snapshot contains a `storage.types` entry that is neither already-stamped nor an untagged codec triple, the script throws and names the offending entry. Hand-edit required.
+
+## `stamp-storage-types-kind-in-source`
+
+The SQL family's `SqlStorage` class now refuses untagged codec triples at construction time. Source code that builds an in-memory `SqlStorage` (or any contract-builder fixture / test that ends up materialising `storage.types`) with raw `{ codecId, nativeType, typeParams }` literals will throw at construction with a diagnostic like:
+
+> `storage.types["Embedding1536"] has missing \`kind\`; expected "codec-instance" or "postgres-enum". Untagged codec triples should be wrapped with toStorageTypeInstance(...) before construction.`
+
+There is no codemod for this — extensions construct `SqlStorage` via too many shapes (builder DSL, direct constructor, test fixtures, ad-hoc literals) for a deterministic transform to be safe. Instead, walk every `.ts` / `.tsx` file matched by the `detection.glob` above and apply these rules locally:
+
+- **Codec-triple literal passed to `new SqlStorage({...})` or a builder that flattens to it** (e.g. `types: { Embedding1536: { codecId: 'pg/vector@1', nativeType: 'vector', typeParams: { length: 1536 } } }`): wrap each value with `toStorageTypeInstance(...)`:
+
+  ```ts
+  import { toStorageTypeInstance } from '@internal/sql-contract';
+
+  const storage = new SqlStorage({
+    types: {
+      Embedding1536: toStorageTypeInstance({
+        codecId: 'pg/vector@1',
+        nativeType: 'vector',
+        typeParams: { length: 1536 },
+      }),
+    },
+    // …
+  });
+  ```
+
+  The helper is idempotent — input already carrying the `kind` field passes through unchanged.
+
+- **Postgres-enum literal** (e.g. `types: { user_type: { codecId: 'pg/enum@1', nativeType: 'user_type', typeParams: { values: ['admin', 'user'] } } }`): the canonical fix is to replace with a `PostgresEnumType` class instance from `@internal/postgres`:
+
+  ```ts
+  import { PostgresEnumType } from '@internal/postgres';
+
+  const storage = new SqlStorage({
+    types: {
+      user_type: new PostgresEnumType({
+        name: 'user_type',
+        nativeType: 'user_type',
+        values: ['admin', 'user'],
+      }),
+    },
+    // …
+  });
+  ```
+
+  The class instance carries `kind: 'postgres-enum'` and the structural shape the family discriminates on. Plain object literals with `kind: 'postgres-enum'` are rejected — the constructor route is mandatory because hydration of raw JSON envelopes is the target-specific serializer's job (cross-domain layering: the SQL family doesn't know about Postgres-enum's concrete class).
+
+  **Minimal-fix alternative for fixtures / round-trip tests.** If the code in question only round-trips the codec triple as a plain envelope (no target-specific enum behaviour — e.g. a planner test fixture that never reaches Postgres-enum planning hooks), stamping `kind: 'codec-instance'` on the existing literal is a sufficient and idempotent fix:
+
+  ```ts
+  const fixtureStorage: SqlStorageInput = {
+    types: {
+      user_type: {
+        kind: 'codec-instance',
+        codecId: 'pg/enum@1',
+        nativeType: 'user_type',
+        typeParams: { values: ['admin', 'user'] },
+      },
+    },
+    // …
+  };
+  ```
+
+  The SQL family treats the entry as an opaque codec triple and round-trips it unchanged. Use this form only when you do not need `PostgresEnumType`'s enum-specific structural fields (`name`, `values` lifted out of `typeParams`) or its enum-planning behaviour — otherwise prefer the `PostgresEnumType` constructor above.
+
+- **Test fixtures that round-trip a contract through JSON** (e.g. `JSON.parse(JSON.stringify(contract))`): ensure the source-side contract is constructed with stamped entries before the round-trip; the deserializer now refuses to silently re-stamp on the read.
+
+- **Extension-contributed codec catalogues** (extensions that register custom codecs): no source change required for the catalogue itself — codec definitions don't carry `kind`. The change is only at the `SqlStorage.types` slot where catalogue entries materialise per-contract.
+
+### Validation
+
+After running the JSON codemod and applying the source-level rules above, run `pnpm typecheck && pnpm test` (or your extension's equivalent). `prisma-8-check-pins` should also pass — the pin set is unchanged for this transition; the breaking change is in runtime construction behaviour, not the dependency contract.
+
+If your extension ships seed migrations under `packages/<extension>/migrations/`, also run the codemod with `--check` against the project root to confirm the seed snapshots all stamp correctly. The user-facing copy of the same codemod (under `../../../app/upgrades/0.9-to-0.10/`) operates on the user's app-space migrations; this copy operates on your extension's seed migrations.