@mandujs/core 0.21.0 → 0.22.0

package/src/resource/ddl/type-map.ts

@@ -0,0 +1,223 @@
+/**
+ * Phase 4c — Dialect-specific type mapping.
+ *
+ * Pure, stateless translation from Mandu's abstract `DdlFieldType` to the
+ * concrete SQL column type declaration for each supported provider.
+ *
+ * This module is intentionally tiny and has no dependency on `emit.ts`; it
+ * is imported by `emit.ts` and may be consumed independently by Agents
+ * D (generator) and F (QA) for table introspection / parity checks.
+ *
+ * ## Type map (v1 definitive)
+ *
+ * | Mandu `type`              | Postgres          | MySQL         | SQLite  |
+ * |---------------------------|-------------------|---------------|---------|
+ * | `string` (no maxLength)   | `TEXT`            | `VARCHAR(255)`| `TEXT`  |
+ * | `string` (maxLength = N)  | `VARCHAR(N)`      | `VARCHAR(N)`  | `TEXT`  |
+ * | `number`                  | `DOUBLE PRECISION`| `DOUBLE`      | `REAL`  |
+ * | `boolean`                 | `BOOLEAN`         | `TINYINT(1)`  | `INTEGER`|
+ * | `date`                    | `TIMESTAMPTZ`     | `DATETIME(6)` | `TEXT`  |
+ * | `uuid`                    | `UUID`            | `CHAR(36)`    | `TEXT`  |
+ * | `email`                   | `VARCHAR(320)`    | `VARCHAR(320)`| `TEXT`  |
+ * | `url`                     | `VARCHAR(2048)`   | `VARCHAR(2048)`| `TEXT` |
+ * | `json` / `array` / `object`| `JSONB`          | `JSON`        | `TEXT`  |
+ *
+ * Rationale for fixed lengths:
+ *   - `email` 320 chars — RFC 5321 cap (64 local + 1 @ + 255 domain).
+ *   - `url`   2048 chars — de facto HTTP URL upper bound used by most
+ *     browsers and CDNs; shorter than many drivers' TEXT truncation.
+ *   - `string` default on MySQL is `VARCHAR(255)` because MySQL without a
+ *     length on `VARCHAR` fails to parse; `TEXT` on MySQL disallows indexes
+ *     without a prefix spec which breaks `indexed: true`.
+ *
+ * SQLite notes:
+ *   - SQLite uses dynamic type affinity; our mapping chooses the canonical
+ *     affinity names (`TEXT`, `REAL`, `INTEGER`) over the richer PG types so
+ *     `SELECT typeof(col)` returns the expected affinity in tests.
+ *   - Booleans are `INTEGER` — SQLite has no native boolean; the driver
+ *     stores `1`/`0`.
+ */
+import type { DdlDefault, DdlFieldDef, DdlFieldType, SqlProvider } from "./types";
+
+// =====================================================================
+// Constants — exposed for testability and to document magic numbers.
+// =====================================================================
+
+/** Default VARCHAR length for MySQL when the `string` field omits `maxLength`. */
+export const MYSQL_DEFAULT_STRING_LENGTH = 255;
+
+/** RFC 5321 email upper bound. Enforced on MySQL/PG as a VARCHAR cap. */
+export const EMAIL_MAX_LENGTH = 320;
+
+/**
+ * Pragmatic HTTP URL cap — shorter than most TEXT truncation points
+ * (e.g. IE's historical 2083 limit) and long enough for OAuth redirects.
+ */
+export const URL_MAX_LENGTH = 2048;
+
+/** Fixed CHAR length for UUIDs on MySQL (36 = canonical hex-with-dashes). */
+export const UUID_CHAR_LENGTH = 36;
+
+// =====================================================================
+// Static per-provider map for non-parameterized types.
+// `string` is resolved dynamically because it depends on `maxLength`.
+// =====================================================================
+
+type StaticType = Exclude<DdlFieldType, "string">;
+
+const TYPE_MAP: Record<SqlProvider, Record<StaticType, string>> = {
+  postgres: {
+    number: "DOUBLE PRECISION",
+    boolean: "BOOLEAN",
+    date: "TIMESTAMPTZ",
+    uuid: "UUID",
+    email: `VARCHAR(${EMAIL_MAX_LENGTH})`,
+    url: `VARCHAR(${URL_MAX_LENGTH})`,
+    json: "JSONB",
+    array: "JSONB",
+    object: "JSONB",
+  },
+  mysql: {
+    number: "DOUBLE",
+    boolean: "TINYINT(1)",
+    date: "DATETIME(6)",
+    uuid: `CHAR(${UUID_CHAR_LENGTH})`,
+    email: `VARCHAR(${EMAIL_MAX_LENGTH})`,
+    url: `VARCHAR(${URL_MAX_LENGTH})`,
+    json: "JSON",
+    array: "JSON",
+    object: "JSON",
+  },
+  sqlite: {
+    number: "REAL",
+    boolean: "INTEGER",
+    date: "TEXT",
+    uuid: "TEXT",
+    email: "TEXT",
+    url: "TEXT",
+    json: "TEXT",
+    array: "TEXT",
+    object: "TEXT",
+  },
+};
+
+// =====================================================================
+// Public API
+// =====================================================================
+
+/**
+ * Dialect-specific NOW() expression. Used by `DdlDefault.kind === "now"`
+ * and by emit.ts when a field's default should map to "current timestamp".
+ *
+ * - Postgres & MySQL — `NOW()` (ANSI-ish, identical semantics).
+ * - SQLite          — `CURRENT_TIMESTAMP` (SQLite has no `NOW()`).
+ */
+export function nowExpr(provider: SqlProvider): string {
+  switch (provider) {
+    case "postgres":
+    case "mysql":
+      return "NOW()";
+    case "sqlite":
+      return "CURRENT_TIMESTAMP";
+  }
+}
+
+/**
+ * Resolve a Mandu field to its dialect-specific SQL column type declaration.
+ *
+ * `maxLength` applies ONLY to `string` — other types have fixed widths
+ * documented in the module header.
+ *
+ * @example
+ *   resolveColumnType({ type: "string", maxLength: 100, ... }, "postgres")
+ *     → "VARCHAR(100)"
+ *   resolveColumnType({ type: "string", ... }, "postgres")
+ *     → "TEXT"
+ *   resolveColumnType({ type: "string", ... }, "mysql")
+ *     → "VARCHAR(255)"
+ */
+export function resolveColumnType(field: DdlFieldDef, provider: SqlProvider): string {
+  if (field.type === "string") {
+    return resolveStringType(field.maxLength, provider);
+  }
+  // Narrowed above — the remaining types are StaticType.
+  return TYPE_MAP[provider][field.type];
+}
+
+/**
+ * Resolve a `DdlDefault` to the SQL literal that goes after `DEFAULT`.
+ *
+ * Returns JUST the expression — the caller prepends `DEFAULT ` when
+ * composing the column definition.
+ *
+ * Escaping rules:
+ *   - `literal: string`  — ANSI single-quote escape (`'` → `''`).
+ *   - `literal: number`  — emitted verbatim (already numeric).
+ *   - `literal: boolean` — Postgres/MySQL `TRUE`/`FALSE`; SQLite `1`/`0`
+ *     (no native boolean).
+ *   - `sql: expr`        — passed through unchanged. Caller is responsible
+ *     for cross-dialect portability; this is the escape hatch for things
+ *     like sequence defaults or Postgres-specific `gen_random_uuid()`.
+ */
+export function resolveDefault(def: NonNullable<DdlFieldDef["default"]>, provider: SqlProvider): string {
+  switch (def.kind) {
+    case "now":
+      return nowExpr(provider);
+    case "null":
+      return "NULL";
+    case "sql":
+      return def.expr;
+    case "literal":
+      return formatLiteral(def.value, provider);
+  }
+  // Exhaustiveness check — if DdlDefault gains a variant, TS will force this
+  // function to be updated before the project type-checks.
+  const _exhaustive: never = def;
+  return _exhaustive;
+}
+
+// =====================================================================
+// Internals
+// =====================================================================
+
+function resolveStringType(maxLength: number | undefined, provider: SqlProvider): string {
+  if (provider === "sqlite") return "TEXT"; // SQLite ignores length spec.
+  if (typeof maxLength === "number" && maxLength > 0) return `VARCHAR(${maxLength})`;
+  if (provider === "postgres") return "TEXT";
+  // MySQL default: we MUST pick a length because `VARCHAR` with no length is
+  // a parse error. 255 is the convention most ORMs settle on.
+  return `VARCHAR(${MYSQL_DEFAULT_STRING_LENGTH})`;
+}
+
+function formatLiteral(value: string | number | boolean, provider: SqlProvider): string {
+  if (typeof value === "string") {
+    return `'${value.replace(/'/g, "''")}'`;
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new Error(`DDL default literal must be a finite number, got ${String(value)}`);
+    }
+    return String(value);
+  }
+  // boolean
+  if (provider === "sqlite") return value ? "1" : "0";
+  return value ? "TRUE" : "FALSE";
+}
+
+// Runtime sanity — exported for test use only.
+export function _internal_allStaticTypes(): StaticType[] {
+  return [
+    "number",
+    "boolean",
+    "date",
+    "uuid",
+    "email",
+    "url",
+    "json",
+    "array",
+    "object",
+  ];
+}
+
+/** Re-export DdlDefault for ergonomic consumer imports. */
+export type { DdlDefault };

