@an5/orm 1.0.9 → 1.1.0

package/generator/src/parser.ts

@@ -1,70 +1,61 @@
 import fs from 'fs';
 import path from 'path';
 import { Model, Field, Relation } from './types';
-
-// SQL Server type → TypeScript type mapping
-const AN5_TO_TS: Record<string, string> = {
-  // String types
-  'NVARCHAR': 'string',
-  'VARCHAR': 'string',
-  'CHAR': 'string',
-  'NCHAR': 'string',
-  'TEXT': 'string',
-  'NTEXT': 'string',
-  'XML': 'string',
-  // Numeric types
-  'INT': 'number',
-  'SMALLINT': 'number',
-  'TINYINT': 'number',
-  'BIGINT': 'number | bigint',
-  'FLOAT': 'number',
-  'REAL': 'number',
-  'DECIMAL': 'number',
-  'NUMERIC': 'number',
-  'MONEY': 'number',
-  'SMALLMONEY': 'number',
-  // Boolean
-  'BIT': 'boolean',
-  // Date types
-  'DATETIME': 'Date',
-  'DATETIME2': 'Date',
-  'SMALLDATETIME': 'Date',
-  'DATE': 'Date',
-  'TIME': 'Date',
-  'DATETIMEOFFSET': 'Date',
-  // Binary types
-  'VARBINARY': 'Buffer',
-  'BINARY': 'Buffer',
-  'IMAGE': 'Buffer',
-  // Other
-  'UNIQUEIDENTIFIER': 'string',
-  'SQL_VARIANT': 'any',
-  'ROWVERSION': 'Buffer',
-  'HIERARCHYID': 'string',
-  'GEOGRAPHY': 'string',
-  'GEOMETRY': 'string',
-  'VECTOR': 'number[] | string',
-};
-
-// Parse base type from "NVARCHAR(255)" → "NVARCHAR"
-function parseSqlType(raw: string): { base: string; params: string } {
-  const match = raw.match(/^(\w+)(?:\((.+)\))?$/);
-  if (!match) return { base: raw, params: '' };
-  return { base: match[1].toUpperCase(), params: match[2] || '' };
+import {
+  DEFAULT_PROVIDER,
+  FieldTypeError,
+  FieldTypeIssue,
+  Provider,
+  readFieldLineHead,
+  resolveFieldType,
+  unknownFieldTypeMessage,
+} from './field-types';
+
+/**
+ * Maps a column type of a provider to its TypeScript type.
+ *
+ * `provider` defaults to SQL Server so existing callers keep their behaviour;
+ * the generator passes the provider derived from the connection string.
+ */
+export function sqlTypeToTs(sqlType: string, provider: Provider = DEFAULT_PROVIDER): string {
+  return resolveFieldType(sqlType, provider)?.ts ?? 'any';
 }
 
-// Map SQL Server type to TypeScript type
-export function sqlTypeToTs(sqlType: string): string {
-  const { base } = parseSqlType(sqlType);
-  return AN5_TO_TS[base] || 'any';
+/**
+ * A field whose type is in no table for this provider. Whether it is a relation
+ * or a typo is not known yet, so the decision waits until the whole schema has
+ * been read.
+ */
+interface PendingModelRef {
+  model: Model;
+  name: string;
+  /** The name as written in the schema, kept verbatim to compare with model names. */
+  type: string;
+  isArray: boolean;
+  isOptional: boolean;
+  /** The original line, needed to read `@relation`/`@description`. */
+  line: string;
 }
 
 export class SchemaParser {
   private schemaText: string = '';
-
-  constructor(private schemaDir: string) {}
+  private issues: FieldTypeIssue[] = [];
+  private modelRefs: PendingModelRef[] = [];
+  private models: Model[] = [];
+
+  /**
+   * @param schemaDir directory holding the `.an5` files
+   * @param provider target database; decides which field types are valid
+   */
+  constructor(
+    private schemaDir: string,
+    private provider: Provider = DEFAULT_PROVIDER,
+  ) {}
 
   public async parse(): Promise<Model[]> {
+    this.issues = [];
+    this.modelRefs = [];
+    this.models = [];
     this.loadSchema();
     const lines = this.schemaText.split('\n');
     const models: Model[] = [];
@@ -80,7 +71,12 @@ export class SchemaParser {
         currentModel = {
           name: modelName,
           tableName: modelName.toLowerCase() + 's',
-          schemaName: 'dbo',
+          // SQL Server's default schema, and only SQL Server's. For SQLite or MySQL
+          // an unqualified name is what the connection resolves, and for PostgreSQL
+          // it follows `search_path` — the same rule `db:push` now uses, so the
+          // generated client and the pushed table cannot drift apart.
+          schemaName: this.provider === 'mssql' ? 'dbo' : '',
+          provider: this.provider,
           fields: [],
           relations: []
         };
@@ -98,6 +94,15 @@ export class SchemaParser {
       }
     }
 
+    this.models = models;
+    this.resolveModelRefs();
+
+    // Every bad type is reported at once, so one pass over the schema is enough
+    // instead of re-running the generator after every line.
+    if (this.issues.length > 0) {
+      throw new FieldTypeError(this.provider, this.issues);
+    }
+
     this.postProcessRelations(models);
     return models;
   }
@@ -120,8 +125,12 @@ export class SchemaParser {
       return;
     }
     if (line.startsWith('@@schema')) {
-      const schemaMatch = line.match(/@@schema\("(.+)"\)/);
-      if (schemaMatch) model.schemaName = schemaMatch[1];
+      // `(.*)` rather than `(.+)`: `@@schema("")` is how a model says "no
+      // schema", needed for databases that have no schema concept. With `(.+)`
+      // the empty string does not match, the directive is silently ignored and
+      // the model keeps `dbo`.
+      const schemaMatch = line.match(/@@schema\("(.*)"\)/);
+      if (schemaMatch) model.schemaName = schemaMatch[1].trim();
       return;
     }
     if (line.startsWith('@@unique')) {
@@ -140,48 +149,71 @@ export class SchemaParser {
     }
     if (line.startsWith('@@')) return;
 
-    const parts = line.split(/\s+/);
-    const fieldName = parts[0];
-    let fieldType = parts[1];
-    if (!fieldName || !fieldType) return;
-
-    const isArray = fieldType.endsWith('[]');
-    const isOptional = fieldType.endsWith('?');
-    const cleanType = fieldType.replace('[]', '').replace('?', '');
+    const head = readFieldLineHead(line);
+    if (!head) return;
 
-    // Parse SQL Server type (e.g., "NVARCHAR(255)" → base="NVARCHAR")
-    const { base: sqlBase } = parseSqlType(cleanType);
+    // No table entry for this provider. This used to fall through to
+    // `tsType = 'any'` (or, worse, become a relation to a model that does not
+    // exist) and the client was still generated; the failure only surfaced
+    // later at the database layer, in a message unrelated to the schema.
+    const resolved = resolveFieldType(head.type, this.provider);
+    if (!resolved) {
+      this.modelRefs.push({ model, name: head.name, type: head.type, isArray: head.isArray, isOptional: head.isOptional, line });
+      return;
+    }
 
-    let tsType = 'any';
-    let isRelation = false;
+    const hasDefault = line.includes('@default') || line.includes('@updatedAt') || line.includes('@id');
+    const isId = line.includes('@id');
+    let description: string | undefined;
+    const descMatch = line.match(/@description\("(.+)"\)/);
+    if (descMatch) description = descMatch[1];
+    model.fields.push({ name: head.name, type: resolved.ts, sqlType: head.type, isOptional: head.isOptional, hasDefault, isId, description });
+  }
 
-    // Check if it's a known SQL Server type
-    if (AN5_TO_TS[sqlBase]) {
-      tsType = sqlTypeToTs(cleanType);
-    } else if (cleanType[0] === cleanType[0].toUpperCase() && !cleanType.includes('(')) {
-      // Uppercase without parens = likely a relation to another model
-      tsType = cleanType;
-      isRelation = true;
-    }
+  /**
+   * Settles the fields that matched no type: a name matching a model in the
+   * schema is a relation, anything else is a bad type — reported with the
+   * provider name and a suggestion.
+   *
+   * The decision has to wait for the whole schema, because a relation may point
+   * at a model declared later. Every upper-case token used to count as a
+   * relation, so `INTEGER` written for SQL Server became a relation to a model
+   * named `INTEGER` and nothing ever complained.
+   */
+  private resolveModelRefs() {
+    const modelNames = this.models.map((model) => model.name);
+
+    for (const ref of this.modelRefs) {
+      if (!modelNames.includes(ref.type)) {
+        this.issues.push({
+          path: `${ref.model.name}.${ref.name}`,
+          message: unknownFieldTypeMessage(ref.type, this.provider, modelNames),
+        });
+        continue;
+      }
 
-    if (isRelation) {
       let foreignKey = '', localKey = '', relationName = '';
-      const nameMatch = line.match(/@relation\("(\w+)"/);
+      const nameMatch = ref.line.match(/@relation\("(\w+)"/);
       if (nameMatch) relationName = nameMatch[1];
-      const relationMatch = line.match(/@relation\((?:.*fields:\s*\[(\w+)\],)?\s*(?:.*references:\s*\[(\w+)\],?)?.*\)/);
+      const relationMatch = ref.line.match(/@relation\((?:.*fields:\s*\[(\w+)\],)?\s*(?:.*references:\s*\[(\w+)\],?)?.*\)/);
       if (relationMatch) {
         foreignKey = relationMatch[1] || '';
         localKey = relationMatch[2] || '';
       }
-      model.relations.push({ name: fieldName, type: tsType, isArray, isOptional, foreignKey, localKey, relationName });
-    } else {
-      const hasDefault = line.includes('@default') || line.includes('@updatedAt') || line.includes('@id');
-      const isId = line.includes('@id');
-      let description: string | undefined;
-      const descMatch = line.match(/@description\("(.+)"\)/);
-      if (descMatch) description = descMatch[1];
-      model.fields.push({ name: fieldName, type: tsType, sqlType: cleanType, isOptional, hasDefault, isId, description });
+      const description = ref.line.match(/@description\("(.+)"\)/)?.[1];
+      ref.model.relations.push({
+        name: ref.name,
+        type: ref.type,
+        isArray: ref.isArray,
+        isOptional: ref.isOptional,
+        foreignKey,
+        localKey,
+        relationName,
+        ...(description ? { description } : {}),
+      });
     }
+
+    this.modelRefs = [];
   }
 
   private postProcessRelations(models: Model[]) {

package/generator/src/push-apply.ts

@@ -0,0 +1,148 @@
+/**
+ * Applying a schema to a database: what `db:push` does once the schema is read.
+ *
+ * Kept out of `push.ts` so the sequence can be run against a real database in a
+ * test — the CLI needs a live server, and a test that re-implements the sequence
+ * instead of calling it proves only that the copy works.
+ *
+ * The database is two functions rather than the adapter, which keeps this testable
+ * and keeps the driver out of the decision making.
+ */
+import { PushDialect } from './dialect';
+import { PushIndex, PushModel, directiveName, qualifiedTableName, safeIdentifierName } from './push-schema';
+
+/** The two things this needs from a database connection. */
+export interface PushDatabase {
+  /** Runs a query and returns its rows; existence checks are `length > 0`. */
+  query(sql: string): Promise<readonly unknown[]>;
+  /** Runs one statement. */
+  execute(sql: string): Promise<void>;
+  /** Progress, so the CLI prints what it is doing. */
+  log(message: string): void;
+}
+
+export interface ApplyResult {
+  /** How many tables were created, and how many altered. */
+  tablesCreated: number;
+  tablesAltered: number;
+  columnsAdded: number;
+  indexesCreated: number;
+  uniqueConstraintsAdded: number;
+}
+
+/**
+ * Creates whatever the schema has and the database does not.
+ *
+ * The order is deliberate: a table first, then missing columns, then unique
+ * constraints and indexes — a unique over a column that does not exist yet fails.
+ * Everything is checked before it is created, so running it twice changes nothing.
+ */
+export async function applySchema(
+  models: readonly PushModel[],
+  dialect: PushDialect,
+  db: PushDatabase,
+): Promise<ApplyResult> {
+  const result: ApplyResult = {
+    tablesCreated: 0,
+    tablesAltered: 0,
+    columnsAdded: 0,
+    indexesCreated: 0,
+    uniqueConstraintsAdded: 0,
+  };
+
+  for (const model of models) {
+    const tableName = qualifiedTableName(model);
+    const sqlTableName = dialect.quoteTable(tableName);
+    const quoteFields = (fields: readonly string[]) => fields.map((field) => dialect.quote(field));
+    db.log(`Processing table ${sqlTableName}...`);
+
+    const safeName = safeIdentifierName(model.tableName);
+    // SQLite has no named unique constraints — a UNIQUE there becomes an index the
+    // engine names itself — so the unique index carries our name instead, and that
+    // name is what the existence check can look for.
+    const compoundUniques = model.compoundUniques.map((directive, idx) => ({
+      name: directiveName(directive, model.tableName, 'compound', idx),
+      fields: directive.fields,
+      directive,
+    }));
+
+    const tableExists = (await db.query(dialect.tableExists(tableName))).length > 0;
+
+    if (!tableExists) {
+      db.log(`Creating table ${sqlTableName}...`);
+      const columnDefs = model.fields.map((field) => dialect.columnDefinition(field));
+      for (const entry of compoundUniques) {
+        if (!dialect.supportsNamedUniqueConstraint) continue;
+        const fieldsStr = quoteFields(entry.fields).join(', ');
+        columnDefs.push(`CONSTRAINT ${dialect.quote(entry.name)} UNIQUE (${fieldsStr})`);
+      }
+      await db.execute(dialect.createTable(sqlTableName, columnDefs));
+      db.log(`✅ Table ${sqlTableName} created.`);
+      result.tablesCreated += 1;
+    } else {
+      for (const field of model.fields) {
+        const columnExists = (await db.query(dialect.columnExists(tableName, field.name))).length > 0;
+        if (columnExists) continue;
+        db.log(`Adding column ${dialect.quote(field.name)} to table ${sqlTableName}...`);
+        await db.execute(dialect.addColumn(sqlTableName, field));
+        result.columnsAdded += 1;
+        // A new `@unique` column needs its unique too, and on SQLite that cannot
+        // ride along with the ADD COLUMN — SQLite refuses to add a UNIQUE column.
+        if (field.isUnique && !field.isId && !dialect.supportsUniqueInlineOnAddColumn) {
+          const indexName = `UQ_${safeName}_${field.name}`;
+          const quoted = dialect.quote(indexName);
+          if ((await db.query(dialect.uniqueConstraintExists(tableName, indexName))).length === 0) {
+            db.log(`Creating unique index ${quoted} on table ${sqlTableName}...`);
+            await db.execute(dialect.createUniqueIndex(quoted, sqlTableName, quoteFields([field.name])));
+            result.uniqueConstraintsAdded += 1;
+          }
+        }
+      }
+      result.tablesAltered += 1;
+    }
+
+    // Unique constraints that are not part of the column definitions above.
+    for (const entry of compoundUniques) {
+      if (await hasUniqueConstraint(db, dialect, tableName, entry.name)) continue;
+      const quoted = dialect.quote(entry.name);
+      if (dialect.supportsNamedUniqueConstraint) {
+        db.log(`Adding compound unique constraint ${quoted} to table ${sqlTableName}...`);
+        await db.execute(dialect.addUniqueConstraint(quoted, sqlTableName, quoteFields(entry.fields)));
+      } else {
+        db.log(`Creating unique index ${quoted} on table ${sqlTableName}...`);
+        await db.execute(dialect.createUniqueIndex(quoted, sqlTableName, quoteFields(entry.fields)));
+        result.indexesCreated += 1;
+        result.uniqueConstraintsAdded += 1;
+      }
+      result.uniqueConstraintsAdded += 1;
+    }
+
+    for (const [idx, directive] of model.indexes.entries()) {
+      const name = directiveName(directive, model.tableName, 'index', idx);
+      if ((await db.query(dialect.indexExists(tableName, name))).length > 0) continue;
+      const quoted = dialect.quote(name);
+      db.log(`Creating index ${quoted} on table ${sqlTableName}...`);
+      await db.execute(dialect.createIndex(quoted, sqlTableName, quoteFields(directive.fields)));
+      result.indexesCreated += 1;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Whether the unique is already there.
+ *
+ * A compound unique created inside `CREATE TABLE` has no separate object to look
+ * for on the providers that keep them, so it is treated as present once the table
+ * exists; the per-column uniques inside a column definition are handled with the
+ * column above.
+ */
+async function hasUniqueConstraint(
+  db: PushDatabase,
+  dialect: PushDialect,
+  tableName: string,
+  name: string,
+): Promise<boolean> {
+  return (await db.query(dialect.uniqueConstraintExists(tableName, name))).length > 0;
+}

package/generator/src/push-schema.ts

@@ -0,0 +1,250 @@
+/**
+ * Reading `.an5` files for `db:push`.
+ *
+ * `SchemaParser` and `parseSchemaText` cover the generators and `db:migrate`;
+ * this is the third reader, and it exists because push needs a shape of its own:
+ * raw `@default` expressions rather than rendered SQL, and the schema a table
+ * lands in. It is kept here rather than inline in `push.ts` so the mapping from
+ * schema text to a column can be tested without a database.
+ */
+import {
+  FieldTypeIssue,
+  Provider,
+  readFieldLineHead,
+  resolveFieldType,
+  unknownFieldTypeMessage,
+} from './field-types';
+
+/** A column, as push needs it: the type as written plus what the dialect renders. */
+export interface PushField {
+  name: string;
+  sqlType: string;
+  isOptional: boolean;
+  isId: boolean;
+  isUnique: boolean;
+  /** The `@default(...)` expression, not SQL: only the dialect knows the spelling. */
+  defaultExpr?: string | undefined;
+}
+
+export interface PushModel {
+  name: string;
+  tableName: string;
+  /** The schema to create the table in; `''` when the provider has none. */
+  schema: string;
+  /** Set only when the schema file named one, so a wrong one can be reported. */
+  declaredSchema?: string | undefined;
+  fields: PushField[];
+  /** `@@unique([a, b])`, as field lists. */
+  compoundUniques: PushIndex[];
+  /** `@@index([a, b])`, as field lists. */
+  indexes: PushIndex[];
+}
+
+/**
+ * The schema a model lands in when the schema file does not say: none, for every
+ * provider, so the name goes wherever the connection resolves.
+ *
+ * The parser used to default this to `dbo` and push followed it, which failed two
+ * ways: SQLite said "unknown database [dbo]", and a SQL Server login whose default
+ * schema was something else had push look for `[dbo].[widgets]`, miss the table it
+ * had created, and then fail with "there is already an object named ...".
+ */
+export function defaultSchemaFor(_provider: Provider): string {
+  return '';
+}
+
+/**
+ * One `@@unique` or `@@index`, with the options `db:migrate` already understands.
+ *
+ * `name` matters as much as the fields: `map:` is how a schema asks for a specific
+ * artifact name, and if push invented its own the two commands would create two
+ * different constraints for the same directive — and the next migration would keep
+ * trying to add the one push never made.
+ */
+export interface PushIndex {
+  fields: string[];
+  name?: string | undefined;
+  includeFields?: string[] | undefined;
+  filter?: string | undefined;
+  options?: string | undefined;
+}
+
+export interface PushSchema {
+  models: PushModel[];
+  /** Field types the provider does not have; empty when the schema is valid. */
+  issues: FieldTypeIssue[];
+}
+
+/** The field list of `@@unique([a, b], …)`, plus whatever options follow it. */
+const DIRECTIVE = /^@@(?:unique|index)\(\s*\[([\w\s,]+)\]([^)]*)\)/;
+
+function parseDirective(line: string, fields: string): PushIndex {
+  const options = line.match(DIRECTIVE)?.[2] ?? '';
+  const name = options.match(/\bmap\s*:\s*"([^"]+)"/)?.[1];
+  const include = options.match(/\binclude\s*:\s*\[([\w,\s]+)\]/)?.[1];
+  const filter = options.match(/\bfilter\s*:\s*"([^"]+)"/)?.[1];
+  const opts = options.match(/\boptions\s*:\s*"([^"]+)"/)?.[1];
+  return {
+    fields: fields.split(',').map((field) => field.trim()).filter(Boolean),
+    ...(name ? { name } : {}),
+    ...(include ? { includeFields: include.split(',').map((field) => field.trim()).filter(Boolean) } : {}),
+    ...(filter ? { filter } : {}),
+    ...(opts ? { options: opts } : {}),
+  };
+}
+
+/**
+ * The name a `@@unique` or `@@index` artifact gets.
+ *
+ * `map:` wins; otherwise the name is derived from the table and fields, which is what
+ * both commands have always done for an unnamed directive.
+ */
+export function directiveName(
+  directive: PushIndex,
+  table: string,
+  kind: 'compound' | 'index',
+  position: number,
+): string {
+  if (directive.name) return safeIdentifierName(directive.name);
+  const base = safeIdentifierName(table);
+  return kind === 'compound'
+    ? `UQ_${base}_compound_${position}`
+    : `IX_${base}_${directive.fields.join('_')}`;
+}
+
+/**
+ * Reads schema text for push, validating every field type against the provider.
+ *
+ * All bad types come back in `issues` rather than as an exception, so the caller
+ * can print them as a group. A field whose type matches no table is only a
+ * mistake once the whole schema has been read: it may be a relation to a model
+ * declared further down.
+ */
+export function parsePushSchema(text: string, provider: Provider): PushSchema {
+  const models: PushModel[] = [];
+  const issues: FieldTypeIssue[] = [];
+  const modelRefs: Array<{ model: string; field: string; type: string }> = [];
+  let current: PushModel | null = null;
+
+  for (const raw of text.split('\n')) {
+    const line = raw.trim();
+    if (!line || line.startsWith('//')) continue;
+
+    const header = line.match(/^model\s+(\w+)\s*\{/);
+    if (header) {
+      current = {
+        name: header[1],
+        tableName: header[1].toLowerCase() + 's',
+        schema: defaultSchemaFor(provider),
+        fields: [],
+        compoundUniques: [],
+        indexes: [],
+      };
+      models.push(current);
+      continue;
+    }
+
+    if (line === '}') {
+      current = null;
+      continue;
+    }
+    if (!current) continue;
+
+    if (line.startsWith('@@map')) {
+      const match = line.match(/@@map\("(.+)"\)/);
+      if (match) current.tableName = match[1];
+      continue;
+    }
+    if (line.startsWith('@@schema')) {
+      // `(.*)` rather than `(.+)`, because `@@schema("")` is how a model says "no
+      // schema" and has to survive as an empty string rather than being dropped as
+      // no match — which is how SQLite and MySQL schemas are written.
+      const match = line.match(/@@schema\("(.*)"\)/);
+      if (match) {
+        current.schema = match[1].trim();
+        current.declaredSchema = current.schema;
+      }
+      continue;
+    }
+    if (line.startsWith('@@unique') || line.startsWith('@@index')) {
+      const match = line.match(DIRECTIVE);
+      if (match) {
+        const definition = parseDirective(line, match[1] ?? '');
+        if (line.startsWith('@@unique')) current.compoundUniques.push(definition);
+        else current.indexes.push(definition);
+      }
+      continue;
+    }
+    if (line.startsWith('@@')) continue;
+
+    const head = readFieldLineHead(line);
+    if (!head) continue;
+
+    if (!resolveFieldType(head.type, provider)) {
+      modelRefs.push({ model: current.name, field: head.name, type: head.type });
+      continue;
+    }
+
+    // The type is kept as written (upper-cased) because that is what the database
+    // is told; which types exist is what `resolveFieldType` just checked.
+    current.fields.push({
+      name: head.name,
+      sqlType: head.type.toUpperCase(),
+      isOptional: head.isOptional,
+      isId: line.includes('@id'),
+      isUnique: line.includes('@unique'),
+      // The expression rather than SQL: `uuid()` and `autoincrement()` are spelled
+      // differently per provider, and only the dialect knows how. `@updatedAt` is
+      // `now()` under another name.
+      defaultExpr: line.match(/@default\((.*)\)/)?.[1]
+        ?? (line.includes('@updatedAt') ? 'now()' : undefined),
+    });
+  }
+
+  // A declared `dbo` on a provider without schemas would push to a database that
+  // does not exist there; SQLite answers "unknown database [dbo]", which says
+  // nothing about the schema file. Only an explicit declaration is worth reporting:
+  // an absent one now means "whatever the connection resolves", on every provider.
+  for (const model of models) {
+    if (model.declaredSchema === 'dbo' && provider !== 'mssql') {
+      issues.push({
+        path: model.name,
+        message:
+          `schema "dbo" does not exist in ${provider}; remove the @@schema directive or set it ` +
+          'to the schema this database uses',
+      });
+    }
+  }
+
+  const modelNames = models.map((model) => model.name);
+  for (const ref of modelRefs) {
+    if (!modelNames.includes(ref.type)) {
+      issues.push({
+        path: `${ref.model}.${ref.field}`,
+        message: unknownFieldTypeMessage(ref.type, provider, modelNames),
+      });
+    }
+  }
+
+  return { models, issues };
+}
+
+/**
+ * The table name to create, `schema.table` unless the model cleared the schema.
+ *
+ * An empty schema has to stay empty: `[].[widgets]` is not valid SQL, which is the
+ * whole reason `@@schema("")` exists.
+ */
+/**
+ * An identifier for a generated artifact name: letters, digits and underscores only.
+ *
+ * The name goes into DDL as an identifier, so anything else is replaced rather than
+ * quoted — `@@map("catalog entries")` must not produce a name the provider rejects.
+ */
+export function safeIdentifierName(raw: string): string {
+  return raw.replace(/[^A-Za-z0-9_]/g, '_').replace(/_+/g, '_').replace(/^_|_$/g, '');
+}
+
+export function qualifiedTableName(model: PushModel): string {
+  return model.schema ? `${model.schema}.${model.tableName}` : model.tableName;
+}