package/src/resource/ddl/types.ts

@@ -0,0 +1,232 @@
+/**
+ * Phase 4c shared types — DDL / diff / migration runtime.
+ *
+ * This file is the CONTRACT between Agents A (DDL emit), B (diff engine),
+ * C (migration runtime), and downstream D (generator) / E (CLI) / F (QA).
+ * Do NOT add logic here — pure types only. Logic belongs next to each
+ * agent's module.
+ *
+ * Source of truth for:
+ * - SqlProvider, DdlFieldType, DdlDefault, DdlFieldDef, DdlIndex, DdlResource
+ * - Snapshot (serialized state of the schema at a point in time)
+ * - Change (discriminated union the diff engine emits)
+ * - PendingMigration / AppliedMigration (runtime plan + history records)
+ * - LockStrategy (per-dialect apply serialization)
+ *
+ * References:
+ *   docs/bun/phase-4c-team-plan.md — team plan + I/O contracts
+ *   docs/rfcs/0001-db-resource-layer.md — design decisions incl. Appendix D
+ */
+
+// ========== Provider + field types ==========
+
+/** Supported SQL providers. Drizzle/Atlas/sqldef all share this same set. */
+export type SqlProvider = "postgres" | "mysql" | "sqlite";
+
+/**
+ * DDL-relevant subset of Mandu's existing `FieldType`. v1 supports:
+ * string/number/boolean/date/uuid/email/url/json/array/object.
+ *
+ * `array` and `object` are persisted as JSON columns (JSONB on Postgres,
+ * JSON on MySQL, TEXT on SQLite). Users who need typed JSON fields should
+ * define a Zod schema in the contract layer; the DB only stores the blob.
+ */
+export type DdlFieldType =
+  | "string"
+  | "number"
+  | "boolean"
+  | "date"
+  | "uuid"
+  | "email"
+  | "url"
+  | "json"
+  | "array"
+  | "object";
+
+/** How a DEFAULT clause is represented. */
+export type DdlDefault =
+  | { kind: "now" } // CURRENT_TIMESTAMP / NOW() — dialect-mapped
+  | { kind: "null" }
+  | { kind: "literal"; value: string | number | boolean }
+  | { kind: "sql"; expr: string }; // raw expression — caller responsible for portability
+
+/**
+ * DDL-level field definition. Normalized form derived from
+ * ResourceField + ResourceDefinition.persistence.fieldOverrides at
+ * snapshot creation time (see `snapshotFromResources`).
+ */
+export interface DdlFieldDef {
+  /** Column name in the DB. Derived from Mandu's field key (e.g. `passwordHash` → `password_hash` when `snake_case: true`). */
+  name: string;
+  /** Abstract Mandu field type. Maps to dialect-specific SQL type via the type map. */
+  type: DdlFieldType;
+  /** Whether NULL is allowed. Default: false (derived from `ResourceField.required === false`). */
+  nullable: boolean;
+  /** Primary key flag. Exactly one field per resource should have this set (composite keys are v2+). */
+  primary: boolean;
+  /** Unique constraint — emits `UNIQUE` on the column (standalone, not composite). */
+  unique: boolean;
+  /** Whether this field participates in a single-column index (non-unique). */
+  indexed: boolean;
+  /** DEFAULT clause. */
+  default?: DdlDefault;
+  /**
+   * For `string` type — VARCHAR length hint. Ignored by SQLite (TEXT is
+   * unbounded). Postgres prefers TEXT when undefined; MySQL emits
+   * VARCHAR(255) default when undefined.
+   */
+  maxLength?: number;
+}
+
+/** Multi-column index definition (composite). Single-column indexes live on `DdlFieldDef.indexed`. */
+export interface DdlIndex {
+  name: string;          // must be unique within the resource
+  fields: string[];      // field names (in order)
+  unique: boolean;
+}
+
+/**
+ * DDL-level resource — what actually reaches the emit / diff engines.
+ * Produced by `snapshotFromResources` from `ParsedResource[]`. Contains
+ * only the information the DB layer cares about.
+ */
+export interface DdlResource {
+  /** Table name in the DB. Usually `pluralize(resourceName)` or explicit override. */
+  name: string;
+  fields: DdlFieldDef[];  // order-preserving; affects emit order
+  indexes: DdlIndex[];    // multi-column indexes only; single-column live on fields
+}
+
+// ========== Snapshots ==========
+
+/**
+ * The full schema state at a point in time. Serialized to JSON and stored
+ * at `.mandu/schema/applied.json` after each successful apply.
+ * The diff engine compares an old snapshot (or null for first run) to a
+ * next snapshot computed from the current resource files.
+ */
+export interface Snapshot {
+  /** Format version of this snapshot file. Bump on breaking schema changes. */
+  version: 1;
+  /** Which provider this snapshot was built for. Diffing across providers is an error. */
+  provider: SqlProvider;
+  /** Resources in deterministic order (sorted by name). */
+  resources: DdlResource[];
+  /** When this snapshot was computed. For provenance only — not used by diff. */
+  generatedAt: string; // ISO 8601
+}
+
+// ========== Changes ==========
+
+/**
+ * Discriminated union emitted by the diff engine. Every `Change` is one
+ * "atomic" DDL operation. Emit order is deterministic so the generated
+ * migration SQL is stable across runs.
+ *
+ * Rename is NOT auto-detected — the diff engine always emits drop + add.
+ * The CLI layer (Agent E) asks the user whether consecutive drop+add are
+ * a rename and rewrites the Change list accordingly before SQL emit.
+ */
+export type Change =
+  | { kind: "create-table"; resource: DdlResource }
+  | { kind: "drop-table"; resourceName: string }
+  | { kind: "add-column"; resourceName: string; field: DdlFieldDef }
+  | { kind: "drop-column"; resourceName: string; fieldName: string }
+  | {
+      kind: "alter-column-type";
+      resourceName: string;
+      fieldName: string;
+      fromType: DdlFieldType;
+      toType: DdlFieldType;
+      /** v1 emits a stub comment. User edits the migration manually. */
+      stub: true;
+    }
+  | { kind: "alter-column-nullable"; resourceName: string; fieldName: string; nullable: boolean }
+  | { kind: "alter-column-default"; resourceName: string; fieldName: string; default?: DdlDefault }
+  | { kind: "add-index"; resourceName: string; index: DdlIndex }
+  | { kind: "drop-index"; resourceName: string; indexName: string }
+  | {
+      kind: "rename-table";
+      oldName: string;
+      newName: string;
+      /** Emitted only after CLI user confirmation. Diff engine never emits directly. */
+      origin: "user-confirmed";
+    }
+  | {
+      kind: "rename-column";
+      resourceName: string;
+      oldName: string;
+      newName: string;
+      origin: "user-confirmed";
+    };
+
+// ========== Migration runtime ==========
+
+/** A migration file that exists in the migrations directory but has not yet been applied. */
+export interface PendingMigration {
+  /** Zero-padded 4-digit sequence, e.g. "0001". Must sort lexicographically. */
+  version: string;
+  /** Filename relative to the migrations dir, e.g. "0001_create_users.sql". */
+  filename: string;
+  /** Full SQL text of the migration. */
+  sql: string;
+  /** SHA-256 of `sql` with `\r\n` normalized to `\n` — used by `__mandu_migrations` for tamper detection. */
+  checksum: string;
+  /** Filesystem mtime of the migration file. */
+  createdAt: Date;
+}
+
+/** A migration that has been applied — read from the `__mandu_migrations` history table. */
+export interface AppliedMigration {
+  version: string;
+  filename: string;
+  checksum: string;
+  appliedAt: Date;
+  executionMs: number;
+  success: boolean;
+}
+
+/** Snapshot of the migration history at call time. */
+export interface MigrationStatus {
+  applied: AppliedMigration[];
+  pending: PendingMigration[];
+  /** Migrations that exist in history but whose checksum no longer matches the file. */
+  tampered: Array<{ version: string; filename: string; storedChecksum: string; currentChecksum: string }>;
+  /** Migration files on disk that have no history row and don't match pending (shouldn't happen but guards against dir corruption). */
+  orphaned: Array<{ filename: string }>;
+}
+
+// ========== Lock strategy (per-dialect apply serialization) ==========
+
+/**
+ * Single-process apply serialization. Multi-instance coordination is out of
+ * scope for v1 (RFC §8 non-goals).
+ *
+ * Defaults per provider (Agent C implements):
+ * - postgres → "pg_advisory_lock"  (`pg_advisory_lock(bigint)` + `pg_advisory_unlock`)
+ * - mysql    → "mysql_get_lock"    (`GET_LOCK('mandu-migrations', 60)` + `RELEASE_LOCK`)
+ * - sqlite   → "sqlite_immediate"  (`BEGIN IMMEDIATE` for the apply transaction)
+ */
+export type LockStrategy = "pg_advisory_lock" | "mysql_get_lock" | "sqlite_immediate" | "none";
+
+// ========== Scope fences — what v1 does NOT cover ==========
+
+/**
+ * v1 scope (enforced by Agent A/B — they should NOT handle these):
+ *   - Foreign keys
+ *   - CHECK constraints
+ *   - ENUM types (custom Postgres ENUMs, MySQL ENUM columns)
+ *   - Computed / GENERATED columns
+ *   - Partitioning
+ *   - Triggers, views, stored procedures
+ *   - Alter column type (stub only — user edits manually)
+ *   - Rename auto-detection (always drop+add unless CLI prompts user)
+ *   - Multi-column primary key (composite)
+ *   - Rollback / DOWN migrations
+ *   - Repeatable migrations (Flyway `R__` style)
+ *
+ * Anything outside this list is intentionally out of scope for Phase 4c
+ * v1. Expansion lands in 4c.1 / 4c.2 patches after 4c merge.
+ */
+export type Phase4cScopeMarker = typeof _PHASE_4C_V1_SCOPE;
+const _PHASE_4C_V1_SCOPE = Symbol.for("@mandujs/core/resource/ddl/phase-4c-v1");